@celilo/cli 2.2.0 → 2.3.0

package/src/cli/commands/module-list-jail.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Tests for `celilo module list`'s jail-exemption marker (per-module-jail-policy
+ * task 3.1/3.4).
+ *
+ * A module with a recorded policy weaker than the system's is marked in the
+ * human list and carries a `jailExemptions` roster entry in JSON. The negative
+ * half is asserted with the same rigour: no row, no marker, empty roster —
+ * a query bug that reported phantom exemptions would look exactly like a
+ * correctly empty one otherwise.
+ *
+ * Isolation mirrors module-jail.test.ts: CELILO_DB_PATH / CELILO_DATA_DIR are
+ * set before the SUT is imported.
+ */
+
+import { afterAll, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+
+const testRoot = mkdtempSync(join(tmpdir(), 'celilo-module-list-jail-'));
+process.env.CELILO_DB_PATH = join(testRoot, 'celilo.db');
+process.env.CELILO_DATA_DIR = join(testRoot, 'data');
+
+const { getDb, closeDb } = await import('../../db/client');
+const { moduleJailPolicies, modules, systemConfig } = await import('../../db/schema');
+const { handleModuleList } = await import('./module-list');
+import type { CommandResult, CommandSuccess } from '../types';
+
+/** Narrow the result union after asserting the branch, so `.message` typechecks. */
+function expectOk(result: CommandResult): asserts result is CommandSuccess {
+  expect(result.success).toBe(true);
+}
+
+function insertModule(id: string): void {
+  getDb()
+    .insert(modules)
+    .values({ id, name: id, sourcePath: `/tmp/${id}`, version: '1.0.0', manifestData: {} })
+    .run();
+}
+
+function setModulePolicy(moduleId: string, policy: string): void {
+  const typed = policy as 'auto' | 'off' | 'required';
+  getDb()
+    .insert(moduleJailPolicies)
+    .values({ moduleId, policy: typed, updatedAt: new Date() })
+    .onConflictDoUpdate({
+      target: moduleJailPolicies.moduleId,
+      set: { policy: typed, updatedAt: new Date() },
+    })
+    .run();
+}
+
+function setSystemPolicy(value: string): void {
+  getDb()
+    .insert(systemConfig)
+    .values({ key: 'hooks.jail_policy', value })
+    .onConflictDoUpdate({ target: systemConfig.key, set: { value } })
+    .run();
+}
+
+function clearModulePolicy(moduleId: string): void {
+  getDb().delete(moduleJailPolicies).where(eq(moduleJailPolicies.moduleId, moduleId)).run();
+}
+
+afterAll(() => {
+  closeDb();
+  rmSync(testRoot, { recursive: true, force: true });
+});
+
+describe('module list — jail exemption marker (per-module-jail-policy task 3.1)', () => {
+  beforeEach(() => {
+    const db = getDb();
+    db.delete(moduleJailPolicies).run();
+    db.delete(systemConfig).where(eq(systemConfig.key, 'hooks.jail_policy')).run();
+    db.delete(modules).run();
+    insertModule('caddy');
+  });
+
+  test('a module weaker than the system is marked, with both policies', async () => {
+    setSystemPolicy('auto');
+    setModulePolicy('caddy', 'off');
+    const result = await handleModuleList({});
+    expectOk(result);
+    expect(result.message).toContain('caddy');
+    expect(result.message).toContain("[jail: off — weaker than the system's auto]");
+  });
+
+  test('a module with no per-module row carries no marker (the negative half of task 3.4)', async () => {
+    setSystemPolicy('auto');
+    const result = await handleModuleList({});
+    expectOk(result);
+    expect(result.message).not.toContain('jail:');
+    expect(result.message).not.toContain('weaker than');
+  });
+
+  test('a module whose row is not weaker than the system carries no marker', async () => {
+    setSystemPolicy('auto');
+    setModulePolicy('caddy', 'required');
+    const result = await handleModuleList({});
+    expectOk(result);
+    expect(result.message).not.toContain('jail:');
+  });
+
+  test('a cleared row stops the marker (the exemption is un-set, not hidden)', async () => {
+    setSystemPolicy('auto');
+    setModulePolicy('caddy', 'off');
+    const before = await handleModuleList({});
+    expectOk(before);
+    expect(before.message).toContain('[jail:');
+    clearModulePolicy('caddy');
+    const after = await handleModuleList({});
+    expectOk(after);
+    expect(after.message).not.toContain('[jail:');
+  });
+
+  test('the JSON roster carries the exemptions', async () => {
+    setSystemPolicy('auto');
+    setModulePolicy('caddy', 'off');
+    const result = await handleModuleList({ json: true });
+    expectOk(result);
+    const parsed = JSON.parse(result.message) as {
+      jailExemptions: Array<{ moduleId: string; policy: string; systemPolicy: string }>;
+    };
+    expect(parsed.jailExemptions).toEqual([
+      { moduleId: 'caddy', policy: 'off', systemPolicy: 'auto' },
+    ]);
+  });
+
+  test('the JSON roster is empty when nothing is exempted', async () => {
+    const result = await handleModuleList({ json: true });
+    expectOk(result);
+    const parsed = JSON.parse(result.message) as { jailExemptions: unknown[] };
+    expect(parsed.jailExemptions).toEqual([]);
+  });
+});

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

@@ -1,6 +1,7 @@
 import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import { loadObservedHealth } from '../../services/alerting/observed-health';
+import { type JailExemption, collectJailExemptions } from '../../services/jail-exemptions';
 import { formatPausedDuration } from '../../services/module-pause';
 import { hasFlag } from '../parser';
 import type { CommandResult } from '../types';
@@ -20,14 +21,29 @@ export async function handleModuleList(
   // Query all modules
   const moduleRows = db.select().from(modules).all();
 
+  // Per-module jail exemptions (per-module-jail-policy task 3.1), from the
+  // shared collector so list, doctor and audit report the same set. A bad
+  // stored row throws here rather than silently listing unmarked — the same
+  // row will fail that module's hooks at execution time.
+  let jailExemptions: JailExemption[];
+  try {
+    jailExemptions = collectJailExemptions(db);
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+  const exemptedById = new Map(jailExemptions.map((e) => [e.moduleId, e]));
+
   // Stable machine-readable roster — the backbone the MCP composite
   // troubleshooting tools correlate audit findings against (ce-77i.5).
   if (hasFlag(flags, 'json')) {
     return {
       success: true,
-      message: JSON.stringify({ modules: moduleRows }, null, 2),
+      message: JSON.stringify({ modules: moduleRows, jailExemptions }, null, 2),
       rawOutput: true,
-      data: moduleRows,
+      data: { modules: moduleRows, jailExemptions },
     };
   }
 
@@ -56,7 +72,9 @@ export async function handleModuleList(
       module.state === 'PAUSED'
         ? `PAUSED (${formatPausedDuration(module.pausedAt)})`
         : module.state;
-    lines.push(`${module.id} (v${module.version}) - ${stateCell}${healthNote}`);
+    lines.push(
+      `${module.id} (v${module.version}) - ${stateCell}${healthNote}${jailNote(exemptedById.get(module.id))}`,
+    );
     if (module.state === 'PAUSED' && module.pauseReason) {
       lines.push(`  Paused: ${module.pauseReason}`);
     }
@@ -75,3 +93,12 @@ export async function handleModuleList(
     data: moduleRows,
   };
 }
+
+/**
+ * The list marker for an exempted module, or '' when the module has no row
+ * (per-module-jail-policy task 3.4: no row, no output).
+ */
+function jailNote(exemption: JailExemption | undefined): string {
+  if (!exemption) return '';
+  return `  [jail: ${exemption.policy} — weaker than the system's ${exemption.systemPolicy}]`;
+}

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,9 +42,8 @@ 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;
+    delete process.env.CELILO_PUBLISH_TOKEN;
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-no-token-${Date.now()}.db`;
     process.env.CELILO_DATA_DIR = `/tmp/test-celilo-data-${Date.now()}`;
     try {
@@ -52,10 +52,9 @@ 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;
+      else delete process.env.CELILO_DATA_DIR;
     }
   });
 
@@ -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 {
@@ -171,15 +169,13 @@ describe('resolveToken — precedence', () => {
       expect(t).toBe('flag-token');
     } 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;
+      else delete process.env.CELILO_PUBLISH_TOKEN;
+      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 {
@@ -187,9 +183,8 @@ describe('resolveToken — precedence', () => {
       expect(t).toBe('env-token');
     } 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;
+      else delete process.env.CELILO_PUBLISH_TOKEN;
+      resetTestDbPath();
     }
   });
 
@@ -197,9 +192,8 @@ 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;
+    delete process.env.CELILO_PUBLISH_TOKEN;
     process.env.CELILO_DB_PATH = `/tmp/test-celilo-resolve-empty-${Date.now()}.db`;
     process.env.CELILO_DATA_DIR = `/tmp/test-celilo-data-empty-${Date.now()}`;
     try {
@@ -207,10 +201,9 @@ 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;
+      else delete process.env.CELILO_DATA_DIR;
     }
   });
 });

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', () => {
@@ -106,12 +107,15 @@ description: fixture
     // Seed the modules table with the "currently installed" record.
     // We deliberately put a registry-style version string in here so
     // displayVersion-less upgrades preserve the previousVersion field.
+    // celilo#1363: updatedAt is seeded frozen so the success assertions can
+    // prove the stamp actually happens whenever the version moves.
     db.insert(modules)
       .values({
         id: 'testmod',
         name: 'Test Module',
         sourcePath: installedDir,
         version: '1.0.0+5',
+        updatedAt: new Date('2026-04-25T16:26:31Z'),
         manifestData: {
           celilo_contract: '1.0',
           id: 'testmod',
@@ -124,8 +128,8 @@ description: fixture
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_ORIGINAL_CWD = undefined;
+    resetTestDbPath();
+    delete process.env.CELILO_ORIGINAL_CWD;
   });
 
   test('returns previousVersion + newVersion in the success outcome', async () => {
@@ -152,6 +156,18 @@ description: fixture
     expect(row.version).toBe('1.0.0+6');
   });
 
+  // celilo#1363: the version moved (1.0.5+5 → +6) while updatedAt stayed at
+  // 2026-04-25, so the audit read the module as untouched and fine. The stamp
+  // must happen in updateOne itself, where every version write lives.
+  test('writing a new version stamps updatedAt', async () => {
+    const result = await updateOne(srcDir, db, {}, { quiet: true, displayVersion: '1.0.0+6' });
+    expect(result.status).toBe('success');
+
+    const row = db.select().from(modules).all()[0];
+    expect(row.version).toBe('1.0.0+6');
+    expect(row.updatedAt?.getTime()).toBeGreaterThan(new Date('2026-04-25T16:26:31Z').getTime());
+  });
+
   test('quiet=true suppresses the per-call log lines (caller renders its own)', async () => {
     // We can't easily intercept the log helpers' output without adding test
     // hooks, so instead we exercise that the call simply succeeds and
@@ -256,7 +272,7 @@ subscriptions:
         bus.close();
       }
     } finally {
-      process.env.EVENT_BUS_DB = undefined;
+      delete process.env.EVENT_BUS_DB;
     }
   });
 });
@@ -313,9 +329,9 @@ 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;
-    process.env.CELILO_ORIGINAL_CWD = undefined;
-    process.env.EVENT_BUS_DB = undefined;
+    resetTestDbPath();
+    delete process.env.CELILO_ORIGINAL_CWD;
+    delete process.env.EVENT_BUS_DB;
   });
 
   test('reports it as unanswered, never as declined, and fails the sweep', async () => {
@@ -387,8 +403,8 @@ description: fixture
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_ORIGINAL_CWD = undefined;
+    resetTestDbPath();
+    delete process.env.CELILO_ORIGINAL_CWD;
   });
 
   test('refuses by name, and writes NOTHING', async () => {
@@ -499,8 +515,8 @@ describe('updateOne — an update that fails partway leaves the install untouche
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_ORIGINAL_CWD = undefined;
+    resetTestDbPath();
+    delete process.env.CELILO_ORIGINAL_CWD;
   });
 
   test('a failed update leaves the installed tree byte-identical', async () => {
@@ -594,8 +610,8 @@ describe('updateOne — a .netapp package source', () => {
 
   afterEach(() => {
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_ORIGINAL_CWD = undefined;
+    resetTestDbPath();
+    delete process.env.CELILO_ORIGINAL_CWD;
   });
 
   // ce-h4of: the temp-dir cleanup ran BEFORE the staged swap, and

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

@@ -475,12 +475,15 @@ export async function updateOne(
 
   // Update manifest in database. We persist the display version (with
   // +N when known) so subsequent `module list` / `module update` calls
-  // see the same version string the registry reported.
+  // see the same version string the registry reported. updatedAt moves with
+  // the version: a frozen timestamp beside a new version read as "nothing
+  // happened here" to the audit (celilo#1363).
   db.update(modules)
     .set({
       manifestData: newManifest as unknown as Record<string, unknown>,
       version: newVersion,
       name: newManifest.name,
+      updatedAt: new Date(),
     })
     .where(eq(modules.id, moduleId))
     .run();

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

@@ -1,12 +1,25 @@
-import { describe, expect, test } from 'bun:test';
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import type { Mock } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { create as tarCreate } from 'tar';
+import { type DbClient, getDb } from '../../db/client';
+import { type ModuleState, modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
+import { RegistryClient } from '../../registry/client';
+import * as moduleDeploy from '../../services/module-deploy';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import {
   type PollCandidate,
   isPollInvocation,
   needsPreUpgradeBackup,
+  needsSystemStateSnapshot,
   pickAutoUpgrade,
   pickUpgradePolicy,
   selectPollTargets,
+  upgradeOneModule,
 } from './module-upgrade';
 
 /** Minimal manifest fixture; only `hooks` matters for the backup gate. */
@@ -69,6 +82,7 @@ describe('selectPollTargets (ISS-0139 — opted-in + a newer registry version)',
     installed: '1.0.0',
     latest: '1.0.1',
     autoUpgrade: true,
+    inError: false,
     ...over,
   });
 
@@ -91,6 +105,13 @@ describe('selectPollTargets (ISS-0139 — opted-in + a newer registry version)',
     expect(selectPollTargets([base({ latest: null })])).toEqual([]);
   });
 
+  // celilo#1363: the poll burned five attempts redeploying celilo-website
+  // against a failure that never went away. A module in ERROR stays skipped
+  // until an attended health check clears it.
+  test('skips modules in ERROR state (a failed upgrade deploy)', () => {
+    expect(selectPollTargets([base({ inError: true })])).toEqual([]);
+  });
+
   test('picks only the eligible subset from a mixed set', () => {
     const targets = selectPollTargets([
       base({ moduleId: 'a', installed: '1.0.0', latest: '1.0.1', autoUpgrade: true }),
@@ -102,6 +123,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.
@@ -121,3 +156,97 @@ describe('needsPreUpgradeBackup (ISS-0168 — gate on the TARGET version manifes
     expect(needsPreUpgradeBackup('safe', manifest(undefined))).toBe(false);
   });
 });
+
+// celilo#1363: fetchAndUpdate commits the new version to the store BEFORE the
+// deploy runs, so a failed deploy left a new version recorded beside a stale
+// VERIFIED state and a frozen updatedAt, and the audit read the module as
+// fine. Option A: the row must say what happened — state ERROR with the
+// error, and updatedAt moving whenever the version moves.
+describe('upgradeOneModule — a failed deploy records the failure in the row (celilo#1363)', () => {
+  const FROZEN = new Date('2026-04-25T16:26:31Z');
+  let tempDir: string;
+  let installedDir: string;
+  let db: DbClient;
+  let getIndexSpy: Mock<(name: string) => Promise<unknown[]>>;
+  let downloadSpy: Mock<(name: string, vers: string, cksum?: string) => Promise<ArrayBuffer>>;
+  let deploySpy: Mock<typeof moduleDeploy.deployModule>;
+
+  beforeEach(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-upgrade-'));
+    process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+    process.env.CELILO_ORIGINAL_CWD = tempDir;
+
+    installedDir = join(tempDir, 'installed', 'testmod');
+    mkdirSync(installedDir, { recursive: true });
+    writeFileSync(
+      join(installedDir, 'manifest.yml'),
+      'celilo_contract: "1.0"\nid: testmod\nname: Test Module\nversion: 1.0.0\ndescription: fixture\n',
+    );
+
+    db = getDb();
+    db.insert(modules)
+      .values({
+        id: 'testmod',
+        name: 'Test Module',
+        sourcePath: installedDir,
+        version: '1.0.0+5',
+        state: 'VERIFIED',
+        updatedAt: FROZEN,
+        manifestData: {
+          celilo_contract: '1.0',
+          id: 'testmod',
+          name: 'Test Module',
+          version: '1.0.0',
+        },
+      })
+      .run();
+
+    // Build the registry package for a patch bump (1.0.0+5 → 1.0.0+6).
+    // Patch/revision → fast posture, so no snapshot and no backup are needed
+    // on the path to the deploy.
+    const srcDir = join(tempDir, 'pkg-src');
+    mkdirSync(srcDir, { recursive: true });
+    writeFileSync(
+      join(srcDir, 'manifest.yml'),
+      'celilo_contract: "1.0"\nid: testmod\nname: Test Module\nversion: 1.0.0\ndescription: fixture v6\n',
+    );
+    const pkgPath = join(tempDir, 'testmod-1.0.0.netapp');
+    await tarCreate({ file: pkgPath, cwd: srcDir }, ['manifest.yml']);
+    const pkgBytes = new Uint8Array(await Bun.file(pkgPath).arrayBuffer());
+
+    getIndexSpy = spyOn(RegistryClient.prototype, 'getIndex').mockResolvedValue([
+      { name: 'testmod', vers: '1.0.0+6', deps: [], cksum: 'abc', yanked: false },
+    ]);
+    downloadSpy = spyOn(RegistryClient.prototype, 'download').mockResolvedValue(pkgBytes.buffer);
+    deploySpy = spyOn(moduleDeploy, 'deployModule').mockResolvedValue({
+      success: false,
+      error: 'ssh: connection refused',
+      phases: {},
+    });
+  });
+
+  afterEach(() => {
+    getIndexSpy.mockRestore();
+    downloadSpy.mockRestore();
+    deploySpy.mockRestore();
+    rmSync(tempDir, { recursive: true, force: true });
+    resetTestDbPath();
+    delete process.env.CELILO_ORIGINAL_CWD;
+  });
+
+  test('a deploy failure leaves state ERROR, the new version, and a moved updatedAt', async () => {
+    const mod = db.select().from(modules).where(eq(modules.id, 'testmod')).get();
+    if (!mod) throw new Error('seed row missing');
+
+    const result = await upgradeOneModule(mod, '1.0.0+6', new RegistryClient(''), db, {});
+
+    expect(result.success).toBe(false);
+    const row = db.select().from(modules).where(eq(modules.id, 'testmod')).get();
+    if (!row) throw new Error('row missing after upgrade');
+    expect(row.version).toBe('1.0.0+6');
+    expect(row.state).toBe<ModuleState>('ERROR');
+    expect(row.errorMessage).toContain('1.0.0+6');
+    expect(row.errorMessage).toContain('ssh: connection refused');
+    expect(row.updatedAt?.getTime()).toBeGreaterThan(FROZEN.getTime());
+  });
+});