@celilo/cli 2.1.0 → 2.2.1

package/src/services/restore-from-file.test.ts

@@ -23,6 +23,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 { applyStagedSystemFiles, restoreFromArtifactFile } from './restore-from-file';
 
 describe('applyStagedSystemFiles', () => {
@@ -44,7 +45,7 @@ describe('applyStagedSystemFiles', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_MASTER_KEY_PATH = undefined;
     process.env.CELILO_DATA_DIR = undefined;
     try {
@@ -86,6 +87,26 @@ describe('applyStagedSystemFiles', () => {
     expect(existsSync(`${livePath}-shm`)).toBe(false);
   });
 
+  // celilo#1293 live repro 2026-09-06: the restore process's own pre-swap
+  // connection can outlive closeDb() at the fd level (measured: bun:sqlite's
+  // close() returned while the fds stayed open), and an IN-PLACE copy
+  // overwrites the inode that connection holds locks on — the swapped-in DB
+  // then inherits locks it must not have, and the next opener's DELETE→WAL
+  // conversion fails with "database is locked". The swap must therefore
+  // replace the INODE (rename), so any lingering lock lands on the unlinked
+  // old inode and is irrelevant to the new file.
+  it('replaces the live DB inode, not just its content', () => {
+    writeFileSync(livePath, 'old-db');
+    writeFileSync(join(stagingDir, 'celilo.db'), 'new-db');
+    const inodeBefore = statSync(livePath).ino;
+
+    applyStagedSystemFiles(stagingDir);
+
+    expect(readFileSync(livePath, 'utf-8')).toBe('new-db');
+    expect(statSync(livePath).ino).not.toBe(inodeBefore);
+    expect(existsSync(`${livePath}.restore-swap`)).toBe(false);
+  });
+
   it('handles partial staging (only master.key, no DB)', () => {
     writeFileSync(join(stagingDir, 'master.key'), 'just-the-key');
     const result = applyStagedSystemFiles(stagingDir);
@@ -185,7 +206,7 @@ describe('restoreFromArtifactFile error paths', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_DATA_DIR = undefined;
     process.env.CELILO_MASTER_KEY_PATH = undefined;
     try {

package/src/services/restore-from-file.ts

@@ -17,7 +17,6 @@
  */
 
 import { Database } from 'bun:sqlite';
-import { execSync } from 'node:child_process';
 import {
   chmodSync,
   closeSync,
@@ -29,20 +28,22 @@ import {
   readFileSync,
   readSync,
   readdirSync,
+  renameSync,
   rmSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
+import { extract as tarExtract } from 'tar';
 import { getDbPath, getMasterKeyPath, getModuleStoragePath } from '../config/paths';
 import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { modules } from '../db/schema';
 import { invokeHook } from '../hooks/executor';
+import { createHookStores } from '../hooks/hook-store';
 import { createConsoleLogger } from '../hooks/logger';
 import type { ModuleManifest } from '../manifest/schema';
 import { getOrCreateMasterKey } from '../secrets/master-key';
-import { shellEscape } from '../utils/shell';
 import { decryptFileToFile } from './backup-cipher';
 import { assertCompatibleSchema, parseManifest } from './backup-manifest';
 import { applyCrossModuleWriteRoot, moduleHasCrossModuleRead } from './cross-module-read';
@@ -128,7 +129,7 @@ export async function restoreFromArtifactFile(
     }
 
     // Extract the envelope tar.
-    execSync(`tar -xf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)}`);
+    await tarExtract({ file: tarPath, cwd: envelopeDir });
 
     // 2. Read + validate the envelope manifest.
     const manifestPath = join(envelopeDir, 'manifest.json');
@@ -221,6 +222,7 @@ export async function restoreFromArtifactFile(
         debug: false,
         systems: getModuleSystems(mod.id, db),
         remoteAccess: remoteAccessPolicy(mod.id, db),
+        hookStores: () => createHookStores(db, mod.id),
       },
     );
     if (!hookResult.success) {
@@ -428,9 +430,22 @@ export function applyStagedSystemFiles(systemStagingDir: string): StagedSystemAp
     closeDb();
     const livePath = getDbPath();
     mkdirSync(join(livePath, '..'), { recursive: true });
-    copyFileSync(stagedDb, livePath);
-
-    // Stale WAL/SHM siblings would corrupt the restored DB.
+    // Swap by RENAME, not by in-place copy. copyFileSync overwrites the live
+    // inode in place, so any connection whose fd close was deferred (measured
+    // 2026-09-06, celilo#1293 live repro: bun:sqlite's close() returns before
+    // the fds are released) keeps its WAL shared locks on the NEW content, and
+    // the next opener's DELETE→WAL conversion in ensureWalMode then fails with
+    // "database is locked" for its whole retry budget. A rename gives the new
+    // file a fresh inode nobody has ever held. It also makes the swap atomic:
+    // a crash mid-copy left a truncated live DB; a crash mid-rename leaves the
+    // old one.
+    const stagedSwapPath = `${livePath}.restore-swap`;
+    copyFileSync(stagedDb, stagedSwapPath);
+    renameSync(stagedSwapPath, livePath);
+
+    // Stale WAL/SHM siblings belong to the replaced inode — remove them before
+    // any new connection opens this path, or SQLite would try to recover
+    // through a foreign WAL.
     for (const suffix of ['-wal', '-shm']) {
       try {
         rmSync(`${livePath}${suffix}`, { force: true });

package/src/services/restore-preflight.test.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { modules } from '../db/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   NonEmptyRestoreTargetError,
   assertRestoreTargetEmpty,
@@ -23,7 +24,7 @@ describe('restore pre-flight', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_DATA_DIR = undefined;
     try {
       rmSync(dir, { recursive: true, force: true });

package/src/services/secret-schema-loader.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { type DbClient, getDb } from '../db/client';
 import { modules } from '../db/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   type SecretsSchema,
   getAllSecretMetadata,
@@ -40,7 +41,7 @@ describe('secret-schema-loader', () => {
   afterEach(() => {
     // Clean up temp directory
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
   });
 
   describe('loadSecretsSchema', () => {

package/src/services/ssh-key-manager.test.ts

@@ -8,6 +8,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 { addMachine } from './machine-pool';
 import {
   LOCAL_MACHINE_IP,
@@ -97,7 +98,7 @@ describe('ssh-key-manager', () => {
     }
 
     // Clear environment variables
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_DATA_DIR = undefined;
     process.env.CELILO_MASTER_KEY_PATH = undefined;
   });

package/src/services/static-content-converge.test.ts

@@ -1,12 +1,22 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { moduleConfigs, modules, webRoutes } from '../db/schema';
 import { setupTestDatabaseAt } from '../test-utils/database';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
+  ansibleTreeMentions,
   buildStaticContentPlan,
   planStaticContent,
   resolveStaticContentRetention,
@@ -55,7 +65,7 @@ describe('planStaticContent — the declared release set (D10 task 4.1)', () =>
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {
@@ -168,7 +178,7 @@ describe('resolveStaticContentRetention — operator config with a default', ()
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {
@@ -246,6 +256,82 @@ describe('staticContentVarsYaml — deterministic desired state', () => {
   });
 });
 
+describe('the state web overlay (celilo#1265)', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'static-converge-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabaseAt(dbPath);
+    writeSite('lunacycle', '<html>luna</html>');
+    db.insert(modules)
+      .values({
+        id: 'lunacycle',
+        name: 'Lunacycle',
+        version: '1.0.0',
+        manifestData: {},
+        sourcePath: join(dir, 'modules', 'lunacycle'),
+      })
+      .onConflictDoNothing()
+      .run();
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    resetTestDbPath();
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function writeSite(moduleId: string, html: string): string {
+    const webRoot = join(dir, 'modules', moduleId, 'site', 'dist');
+    mkdirSync(webRoot, { recursive: true });
+    writeFileSync(join(webRoot, 'index.html'), html, 'utf-8');
+    return webRoot;
+  }
+
+  function insertRoute(route: { slug: string; moduleId: string; hostname: string }) {
+    db.insert(webRoutes)
+      .values({
+        slug: route.slug,
+        moduleId: route.moduleId,
+        type: 'static',
+        path: '/',
+        hostname: route.hostname,
+        websocket: false,
+        contentHash: HASH1,
+      })
+      .run();
+  }
+
+  it('a release with a state overlay carries its directory; one without does not', () => {
+    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
+
+    // No overlay in state: the release names no overlay_dir, and the converge
+    // role has nothing second to copy.
+    const bare = planStaticContent(db);
+    expect(bare).toHaveLength(1);
+    expect(bare[0]?.overlayDir).toBeUndefined();
+    expect(staticContentVarsYaml({ retention: 1, releases: bare })).not.toContain('overlay_dir');
+
+    // The hook wrote generated files into `<module>/state/site`: the converge
+    // must copy them over the release, or a rebuilt host loses the file.
+    const overlay = join(dir, 'modules', 'lunacycle', 'state', 'site');
+    mkdirSync(overlay, { recursive: true });
+    writeFileSync(join(overlay, 'ca.crt'), '---CERT---', 'utf-8');
+
+    const overlaid = planStaticContent(db);
+    expect(overlaid[0]?.overlayDir).toBe(overlay);
+    const yaml = staticContentVarsYaml({ retention: 1, releases: overlaid });
+    expect(yaml).toContain('overlay_dir:');
+  });
+});
+
 describe('writeStaticContentVars — lands in the generated inventory', () => {
   let dir: string;
   let db: DbClient;
@@ -274,7 +360,7 @@ describe('writeStaticContentVars — lands in the generated inventory', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {
@@ -336,3 +422,56 @@ describe('writeStaticContentVars — lands in the generated inventory', () => {
     expect(plan.releases).toHaveLength(1);
   });
 });
+
+describe('the stale-project guard reaches the whole generated tree (celilo#1248)', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'static-guard-reach-'));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('sees a converge that lives in a role task file, not in playbook.yml', () => {
+    // Mirror DERIVED from the real module, never hand-written: a hand-built
+    // tree would give confident reach data about a world that does not exist,
+    // which is the same bug one level up.
+    const real = resolve(import.meta.dir, '../../../..', 'modules/caddy/ansible');
+    cpSync(real, join(dir, 'ansible'), { recursive: true });
+
+    // The premise this guards. caddy's playbook is a thin hosts/vars/roles
+    // stanza; if it ever DOES name static_releases, this test stops proving
+    // anything and should be re-derived rather than deleted.
+    const playbook = readFileSync(join(dir, 'ansible/playbook.yml.tpl'), 'utf-8');
+    expect(playbook).not.toContain('static_releases');
+
+    expect(ansibleTreeMentions(join(dir, 'ansible'), 'static_releases')).toBe(true);
+  });
+
+  it('still refuses a project that mentions the var nowhere', () => {
+    // A pre-converge generated project. Hand-built deliberately, and it has to
+    // be: no deploy on today's code can produce a tree without the role tasks,
+    // so this legacy shape is the fixture and not a shortcut.
+    mkdirSync(join(dir, 'ansible/roles/caddy/tasks'), { recursive: true });
+    writeFileSync(
+      join(dir, 'ansible/playbook.yml'),
+      '---\n- hosts: caddy\n  roles:\n    - caddy\n',
+    );
+    writeFileSync(
+      join(dir, 'ansible/roles/caddy/tasks/main.yml'),
+      '---\n- name: install\n  debug: {}\n',
+    );
+
+    expect(ansibleTreeMentions(join(dir, 'ansible'), 'static_releases')).toBe(false);
+  });
+
+  it('ignores non-text files rather than reading assets as utf-8', () => {
+    mkdirSync(join(dir, 'ansible/files'), { recursive: true });
+    writeFileSync(join(dir, 'ansible/files/logo.png'), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+    writeFileSync(join(dir, 'ansible/site.yml'), 'vars:\n  static_releases: []\n');
+
+    expect(ansibleTreeMentions(join(dir, 'ansible'), 'static_releases')).toBe(true);
+    expect(ansibleTreeMentions(join(dir, 'ansible'), 'PNG')).toBe(false);
+  });
+});

package/src/services/static-content-converge.ts

@@ -23,14 +23,14 @@
  * `module verify` (celilo#1018, deliberately left to that thread).
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { and, eq, isNotNull } from 'drizzle-orm';
 import { stringify as stringifyYaml } from 'yaml';
 import type { DbClient } from '../db/client';
 import { moduleConfigs, modules, webRoutes } from '../db/schema';
-import { resolveModuleWebRoot } from '../module/web-root';
+import { resolveModuleStateWebRoot, resolveModuleWebRoot } from '../module/web-root';
 import { parseStoredConfigValue } from './module-config';
 
 /** One content-hashed release the provider host must serve. */
@@ -43,6 +43,13 @@ export interface StaticRelease {
   hostnames: string[];
   /** Absolute celilo-mgr path core derived: `<module source_path>/site/dist`. */
   sourceDir: string;
+  /**
+   * Absolute path to `<module source_path>/state/site` (celilo#1265), present
+   * ONLY when that directory exists. The role copies it over the release
+   * after the web root, so a hook-generated file wins over a built one. A
+   * module with no generated site content has no overlay and no row.
+   */
+  overlayDir?: string;
 }
 
 export interface StaticContentPlan {
@@ -172,11 +179,17 @@ export function planStaticContent(db: DbClient): StaticRelease[] {
       );
     }
 
+    // Present only when the module's hook actually wrote an overlay —
+    // otherwise the vars file would name a directory that does not exist
+    // and the role's copy task would have nothing to copy from.
+    const stateWebRoot = resolveModuleStateWebRoot(moduleId, db);
+    const overlayDir = stateWebRoot && existsSync(stateWebRoot) ? stateWebRoot : undefined;
     releases.push({
       slug,
       contentHash,
       hostnames: [...new Set(group.map((r) => r.hostname))].sort(),
       sourceDir,
+      ...(overlayDir ? { overlayDir } : {}),
     });
   }
 
@@ -208,6 +221,9 @@ export function staticContentVarsYaml(plan: StaticContentPlan): string {
       content_hash: r.contentHash,
       hostnames: r.hostnames,
       source_dir: r.sourceDir,
+      // Absent when there is no overlay, so the role's `when:` guard reads a
+      // clean variable — not an empty string a copy task would choke on.
+      ...(r.overlayDir ? { overlay_dir: r.overlayDir } : {}),
     })),
   };
   const header =
@@ -221,9 +237,10 @@ export function staticContentVarsYaml(plan: StaticContentPlan): string {
  *
  * The shared half of both converge triggers: the capability's callback adds
  * `executeAnsible` after this, and the provider's own deploy already runs it.
- * Writing happens AFTER the deploy's staleness check (`refuseIfGeneratedIsStale`
- * only inspects verbatim role assets), so an injected vars file never reads as
- * a stale generation.
+ * Nothing inspects verbatim role assets any more — the staleness pre-flight
+ * retired with the ephemeral generated tree (D5 of
+ * control-plane-stops-building-modules), so an injected vars file cannot read
+ * as a stale generation because nothing reads staleness.
  */
 export async function writeStaticContentVars(
   db: DbClient,
@@ -249,6 +266,40 @@ export async function writeStaticContentVars(
  * never happen, so the playbook is checked for the converge's own variable
  * first and a stale project fails loudly with the redeploy that fixes it.
  */
+/**
+ * Whether any text file in a generated Ansible tree mentions `needle`.
+ *
+ * Scans the TREE rather than `playbook.yml`, because a provider's converge
+ * belongs in one of its role's task files and a generated `playbook.yml` is a
+ * thin hosts/vars/roles stanza that names no variable at all. caddy is the
+ * worked example: `static_releases` appears in
+ * `roles/caddy/tasks/static-content.yml`, `.../main.yml.tpl` and
+ * `.../converge-release.yml`, and zero times in its playbook.
+ *
+ * @psbanka - 2026-09: this used to read `ansible/playbook.yml` alone, which
+ * could not reach the string it was looking for. The guard below therefore
+ * refused EVERY provider that had the converge support, and its remedy told the
+ * operator to redeploy — which regenerates the same thin playbook and cannot
+ * help. Guard and role tasks landed in the same commit (1fd3595e), so it had
+ * never once passed, and it held three e2e suites red where nobody was looking.
+ * celilo#1248.
+ */
+export function ansibleTreeMentions(dir: string, needle: string): boolean {
+  if (!existsSync(dir)) return false;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (ansibleTreeMentions(full, needle)) return true;
+      continue;
+    }
+    // Text only. A generated tree can carry static assets, and reading those
+    // as utf-8 to look for a variable name is waste at best.
+    if (!/\.(ya?ml|j2|tpl|cfg|ini|conf)$/.test(entry.name)) continue;
+    if (readFileSync(full, 'utf-8').includes(needle)) return true;
+  }
+  return false;
+}
+
 export async function convergeStaticContent(
   db: DbClient,
   providerModuleId: string,
@@ -258,25 +309,40 @@ export async function convergeStaticContent(
     return { success: false, error: `Provider module '${providerModuleId}' is not installed` };
   }
   const generatedPath = join(module.sourcePath, 'generated');
+  // D4 (control-plane-stops-building-modules): the generated project is
+  // ephemeral, so a successful provider deploy deletes it and nothing is
+  // persisted for this converge to read. Render it here, on demand, from the
+  // signed payload plus resolved config — generation is fast and local. A
+  // render failure fails loudly with the deploy-once remedy, same as the old
+  // missing-project refusal did; a tree that predates the converge support is
+  // still refused by the static_releases check below.
   if (!existsSync(generatedPath)) {
-    return {
-      success: false,
-      error:
-        `public_web provider '${providerModuleId}' has no generated deploy project at ${generatedPath}. ` +
-        `Run \`celilo module deploy ${providerModuleId}\` once, then retry the publish.`,
-    };
+    const { generateTemplates } = await import('../templates/generator');
+    const rendered = await generateTemplates({
+      moduleId: providerModuleId,
+      modulePath: module.sourcePath,
+      outputPath: generatedPath,
+      db,
+      skipVariableValidation: false,
+    });
+    if (!rendered.success) {
+      return {
+        success: false,
+        error:
+          `public_web provider '${providerModuleId}' has no generated deploy project at ${generatedPath} ` +
+          `and rendering one failed: ${rendered.error ?? 'unknown error'}. ` +
+          `Run \`celilo module deploy ${providerModuleId}\` once, then retry the publish.`,
+      };
+    }
   }
 
   const written = await writeStaticContentVars(db, providerModuleId, generatedPath);
 
   // A generated project that predates the converge role tasks would read the
   // new vars file and converge nothing. `static_releases` appearing nowhere in
-  // the playbook is the tell. Generic string check — core names no module.
-  const playbookPath = join(generatedPath, 'ansible', 'playbook.yml');
-  if (
-    existsSync(playbookPath) &&
-    !readFileSync(playbookPath, 'utf-8').includes('static_releases')
-  ) {
+  // the project is the tell. Generic string check — core names no module.
+  const ansiblePath = join(generatedPath, 'ansible');
+  if (existsSync(ansiblePath) && !ansibleTreeMentions(ansiblePath, 'static_releases')) {
     return {
       success: false,
       error: `The generated project for '${providerModuleId}' predates the static-content converge (its playbook never reads static_releases). Redeploy the provider (\`celilo module deploy ${providerModuleId}\`) to regenerate it, then retry the publish.`,
@@ -295,5 +361,9 @@ export async function convergeStaticContent(
       varsPath: written.varsPath,
     };
   }
+  // D4: the converge rendered the tree, used it, and is done with it. The same
+  // no-secrets-at-rest rule the deploy follows applies here; on the failure
+  // paths above the tree stays for inspection.
+  rmSync(generatedPath, { recursive: true, force: true });
   return { success: true, varsPath: written.varsPath };
 }

package/src/services/system-config-schema-types.ts

@@ -14,7 +14,7 @@ export interface SystemConfigProperty {
   maximum?: number;
   default?: string | number | boolean;
   description?: string;
-  format?: 'email';
+  format?: 'email' | 'cidr-list';
 }
 
 /**

package/src/services/system-config-validator.test.ts

@@ -119,6 +119,42 @@ describe('validateValue', () => {
       expect(result.valid).toBe(false);
     });
   });
+
+  describe('cidr-list format validation', () => {
+    const property: SystemConfigProperty = {
+      type: 'string',
+      format: 'cidr-list',
+      description: 'Trusted source subnets',
+    };
+
+    it('accepts both stored forms: comma-separated CIDRs and a JSON array', () => {
+      expect(validateValue('firewall.trusted_subnets', '10.0.0.0/24', property).valid).toBe(true);
+      expect(
+        validateValue('firewall.trusted_subnets', '10.0.0.0/24, 10.1.0.0/24', property).valid,
+      ).toBe(true);
+      expect(validateValue('firewall.trusted_subnets', '["10.226.120.0/24"]', property).valid).toBe(
+        true,
+      );
+    });
+
+    it('rejects a token that is not a CIDR, naming it, at write time', () => {
+      const result = validateValue(
+        'firewall.trusted_subnets',
+        '["10.226.120.0/24", oops]',
+        property,
+      );
+      expect(result.valid).toBe(false);
+      if (result.valid) return;
+      expect(result.error).toContain('looks like JSON but does not parse');
+    });
+
+    it('rejects a JSON-looking value outright rather than mangling it into a subnet name', () => {
+      const result = validateValue('firewall.trusted_subnets', 'nonsense', property);
+      expect(result.valid).toBe(false);
+      if (result.valid) return;
+      expect(result.error).toContain('nonsense');
+    });
+  });
 });
 
 describe('validateKey', () => {

package/src/services/system-config-validator.ts

@@ -5,6 +5,7 @@
  */
 
 import type { SystemConfigProperty, SystemConfigSchema } from './system-config-schema-types';
+import { parseOperatorTrustedSubnets } from './trusted-sources';
 
 /**
  * Validation result (discriminated union)
@@ -55,6 +56,16 @@ export function validateValue(
     }
   }
 
+  // CIDR lists validate through the key's own parser, so the write-time check
+  // and the converge-time read can never disagree about what is valid.
+  if (property.format === 'cidr-list') {
+    try {
+      parseOperatorTrustedSubnets(value);
+    } catch (e) {
+      return { valid: false, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
   return { valid: true };
 }
 

package/src/services/system-state-stage.test.ts

@@ -13,6 +13,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { snapshotDatabase, stageSystemState } from './system-state-stage';
 
 describe('stageSystemState', () => {
@@ -38,7 +39,7 @@ describe('stageSystemState', () => {
 
   afterEach(() => {
     process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_MASTER_KEY_PATH = undefined;
     rmSync(dataDir, { recursive: true, force: true });
   });