log-llm-config-staging 1.3.44

package/dist/log_config_files/runtime/remediation_sync.js

@@ -0,0 +1,1290 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { delimiter, dirname } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { executeGet, executeBody } from '../../endpoint_client/http_transport.js';
+import { complianceRunnerDiag, hookRunLog, logRemediationApplyFailure } from './hook_logger.js';
+import { atomicWriteJson, getDeferredVscdbApplyPath, getFileCollectionVscdbContractPath, getRemediationInstructionsPath, readFileCollectionVscdbContract, readRemediationInstructionsFile, writeRemediationInstructionsFile, } from './management_storage.js';
+import { readStoredAuthKey } from '../auth/auth_key_store.js';
+import { createSignature } from '../sender/signing.js';
+import { loadEndpointBase } from '../sender/endpoint_config.js';
+import { tryResolveHardwareUuid } from './hardware_uuid.js';
+import { CURSOR_SCALAR_ITEMTABLE_FIELDS, persistVscdbComposerContractFromPatternsResponse, readVscdbItemTableJson, } from '../readers/vscdb_reader.js';
+import { sendConfigFile } from '../sender/batch_sender.js';
+import { buildApiUrl, getFileCollectionPatterns } from '../../endpoint_client/registry_api.js';
+import { resolveRemediationConfigPath } from './remediation_config_path.js';
+import { resolveSqlite3Binary } from './sqlite_binary.js';
+/** Best-effort detail from execFileSync failures (stderr, exit code, errno). */
+function formatNodeChildException(err) {
+    if (!(err instanceof Error)) {
+        const s = String(err);
+        return { short: s, long: s };
+    }
+    const e = err;
+    const bits = [e.message];
+    if (e.code)
+        bits.push(`errno_code=${e.code}`);
+    if (typeof e.status === 'number')
+        bits.push(`exit_status=${e.status}`);
+    let stderr = '';
+    if (e.stderr != null) {
+        stderr = typeof e.stderr === 'string' ? e.stderr : e.stderr.toString('utf8');
+        const t = stderr.trim();
+        if (t)
+            bits.push(`stderr=${t.slice(0, 1200)}`);
+    }
+    const long = bits.join(' | ');
+    return { short: bits.slice(0, 2).join(' | '), long };
+}
+function reactiveStorageItemKeyFromContract() {
+    const k = readFileCollectionVscdbContract()?.reactive_storage_item_key;
+    return typeof k === 'string' && k.trim() !== '' ? k.trim() : undefined;
+}
+function composerShadowKeySetFromContract() {
+    return new Set(readFileCollectionVscdbContract()?.composer_shadow_keys ?? []);
+}
+/** Resolve fix payload from API or legacy `compliance` key in local JSON. */
+export function remediationFixSpec(inst) {
+    return inst.fix ?? inst.compliance ?? null;
+}
+/** True when this row should be replaced from GET manifest (missing or empty fix checks). */
+function needsManifestRefetch(inst) {
+    if (!inst)
+        return true;
+    const spec = remediationFixSpec(inst);
+    if (!spec)
+        return true;
+    const checks = spec.checks;
+    return !Array.isArray(checks) || checks.length === 0;
+}
+// ---------------------------------------------------------------------------
+// Persistence (single file: remediation_instructions.json)
+// ---------------------------------------------------------------------------
+function readInstructions() {
+    const { remediations } = readRemediationInstructionsFile();
+    return { remediations: remediations };
+}
+function writeInstructions(file) {
+    writeRemediationInstructionsFile(file);
+}
+/**
+ * Merge persisted rows with API overlay; GET manifest for enforced UUIDs still missing rows.
+ */
+async function ensureInstructionsForUuids(endpointBase, machineUuid, want, overlayFromApi) {
+    const byUuid = new Map();
+    for (const inst of readInstructions().remediations) {
+        if (want.has(inst.uuid))
+            byUuid.set(inst.uuid, inst);
+    }
+    for (const inst of overlayFromApi ?? []) {
+        if (want.has(inst.uuid))
+            byUuid.set(inst.uuid, inst);
+    }
+    // Refetch rows that are missing entirely or have no usable checks (stale/incomplete local cache).
+    const missing = [...want].filter((u) => needsManifestRefetch(byUuid.get(u)));
+    if (missing.length > 0) {
+        try {
+            const fetched = await fetchManifest(endpointBase, machineUuid, missing);
+            if (fetched) {
+                for (const inst of fetched) {
+                    if (want.has(inst.uuid))
+                        byUuid.set(inst.uuid, inst);
+                }
+            }
+        }
+        catch (err) {
+            hookRunLog(`remediation_manifest_backfill_error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const stillMissing = [...want].filter((u) => !byUuid.has(u));
+        if (stillMissing.length > 0) {
+            hookRunLog(`remediation_manifest_backfill_incomplete: uuids=${stillMissing.join(',')}`);
+        }
+    }
+    const remediations = [...byUuid.values()].sort((a, b) => a.uuid.localeCompare(b.uuid));
+    const payload = { remediations };
+    const nextJson = JSON.stringify(payload, null, 2);
+    const path = getRemediationInstructionsPath();
+    let prev = '';
+    if (existsSync(path)) {
+        try {
+            prev = readFileSync(path, 'utf8');
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (prev !== nextJson) {
+        writeInstructions(payload);
+    }
+}
+// ---------------------------------------------------------------------------
+// API helpers
+// ---------------------------------------------------------------------------
+export async function fetchSync(endpointBase, machineUuid, activeUuids, timeoutMs = 8000) {
+    const uuidsParam = activeUuids.join(',');
+    const url = `${buildApiUrl(endpointBase, '/api/findings/remediations/sync/')}?machine_uuid=${encodeURIComponent(machineUuid)}&active_uuids=${encodeURIComponent(uuidsParam)}`;
+    const { statusCode, body } = await executeGet(url, timeoutMs);
+    if (statusCode !== 200 || !body) {
+        const line = `remediation_sync_get: url=${url} status=${statusCode} bytes=${body?.length ?? 0}`;
+        hookRunLog(line);
+        complianceRunnerDiag(line);
+        return null;
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        hookRunLog('remediation_sync_get: invalid JSON body');
+        complianceRunnerDiag('remediation_sync_get: invalid JSON body');
+        return null;
+    }
+}
+async function fetchManifest(endpointBase, machineUuid, uuids, timeoutMs = 8000) {
+    const url = `${buildApiUrl(endpointBase, '/api/findings/remediations/manifest/')}?machine_uuid=${encodeURIComponent(machineUuid)}&uuids=${encodeURIComponent(uuids.join(','))}`;
+    const { statusCode, body } = await executeGet(url, timeoutMs);
+    if (statusCode !== 200 || !body) {
+        const line = `remediation_manifest_get: url=${url} status=${statusCode} bytes=${body?.length ?? 0}`;
+        hookRunLog(line);
+        complianceRunnerDiag(line);
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(body);
+        if (!Array.isArray(parsed.remediations)) {
+            complianceRunnerDiag('remediation_manifest_get: JSON remediations is not an array');
+            return null;
+        }
+        return parsed.remediations.map((raw) => {
+            const { compliance, ...rest } = raw;
+            const fix = rest.fix ?? compliance ?? null;
+            return { ...rest, fix };
+        });
+    }
+    catch {
+        complianceRunnerDiag('remediation_manifest_get: invalid JSON body');
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Enforce / remove
+// ---------------------------------------------------------------------------
+function setByPath(obj, path, value) {
+    const parts = path.split('.');
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (current[part] == null || typeof current[part] !== 'object' || Array.isArray(current[part])) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+/** Traverse a JSON object using dot-notation path. Returns undefined if any segment is missing. */
+function getByPath(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/** Recursively set a value at a dot-notation path in a JSON object. */
+function setByPathNested(obj, path, value) {
+    const parts = path.split('.');
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (current[part] == null || typeof current[part] !== 'object' || Array.isArray(current[part])) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+function applyStringArrayDelta(current, before, after) {
+    const cur = isStringArray(current) ? [...current] : [];
+    const b = isStringArray(before) ? before : [];
+    const a = isStringArray(after) ? after : [];
+    const bSet = new Set(b);
+    const aSet = new Set(a);
+    const removed = b.filter((x) => !aSet.has(x));
+    const added = a.filter((x) => !bSet.has(x));
+    // Remove any items that were removed by the remediation (preserve other local additions).
+    const removedSet = new Set(removed);
+    const next = cur.filter((x) => !removedSet.has(x));
+    // Append items that were added by the remediation (avoid duplicates).
+    const nextSet = new Set(next);
+    for (const x of added) {
+        if (!nextSet.has(x)) {
+            next.push(x);
+            nextSet.add(x);
+        }
+    }
+    return next;
+}
+function applyCheck(configJson, check) {
+    const parts = check.setting_path.split('.');
+    const leafKey = parts[parts.length - 1] ?? '';
+    const parentPath = parts.slice(0, -1).join('.');
+    // Prefer explicit ops when provided by server (safest: avoids clobbering local edits).
+    if (check.ops && typeof check.ops === 'object') {
+        const { set, add, remove } = check.ops;
+        const keys = new Set([
+            ...Object.keys(set ?? {}),
+            ...Object.keys(add ?? {}),
+            ...Object.keys(remove ?? {}),
+        ]);
+        for (const k of keys) {
+            const targetPath = k === leafKey || keys.size === 1 && (k === leafKey || k === '')
+                ? check.setting_path
+                : parentPath
+                    ? `${parentPath}.${k}`
+                    : k;
+            if (set && Object.prototype.hasOwnProperty.call(set, k)) {
+                setByPath(configJson, targetPath, set[k]);
+                continue;
+            }
+            const curVal = getByPath(configJson, targetPath);
+            const cur = isStringArray(curVal) ? [...curVal] : [];
+            const toRemove = (remove && remove[k]) ?? [];
+            const toAdd = (add && add[k]) ?? [];
+            const rmSet = new Set(toRemove);
+            const next = cur.filter((x) => !rmSet.has(x));
+            const nextSet = new Set(next);
+            for (const x of toAdd) {
+                if (!nextSet.has(x)) {
+                    next.push(x);
+                    nextSet.add(x);
+                }
+            }
+            setByPath(configJson, targetPath, next);
+        }
+        return;
+    }
+    // Normal v2 shape: after[leafKey] is the intended leaf value.
+    // Some remediations may include multi-key objects (e.g. {allow, deny}) while the path points at one leaf.
+    // In that case, treat the payload as a patch for the parent object and apply per-key deltas.
+    if (isPlainObject(check.before) && isPlainObject(check.after)) {
+        const afterKeys = Object.keys(check.after);
+        const beforeKeys = Object.keys(check.before);
+        const looksMultiKey = afterKeys.length > 1 || (afterKeys.length > 0 && !Object.prototype.hasOwnProperty.call(check.after, leafKey));
+        if (looksMultiKey) {
+            for (const k of afterKeys) {
+                const targetPath = parentPath ? `${parentPath}.${k}` : k;
+                const curVal = getByPath(configJson, targetPath);
+                const bVal = check.before[k];
+                const aVal = check.after[k];
+                if (isStringArray(bVal) && isStringArray(aVal)) {
+                    setByPath(configJson, targetPath, applyStringArrayDelta(curVal, bVal, aVal));
+                }
+                else {
+                    setByPath(configJson, targetPath, aVal);
+                }
+            }
+            return;
+        }
+    }
+    let value = undefined;
+    if (isPlainObject(check.after) && Object.prototype.hasOwnProperty.call(check.after, leafKey)) {
+        value = check.after[leafKey];
+    }
+    else {
+        value = check.after;
+    }
+    // If the leaf is a string[] and we have before/after snapshots, apply delta not replacement.
+    if (isPlainObject(check.before) && isPlainObject(check.after)) {
+        const b = check.before[leafKey];
+        const a = check.after[leafKey];
+        if (isStringArray(b) && isStringArray(a)) {
+            const cur = getByPath(configJson, check.setting_path);
+            setByPath(configJson, check.setting_path, applyStringArrayDelta(cur, b, a));
+            return;
+        }
+    }
+    setByPath(configJson, check.setting_path, value);
+}
+function mergePostApplyUploadIntoPayload(payload, hint) {
+    if (!hint)
+        return;
+    const ft = hint.file_type?.trim();
+    if (!ft || !hint.file_path.includes('#'))
+        return;
+    if (!payload.post_apply_uploads)
+        payload.post_apply_uploads = [];
+    if (payload.post_apply_uploads.some((u) => u.file_path === hint.file_path))
+        return;
+    payload.post_apply_uploads.push({ file_path: hint.file_path, file_type: ft });
+}
+function assertSqlite3Available() {
+    const bin = resolveSqlite3Binary();
+    if (bin) {
+        complianceRunnerDiag(`sqlite_update: using sqlite3 binary ${bin}`);
+        return true;
+    }
+    const pathEnv = process.env.PATH ?? '';
+    const n = pathEnv ? pathEnv.split(delimiter).filter(Boolean).length : 0;
+    const line = 'sqlite_update: sqlite3 command not found';
+    hookRunLog(line);
+    hookRunLog(`sqlite_update: no sqlite3 resolved after checking env OPTIMUS_SQLITE3/SQLITE3_PATH, common paths, and PATH (${n} entries)`);
+    hookRunLog('sqlite_update: hint set OPTIMUS_SQLITE3 to the full path (e.g. /usr/bin/sqlite3 on macOS) if sqlite3 is outside PATH');
+    complianceRunnerDiag(`${line} PATH_entry_count=${n}`);
+    return false;
+}
+/**
+ * Unquoted SQLite identifiers must be [A-Za-z_][A-Za-z0-9_]* so values read from
+ * deferred_vscdb_apply.json cannot inject SQL via bogus table/column names.
+ */
+function isSafeSqliteIdentifier(ident) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(ident);
+}
+function assertSafeSqliteIdentifiersForItemTable(table, keyColumn, valueColumn) {
+    if (isSafeSqliteIdentifier(table) && isSafeSqliteIdentifier(keyColumn) && isSafeSqliteIdentifier(valueColumn)) {
+        return true;
+    }
+    hookRunLog(`sqlite_update: rejected unsafe SQL identifier(s) table=${table} key_column=${keyColumn} value_column=${valueColumn}`);
+    complianceRunnerDiag('sqlite_update: rejected unsafe SQL identifier(s)');
+    return false;
+}
+/**
+ * Canonical Cursor restart_command strings — single source for buildDeferredCursorRestartCommand + allowlist.
+ *
+ * - **SQLite / state.vscdb (deferred):** autofix queued ItemTable writes; restart runs `apply_deferred_vscdb` then reopens Cursor.
+ * - **JSON settings files:** autofix wrote normal config JSON; restart is kill + reopen only (no deferred apply).
+ *
+ * Exact-match only: `spawn('sh', ['-c', cmd])` runs the whole string; substring checks would allow
+ * appending `; arbitrary shell` after a trusted prefix.
+ */
+const TRUSTED_CURSOR_SQLITE_DEFERRED_RESTART_COMMAND = 'REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd) && export REPO_ROOT && ' +
+    'CURSOR_PROJECT="${CURSOR_PROJECT_DIR:-$REPO_ROOT}" && export CURSOR_PROJECT && ' +
+    'OPTIMUS_DEFERRED_LOG="${HOME}/opt-ai-sec/management/deferred_vscdb_restart.log" && mkdir -p "$(dirname "$OPTIMUS_DEFERRED_LOG")" && export OPTIMUS_DEFERRED_LOG && ' +
+    "nohup bash -c 'exec >>\"\$OPTIMUS_DEFERRED_LOG\" 2>&1; echo deferred_restart:begin ts=\$(date -u +%Y-%m-%dT%H:%M:%SZ) REPO_ROOT=\"\$REPO_ROOT\" CURSOR_PROJECT=\"\$CURSOR_PROJECT\"; sleep 2; if [ -f \"\$REPO_ROOT/dev_npx_packages/log-llm-config/dist/apply_deferred_vscdb.js\" ]; then echo deferred_restart:apply_via_monorepo_node; node \"\$REPO_ROOT/dev_npx_packages/log-llm-config/dist/apply_deferred_vscdb.js\"; APPLY_EC=\$?; else echo deferred_restart:apply_via_npx; cd \"\$REPO_ROOT\" && npx --yes log-llm-config@latest apply-deferred-vscdb; APPLY_EC=\$?; fi; echo deferred_restart:apply_exit=\$APPLY_EC; if [ \$APPLY_EC -ne 0 ]; then echo deferred_restart:APPLY_FAILED_see_messages_above; fi; echo deferred_restart:open_cursor; open -a Cursor \"\$CURSOR_PROJECT\"; echo deferred_restart:open_exit=\$?; echo deferred_restart:end ts=\$(date -u +%Y-%m-%dT%H:%M:%SZ)' >/dev/null 2>&1 & killall -9 Cursor";
+const TRUSTED_CURSOR_JSON_SETTINGS_RESTART_COMMAND = 'CURSOR_PROJECT=$(git rev-parse --show-toplevel 2>/dev/null || pwd) && export CURSOR_PROJECT && nohup bash -c \'sleep 2 && open -a Cursor "$CURSOR_PROJECT"\' >/dev/null 2>&1 & killall -9 Cursor';
+const TRUSTED_CLAUDE_RESTART_COMMAND = "nohup bash -c 'sleep 2 && open -a Claude' >/dev/null 2>&1 & pkill -x 'Claude'";
+/**
+ * Autofix restart_command allowlist: manifest strings are attacker-controlled if JSON is tampered.
+ * SQLite-deferred Cursor path always uses {@link buildDeferredCursorRestartCommand}; manifests may still
+ * embed the JSON-settings-only Cursor template when `restart_required` applies to file-based autofix.
+ */
+export function isTrustedRestartCommandForAutofix(cmd) {
+    const t = cmd.trim();
+    if (!t)
+        return false;
+    return (t === TRUSTED_CURSOR_SQLITE_DEFERRED_RESTART_COMMAND ||
+        t === TRUSTED_CURSOR_JSON_SETTINGS_RESTART_COMMAND ||
+        t === TRUSTED_CLAUDE_RESTART_COMMAND);
+}
+/** Legacy Cursor: dedicated ItemTable row `composerState`. Current Cursor: nested under reactive `applicationUser` blob. */
+function cursorVscdbHasUsableComposerStateRow(dbPath, sqliteOp) {
+    const raw = sqliteSelectValueCell(dbPath, sqliteOp.table, sqliteOp.key_column, sqliteOp.value_column, 'composerState').trim();
+    if (!raw || raw === '{}')
+        return false;
+    try {
+        const o = JSON.parse(raw);
+        return typeof o === 'object' && o !== null && !Array.isArray(o) && Object.keys(o).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveCursorComposerSqliteOp(dbPath, sqliteOp) {
+    if (sqliteOp.target_key !== 'composerState')
+        return sqliteOp;
+    const reactiveKey = reactiveStorageItemKeyFromContract();
+    /** Merge into applicationUser (or equivalent) JSON: inner `composerState` or nested path under it. */
+    const resolveToReactive = () => {
+        if (!reactiveKey)
+            return sqliteOp;
+        const jp = (sqliteOp.json_path ?? '').trim();
+        if (!jp) {
+            return {
+                ...sqliteOp,
+                target_key: reactiveKey,
+                json_path: 'composerState',
+            };
+        }
+        const nestedPath = jp.startsWith('composerState.') ? jp : `composerState.${jp}`;
+        return {
+            ...sqliteOp,
+            target_key: reactiveKey,
+            json_path: nestedPath,
+        };
+    };
+    // Prefer the reactive storage blob when it exists and is non-empty. Cursor reads web/composer
+    // toggles from there; a legacy ItemTable `composerState` row may still hold stale JSON — writing
+    // only that row leaves the UI unchanged (user sees "remediation did nothing" after restart).
+    if (reactiveKey) {
+        const raw = sqliteSelectValueCell(dbPath, sqliteOp.table, sqliteOp.key_column, sqliteOp.value_column, reactiveKey).trim();
+        const reactiveHasBlob = raw !== '' && raw !== '{}';
+        if (reactiveHasBlob) {
+            return resolveToReactive();
+        }
+    }
+    if (cursorVscdbHasUsableComposerStateRow(dbPath, sqliteOp))
+        return sqliteOp;
+    if (reactiveKey) {
+        return resolveToReactive();
+    }
+    hookRunLog('vscdb_contract: missing file_collection_vscdb_contract.json (reactive_storage_item_key); run log-config or remediation sync against API');
+    return sqliteOp;
+}
+/** Apply sqlite merge: dot-path, or array match where `json_path` is `…container.arrayKey` (e.g. `modes4` or `composerState.modes4`). */
+function coerceScalarForItemTableField(parsed) {
+    if (typeof parsed === 'boolean')
+        return parsed;
+    if (typeof parsed === 'string') {
+        const lower = parsed.trim().toLowerCase();
+        if (lower === 'true' || lower === '1' || lower === 'yes')
+            return true;
+        return false;
+    }
+    if (typeof parsed === 'number' && !Number.isNaN(parsed))
+        return parsed !== 0;
+    return undefined;
+}
+/**
+ * ItemTable values are sometimes bare JSON booleans for toggle keys; sqlite merge expects an object root.
+ * Maps known scalar roots to the policy-shaped object before applying updates.
+ */
+function coerceItemTableValueToObjectRoot(targetKey, parsed) {
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    const field = CURSOR_SCALAR_ITEMTABLE_FIELDS[targetKey];
+    if (field) {
+        const b = coerceScalarForItemTableField(parsed);
+        if (b !== undefined)
+            return { [field]: b };
+    }
+    return {};
+}
+/**
+ * Cursor stores some ItemTable toggles as bare JSON booleans (`true`/`false` text). Writing a wrapper
+ * object can be ignored or overwritten on launch; match the native primitive shape when disabling.
+ */
+function serializeItemTableValueForWrite(targetKey, root) {
+    const field = CURSOR_SCALAR_ITEMTABLE_FIELDS[targetKey];
+    if (field) {
+        const keys = Object.keys(root);
+        if (keys.length === 1 && keys[0] === field) {
+            const v = root[field];
+            if (typeof v === 'boolean')
+                return v ? 'true' : 'false';
+            if (typeof v === 'number' && !Number.isNaN(v))
+                return v !== 0 ? 'true' : 'false';
+        }
+    }
+    return JSON.stringify(root);
+}
+function mergeSqliteOpIntoJson(currentJson, sqliteOp) {
+    const where = sqliteOp.array_item_where;
+    const jp = sqliteOp.json_path ?? '';
+    if (where && typeof where === 'object' && Object.keys(where).length > 0 && jp) {
+        const parts = jp.split('.').filter(Boolean);
+        if (parts.length < 1) {
+            mergeJsonAtSqlitePath(currentJson, sqliteOp.json_path, sqliteOp.updates);
+            return;
+        }
+        const arrayKey = parts[parts.length - 1];
+        const parentParts = parts.slice(0, -1);
+        let node = currentJson;
+        for (const p of parentParts) {
+            if (node == null || typeof node !== 'object' || Array.isArray(node))
+                return;
+            const rec = node;
+            const child = rec[p];
+            if (child == null) {
+                rec[p] = {};
+                node = rec[p];
+            }
+            else if (typeof child === 'object' && !Array.isArray(child)) {
+                node = child;
+            }
+            else {
+                return;
+            }
+        }
+        if (node == null || typeof node !== 'object' || Array.isArray(node))
+            return;
+        const container = node;
+        const existing = container[arrayKey];
+        let arr;
+        if (Array.isArray(existing)) {
+            arr = existing;
+        }
+        else if (existing == null) {
+            arr = [];
+            container[arrayKey] = arr;
+        }
+        else {
+            return;
+        }
+        const idx = arr.findIndex((item) => {
+            if (item === null || typeof item !== 'object')
+                return false;
+            const o = item;
+            return Object.entries(where).every(([k, v]) => o[k] === v);
+        });
+        if (idx >= 0) {
+            Object.assign(arr[idx], sqliteOp.updates);
+            return;
+        }
+        const newItem = { ...where };
+        Object.assign(newItem, sqliteOp.updates);
+        arr.push(newItem);
+        return;
+    }
+    mergeJsonAtSqlitePath(currentJson, sqliteOp.json_path, sqliteOp.updates);
+    mirrorComposerShadowKeysToReactiveRoot(currentJson, sqliteOp);
+}
+/**
+ * Cursor remediations historically used json_path `composerState.` (trailing dot). That yields an empty
+ * segment and mergeJsonAtSqlitePath wrote under composerState[''] instead of composerState — the real
+ * isWebFetchToolEnabled stayed true. Strip that spurious object if present.
+ */
+function repairComposerStateEmptySegmentBug(root) {
+    const cs = root.composerState;
+    if (!cs || typeof cs !== 'object' || Array.isArray(cs))
+        return;
+    const o = cs;
+    if (!('' in o))
+        return;
+    delete o[''];
+}
+/**
+ * Cursor sometimes reads web-tool toggles from the reactive blob root; policy/reads merge those into
+ * `composerState` for scan. After patching `composerState` directly (resolved json_path exactly
+ * `composerState`), copy whitelisted keys to the root using cached
+ * `composer_shadow_keys` from the file-patterns API.
+ * Skips array-target ops (`modes4`, etc.).
+ */
+function mirrorComposerShadowKeysToReactiveRoot(root, resolvedOp) {
+    const rk = reactiveStorageItemKeyFromContract();
+    if (!rk || resolvedOp.target_key !== rk)
+        return;
+    const where = resolvedOp.array_item_where;
+    if (where && typeof where === 'object' && Object.keys(where).length > 0)
+        return;
+    const jp = (resolvedOp.json_path ?? '').split('.').filter(Boolean);
+    if (jp.length !== 1 || jp[0] !== 'composerState')
+        return;
+    const updates = resolvedOp.updates;
+    if (!updates || typeof updates !== 'object')
+        return;
+    const shadow = composerShadowKeySetFromContract();
+    for (const k of Object.keys(updates)) {
+        if (shadow.has(k))
+            root[k] = updates[k];
+    }
+}
+/** Merge `updates` into JSON at dot-path `json_path` (same rules as server-generated ops). */
+function mergeJsonAtSqlitePath(currentJson, json_path, updates) {
+    if (json_path?.trim()) {
+        const pathParts = json_path.split('.').filter(Boolean);
+        if (pathParts.length === 0) {
+            Object.assign(currentJson, updates);
+            return;
+        }
+        let current = currentJson;
+        for (let i = 0; i < pathParts.length - 1; i++) {
+            const part = pathParts[i];
+            const idx = parseInt(part, 10);
+            if (!isNaN(idx) && Array.isArray(current)) {
+                if (!current[idx])
+                    current[idx] = {};
+                current = current[idx];
+            }
+            else {
+                if (!current[part])
+                    current[part] = {};
+                current = current[part];
+            }
+        }
+        const lastPart = pathParts[pathParts.length - 1];
+        const lastIdx = parseInt(lastPart, 10);
+        if (!isNaN(lastIdx) && Array.isArray(current)) {
+            if (!current[lastIdx])
+                current[lastIdx] = {};
+            const target = current[lastIdx];
+            Object.assign(target, updates);
+        }
+        else {
+            if (!current[lastPart])
+                current[lastPart] = {};
+            const target = current[lastPart];
+            Object.assign(target, updates);
+        }
+    }
+    else {
+        Object.assign(currentJson, updates);
+    }
+}
+function sqliteSelectValueCell(dbPath, table, key_column, value_column, target_key) {
+    if (!assertSafeSqliteIdentifiersForItemTable(table, key_column, value_column)) {
+        return '';
+    }
+    const sqlite3 = resolveSqlite3Binary();
+    if (!sqlite3) {
+        const line = 'sqlite_update: sqliteSelectValueCell called with no resolved sqlite3 binary (logic error: assertSqlite3Available should run first)';
+        hookRunLog(line);
+        complianceRunnerDiag(line);
+        return '';
+    }
+    const safeName = target_key.replace(/'/g, "''");
+    const script = `.timeout 60000\nSELECT ${value_column} FROM ${table} WHERE ${key_column}='${safeName}';\n`;
+    try {
+        return execFileSync(sqlite3, ['-noheader', dbPath], {
+            input: script,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (err) {
+        const { short, long } = formatNodeChildException(err);
+        hookRunLog(`sqlite_update: SELECT failed binary=${sqlite3} db=${dbPath} table=${table} target_key=${target_key} ${long}`);
+        complianceRunnerDiag(`sqlite_update: SELECT failed target_key=${target_key} ${long.slice(0, 1800)}`);
+        throw new Error(`sqlite3 SELECT failed: ${short}`);
+    }
+}
+function sqliteExecWithTimeout(dbPath, sqlBody) {
+    const sqlite3 = resolveSqlite3Binary();
+    if (!sqlite3)
+        throw new Error('sqlite3 not found');
+    const script = `.timeout 60000\n${sqlBody}\n`;
+    try {
+        execFileSync(sqlite3, [dbPath], {
+            input: script,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const { long } = formatNodeChildException(err);
+        hookRunLog(`sqlite_update: UPDATE/exec failed binary=${sqlite3} db=${dbPath} ${long}`);
+        complianceRunnerDiag(`sqlite_update: UPDATE/exec failed ${long.slice(0, 1800)}`);
+        throw err;
+    }
+}
+/** Runs a single UPDATE (or other SQL) and returns sqlite `changes()` for the last statement. */
+function sqliteRunUpdateReturningChanges(dbPath, updateSql) {
+    const sqlite3 = resolveSqlite3Binary();
+    if (!sqlite3)
+        throw new Error('sqlite3 not found');
+    const script = `.timeout 60000\n${updateSql}\nSELECT changes();\n`;
+    let out;
+    try {
+        out = execFileSync(sqlite3, [dbPath], {
+            input: script,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (err) {
+        const { long } = formatNodeChildException(err);
+        hookRunLog(`sqlite_update: batch UPDATE/changes failed binary=${sqlite3} db=${dbPath} ${long}`);
+        complianceRunnerDiag(`sqlite_update: batch UPDATE failed ${long.slice(0, 1800)}`);
+        throw err;
+    }
+    const lines = out.split(/\r?\n/).filter((l) => l.length > 0);
+    const last = lines[lines.length - 1] ?? '0';
+    return parseInt(last, 10) || 0;
+}
+function queueDeferredVscdbItem(item, postApplyUpload) {
+    const path = getDeferredVscdbApplyPath();
+    let payload = { version: 1, items: [] };
+    if (existsSync(path)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (parsed?.items && Array.isArray(parsed.items)) {
+                payload = parsed;
+                if (!Array.isArray(payload.post_apply_uploads))
+                    payload.post_apply_uploads = [];
+            }
+        }
+        catch {
+            /* replace corrupt file */
+        }
+    }
+    payload.items.push(item);
+    mergePostApplyUploadIntoPayload(payload, postApplyUpload);
+    atomicWriteJson(path, payload);
+}
+/**
+ * After Cursor exits: apply queued ItemTable JSON updates, optional log-config-file uploads (re-read sqlite),
+ * then delete the queue file.
+ * No-op (returns true) if there is nothing pending so `open -a Cursor` still runs.
+ */
+export async function applyDeferredVscdbFromDisk() {
+    const path = getDeferredVscdbApplyPath();
+    hookRunLog(`deferred_vscdb: applyDeferredVscdbFromDisk queue_path=${path} exists=${existsSync(path)}`);
+    complianceRunnerDiag(`deferred_vscdb: applyDeferredVscdbFromDisk start exists=${existsSync(path)}`);
+    if (!existsSync(path))
+        return true;
+    if (!assertSqlite3Available())
+        return false;
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        hookRunLog('deferred_vscdb: could not parse queue file');
+        return false;
+    }
+    const postApplyUploads = [...(payload.post_apply_uploads ?? [])];
+    if (!payload.items?.length) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            /* ignore */
+        }
+        return true;
+    }
+    try {
+        for (const it of payload.items) {
+            if (!existsSync(it.dbPath)) {
+                hookRunLog(`deferred_vscdb: database missing ${it.dbPath}`);
+                return false;
+            }
+            if (!assertSafeSqliteIdentifiersForItemTable(it.table, it.key_column, it.value_column)) {
+                return false;
+            }
+            const safeJson = it.new_value_json.replace(/'/g, "''");
+            const safeName = it.target_key.replace(/'/g, "''");
+            const sql = `UPDATE ${it.table} SET ${it.value_column}='${safeJson}' WHERE ${it.key_column}='${safeName}';`;
+            const changed = sqliteRunUpdateReturningChanges(it.dbPath, sql);
+            if (changed < 1) {
+                hookRunLog(`deferred_vscdb: UPDATE changed 0 rows key=${it.target_key} db=${it.dbPath} — keeping queue file`);
+                return false;
+            }
+        }
+        hookRunLog(`deferred_vscdb: applied ${payload.items.length} queued update(s)`);
+        const authKey = readStoredAuthKey();
+        for (const u of postApplyUploads) {
+            if (!authKey) {
+                hookRunLog(`deferred_vscdb: skip post-apply upload (no auth) path=${u.file_path}`);
+                continue;
+            }
+            const hi = u.file_path.indexOf('#');
+            if (hi < 0)
+                continue;
+            const dbPath = u.file_path.slice(0, hi);
+            const itemKey = u.file_path.slice(hi + 1).trim();
+            if (!itemKey)
+                continue;
+            const rawContent = readVscdbItemTableJson(dbPath, itemKey);
+            if (rawContent === null) {
+                hookRunLog(`deferred_vscdb: post-apply read failed path=${u.file_path}`);
+                continue;
+            }
+            const hw = tryResolveHardwareUuid();
+            if (!hw) {
+                hookRunLog(`deferred_vscdb: skip post-apply upload (hardware UUID unavailable) path=${u.file_path}`);
+                continue;
+            }
+            const sent = await sendConfigFile({ file_type: u.file_type, file_path: u.file_path, raw_content: rawContent }, hw, authKey);
+            hookRunLog(`deferred_vscdb: post-apply upload path=${u.file_path} ok=${sent}`);
+        }
+        unlinkSync(path);
+        return true;
+    }
+    catch (e) {
+        hookRunLog(`deferred_vscdb: apply failed: ${e instanceof Error ? e.message : String(e)}`);
+        return false;
+    }
+}
+/**
+ * macOS Cursor: after deferred **SQLite / state.vscdb** autofix — apply queued writes, SIGKILL, reopen project.
+ *
+ * When autofix used the deferred vscdb path, `applyAutofixViolations` replaces any manifest `restart_command`
+ * with this string (see compliance_check.ts). For **JSON settings-file** remediations only, the trusted template
+ * is the JSON-settings-only Cursor template (kill + reopen, no `apply_deferred_vscdb`).
+ */
+export function buildDeferredCursorRestartCommand() {
+    // Prefer monorepo path when hooks run from optimus-secure-fdn; otherwise `npx --yes log-llm-config@latest apply-deferred-vscdb`
+    // (package bin) so published installs work without a local dev_npx_packages copy.
+    return TRUSTED_CURSOR_SQLITE_DEFERRED_RESTART_COMMAND;
+}
+function sqliteRowGroupKey(dbPath, op) {
+    return `${dbPath}|${op.table}|${op.key_column}|${op.value_column}|${op.target_key}`;
+}
+/**
+ * Deferred sqlite path: one read per logical row, apply every `sqlite_op` merge in memory, then one queue
+ * entry per row. Without this, two ops on the same `composerState` row each read the stale DB and queue
+ * two full JSON blobs — the second UPDATE overwrites the first (e.g. only one of autoRun/fullAutoRun sticks).
+ */
+/** ItemTable keys must not contain SQL-quote garbage (bad vscdb #fragment or corrupted manifest). */
+function assertSafeDeferredItemTableKey(targetKey) {
+    if (!targetKey || targetKey.length > 512)
+        return false;
+    if (/['"\\]/.test(targetKey))
+        return false;
+    return true;
+}
+function queueDeferredSqliteOpsMerged(configPath, sqliteOps, postApplyUpload) {
+    const dbPath = configPath.split('#')[0];
+    hookRunLog(`sqlite_update: deferred_queue begin configPath=${configPath} dbPath=${dbPath} dbExists=${existsSync(dbPath)} sqliteOps=${sqliteOps.length}`);
+    complianceRunnerDiag(`sqlite_update: deferred_queue begin dbExists=${existsSync(dbPath)} ops=${sqliteOps.length}`);
+    if (!existsSync(dbPath)) {
+        const line = `sqlite_update: database not found at ${dbPath}`;
+        hookRunLog(line);
+        hookRunLog(`sqlite_update: parent dir exists=${existsSync(dirname(dbPath))} (if false, wrong Cursor profile path or never launched Cursor)`);
+        complianceRunnerDiag(line);
+        return {
+            ok: false,
+            reason: `state.vscdb not on disk at ${dbPath} (Cursor may not have created globalStorage yet — open Cursor once).`,
+        };
+    }
+    if (!assertSqlite3Available()) {
+        return {
+            ok: false,
+            reason: 'sqlite3 CLI not found (IDE hooks often have a minimal PATH). On macOS try OPTIMUS_SQLITE3=/usr/bin/sqlite3 or install sqlite3 and fix PATH.',
+        };
+    }
+    const resolvedOps = sqliteOps.map((op) => resolveCursorComposerSqliteOp(dbPath, op));
+    const groups = new Map();
+    for (const op of resolvedOps) {
+        const k = sqliteRowGroupKey(dbPath, op);
+        const arr = groups.get(k);
+        if (arr)
+            arr.push(op);
+        else
+            groups.set(k, [op]);
+    }
+    try {
+        for (const ops of groups.values()) {
+            const first = ops[0];
+            if (!assertSafeDeferredItemTableKey(first.target_key)) {
+                const line = `sqlite_update: rejected unsafe or empty target_key for deferred queue (refusing to write state.vscdb)`;
+                hookRunLog(line);
+                complianceRunnerDiag(`${line} target_key_preview=${first.target_key.slice(0, 80)}`);
+                return { ok: false, reason: 'unsafe or empty ItemTable target_key (see hook_log).' };
+            }
+            complianceRunnerDiag(`sqlite_update: deferred merge db=${dbPath} target_key=${first.target_key} operations=${ops.length}`);
+            let currentJson = {};
+            let rawSelectLength = 0;
+            try {
+                const result = sqliteSelectValueCell(dbPath, first.table, first.key_column, first.value_column, first.target_key);
+                rawSelectLength = result.length;
+                if (result) {
+                    const parsed = JSON.parse(result);
+                    currentJson = coerceItemTableValueToObjectRoot(first.target_key, parsed);
+                }
+            }
+            catch (e) {
+                const line = `sqlite_update: error querying database: ${e instanceof Error ? e.message : String(e)}`;
+                hookRunLog(line);
+                complianceRunnerDiag(line);
+                return {
+                    ok: false,
+                    reason: `sqlite read/parse failed: ${e instanceof Error ? e.message : String(e)}`,
+                };
+            }
+            for (const op of ops) {
+                mergeSqliteOpIntoJson(currentJson, op);
+            }
+            repairComposerStateEmptySegmentBug(currentJson);
+            const updatedJson = serializeItemTableValueForWrite(first.target_key, currentJson);
+            if (updatedJson === '{}' && Object.keys(currentJson).length === 0) {
+                const opSummary = ops
+                    .map((o) => `path=${o.json_path ?? ''} updates=${JSON.stringify(o.updates ?? {})}`)
+                    .join(' || ')
+                    .slice(0, 900);
+                const line = `sqlite_update: deferred merge produced empty JSON — refusing to queue (would wipe ItemTable row) target_key=${first.target_key} raw_cell_len=${rawSelectLength} ops=${opSummary}`;
+                hookRunLog(line);
+                complianceRunnerDiag(line.slice(0, 2000));
+                return {
+                    ok: false,
+                    reason: `merge produced empty JSON after ops (target_key=${first.target_key}, raw_cell_len=${rawSelectLength}). Check sqlite_update lines above for SELECT errors or bad sqlite_op merge.`,
+                };
+            }
+            queueDeferredVscdbItem({
+                dbPath,
+                table: first.table,
+                key_column: first.key_column,
+                value_column: first.value_column,
+                target_key: first.target_key,
+                new_value_json: updatedJson,
+            }, postApplyUpload);
+            const okLine = `sqlite_update: queued deferred write (merged ${ops.length} op(s)) for ${first.target_key} in ${dbPath}`;
+            hookRunLog(okLine);
+            complianceRunnerDiag(okLine);
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        const line = `sqlite_update: unexpected error: ${err instanceof Error ? err.message : String(err)}`;
+        hookRunLog(line);
+        complianceRunnerDiag(line);
+        return {
+            ok: false,
+            reason: `unexpected: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/**
+ * Read + merge JSON for a sqlite op; when `deferred`, queue UPDATE for after IDE exit (state.vscdb lock).
+ */
+function applyOrQueueSqliteJsonUpdate(configPath, sqliteOp, deferred) {
+    try {
+        const dbPath = configPath.split('#')[0];
+        complianceRunnerDiag(`sqlite_update: attempt db=${dbPath} target_key=${sqliteOp.target_key} json_path=${sqliteOp.json_path} deferred=${deferred}`);
+        if (!existsSync(dbPath)) {
+            const line = `sqlite_update: database not found at ${dbPath}`;
+            hookRunLog(line);
+            complianceRunnerDiag(line);
+            return false;
+        }
+        if (!assertSqlite3Available())
+            return false;
+        sqliteOp = resolveCursorComposerSqliteOp(dbPath, sqliteOp);
+        const { table, key_column, value_column, target_key } = sqliteOp;
+        if (!assertSafeSqliteIdentifiersForItemTable(table, key_column, value_column)) {
+            return false;
+        }
+        const safeName = target_key.replace(/'/g, "''");
+        let currentJson = {};
+        try {
+            const result = sqliteSelectValueCell(dbPath, table, key_column, value_column, target_key);
+            if (result) {
+                const parsed = JSON.parse(result);
+                currentJson = coerceItemTableValueToObjectRoot(target_key, parsed);
+            }
+        }
+        catch (e) {
+            const line = `sqlite_update: error querying database: ${e instanceof Error ? e.message : String(e)}`;
+            hookRunLog(line);
+            complianceRunnerDiag(line);
+            return false;
+        }
+        mergeSqliteOpIntoJson(currentJson, sqliteOp);
+        repairComposerStateEmptySegmentBug(currentJson);
+        const updatedJson = serializeItemTableValueForWrite(target_key, currentJson);
+        if (deferred) {
+            queueDeferredVscdbItem({
+                dbPath,
+                table,
+                key_column,
+                value_column,
+                target_key,
+                new_value_json: updatedJson,
+            });
+            const okLine = `sqlite_update: queued deferred write for ${target_key} in ${dbPath}`;
+            hookRunLog(okLine);
+            complianceRunnerDiag(okLine);
+            return true;
+        }
+        const safeJson = updatedJson.replace(/'/g, "''");
+        const updateSql = `UPDATE ${table} SET ${value_column}='${safeJson}' WHERE ${key_column}='${safeName}';`;
+        try {
+            sqliteExecWithTimeout(dbPath, updateSql);
+            const okLine = `sqlite_update: successfully updated ${target_key} in ${dbPath}`;
+            hookRunLog(okLine);
+            complianceRunnerDiag(okLine);
+            return true;
+        }
+        catch (e) {
+            const line = `sqlite_update: error updating database: ${e instanceof Error ? e.message : String(e)}`;
+            hookRunLog(line);
+            complianceRunnerDiag(line);
+            return false;
+        }
+    }
+    catch (err) {
+        const line = `sqlite_update: unexpected error: ${err instanceof Error ? err.message : String(err)}`;
+        hookRunLog(line);
+        complianceRunnerDiag(line);
+        return false;
+    }
+}
+export function enforceRemediation(instruction) {
+    const resolvedPath = resolveRemediationConfigPath(instruction.config_file_path);
+    const inst = resolvedPath === instruction.config_file_path
+        ? instruction
+        : { ...instruction, config_file_path: resolvedPath };
+    const fail = (reason, extra) => {
+        const spec = remediationFixSpec(inst);
+        logRemediationApplyFailure('enforceRemediation', {
+            uuid: inst.uuid,
+            config_file_path: inst.config_file_path,
+            file_type: inst.file_type ?? '',
+            finding_formatted_id: spec?.finding_formatted_id ?? '',
+            reason,
+            ...extra,
+        });
+        hookRunLog(`remediation_enforce: failed uuid=${inst.uuid} reason=${reason}`);
+        return { ok: false, failureReason: reason };
+    };
+    try {
+        const fixSpec = remediationFixSpec(inst);
+        const checks = fixSpec?.checks ?? [];
+        if (checks.length === 0) {
+            return fail('no checks in fix spec (empty or missing compliance checks)');
+        }
+        const sqliteOps = checks.filter((c) => {
+            const raw = c;
+            return raw.sqlite_op !== undefined;
+        });
+        if (sqliteOps.length > 0) {
+            complianceRunnerDiag(`remediation_enforce: sqlite path uuid=${inst.uuid} checks_with_sqlite=${sqliteOps.length}`);
+            const restartRequired = !!fixSpec?.restart_required;
+            if (restartRequired) {
+                const ops = sqliteOps.map((c) => c.sqlite_op);
+                const ft = inst.file_type?.trim();
+                const postApplyUpload = ft && inst.config_file_path.includes('#')
+                    ? { file_path: inst.config_file_path, file_type: ft }
+                    : undefined;
+                const q = queueDeferredSqliteOpsMerged(inst.config_file_path, ops, postApplyUpload);
+                if (!q.ok) {
+                    const dbOnly = inst.config_file_path.split('#')[0];
+                    return fail(`deferred state.vscdb queue failed — ${q.reason} (see sqlite_update lines above in hook_log for SELECT/exec details)`, {
+                        config_file_path: inst.config_file_path,
+                        resolved_db_path: dbOnly,
+                        sqlite3_binary: resolveSqlite3Binary() ?? 'unresolved',
+                    });
+                }
+                return { ok: true, deferredSqlite: true };
+            }
+            let allSuccess = true;
+            for (const check of sqliteOps) {
+                const raw = check;
+                const sqliteOp = raw.sqlite_op;
+                const rowOk = applyOrQueueSqliteJsonUpdate(inst.config_file_path, sqliteOp, false);
+                if (!rowOk)
+                    allSuccess = false;
+            }
+            if (!allSuccess) {
+                return fail('immediate sqlite apply failed for one or more checks');
+            }
+            return { ok: true, deferredSqlite: false };
+        }
+        if (fixSpec?.file_format !== 'json') {
+            return fail(`unsupported file format: ${String(fixSpec?.file_format ?? 'undefined')}`);
+        }
+        const dir = dirname(inst.config_file_path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        let configJson = {};
+        if (existsSync(inst.config_file_path)) {
+            try {
+                configJson = JSON.parse(readFileSync(inst.config_file_path, 'utf8'));
+            }
+            catch {
+                hookRunLog(`remediation_enforce: could not parse existing file, starting fresh uuid=${inst.uuid}`);
+            }
+        }
+        for (const check of checks) {
+            applyCheck(configJson, check);
+        }
+        const content = JSON.stringify(configJson, null, 2);
+        const tmp = `${inst.config_file_path}.tmp`;
+        writeFileSync(tmp, content, 'utf8');
+        renameSync(tmp, inst.config_file_path);
+        return { ok: true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error ? err.stack : undefined;
+        logRemediationApplyFailure('enforceRemediation', {
+            uuid: inst.uuid,
+            config_file_path: inst.config_file_path,
+            file_type: inst.file_type ?? '',
+            finding_formatted_id: remediationFixSpec(inst)?.finding_formatted_id ?? '',
+            reason: 'exception during enforce',
+            error: msg,
+            stack: stack ?? '',
+        });
+        hookRunLog(`remediation_enforce_error: uuid=${inst.uuid} err=${msg}`);
+        return { ok: false, failureReason: `exception: ${msg}` };
+    }
+}
+// ---------------------------------------------------------------------------
+// Autofix reporting
+// ---------------------------------------------------------------------------
+/**
+ * Fire-and-forget: notify the server that this machine applied an autofix for the given
+ * remediation UUID. Creates one EnforcementLog row on the server for the audit trail.
+ * Never throws — any failure is logged and silently swallowed so it cannot block the
+ * autofix flow.
+ */
+export function reportAutofixApplied(remediationUuid, result) {
+    const authKey = readStoredAuthKey();
+    if (!authKey) {
+        hookRunLog(`autofix_report: no auth key available, skipping report for uuid=${remediationUuid}`);
+        return Promise.resolve();
+    }
+    const hardwareUuid = tryResolveHardwareUuid();
+    if (!hardwareUuid) {
+        hookRunLog(`autofix_report: hardware UUID unavailable, skipping report for uuid=${remediationUuid}`);
+        return Promise.resolve();
+    }
+    const endpointBase = loadEndpointBase();
+    const url = buildApiUrl(endpointBase, '/endpoint_security/api/autofix-applied/');
+    const payload = { hardware_uuid: hardwareUuid, remediation_uuid: remediationUuid, result };
+    const signature = createSignature(payload, authKey.key);
+    const body = JSON.stringify({ ...payload, signature });
+    return executeBody(url, 'POST', body, 8000)
+        .then(({ statusCode }) => {
+        if (statusCode !== 200) {
+            hookRunLog(`autofix_report: server returned ${statusCode} for uuid=${remediationUuid}`);
+        }
+    })
+        .catch((err) => {
+        hookRunLog(`autofix_report: request failed for uuid=${remediationUuid}: ${err instanceof Error ? err.message : String(err)}`);
+    });
+}
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+export async function syncRemediations(endpointBase, machineUuid) {
+    let remediations = readInstructions().remediations;
+    const activeUuids = remediations.map((r) => r.uuid);
+    complianceRunnerDiag(`remediation_sync: begin endpoint=${endpointBase} machine_uuid=${machineUuid} local_rows=${remediations.length}`);
+    try {
+        if (!existsSync(getFileCollectionVscdbContractPath())) {
+            const pr = await getFileCollectionPatterns(endpointBase);
+            if (pr)
+                persistVscdbComposerContractFromPatternsResponse(pr);
+        }
+    }
+    catch {
+        /* contract also written on full log-config run */
+    }
+    let syncResult;
+    try {
+        syncResult = await fetchSync(endpointBase, machineUuid, activeUuids);
+    }
+    catch (err) {
+        const msg = `remediation_sync_error: ${err instanceof Error ? err.message : String(err)}`;
+        hookRunLog(msg);
+        complianceRunnerDiag(msg);
+        return;
+    }
+    if (!syncResult) {
+        hookRunLog(`remediation_sync: no response from server, skipping`);
+        complianceRunnerDiag('remediation_sync: no response from server (non-200 or empty body), skipping');
+        return;
+    }
+    if (syncResult.status === 'unchanged') {
+        hookRunLog(`remediation_sync: unchanged enforced=${activeUuids.length}`);
+        complianceRunnerDiag(`remediation_sync: server status=unchanged local_uuids=${activeUuids.length} — no new rows to fetch; if a deploy should exist, verify Finding.machine matches this hardware_uuid`);
+        const want = new Set(activeUuids);
+        const have = new Map(remediations.map((r) => [r.uuid, r]));
+        const needBackfill = activeUuids.some((u) => !have.has(u));
+        const haveIncomplete = remediations.some((r) => want.has(r.uuid) && needsManifestRefetch(r));
+        const haveOrphan = remediations.some((r) => !want.has(r.uuid));
+        const path = getRemediationInstructionsPath();
+        if (activeUuids.length > 0) {
+            if (needBackfill || haveIncomplete || haveOrphan || !existsSync(path)) {
+                try {
+                    await ensureInstructionsForUuids(endpointBase, machineUuid, want, null);
+                }
+                catch (err) {
+                    hookRunLog(`remediation_instructions_reconcile_error: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        else if (remediations.length > 0) {
+            try {
+                await ensureInstructionsForUuids(endpointBase, machineUuid, new Set(), null);
+            }
+            catch (err) {
+                hookRunLog(`remediation_instructions_reconcile_error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return;
+    }
+    const { added, removed } = syncResult;
+    hookRunLog(`remediation_sync: status=updated added=${added.length} removed=${removed.length}`);
+    complianceRunnerDiag(`remediation_sync: server status=updated added=${JSON.stringify(added)} removed=${JSON.stringify(removed)}`);
+    const removedSet = new Set(removed);
+    let removedCount = 0;
+    remediations = remediations.filter((r) => {
+        if (removedSet.has(r.uuid)) {
+            removedCount++;
+            hookRunLog(`remediation_remove: uuid=${r.uuid} path=${r.config_file_path}`);
+            return false;
+        }
+        return true;
+    });
+    let manifest = null;
+    if (added.length > 0) {
+        try {
+            manifest = await fetchManifest(endpointBase, machineUuid, added);
+        }
+        catch (err) {
+            const msg = `remediation_manifest_error: ${err instanceof Error ? err.message : String(err)}`;
+            hookRunLog(msg);
+            complianceRunnerDiag(msg);
+            if (removedCount > 0) {
+                remediations.sort((a, b) => a.uuid.localeCompare(b.uuid));
+                writeInstructions({ remediations });
+            }
+            return;
+        }
+        if (!manifest) {
+            hookRunLog(`remediation_sync: manifest fetch failed, skipping`);
+            complianceRunnerDiag('remediation_sync: manifest fetch failed (null), skipping — remediation_instructions.json not updated');
+            if (removedCount > 0) {
+                remediations.sort((a, b) => a.uuid.localeCompare(b.uuid));
+                writeInstructions({ remediations });
+            }
+            return;
+        }
+    }
+    const existingUuids = new Set(remediations.map((r) => r.uuid));
+    const addedSet = new Set(added);
+    const overlay = [];
+    for (const instruction of manifest ?? []) {
+        if (!addedSet.has(instruction.uuid))
+            continue;
+        if (existingUuids.has(instruction.uuid)) {
+            // Enforced remediations are always in `added`; overwrite local copy with fresh server data.
+            const idx = remediations.findIndex((r) => r.uuid === instruction.uuid);
+            if (idx >= 0)
+                remediations[idx] = instruction;
+        }
+        else {
+            remediations.push(instruction);
+            existingUuids.add(instruction.uuid);
+        }
+        overlay.push(instruction);
+        hookRunLog(`remediation_instructions_saved: uuid=${instruction.uuid} path=${instruction.config_file_path}`);
+    }
+    const addedCount = overlay.length;
+    if (added.length > 0 && addedCount === 0) {
+        const msg = `remediation_sync: manifest had no rows for added uuids=${added.join(',')} — check server manifest/machine linkage`;
+        hookRunLog(msg);
+        complianceRunnerDiag(`${msg} — remediation_instructions.json not written`);
+    }
+    if (removedCount > 0 || addedCount > 0) {
+        remediations.sort((a, b) => a.uuid.localeCompare(b.uuid));
+        writeInstructions({ remediations });
+        complianceRunnerDiag(`remediation_sync: wrote ${getRemediationInstructionsPath()} rows=${remediations.length} (added_from_manifest=${addedCount} removed=${removedCount})`);
+        const finalWant = new Set(remediations.map((r) => r.uuid));
+        try {
+            await ensureInstructionsForUuids(endpointBase, machineUuid, finalWant, overlay.length > 0 ? overlay : null);
+        }
+        catch (err) {
+            hookRunLog(`remediation_instructions_persist_error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Post-sync heartbeat: report the updated UUID set so the server has a before/after pair.
+        const finalUuids = remediations.map((r) => r.uuid);
+        try {
+            await fetchSync(endpointBase, machineUuid, finalUuids);
+            hookRunLog(`remediation_sync: post-sync heartbeat reported uuids=${finalUuids.length}`);
+        }
+        catch {
+            // Non-critical — skip silently.
+        }
+    }
+    hookRunLog(`remediation_sync: saved=${addedCount} removed=${removedCount}`);
+    complianceRunnerDiag(`remediation_sync: done saved=${addedCount} removed=${removedCount}`);
+}