@celilo/cli 2.2.0 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -60,7 +60,7 @@
     "@aws-sdk/lib-storage": "^3.1101.0",
     "@celilo/capabilities": "^4.2.0",
     "@celilo/cli-display": "^0.2.0",
-    "@celilo/core": "^0.11.0",
+    "@celilo/core": "^0.11.1",
     "@celilo/event-bus": "^0.6.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/schemas/system_config.json

@@ -118,6 +118,11 @@
       "type": "string",
       "description": "SSH public key for container access"
     },
+    "hooks.jail_policy": {
+      "type": "string",
+      "pattern": "^(auto|off|required)$",
+      "description": "Hook jail policy: 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off' (hooks run unjailed). Precedence: the CELILO_HOOK_JAIL environment variable wins over this stored value. Run 'celilo system doctor' to see the effective policy and which source it came from."
+    },
     "public_dns.resolver": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",

package/src/ansible/inventory.test.ts

@@ -4,6 +4,7 @@ import { rm } from 'node:fs/promises';
 import { type DbClient, createDbClient } from '../db/client';
 import { systemConfig } from '../db/schema';
 import { upsertModuleConfig } from '../services/module-config';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   buildHostVars,
   buildSystemVars,
@@ -286,7 +287,7 @@ describe('Database integration', () => {
   afterEach(async () => {
     db.$client.close();
     // Clean up environment variable
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     if (existsSync(TEST_DB_PATH)) {
       await rm(TEST_DB_PATH);
     }

package/src/api/sessions.test.ts

@@ -32,6 +32,7 @@ import { handleModuleUpdate } from '../cli/commands/module-update';
 import { getDb } from '../db/client';
 import { modules } from '../db/schema';
 import { RESPONDER_PROBE_EVENT } from '../services/responder-probe';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { SessionWriter, listSessions, reapExpiredSessions } from './sessions';
 
 const NO_SCHEMAS = defineEvents({});
@@ -99,7 +100,7 @@ beforeEach(() => {
 afterEach(() => {
   server.stop(true);
   rmSync(dir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
   process.env.CELILO_DATA_DIR = undefined;
   process.env.CELILO_ORIGINAL_CWD = undefined;
   process.env.EVENT_BUS_DB = undefined;

package/src/cli/backup-rename.test.ts

@@ -16,6 +16,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { runCli } from './index';
 
 describe('celilo module backup (renamed surface)', () => {
@@ -48,7 +49,7 @@ describe('celilo module backup (renamed surface)', () => {
       warnSpy = null;
     }
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_MASTER_KEY_PATH = undefined;
     process.env.CELILO_SUPPRESS_DEPRECATION = undefined;
     try {

package/src/cli/cli.test.ts

@@ -8,6 +8,7 @@ import { moduleConfigs, modules, secrets } from '../db/schema';
 import { encryptSecret } from '../secrets/encryption';
 import { generateMasterKey, writeMasterKey } from '../secrets/master-key';
 import { upsertModuleConfig } from '../services/module-config';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { runCli } from './index';
 
 const TEST_DB_PATH = `./test-cli-${Date.now()}-${Math.random()}.db`;
@@ -147,7 +148,7 @@ description: Test module for CLI
 
     // Clear environment variables
     process.env.CELILO_MASTER_KEY_PATH = undefined;
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
   });
 
   describe('help', () => {

package/src/cli/commands/console-get-chain.test.ts

@@ -15,6 +15,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { resetTestDbPath } from '../../test-utils/db-path';
 
 let testDir: string;
 
@@ -26,7 +27,7 @@ beforeEach(() => {
 
 afterEach(() => {
   rmSync(testDir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
 });
 
 /** The live fleet's firewall shape: caddy on iptables, iptables on the router. */

package/src/cli/commands/firewall-interface-list.test.ts

@@ -12,6 +12,7 @@ import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { resetTestDbPath } from '../../test-utils/db-path';
 
 // The command reaches boxes ONLY through these two modules, and both are
 // mocked below so the tests can drive the live-read and fallback paths without
@@ -67,7 +68,7 @@ beforeEach(() => {
 afterEach(() => {
   console.log = originalLog;
   rmSync(testDir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
   process.env.CELILO_DATA_DIR = undefined;
   process.env.CELILO_MASTER_KEY_PATH = undefined;
 });

package/src/cli/commands/module-config.test.ts

@@ -12,6 +12,7 @@ import { join } from 'node:path';
 import { type DbClient, getDb } from '../../db/client';
 import { moduleConfigs, modules } from '../../db/schema';
 import { resolveDeployPosture } from '../../services/deploy-posture';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import {
   FRAMEWORK_CONFIG_KEYS,
   handleModuleConfigGet,
@@ -51,7 +52,7 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
   });
 
   test('rejects an infrastructure-managed key (no silent accept-then-override)', async () => {

package/src/cli/commands/module-deploy.ts

@@ -14,7 +14,7 @@ import type { CommandResult } from '../types';
  * Handle module deploy command
  *
  * Usage:
- *   celilo module deploy <module-id> [--debug] [--preflight] [--verbose]
+ *   celilo module deploy <module-id> [--debug] [--preflight] [--verbose] [--keep]
  *
  * Note: there is no `--no-interactive` flag. The deploy interview
  * runs through the bus event system; automation answers via a
@@ -59,8 +59,14 @@ export async function handleModuleDeploy(
   const debug = hasFlag(flags, 'debug');
   const verbose = hasFlag(flags, 'verbose');
   const stopAfterInterview = hasFlag(flags, 'stop-after-interview');
+  const keepGeneratedProject = hasFlag(flags, 'keep');
 
-  const result = await deployModule(moduleId, db, { debug, verbose, stopAfterInterview });
+  const result = await deployModule(moduleId, db, {
+    debug,
+    verbose,
+    stopAfterInterview,
+    keepGeneratedProject,
+  });
 
   if (!result.success) {
     return {

package/src/cli/commands/module-generate.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, 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 type { ModuleManifest } from '../../manifest/schema';
+import { missingBuildOutputs } from './module-generate';
+
+const DECLARED = join('ansible', 'roles', 'fixture', 'files', 'binary');
+
+function manifestWithArtifacts(artifacts: string[]): ModuleManifest {
+  return {
+    celilo_contract: '1.0',
+    id: 'fixture',
+    name: 'Fixture',
+    version: '1.0.0',
+    description: 'fixture',
+    build: { command: 'true', artifacts },
+  } as ModuleManifest;
+}
+
+describe('missingBuildOutputs', () => {
+  let payload: string;
+
+  beforeEach(() => {
+    payload = mkdtempSync(join(tmpdir(), 'celilo-missing-outputs-'));
+  });
+
+  afterEach(() => {
+    rmSync(payload, { recursive: true, force: true });
+  });
+
+  test('names the declared output the payload is missing', () => {
+    expect(missingBuildOutputs(payload, manifestWithArtifacts([DECLARED]))).toEqual([DECLARED]);
+  });
+
+  test('reports nothing when the payload carries its declared outputs', () => {
+    mkdirSync(join(payload, 'ansible', 'roles', 'fixture', 'files'), { recursive: true });
+    writeFileSync(join(payload, DECLARED), 'built-bytes');
+    expect(missingBuildOutputs(payload, manifestWithArtifacts([DECLARED]))).toEqual([]);
+  });
+
+  test('reports nothing for a module with no build block', () => {
+    expect(
+      missingBuildOutputs(payload, {
+        celilo_contract: '1.0',
+        id: 'fixture',
+        name: 'Fixture',
+        version: '1.0.0',
+        description: 'fixture',
+      } as ModuleManifest),
+    ).toEqual([]);
+  });
+});

package/src/cli/commands/module-generate.ts

@@ -3,7 +3,7 @@
  */
 
 import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { eq } from 'drizzle-orm';
 import {
   promptForMissingCapabilitySecrets,
@@ -13,12 +13,25 @@ import { getDb } from '../../db/client';
 import { moduleConfigs, modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
 import { interviewForMissingSecrets, validateModuleSecrets } from '../../services/config-interview';
-import { getModuleBuildStatus, verifyArtifactsExist } from '../../services/module-build';
 import { generateTemplates } from '../../templates/generator';
 import { promptForMissingConfig } from '../interactive-config';
 import { getArg, getFlag, validateRequiredArgs } from '../parser';
 import type { CommandResult } from '../types';
 
+/**
+ * Declared `build.artifacts` absent from the module's delivered payload.
+ *
+ * D1 (control-plane-stops-building-modules): generation consumes the payload.
+ * A declared output the payload does not carry is a publish defect, so it is
+ * reported to the caller and named, never repaired by running a build here.
+ * A fallback build is the shape that hid celilo#1307 for four months: the
+ * failure must fail loudly at the boundary, not be repaired downstream.
+ */
+export function missingBuildOutputs(modulePath: string, manifest: ModuleManifest): string[] {
+  const artifacts = manifest.build?.artifacts ?? [];
+  return artifacts.filter((artifact) => !existsSync(join(modulePath, artifact)));
+}
+
 /**
  * Handle module generate command
  *
@@ -71,31 +84,23 @@ export async function handleModuleGenerate(
     };
   }
 
-  // Check if module requires build step
+  // D1 (control-plane-stops-building-modules): generation consumes the
+  // delivered payload. Whether this machine ever ran a build is a fact about
+  // its own history, not about the module in front of it — gating on it is
+  // what made celilo#1307 refuse generation on a production control plane
+  // whose payload carried the correct binaries one directory away.
   const manifest = module.manifestData as ModuleManifest;
-  if (manifest.build) {
-    const buildStatus = await getModuleBuildStatus(moduleId, db);
-
-    if (!buildStatus || buildStatus.status !== 'success') {
-      return {
-        success: false,
-        error:
-          `Module ${moduleId} requires build step before generation.\n\n` +
-          `Run: celilo module build ${moduleId}`,
-      };
-    }
-
-    // Verify artifacts still exist
-    if (buildStatus.artifacts.length > 0) {
-      const artifactsValid = verifyArtifactsExist(buildStatus.artifacts);
-
-      if (!artifactsValid) {
-        return {
-          success: false,
-          error: `Build artifacts missing or invalid.\n\nRebuild: celilo module build ${moduleId}`,
-        };
-      }
-    }
+  const missingOutputs = missingBuildOutputs(modulePath, manifest);
+  if (missingOutputs.length > 0) {
+    return {
+      success: false,
+      error: [
+        `Module payload is missing ${missingOutputs.length} declared build output(s):`,
+        ...missingOutputs.map((artifact) => `  ${artifact}`),
+        '',
+        "The payload must carry the module's build outputs; a control plane never builds. This is a publish defect: re-package the module and update it. Generation will not fall back to running a build.",
+      ].join('\n'),
+    };
   }
 
   const outputPathFlag = getFlag(flags, 'output', '');

package/src/cli/commands/module-import-aspect.test.ts

@@ -12,6 +12,7 @@ import { closeDb, getDb } from '../../db/client';
 import { runMigrations } from '../../db/migrate';
 import { modules } from '../../db/schema';
 import type { BaseModuleAspect } from '../../manifest/schema';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handleAspectApprovalAfterImport } from './module-import';
 
 const aspect: BaseModuleAspect = {
@@ -61,7 +62,7 @@ describe('handleAspectApprovalAfterImport (non-interactive)', () => {
   afterEach(() => {
     setTTY(originalIsTTY);
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/cli/commands/module-import-registry.test.ts

@@ -17,6 +17,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { IndexEntry } from '../../registry/client';
 import { RegistryClient } from '../../registry/client';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handlePublicRegistryImport } from './module-import';
 
 // handlePublicRegistryImport is not exported by default — re-exported at end of module-import.ts
@@ -42,7 +43,7 @@ afterEach(() => {
   getIndexSpy.mockRestore();
   downloadSpy.mockRestore();
   rmSync(tempDir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
   process.env.CELILO_DATA_DIR = undefined;
 });
 

package/src/cli/commands/module-operations.test.ts

@@ -7,6 +7,7 @@ import { closeDb, getDb } from '../../db/client';
 import { runMigrations } from '../../db/migrate';
 import { moduleOperations } from '../../db/schema';
 import { ABANDONED_RELEASE_MESSAGE, OPERATION_TTL_MS } from '../../services/module-operations';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handleModuleOperations } from './module-operations';
 
 describe('celilo module operations', () => {
@@ -20,7 +21,7 @@ describe('celilo module operations', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     rmSync(dir, { recursive: true, force: true });
   });
 

package/src/cli/commands/module-publish.test.ts

@@ -15,6 +15,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import type { IndexEntry } from '../../registry/client';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handleModulePublish, resolveToken } from './module-publish';
 
 const TEST_DIR = `/tmp/test-module-publish-${Date.now()}`;
@@ -41,7 +42,6 @@ describe('handleModulePublish — validation', () => {
     // fallback in resolveToken() may read a real publish token and the test
     // will skip the validation path it's trying to exercise.
     const origToken = process.env.CELILO_PUBLISH_TOKEN;
-    const origDbPath = process.env.CELILO_DB_PATH;
     const origDataDir = process.env.CELILO_DATA_DIR;
     process.env.CELILO_PUBLISH_TOKEN = undefined;
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-no-token-${Date.now()}.db`;
@@ -52,8 +52,7 @@ describe('handleModulePublish — validation', () => {
       if (!result.success) expect(result.error).toContain('Publish token required');
     } finally {
       if (origToken !== undefined) process.env.CELILO_PUBLISH_TOKEN = origToken;
-      if (origDbPath !== undefined) process.env.CELILO_DB_PATH = origDbPath;
-      else process.env.CELILO_DB_PATH = undefined;
+      resetTestDbPath();
       if (origDataDir !== undefined) process.env.CELILO_DATA_DIR = origDataDir;
       else process.env.CELILO_DATA_DIR = undefined;
     }
@@ -163,7 +162,6 @@ describe('revision auto-detection algorithm', () => {
 describe('resolveToken — precedence', () => {
   test('--token flag wins over env var and secret store', async () => {
     const origEnv = process.env.CELILO_PUBLISH_TOKEN;
-    const origDbPath = process.env.CELILO_DB_PATH;
     process.env.CELILO_PUBLISH_TOKEN = 'env-token';
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-resolve-${Date.now()}.db`;
     try {
@@ -172,14 +170,12 @@ describe('resolveToken — precedence', () => {
     } finally {
       if (origEnv !== undefined) process.env.CELILO_PUBLISH_TOKEN = origEnv;
       else process.env.CELILO_PUBLISH_TOKEN = undefined;
-      if (origDbPath !== undefined) process.env.CELILO_DB_PATH = origDbPath;
-      else process.env.CELILO_DB_PATH = undefined;
+      resetTestDbPath();
     }
   });
 
   test('env var used when --token flag is empty', async () => {
     const origEnv = process.env.CELILO_PUBLISH_TOKEN;
-    const origDbPath = process.env.CELILO_DB_PATH;
     process.env.CELILO_PUBLISH_TOKEN = 'env-token';
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-resolve-${Date.now()}.db`;
     try {
@@ -188,8 +184,7 @@ describe('resolveToken — precedence', () => {
     } finally {
       if (origEnv !== undefined) process.env.CELILO_PUBLISH_TOKEN = origEnv;
       else process.env.CELILO_PUBLISH_TOKEN = undefined;
-      if (origDbPath !== undefined) process.env.CELILO_DB_PATH = origDbPath;
-      else process.env.CELILO_DB_PATH = undefined;
+      resetTestDbPath();
     }
   });
 
@@ -197,7 +192,6 @@ describe('resolveToken — precedence', () => {
     // All three sources empty: secret-store fallback hits an isolated empty
     // DB and returns null gracefully.
     const origEnv = process.env.CELILO_PUBLISH_TOKEN;
-    const origDbPath = process.env.CELILO_DB_PATH;
     const origDataDir = process.env.CELILO_DATA_DIR;
     process.env.CELILO_PUBLISH_TOKEN = undefined;
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-resolve-empty-${Date.now()}.db`;
@@ -207,8 +201,7 @@ describe('resolveToken — precedence', () => {
       expect(t).toBe('');
     } finally {
       if (origEnv !== undefined) process.env.CELILO_PUBLISH_TOKEN = origEnv;
-      if (origDbPath !== undefined) process.env.CELILO_DB_PATH = origDbPath;
-      else process.env.CELILO_DB_PATH = undefined;
+      resetTestDbPath();
       if (origDataDir !== undefined) process.env.CELILO_DATA_DIR = origDataDir;
       else process.env.CELILO_DATA_DIR = undefined;
     }

package/src/cli/commands/module-update.test.ts

@@ -21,6 +21,7 @@ import { eq } from 'drizzle-orm';
 import { create as tarCreate } from 'tar';
 import { type DbClient, getDb } from '../../db/client';
 import { moduleIntegrity, modules } from '../../db/schema';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { classifyVersionChange, handleModuleUpdate, updateOne } from './module-update';
 
 describe('classifyVersionChange', () => {
@@ -124,7 +125,7 @@ description: fixture
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_ORIGINAL_CWD = undefined;
   });
 
@@ -313,7 +314,7 @@ describe('registry sweep — an unanswered breaking update is not a decline', ()
   afterEach(() => {
     server.stop(true);
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_ORIGINAL_CWD = undefined;
     process.env.EVENT_BUS_DB = undefined;
   });
@@ -387,7 +388,7 @@ description: fixture
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_ORIGINAL_CWD = undefined;
   });
 
@@ -499,7 +500,7 @@ describe('updateOne — an update that fails partway leaves the install untouche
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_ORIGINAL_CWD = undefined;
   });
 
@@ -594,7 +595,7 @@ describe('updateOne — a .netapp package source', () => {
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_ORIGINAL_CWD = undefined;
   });
 

package/src/cli/commands/module-upgrade.test.ts

@@ -4,6 +4,7 @@ import {
   type PollCandidate,
   isPollInvocation,
   needsPreUpgradeBackup,
+  needsSystemStateSnapshot,
   pickAutoUpgrade,
   pickUpgradePolicy,
   selectPollTargets,
@@ -102,6 +103,20 @@ describe('selectPollTargets (ISS-0139 — opted-in + a newer registry version)',
   });
 });
 
+// A 0.x minor/major bump can migrate the celilo DB schema; the system_state
+// snapshot is what makes a later `apt install celilo=<old>` (or dpkg -i from
+// the apt cache) a real rollback instead of a gamble. Patch/revision bumps
+// don't migrate, so they stay fast.
+describe('needsSystemStateSnapshot (safe posture snapshots the celilo DB before mutating)', () => {
+  test('safe posture (minor/major) requires the snapshot', () => {
+    expect(needsSystemStateSnapshot('safe')).toBe(true);
+  });
+
+  test('fast posture (patch/revision) skips the snapshot', () => {
+    expect(needsSystemStateSnapshot('fast')).toBe(false);
+  });
+});
+
 describe('needsPreUpgradeBackup (ISS-0168 — gate on the TARGET version manifest)', () => {
   // The regression: the upgrade that FIRST adds on_backup must still back up.
   // The installed version lacked the hook; the target (passed here) adds it.

package/src/cli/commands/module-upgrade.ts

@@ -20,7 +20,8 @@ import { type DbClient, getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
-import { createModuleBackup } from '../../services/backup-create';
+import { createModuleBackup, createSystemStateBackup } from '../../services/backup-create';
+import { getDefaultBackupStorage } from '../../services/backup-storage';
 import {
   type DeployPosture,
   type UpgradePolicy,
@@ -79,6 +80,47 @@ export function needsPreUpgradeBackup(
   return posture === 'safe' && Boolean(targetManifest.hooks?.on_backup);
 }
 
+/**
+ * Pure (Rule 10): does this upgrade snapshot the celilo DB first? Safe posture
+ * means a minor/major bump, and a minor bump can migrate the DB schema — the
+ * snapshot is what makes a later package downgrade a real rollback instead of
+ * a gamble on an older binary reading a newer-migrated database.
+ */
+export function needsSystemStateSnapshot(posture: DeployPosture): boolean {
+  return posture === 'safe';
+}
+
+/**
+ * Take the system_state snapshot a safe-posture upgrade requires.
+ *
+ * A host with no default backup storage keeps today's behavior (warn and
+ * proceed): refusing every safe upgrade there would break CD for a config
+ * gap, and the module-level backup below still runs when the target manifest
+ * declares on_backup. A configured-but-failing snapshot refuses the upgrade,
+ * same rule `system update` applies to its own snapshot (D7): the DB snapshot
+ * is the safety net, and an upgrade that cannot take it should not mutate.
+ */
+async function snapshotSystemStateBeforeUpgrade(
+  moduleId: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    if (!getDefaultBackupStorage()) {
+      log.warn(
+        `${moduleId}: no default backup storage configured — skipping pre-upgrade system_state snapshot`,
+      );
+      return { ok: true };
+    }
+    const snapshot = await createSystemStateBackup();
+    if (!snapshot.success) {
+      return { ok: false, error: snapshot.error ?? 'system_state backup failed' };
+    }
+    log.success(`System state snapshot taken before upgrading ${moduleId}`);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 export interface PollCandidate {
   moduleId: string;
   installed: string;
@@ -168,7 +210,17 @@ async function upgradeOneModule(
   });
   log.info(`Upgrading ${moduleId} ${mod.version} → ${targetVersion} (${posture} — ${reason})`);
 
-  // Safe → back up first, gated on the TARGET manifest's on_backup hook.
+  // Safe → snapshot the celilo DB first (the package rollback pair), then
+  // back up the module itself, gated on the TARGET manifest's on_backup hook.
+  if (needsSystemStateSnapshot(posture)) {
+    const snapshot = await snapshotSystemStateBeforeUpgrade(moduleId);
+    if (!snapshot.ok) {
+      return {
+        success: false,
+        error: `Pre-upgrade system_state snapshot failed for ${moduleId}: ${snapshot.error}`,
+      };
+    }
+  }
   if (needsPreUpgradeBackup(posture, targetManifest)) {
     const backup = await createModuleBackup(moduleId);
     if (!backup.success) {

package/src/cli/commands/module-verify.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { moduleAudit } from './module-audit';
 import { moduleVerify } from './module-verify';
 
@@ -19,7 +20,6 @@ describe('moduleVerify', () => {
 describe('moduleAudit (deprecation alias)', () => {
   let dataDir: string;
   const originalDataDir = process.env.CELILO_DATA_DIR;
-  const originalDbPath = process.env.CELILO_DB_PATH;
 
   beforeEach(() => {
     dataDir = mkdtempSync(join(tmpdir(), 'celilo-audit-alias-'));
@@ -29,10 +29,9 @@ describe('moduleAudit (deprecation alias)', () => {
 
   afterEach(() => {
     rmSync(dataDir, { recursive: true, force: true });
+    resetTestDbPath();
     if (originalDataDir === undefined) process.env.CELILO_DATA_DIR = undefined;
     else process.env.CELILO_DATA_DIR = originalDataDir;
-    if (originalDbPath === undefined) process.env.CELILO_DB_PATH = undefined;
-    else process.env.CELILO_DB_PATH = originalDbPath;
   });
 
   test('writes a deprecation warning to stderr and delegates to verify', async () => {

package/src/cli/commands/module-verify.ts

@@ -102,7 +102,6 @@ export async function moduleVerify(
     modified: '✗',
     extra: '!',
     'stale-baseline': '⚠',
-    'stale-generated': '✗',
   };
 
   return {