@celilo/cli 2.1.0 → 2.2.0

package/src/services/module-validator/git-hygiene.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
+import { classifyModulePath } from '../../module/packaging/package-rules';
 import { collectGitInfo, makeRealGitRunner } from '../../module/packaging/release-metadata';
 import type { Check } from './types';
 
@@ -19,10 +20,14 @@ export interface StalenessIssue {
  * anywhere should still talk to lunacycle's git history).
  */
 function lastCommitTouching(cwd: string, pathspec: string[]): string | null {
+  // timeout: a hung git degrades to the "can't determine — skip" path (status
+  // null) instead of hanging `module check` forever. 30s is enormous against
+  // the milliseconds a bounded `git log -1` takes on any real repo.
   const r = spawnSync('git', ['log', '-1', '--format=%H', '--', ...pathspec], {
     cwd,
     stdio: ['ignore', 'pipe', 'ignore'],
     encoding: 'utf-8',
+    timeout: 30_000,
   });
   if (r.status !== 0) return null;
   const sha = r.stdout.trim();
@@ -33,17 +38,90 @@ function isAncestor(cwd: string, maybeAncestor: string, descendant: string): boo
   const r = spawnSync('git', ['merge-base', '--is-ancestor', maybeAncestor, descendant], {
     cwd,
     stdio: 'ignore',
+    timeout: 30_000,
   });
   return r.status === 0;
 }
 
+/**
+ * One commit from `git log --name-only`: its SHA and the repo-root-relative
+ * paths it changed. A merge commit carries an empty file list (git log omits
+ * diffs for merges), so it never qualifies as a src commit — which is right,
+ * a merge changes no authored byte of its own.
+ */
+interface CommitWithPaths {
+  sha: string;
+  paths: string[];
+}
+
+/**
+ * The commits touching `pathspec`, newest first, with the repo-root-relative
+ * paths each one changed. `git log --name-only` prints repo-root-relative
+ * paths even when cwd is a subdirectory (measured: it does not honor cwd for
+ * output), so the caller strips the prefix itself via `show-prefix`.
+ */
+function listCommitsTouching(cwd: string, pathspec: string): CommitWithPaths[] {
+  const r = spawnSync(
+    'git',
+    ['-c', 'core.quotePath=false', 'log', '--format=%H', '--name-only', '--', pathspec],
+    { cwd, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' },
+  );
+  if (r.status !== 0) return [];
+  const commits: CommitWithPaths[] = [];
+  let current: CommitWithPaths | null = null;
+  for (const line of (r.stdout ?? '').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (/^[0-9a-f]{40}$/.test(trimmed)) {
+      current = { sha: trimmed, paths: [] };
+      commits.push(current);
+    } else if (current) {
+      current.paths.push(trimmed);
+    }
+  }
+  return commits;
+}
+
+/**
+ * SHA of the last commit that touched SHIPPED module source, or null when no
+ * commit qualifies (no history, or only non-shipped paths ever committed).
+ *
+ * The staleness scan's reach is the PACKAGER's rule, not a second list beside
+ * it (celilo#1270). A path counts as source exactly when `classifyModulePath`
+ * calls it `package` — the same answer that decides whether the path lands in
+ * the .netapp. So a commit touching only `e2e/**`, `*.test.ts`, or
+ * `tsconfig.json` changes no installed byte and must not read as drift.
+ *
+ * Excluding manifest.yml from the "src" scan is the gate's own semantics, not
+ * packaging: we want to know if anything else shipped past it. node_modules,
+ * dist, and other build outputs are gitignored and so never appear here.
+ */
+function lastShippedSourceCommit(moduleDir: string): string | null {
+  const prefixR = spawnSync('git', ['rev-parse', '--show-prefix'], {
+    cwd: moduleDir,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    encoding: 'utf-8',
+  });
+  if (prefixR.status !== 0) return null;
+  const repoPrefix = (prefixR.stdout ?? '').trim();
+  for (const commit of listCommitsTouching(moduleDir, moduleDir)) {
+    for (const p of commit.paths) {
+      if (repoPrefix && !p.startsWith(repoPrefix)) continue;
+      const rel = repoPrefix ? p.slice(repoPrefix.length) : p;
+      if (rel === 'manifest.yml') continue;
+      if (classifyModulePath(rel) === 'package') return commit.sha;
+    }
+  }
+  return null;
+}
+
 /**
  * Detect "I edited module src but forgot to bump (or touch) manifest.yml."
  *
- * Returns null when the manifest is the most recently-touched file in the
- * dir (or when neither side has any commit history — e.g. brand-new module
- * not yet committed). Returns a StalenessIssue when src has commits AFTER
- * the last manifest.yml change — the operator must bump the manifest
+ * Returns null when the manifest is the most recently-touched shipped file in
+ * the dir (or when neither side has any commit history — e.g. brand-new module
+ * not yet committed). Returns a StalenessIssue when shipped src has commits
+ * AFTER the last manifest.yml change — the operator must bump the manifest
  * (semver change → reset +N to 1) or just touch it (release-only change →
  * auto-bump +N), then re-publish.
  *
@@ -54,16 +132,7 @@ function isAncestor(cwd: string, maybeAncestor: string, descendant: string): boo
 export function checkModuleStale(moduleDir: string): StalenessIssue | null {
   const manifestPath = join(moduleDir, 'manifest.yml');
   const lastManifest = lastCommitTouching(moduleDir, [manifestPath]);
-  // Excluding manifest.yml from the "src" pathspec is the whole point — we
-  // want to know if anything ELSE in the dir moved past it. node_modules
-  // and common build outputs are gitignored already, but be explicit
-  // defensively.
-  const lastSrc = lastCommitTouching(moduleDir, [
-    moduleDir,
-    `:(exclude)${manifestPath}`,
-    `:(exclude)${moduleDir}/node_modules`,
-    `:(exclude)${moduleDir}/dist`,
-  ]);
+  const lastSrc = lastShippedSourceCommit(moduleDir);
   if (!lastManifest || !lastSrc) return null;
   if (lastSrc === lastManifest) return null;
   if (!isAncestor(moduleDir, lastManifest, lastSrc)) return null;

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

@@ -86,6 +86,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);

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/static-content-converge.test.ts

@@ -1,12 +1,21 @@
 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 {
+  ansibleTreeMentions,
   buildStaticContentPlan,
   planStaticContent,
   resolveStaticContentRetention,
@@ -246,6 +255,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();
+    process.env.CELILO_DB_PATH = undefined;
+    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;
@@ -336,3 +421,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 } 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 =
@@ -249,6 +265,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,
@@ -271,12 +321,9 @@ export async function convergeStaticContent(
 
   // 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.`,

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/trusted-sources.test.ts

@@ -256,5 +256,35 @@ describe('parsing the operator override', () => {
   it('an unset key contributes nothing', () => {
     expect(parseOperatorTrustedSubnets(undefined)).toEqual([]);
     expect(parseOperatorTrustedSubnets('')).toEqual([]);
+    expect(parseOperatorTrustedSubnets('   ')).toEqual([]);
+  });
+
+  it('parses the JSON-array form every sibling config key uses', () => {
+    expect(parseOperatorTrustedSubnets('["10.226.120.0/24"]')).toEqual(['10.226.120.0/24']);
+    expect(parseOperatorTrustedSubnets('[ "10.1.0.0/24" , "10.2.0.0/24" ]')).toEqual([
+      '10.1.0.0/24',
+      '10.2.0.0/24',
+    ]);
+  });
+
+  it('refuses a JSON-looking value that does not parse to an array of strings', () => {
+    // The exact e2e failure (ce-yaqa): a JSON array read as ONE subnet named
+    // ["10.226.120.0/24"], rendered verbatim into rules.v4, and
+    // iptables-restore failed the converge with "Bad argument `]'".
+    expect(() => parseOperatorTrustedSubnets('{"a":1}')).toThrow(/JSON array of CIDR strings/);
+    expect(() => parseOperatorTrustedSubnets('["10.0.0.0/24", 5]')).toThrow(
+      /JSON array of CIDR strings/,
+    );
+    expect(() => parseOperatorTrustedSubnets('[10.0.0.0/24')).toThrow(
+      /looks like JSON but does not parse/,
+    );
+  });
+
+  it('refuses a token that is not an IPv4 CIDR, naming it', () => {
+    expect(() => parseOperatorTrustedSubnets('10.0.0.1')).toThrow(/10\.0\.0\.1/);
+    expect(() => parseOperatorTrustedSubnets('10.0.0.1')).toThrow(/not an IPv4 CIDR/);
+    expect(() => parseOperatorTrustedSubnets('10.0.0.0/24, hostname.local')).toThrow(
+      /hostname\.local/,
+    );
   });
 });