shieldcortex 4.31.2 → 4.32.0

package/dist/cloud/config.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, statSync, renameSync, rmSync } from 'fs';
 import { join } from 'path';
 import { homedir, hostname } from 'os';
 import { randomUUID, randomBytes, createHmac, timingSafeEqual } from 'crypto';
@@ -42,6 +42,15 @@ const DEFAULT_REVIEW_COPILOT_CONFIG = {
 // Cache to avoid repeated file reads
 let cachedConfig = null;
 let cachedConfigFile = null;
+// Raw-config cache keyed on (file path, mtimeMs). The defence pipeline reads
+// the config on every scan via getDefenceMode() and ~30 other accessors all
+// funnel through readRawConfig(); without this each call re-read + re-parsed +
+// re-HMAC-verified the file. The mtime key means an external write (any other
+// process) is picked up on its next stat, while a hot loop in one process pays
+// for the read+parse+verify exactly once per actual file change.
+let cachedRawConfig = null;
+let cachedRawConfigFile = null;
+let cachedRawConfigMtimeMs = null;
 // ── Config Integrity (HMAC) ──────────────────────────────
 let cachedIntegrityKey = null;
 let cachedIntegrityKeyFile = null;
@@ -74,6 +83,25 @@ function getIntegrityKey() {
 function signConfig(jsonContent) {
     return createHmac('sha256', getIntegrityKey()).update(jsonContent, 'utf-8').digest('hex');
 }
+/**
+ * The exact byte string the HMAC is computed over for the embedded-`_sig`
+ * scheme. Defined once and used by BOTH the write path and the verify path so
+ * they can never diverge: the canonical body is the config object with `_sig`
+ * stripped, serialised with `JSON.stringify(rest, null, 2)`. Whatever the
+ * writer signs, the verifier recomputes over the identical bytes.
+ */
+function canonicalBodyForSig(obj) {
+    const rest = { ...obj };
+    delete rest._sig;
+    return JSON.stringify(rest, null, 2);
+}
+function constantTimeEqualHex(storedSig, computedSig) {
+    const a = Buffer.from(storedSig, 'utf-8');
+    const b = Buffer.from(computedSig, 'utf-8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
 function writeConfigSignature(jsonContent) {
     const sig = signConfig(jsonContent);
     const sigFile = getSigFile();
@@ -83,21 +111,41 @@ function writeConfigSignature(jsonContent) {
     }
     catch { /* best-effort */ }
 }
-function verifyConfigIntegrity(jsonContent) {
+/**
+ * Verify a parsed config object's integrity.
+ *
+ * Two on-disk formats are supported for backward compatibility:
+ *   - **Embedded (new, v4.32+):** the object carries a top-level `_sig` field;
+ *     verify it against the HMAC of `canonicalBodyForSig(obj)`.
+ *   - **Legacy (pre-v4.32):** no `_sig` field — the signature lives in a
+ *     separate `.config-sig` file, computed over the EXACT file bytes
+ *     (`rawFileContent`). This is the original scheme; we keep reading it so an
+ *     install that hasn't been rewritten yet never false-tampers. The next
+ *     write upgrades it to the embedded format.
+ *
+ * `rawFileContent` is the literal bytes read from disk (needed for the legacy
+ * whole-file signature). On a missing legacy sig file we adopt the current
+ * content as trusted (first run after upgrade), matching prior behaviour.
+ */
+function verifyConfigIntegrity(parsed, rawFileContent) {
     try {
+        if (typeof parsed._sig === 'string') {
+            // Embedded scheme: recompute over the canonical body (object minus _sig).
+            const computed = signConfig(canonicalBodyForSig(parsed));
+            return constantTimeEqualHex(parsed._sig, computed);
+        }
+        // Legacy scheme: separate .config-sig file signed over the whole file.
         const sigFile = getSigFile();
         if (!existsSync(sigFile)) {
-            // First run after upgrade — create signature, don't flag tamper
-            writeConfigSignature(jsonContent);
+            // First run after upgrade with no sig yet — adopt as trusted, write a
+            // legacy sig so a subsequent read (before the next write upgrades it)
+            // still verifies. Matches the prior behaviour to avoid a false tamper.
+            writeConfigSignature(rawFileContent);
             return true;
         }
         const storedSig = readFileSync(sigFile, 'utf-8').trim();
-        const computedSig = signConfig(jsonContent);
-        const a = Buffer.from(storedSig, 'utf-8');
-        const b = Buffer.from(computedSig, 'utf-8');
-        if (a.length !== b.length)
-            return false;
-        return timingSafeEqual(a, b);
+        const computedSig = signConfig(rawFileContent);
+        return constantTimeEqualHex(storedSig, computedSig);
     }
     catch {
         return false;
@@ -111,55 +159,42 @@ export function getCloudConfig() {
     const configFile = getConfigFile();
     if (cachedConfig && cachedConfigFile === configFile)
         return cachedConfig;
-    try {
-        if (!existsSync(configFile)) {
-            return { cloudApiKey: null, cloudBaseUrl: DEFAULT_BASE_URL, cloudEnabled: false };
-        }
-        const raw = JSON.parse(readFileSync(configFile, 'utf-8'));
-        cachedConfig = {
-            cloudApiKey: raw.cloudApiKey ?? null,
-            cloudBaseUrl: raw.cloudBaseUrl ?? DEFAULT_BASE_URL,
-            cloudEnabled: raw.cloudEnabled ?? false,
-        };
-        cachedConfigFile = configFile;
-        return cachedConfig;
-    }
-    catch {
-        return { cloudApiKey: null, cloudBaseUrl: DEFAULT_BASE_URL, cloudEnabled: false };
-    }
+    // Route through the shared, mtime-cached, integrity-verified read so the
+    // cloud config reflects the same view (and `_sig` stripping) as every other
+    // accessor — no second bespoke parse path that could drift.
+    const raw = readRawConfig();
+    cachedConfig = {
+        cloudApiKey: raw.cloudApiKey ?? null,
+        cloudBaseUrl: raw.cloudBaseUrl ?? DEFAULT_BASE_URL,
+        cloudEnabled: raw.cloudEnabled ?? false,
+    };
+    cachedConfigFile = configFile;
+    return cachedConfig;
 }
 export function setCloudConfig(updates) {
-    let existing = {};
-    try {
-        const configFile = getConfigFile();
-        if (existsSync(configFile)) {
-            existing = JSON.parse(readFileSync(configFile, 'utf-8'));
-        }
-    }
-    catch {
-        // Start fresh if parse fails
-    }
-    if (updates.cloudApiKey !== undefined)
-        existing.cloudApiKey = updates.cloudApiKey;
-    if (updates.cloudBaseUrl !== undefined)
-        existing.cloudBaseUrl = updates.cloudBaseUrl;
-    if (updates.cloudEnabled !== undefined)
-        existing.cloudEnabled = updates.cloudEnabled;
-    const configDir = getConfigDir();
-    const configFile = getConfigFile();
-    mkdirSync(configDir, { recursive: true });
-    const content = JSON.stringify(existing, null, 2) + '\n';
-    writeFileSync(configFile, content);
-    writeConfigSignature(content);
-    // Invalidate cache
+    // Read-modify-write through mutateRawConfig: preserves every other field
+    // (defenceMode, deviceId, sync controls…) and writes atomically with the
+    // embedded `_sig`. On a corrupt/unreadable file we do NOT silently start
+    // fresh — that would wipe a credential the user is still relying on; the
+    // helper throws so the caller surfaces the problem rather than losing data.
+    mutateRawConfig((existing) => {
+        if (updates.cloudApiKey !== undefined)
+            existing.cloudApiKey = updates.cloudApiKey;
+        if (updates.cloudBaseUrl !== undefined)
+            existing.cloudBaseUrl = updates.cloudBaseUrl;
+        if (updates.cloudEnabled !== undefined)
+            existing.cloudEnabled = updates.cloudEnabled;
+    });
+    // Invalidate the derived cloud-config cache (writeRawConfig already cleared
+    // the raw cache and tamper flag).
     cachedConfig = null;
     cachedConfigFile = null;
-    configTampered = false;
 }
 /** Reset the in-memory cache (useful for testing) */
 export function clearCloudConfigCache() {
     cachedConfig = null;
     cachedConfigFile = null;
+    invalidateRawConfigCache();
 }
 function normalizeProjectList(value) {
     if (!Array.isArray(value))
@@ -170,19 +205,31 @@ function normalizeProjectList(value) {
             .filter(Boolean))].sort((a, b) => a.localeCompare(b));
 }
 export function getCloudSyncControls() {
-    const raw = readRawConfig();
+    // This is a READER. On a parse failure we must return the in-memory defaults
+    // and NOT write — readRawConfigState preserves `parseFailed` so the one-shot
+    // migration below never runs against a `{}` derived from a corrupt file
+    // (which would persist a near-empty, signed config and wipe cloudApiKey).
+    const { data: raw, parseFailed } = readRawConfigState();
     // One-shot v4.27 migration: pre-upgrade configs with cloud sync enabled
     // were silently shipping CONFIDENTIAL+ content because `excludeSensitive`
     // defaulted to false. Detect those configs (cloud on, no explicit setting,
     // no prior migration stamp) and rewrite them to the new safe default. If
     // the user later opts back in via `--cloud-include-sensitive`, that writes
     // `cloudSyncExcludeSensitive: false` explicitly and this branch is skipped.
-    if (raw.cloudEnabled === true &&
+    // Skip entirely on parseFailed: never write through a reader path.
+    if (!parseFailed &&
+        raw.cloudEnabled === true &&
         typeof raw.cloudSyncExcludeSensitive !== 'boolean' &&
         typeof raw.cloudSyncDefaultsMigratedAt !== 'string') {
+        // Route the migration write through the guarded helper (skip-policy: a
+        // reader must never throw). The earlier !parseFailed guard makes the skip
+        // path unreachable here, but going through mutateRawConfig keeps the
+        // single-source-of-truth invariant: no bare writeRawConfig outside it.
+        mutateRawConfig((m) => {
+            m.cloudSyncExcludeSensitive = true;
+            m.cloudSyncDefaultsMigratedAt = new Date().toISOString();
+        }, 'skip');
         raw.cloudSyncExcludeSensitive = true;
-        raw.cloudSyncDefaultsMigratedAt = new Date().toISOString();
-        writeRawConfig(raw);
     }
     const projectMode = raw.cloudSyncProjectMode;
     const contentMode = raw.cloudSyncContentMode;
@@ -198,16 +245,16 @@ export function getCloudSyncControls() {
     };
 }
 export function setCloudSyncControls(updates) {
-    const raw = readRawConfig();
-    if (updates.projectMode !== undefined)
-        raw.cloudSyncProjectMode = updates.projectMode;
-    if (updates.projects !== undefined)
-        raw.cloudSyncProjects = normalizeProjectList(updates.projects);
-    if (updates.contentMode !== undefined)
-        raw.cloudSyncContentMode = updates.contentMode;
-    if (updates.excludeSensitive !== undefined)
-        raw.cloudSyncExcludeSensitive = updates.excludeSensitive;
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        if (updates.projectMode !== undefined)
+            raw.cloudSyncProjectMode = updates.projectMode;
+        if (updates.projects !== undefined)
+            raw.cloudSyncProjects = normalizeProjectList(updates.projects);
+        if (updates.contentMode !== undefined)
+            raw.cloudSyncContentMode = updates.contentMode;
+        if (updates.excludeSensitive !== undefined)
+            raw.cloudSyncExcludeSensitive = updates.excludeSensitive;
+    });
 }
 export function shouldSyncProject(project, controls = getCloudSyncControls()) {
     const normalized = (project ?? '').trim();
@@ -222,70 +269,211 @@ export function isSensitiveLevel(level) {
     const normalized = level.trim().toUpperCase();
     return normalized.length > 0 && normalized !== 'PUBLIC' && normalized !== 'INTERNAL';
 }
-// ── Trusted Skills ──────────────────────────────────────
-export function readRawConfig() {
+/**
+ * Read + verify the raw config, distinguishing "file absent/empty" (safe to
+ * write) from "file present but unparseable" (must stay read-only). Backed by
+ * an mtime cache so a hot path (per-scan getDefenceMode) doesn't re-read,
+ * re-parse and re-HMAC the file on every call.
+ */
+function readRawConfigState() {
+    const configFile = getConfigFile();
+    // mtime cache: if the file is unchanged since the last successful read,
+    // return the cached parsed object without touching disk again.
+    try {
+        const mtimeMs = statSync(configFile).mtimeMs;
+        if (cachedRawConfig !== null &&
+            cachedRawConfigFile === configFile &&
+            cachedRawConfigMtimeMs === mtimeMs) {
+            // Return a shallow copy so callers can mutate freely without poisoning
+            // the cache (accessors push to arrays / set fields before writing back).
+            return { data: { ...cachedRawConfig }, parseFailed: false };
+        }
+    }
+    catch {
+        // stat failed (file likely absent) — fall through to the real read.
+    }
     try {
-        const configFile = getConfigFile();
         if (existsSync(configFile)) {
+            // Capture mtime BEFORE reading the bytes. The cache key must describe the
+            // exact bytes we're about to read: if we stat AFTER readFileSync, a
+            // concurrent write between read and stat would cache the OLD bytes under
+            // the NEW mtime, so a later read at that mtime would serve stale content.
+            // Stat-before-read closes that window (a write after this stat bumps the
+            // mtime past the cached key, forcing a re-read next time).
+            let mtimeMsForCache = null;
+            try {
+                mtimeMsForCache = statSync(configFile).mtimeMs;
+            }
+            catch { /* best-effort */ }
             const content = readFileSync(configFile, 'utf-8');
-            const data = JSON.parse(content);
-            // Verify HMAC integrity
-            if (!verifyConfigIntegrity(content)) {
+            // An empty file is treated as "no config yet", not a parse failure.
+            if (content.trim().length === 0) {
+                return { data: {}, parseFailed: false };
+            }
+            let data;
+            try {
+                data = JSON.parse(content);
+            }
+            catch {
+                // File exists but is corrupt/torn. Do NOT return {} as writable —
+                // signal parseFailed so persisters skip the write and we never clobber
+                // a momentarily-unreadable config.
+                return { data: {}, parseFailed: true };
+            }
+            // Verify HMAC integrity (embedded `_sig`, else legacy `.config-sig`).
+            if (!verifyConfigIntegrity(data, content)) {
                 configTampered = true;
                 console.error('[ShieldCortex] WARNING: Config file integrity check failed — possible tampering detected. Falling back to strict mode.');
                 // Force strict mode on tampered config
                 data.defenceMode = 'strict';
             }
-            return data;
+            // `_sig` is an integrity artefact, never config data — strip it so it
+            // can't leak into CloudConfig or get re-serialised as a normal field.
+            delete data._sig;
+            // Populate the mtime cache from the parsed (sig-stripped) object, keyed on
+            // the mtime captured BEFORE the read (matches the bytes actually parsed).
+            if (mtimeMsForCache !== null) {
+                cachedRawConfig = { ...data };
+                cachedRawConfigFile = configFile;
+                cachedRawConfigMtimeMs = mtimeMsForCache;
+            }
+            return { data, parseFailed: false };
         }
     }
-    catch { /* ignore */ }
-    return {};
+    catch { /* ignore — treat as absent */ }
+    return { data: {}, parseFailed: false };
 }
+export function readRawConfig() {
+    return readRawConfigState().data;
+}
+function invalidateRawConfigCache() {
+    cachedRawConfig = null;
+    cachedRawConfigFile = null;
+    cachedRawConfigMtimeMs = null;
+}
+/**
+ * Atomically persist the raw config with the HMAC embedded as a top-level
+ * `_sig` field, computed over `canonicalBodyForSig` (the object WITHOUT
+ * `_sig`). Because the signature lives inside the same file and the file is
+ * swapped in via `renameSync` (atomic on POSIX), a concurrent reader can never
+ * observe a half-written file or a config/signature pair that are out of step
+ * — the two torn-read cases the audit found.
+ */
 function writeRawConfig(raw) {
     const configDir = getConfigDir();
     const configFile = getConfigFile();
     mkdirSync(configDir, { recursive: true });
-    const content = JSON.stringify(raw, null, 2) + '\n';
-    writeFileSync(configFile, content);
-    // Sign the config after writing
-    writeConfigSignature(content);
+    // Never carry an inbound `_sig` through; we always recompute it.
+    const { _sig: _ignored, ...rest } = raw;
+    const body = canonicalBodyForSig(rest);
+    const sig = signConfig(body);
+    const out = JSON.stringify({ ...rest, _sig: sig }, null, 2) + '\n';
+    // Write to a unique temp file in the same dir, then atomically rename over
+    // the target. The original config survives a failed/partial write — we never
+    // truncate it. Same-dir tmp guarantees rename is a same-filesystem move.
+    const tmpFile = `${configFile}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
+    try {
+        writeFileSync(tmpFile, out, { mode: 0o600 });
+        // On Windows, renameSync over an EXISTING target can throw EPERM if another
+        // process has the destination open concurrently. This is non-corrupting:
+        // the original config is left intact and the catch below removes the tmp
+        // file and rethrows, so a write may FAIL rather than damage the config.
+        renameSync(tmpFile, configFile);
+    }
+    catch (err) {
+        try {
+            if (existsSync(tmpFile))
+                rmSync(tmpFile, { force: true });
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
+    // The embedded `_sig` is now the source of truth. Delete the stale legacy
+    // `.config-sig` only after a successful embedded write, only if it exists —
+    // this completes the one-way upgrade from the legacy format.
+    try {
+        const sigFile = getSigFile();
+        if (existsSync(sigFile))
+            rmSync(sigFile, { force: true });
+    }
+    catch { /* best-effort */ }
     cachedConfig = null;
     cachedConfigFile = null;
+    invalidateRawConfigCache();
     // Clear tamper flag on legitimate write
     configTampered = false;
 }
+/**
+ * The ONLY sanctioned read-modify-write path for config.json.
+ *
+ * EVERY mutating accessor MUST go through this helper. Do NOT call
+ * `writeRawConfig` with a `raw` object obtained from a bare `readRawConfig()`:
+ * `readRawConfig()` collapses a parse failure to `{}`, discarding the
+ * `parseFailed` flag, so mutating that `{}` and writing it back atomically
+ * persists a near-empty, validly-signed config — wiping `cloudApiKey` and every
+ * other setting the corrupt file still holds, with no error signal. This helper
+ * reads through `readRawConfigState()` (which preserves `parseFailed`) and
+ * refuses to write when the on-disk config is unreadable.
+ *
+ * `onParseFail`:
+ *   - `'throw'` (default): surface corruption to user-facing/explicit setters so
+ *     the caller sees the problem rather than silently losing credentials.
+ *   - `'skip'`: silently no-op for automatic / hot-path writes that must NEVER
+ *     throw (background sync, read-with-migration). Returns false so the caller
+ *     can tell the write was skipped.
+ *
+ * Returns true if the mutation was applied and persisted, false if it was
+ * skipped because the config was unparseable (`onParseFail: 'skip'`).
+ */
+function mutateRawConfig(fn, onParseFail = 'throw') {
+    const { data, parseFailed } = readRawConfigState();
+    if (parseFailed) {
+        console.error('[ShieldCortex] config.json is unreadable — refusing to overwrite (would wipe settings incl. cloudApiKey). Fix or remove the file.');
+        if (onParseFail === 'throw') {
+            throw new Error('ShieldCortex config.json is corrupt/unparseable; refusing to overwrite to avoid losing settings. ' +
+                'Fix or remove ~/.shieldcortex/config.json and retry.');
+        }
+        return false;
+    }
+    fn(data);
+    writeRawConfig(data);
+    return true;
+}
 export function getTrustedSkills() {
     const raw = readRawConfig();
     return Array.isArray(raw.trustedSkills) ? raw.trustedSkills : [];
 }
 export function addTrustedSkill(path) {
-    const raw = readRawConfig();
-    const list = Array.isArray(raw.trustedSkills) ? raw.trustedSkills : [];
-    if (!list.includes(path)) {
-        list.push(path);
+    // Throw-policy explicit setter: on a corrupt config mutateRawConfig throws
+    // (surfacing the corruption) rather than wiping it. The closure is itself a
+    // no-op write when the skill is already present, which is acceptable churn on
+    // a VALID config and avoids a second bare read just to skip a write — the one
+    // case we must not silently swallow is the corrupt one, which the helper
+    // handles by throwing.
+    mutateRawConfig((raw) => {
+        const list = Array.isArray(raw.trustedSkills) ? raw.trustedSkills : [];
+        if (!list.includes(path))
+            list.push(path);
         raw.trustedSkills = list;
-        writeRawConfig(raw);
-    }
+    });
 }
 export function removeTrustedSkill(path) {
-    const raw = readRawConfig();
-    const list = Array.isArray(raw.trustedSkills) ? raw.trustedSkills : [];
-    const idx = list.indexOf(path);
-    if (idx !== -1) {
-        list.splice(idx, 1);
+    mutateRawConfig((raw) => {
+        const list = Array.isArray(raw.trustedSkills) ? raw.trustedSkills : [];
+        const idx = list.indexOf(path);
+        if (idx !== -1)
+            list.splice(idx, 1);
         raw.trustedSkills = list;
-        writeRawConfig(raw);
-    }
+    });
 }
 // ── Cloud Iron Dome Cache ─────────────────────────────
 /**
  * Persist cloud Iron Dome data (patterns + policy) to config.json with HMAC integrity.
  */
 export function setCloudIronDomeCache(data) {
-    const raw = readRawConfig();
-    raw.cloudIronDome = data;
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        raw.cloudIronDome = data;
+    });
 }
 /**
  * Read cached cloud Iron Dome data from config.json.
@@ -298,13 +486,66 @@ export function getCloudIronDomeCache() {
     return null;
 }
 // ── Sync Timestamp ────────────────────────────────────
+// Debounce state for lastSyncAt. The sync queue, graph-sync and memory-sync all
+// call updateLastSyncAt() after EVERY successful upload — a busy agent fired a
+// full read-modify-write of config.json per record. We keep the latest value in
+// memory and only persist at most once per LAST_SYNC_PERSIST_INTERVAL_MS, which
+// collapses a burst to a single write while readers still see a fresh value.
+const LAST_SYNC_PERSIST_INTERVAL_MS = 60_000;
+let pendingLastSyncAt = null;
+let lastSyncPersistedAtMs = 0;
 /**
- * Write lastSyncAt timestamp to config.json on successful cloud sync.
+ * Record a successful cloud sync. Always updates the in-memory timestamp;
+ * persists to config.json at most once per 60s (time-debounced). Callers
+ * (sync.ts / sync-queue.ts / memory-sync.ts) are unchanged — the debounce is
+ * internal.
  */
 export function updateLastSyncAt() {
+    const now = Date.now();
+    pendingLastSyncAt = new Date(now).toISOString();
+    if (now - lastSyncPersistedAtMs < LAST_SYNC_PERSIST_INTERVAL_MS) {
+        return; // within the debounce window — memory updated, disk left alone
+    }
+    persistLastSyncAt(now);
+}
+function persistLastSyncAt(nowMs) {
+    if (pendingLastSyncAt === null)
+        return;
+    // Automatic / hot path (fires after cloud uploads): MUST NOT throw. The
+    // 'skip' policy makes mutateRawConfig a silent no-op on an unreadable config
+    // (returns false) instead of clobbering it. Only stamp the debounce clock
+    // when the write actually landed, so a skipped write is retried next call.
+    const written = mutateRawConfig((raw) => {
+        raw.lastSyncAt = pendingLastSyncAt;
+    }, 'skip');
+    if (written)
+        lastSyncPersistedAtMs = nowMs;
+}
+/**
+ * Force-persist the latest in-memory lastSyncAt regardless of the debounce
+ * window, so the final sync timestamp isn't lost if the process exits inside
+ * the debounce window. Safe no-op if nothing is pending.
+ *
+ * Available for a shutdown path (not currently wired): the existing
+ * SIGINT/SIGTERM/exit handlers (src/index.ts, src/api/visualization-server.ts)
+ * are MCP-server / dashboard lifecycle concerns and don't obviously own the
+ * cloud-sync clock, so wiring is left to whichever shutdown owner adopts it
+ * rather than bolted onto an unrelated handler. Losing at most one debounced
+ * timestamp on abrupt exit is non-critical (the next sync re-stamps it).
+ */
+export function flushLastSyncAt() {
+    persistLastSyncAt(Date.now());
+}
+/**
+ * Returns the most recent sync timestamp, preferring the in-memory value (which
+ * may be ahead of disk inside the debounce window) and falling back to the
+ * persisted config value.
+ */
+export function getLastSyncAt() {
+    if (pendingLastSyncAt !== null)
+        return pendingLastSyncAt;
     const raw = readRawConfig();
-    raw.lastSyncAt = new Date().toISOString();
-    writeRawConfig(raw);
+    return typeof raw.lastSyncAt === 'string' ? raw.lastSyncAt : null;
 }
 const VALID_MODES = ['strict', 'balanced', 'permissive'];
 /**
@@ -325,9 +566,9 @@ export function setDefenceMode(mode) {
     if (!VALID_MODES.includes(mode)) {
         throw new Error(`Invalid defence mode: ${mode}. Must be one of: ${VALID_MODES.join(', ')}`);
     }
-    const raw = readRawConfig();
-    raw.defenceMode = mode;
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        raw.defenceMode = mode;
+    });
 }
 const DEFAULT_VERIFY_CONFIG = {
     verifyEnabled: false,
@@ -352,16 +593,16 @@ export function getVerifyConfig() {
  * Persists LLM verification config to ~/.shieldcortex/config.json.
  */
 export function setVerifyConfig(updates) {
-    const raw = readRawConfig();
-    if (updates.verifyEnabled !== undefined)
-        raw.verifyEnabled = updates.verifyEnabled;
-    if (updates.verifyMode !== undefined)
-        raw.verifyMode = updates.verifyMode;
-    if (updates.verifyTriggers !== undefined)
-        raw.verifyTriggers = updates.verifyTriggers;
-    if (updates.verifyTimeoutMs !== undefined)
-        raw.verifyTimeoutMs = updates.verifyTimeoutMs;
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        if (updates.verifyEnabled !== undefined)
+            raw.verifyEnabled = updates.verifyEnabled;
+        if (updates.verifyMode !== undefined)
+            raw.verifyMode = updates.verifyMode;
+        if (updates.verifyTriggers !== undefined)
+            raw.verifyTriggers = updates.verifyTriggers;
+        if (updates.verifyTimeoutMs !== undefined)
+            raw.verifyTimeoutMs = updates.verifyTimeoutMs;
+    });
 }
 // ── Review Copilot Config ───────────────────────────────
 function readReviewCopilotRaw() {
@@ -400,15 +641,15 @@ export function getReviewCopilotConfig() {
  * Persists local Review Copilot config.
  */
 export function setReviewCopilotConfig(updates) {
-    const raw = readRawConfig();
-    const existing = raw.reviewCopilot && typeof raw.reviewCopilot === 'object'
-        ? raw.reviewCopilot
-        : {};
-    raw.reviewCopilot = {
-        ...existing,
-        ...updates,
-    };
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        const existing = raw.reviewCopilot && typeof raw.reviewCopilot === 'object'
+            ? raw.reviewCopilot
+            : {};
+        raw.reviewCopilot = {
+            ...existing,
+            ...updates,
+        };
+    });
 }
 // ── Ranker Config ─────────────────────────────────────
 const DEFAULT_RANKER_CONFIG = {
@@ -469,18 +710,18 @@ export function getRankerConfig() {
  * fields supplied in `updates` are written; other fields are preserved.
  */
 export function setRankerConfig(updates) {
-    const raw = readRawConfig();
-    const existing = raw.ranker && typeof raw.ranker === 'object'
-        ? raw.ranker
-        : {};
-    if (updates.engine !== undefined)
-        existing.engine = updates.engine;
-    if (updates.rrfK !== undefined)
-        existing.rrfK = updates.rrfK;
-    if (updates.weights !== undefined)
-        existing.weights = updates.weights;
-    raw.ranker = existing;
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        const existing = raw.ranker && typeof raw.ranker === 'object'
+            ? raw.ranker
+            : {};
+        if (updates.engine !== undefined)
+            existing.engine = updates.engine;
+        if (updates.rrfK !== undefined)
+            existing.rrfK = updates.rrfK;
+        if (updates.weights !== undefined)
+            existing.weights = updates.weights;
+        raw.ranker = existing;
+    });
 }
 const DEFAULT_OPENCLAW_MEMORY_CONFIG = {
     autoMemory: true,
@@ -513,18 +754,18 @@ export function getOpenClawMemoryConfig() {
  * Persists OpenClaw memory integration config.
  */
 export function setOpenClawMemoryConfig(updates) {
-    const raw = readRawConfig();
-    if (updates.autoMemory !== undefined)
-        raw.openclawAutoMemory = updates.autoMemory;
-    if (updates.dedupe !== undefined)
-        raw.openclawAutoMemoryDedupe = updates.dedupe;
-    if (updates.noveltyThreshold !== undefined) {
-        raw.openclawAutoMemoryNoveltyThreshold = clamp(updates.noveltyThreshold, 0.6, 0.99);
-    }
-    if (updates.maxRecent !== undefined) {
-        raw.openclawAutoMemoryMaxRecent = Math.floor(clamp(updates.maxRecent, 50, 1000));
-    }
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        if (updates.autoMemory !== undefined)
+            raw.openclawAutoMemory = updates.autoMemory;
+        if (updates.dedupe !== undefined)
+            raw.openclawAutoMemoryDedupe = updates.dedupe;
+        if (updates.noveltyThreshold !== undefined) {
+            raw.openclawAutoMemoryNoveltyThreshold = clamp(updates.noveltyThreshold, 0.6, 0.99);
+        }
+        if (updates.maxRecent !== undefined) {
+            raw.openclawAutoMemoryMaxRecent = Math.floor(clamp(updates.maxRecent, 50, 1000));
+        }
+    });
 }
 /**
  * Returns whether OpenClaw auto-memory extraction is enabled.
@@ -554,9 +795,9 @@ export function isProactiveRecallEnabled() {
  * Persists proactive recall preference to ~/.shieldcortex/config.json.
  */
 export function setProactiveRecall(enabled) {
-    const raw = readRawConfig();
-    raw.proactiveRecall = enabled;
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        raw.proactiveRecall = enabled;
+    });
 }
 /**
  * Restores the v4.10.x defaults for users who preferred the old behaviour.
@@ -564,32 +805,32 @@ export function setProactiveRecall(enabled) {
  * so the flip is a one-command undo.
  */
 export function restore410Defaults() {
-    const raw = readRawConfig();
-    raw.proactiveRecall = true;
-    const existingInterceptor = (raw.interceptor && typeof raw.interceptor === 'object')
-        ? raw.interceptor
-        : {};
-    const existingSeverity = (existingInterceptor.severityActions && typeof existingInterceptor.severityActions === 'object')
-        ? existingInterceptor.severityActions
-        : {};
-    raw.interceptor = {
-        ...existingInterceptor,
-        severityActions: {
-            ...existingSeverity,
-            low: 'log',
-            medium: 'warn',
-            high: 'require_approval',
-            critical: 'require_approval',
-        },
-    };
-    const existingSessionStart = (raw.sessionStart && typeof raw.sessionStart === 'object')
-        ? raw.sessionStart
-        : {};
-    raw.sessionStart = {
-        ...existingSessionStart,
-        preamble: 'minimal',
-    };
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        raw.proactiveRecall = true;
+        const existingInterceptor = (raw.interceptor && typeof raw.interceptor === 'object')
+            ? raw.interceptor
+            : {};
+        const existingSeverity = (existingInterceptor.severityActions && typeof existingInterceptor.severityActions === 'object')
+            ? existingInterceptor.severityActions
+            : {};
+        raw.interceptor = {
+            ...existingInterceptor,
+            severityActions: {
+                ...existingSeverity,
+                low: 'log',
+                medium: 'warn',
+                high: 'require_approval',
+                critical: 'require_approval',
+            },
+        };
+        const existingSessionStart = (raw.sessionStart && typeof raw.sessionStart === 'object')
+            ? raw.sessionStart
+            : {};
+        raw.sessionStart = {
+            ...existingSessionStart,
+            preamble: 'minimal',
+        };
+    });
 }
 /**
  * Returns the resolved on/off state of the opt-in auto-memory hooks.
@@ -618,16 +859,16 @@ export function getAutoMemoryEnableConfig() {
  * runtime gate cannot disagree.
  */
 export function setAutoMemoryEnableConfig(updates) {
-    const raw = readRawConfig();
-    const existing = raw.autoMemory && typeof raw.autoMemory === 'object'
-        ? raw.autoMemory
-        : {};
-    if (updates.enableStop !== undefined)
-        existing.enableStop = updates.enableStop;
-    if (updates.enableSessionEnd !== undefined)
-        existing.enableSessionEnd = updates.enableSessionEnd;
-    raw.autoMemory = existing;
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        const existing = raw.autoMemory && typeof raw.autoMemory === 'object'
+            ? raw.autoMemory
+            : {};
+        if (updates.enableStop !== undefined)
+            existing.enableStop = updates.enableStop;
+        if (updates.enableSessionEnd !== undefined)
+            existing.enableSessionEnd = updates.enableSessionEnd;
+        raw.autoMemory = existing;
+    });
 }
 const DEFAULT_TOOL_RESPONSE_SCAN_CONFIG = {
     scanToolResponses: true,
@@ -647,12 +888,12 @@ export function getToolResponseScanConfig() {
  * Persists tool response scanning config.
  */
 export function setToolResponseScanConfig(updates) {
-    const raw = readRawConfig();
-    if (updates.scanToolResponses !== undefined)
-        raw.scanToolResponses = updates.scanToolResponses;
-    if (updates.toolResponseMode !== undefined)
-        raw.toolResponseMode = updates.toolResponseMode;
-    writeRawConfig(raw);
+    mutateRawConfig((raw) => {
+        if (updates.scanToolResponses !== undefined)
+            raw.scanToolResponses = updates.scanToolResponses;
+        if (updates.toolResponseMode !== undefined)
+            raw.toolResponseMode = updates.toolResponseMode;
+    });
 }
 // ── Device Identity ────────────────────────────────────
 /**
@@ -660,13 +901,26 @@ export function setToolResponseScanConfig(updates) {
  * Generates and persists on first call; reads from config thereafter.
  */
 export function getDeviceId() {
-    const raw = readRawConfig();
+    const { data: raw, parseFailed } = readRawConfigState();
     if (typeof raw.deviceId === 'string' && raw.deviceId) {
         return raw.deviceId;
     }
     const id = randomUUID();
-    raw.deviceId = id;
-    writeRawConfig(raw);
+    if (parseFailed) {
+        // The config file exists but is unreadable. Persisting now would write
+        // `{ deviceId }` over the corrupt bytes and destroy cloudApiKey and every
+        // other setting the file still holds. Return an ephemeral id this run and
+        // leave the file untouched — identity persists once the file is readable.
+        // (mutateRawConfig('skip') would no-op here too, but we want this specific
+        // diagnostic, so we short-circuit before calling it.)
+        console.error('[ShieldCortex] config.json unreadable — using an ephemeral device id this run; identity was NOT persisted.');
+        return id;
+    }
+    // Persist through the guarded helper so no bare writeRawConfig exists outside
+    // mutateRawConfig; skip-policy keeps this read-then-persist path non-throwing.
+    mutateRawConfig((m) => {
+        m.deviceId = id;
+    }, 'skip');
     return id;
 }
 /**
@@ -674,12 +928,18 @@ export function getDeviceId() {
  * Stores in config on first call; reads from config thereafter.
  */
 export function getDeviceName() {
-    const raw = readRawConfig();
+    const { data: raw, parseFailed } = readRawConfigState();
     if (typeof raw.deviceName === 'string' && raw.deviceName) {
         return raw.deviceName;
     }
     const name = hostname();
-    raw.deviceName = name;
-    writeRawConfig(raw);
+    if (parseFailed) {
+        // See getDeviceId — never overwrite an unreadable config.
+        console.error('[ShieldCortex] config.json unreadable — using the live hostname this run; device name was NOT persisted.');
+        return name;
+    }
+    mutateRawConfig((m) => {
+        m.deviceName = name;
+    }, 'skip');
     return name;
 }