@optimuslabs/harness-map-staging 1.5.16

package/dist/log_config_files/runtime/remediation_sync.js

@@ -0,0 +1,1705 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { executeBody } from '../../endpoint_client/http_transport.js';
+import { parseJsonWithJsoncFallback, parseTomlText, stringifyToml } from '../readers/file_readers.js';
+import { complianceRunnerDiag, hookRunLog, logRemediationApplyFailure } from './hook_logger.js';
+import { atomicWriteJson, getDeferredVscdbApplyPath, getFileCollectionVscdbContractPath, getRemediationInstructionsPath, readRemediationInstructionsFile, writeRemediationInstructionsFile, } from './management_storage.js';
+import { readStoredAuthKey } from '../auth/auth_key_store.js';
+import { ensureAuthentication } from '../auth/auth_flow.js';
+import { createSignature } from '../sender/signing.js';
+import { loadEndpointBase } from '../sender/endpoint_config.js';
+import { tryResolveHardwareUuid } from './hardware_uuid.js';
+import { clearRemediationApplyQuarantine, readRemediationApplyTrackingFile, writeRemediationApplyTrackingFile, } from './remediation_apply_tracking.js';
+import { CURSOR_SCALAR_ITEMTABLE_FIELDS, buildVscdbPostApplyRawContent, persistVscdbComposerContractFromPatternsResponse, } from '../readers/vscdb_reader.js';
+import { sendConfigFile } from '../sender/batch_sender.js';
+import { parseWorktreeRootFromPath } from './worktree_scanner.js';
+import { reportAbsentWorktrees } from './worktree_absent.js';
+import { buildApiUrl, getFileCollectionPatterns } from '../../endpoint_client/registry_api.js';
+import { resolveRemediationConfigPath } from './remediation_config_path.js';
+import { resolveOpsTargetPath } from './ops_target_path.js';
+import { execSqlite3, resolveSqlite3Binary } from './sqlite_binary.js';
+import { CURSOR_COMPOSER_SHADOW_KEYS } from '../readers/cursor_shadow_merge_ruleset.js';
+import { REACTIVE_STORAGE_ITEM_KEY_SUFFIX, composerShadowKeysFromContract, reactiveStorageItemKeyForVscdb, } from '../readers/vscdb_reactive_storage.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 composerShadowKeySetFromContract() {
+    return new Set(composerShadowKeysFromContract());
+}
+/** 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);
+    }
+}
+function applyClearApplyTrackingUuids(uuids) {
+    if (!uuids?.length)
+        return;
+    for (const uuid of uuids) {
+        clearRemediationApplyQuarantine(uuid);
+        hookRunLog(`remediation_sync: cleared apply quarantine uuid=${uuid}`);
+    }
+}
+/** When the server redeploys enforcement under a new UUID, keep local quarantine state. */
+function transferQuarantineForRetiredUuids(removed, added, retiredInstructions, addedInstructions) {
+    if (removed.length === 0 || added.length === 0 || addedInstructions.length === 0)
+        return;
+    const file = readRemediationApplyTrackingFile();
+    let changed = false;
+    for (const removedUuid of removed) {
+        const prev = file.entries[removedUuid];
+        if (!prev?.quarantined)
+            continue;
+        const retired = retiredInstructions.find((r) => r.uuid === removedUuid);
+        const retiredPath = retired?.config_file_path ?? '';
+        for (const inst of addedInstructions) {
+            if (!added.includes(inst.uuid))
+                continue;
+            if (retiredPath && inst.config_file_path !== retiredPath)
+                continue;
+            file.entries[inst.uuid] = {
+                ...prev,
+                pending_post_restart_verify: false,
+            };
+            changed = true;
+            hookRunLog(`remediation_sync: transferred quarantine ${removedUuid} -> ${inst.uuid} path=${inst.config_file_path}`);
+        }
+        delete file.entries[removedUuid];
+        changed = true;
+    }
+    if (changed)
+        writeRemediationApplyTrackingFile(file);
+}
+async function ensureAuthKeyForMachine(endpointBase, machineUuid) {
+    try {
+        return await ensureAuthentication(machineUuid, endpointBase);
+    }
+    catch (err) {
+        hookRunLog(`remediation_sync: ensureAuthentication failed: ${err instanceof Error ? err.message : String(err)}`);
+        complianceRunnerDiag(`remediation_sync: ensureAuthentication failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+function buildSignedMachinePostBody(machineUuid, fields, authKey) {
+    const payload = { machine_uuid: machineUuid, ...fields };
+    const signature = createSignature(payload, authKey.key);
+    return JSON.stringify({ ...payload, signature });
+}
+export async function fetchSync(endpointBase, machineUuid, activeUuids, timeoutMs = 8000) {
+    const sortedUuids = [...new Set(activeUuids.map((u) => u.trim()).filter(Boolean))].sort();
+    const authKey = await ensureAuthKeyForMachine(endpointBase, machineUuid);
+    if (!authKey) {
+        hookRunLog('remediation_sync_post: no auth key, skipping');
+        complianceRunnerDiag('remediation_sync_post: no auth key');
+        return null;
+    }
+    const url = buildApiUrl(endpointBase, '/api/findings/remediations/sync/');
+    const body = buildSignedMachinePostBody(machineUuid, { active_uuids: sortedUuids }, authKey);
+    let statusCode = 0;
+    let responseBody = '';
+    try {
+        const result = await executeBody(url, 'POST', body, timeoutMs);
+        statusCode = result.statusCode;
+        responseBody = result.body;
+    }
+    catch (err) {
+        const line = `remediation_sync_post: url=${url} error=${err instanceof Error ? err.message : String(err)}`;
+        hookRunLog(line);
+        complianceRunnerDiag(line);
+        return null;
+    }
+    if (statusCode !== 200 || !responseBody) {
+        const bodyHint = responseBody && responseBody.length < 500
+            ? ` body=${responseBody.replace(/\s+/g, ' ').trim()}`
+            : '';
+        const line = `remediation_sync_post: url=${url} status=${statusCode} bytes=${responseBody?.length ?? 0}${bodyHint}`;
+        hookRunLog(line);
+        complianceRunnerDiag(line);
+        return null;
+    }
+    try {
+        return JSON.parse(responseBody);
+    }
+    catch {
+        hookRunLog('remediation_sync_post: invalid JSON body');
+        complianceRunnerDiag('remediation_sync_post: invalid JSON body');
+        return null;
+    }
+}
+async function fetchManifest(endpointBase, machineUuid, uuids, timeoutMs = 8000) {
+    const sortedUuids = [...new Set(uuids.map((u) => u.trim()).filter(Boolean))].sort();
+    const authKey = await ensureAuthKeyForMachine(endpointBase, machineUuid);
+    if (!authKey) {
+        hookRunLog('remediation_manifest_post: no auth key, skipping');
+        complianceRunnerDiag('remediation_manifest_post: no auth key');
+        return null;
+    }
+    const url = buildApiUrl(endpointBase, '/api/findings/remediations/manifest/');
+    const body = buildSignedMachinePostBody(machineUuid, { uuids: sortedUuids }, authKey);
+    let statusCode = 0;
+    let responseBody = '';
+    try {
+        const result = await executeBody(url, 'POST', body, timeoutMs);
+        statusCode = result.statusCode;
+        responseBody = result.body;
+    }
+    catch (err) {
+        const line = `remediation_manifest_post: url=${url} error=${err instanceof Error ? err.message : String(err)}`;
+        hookRunLog(line);
+        complianceRunnerDiag(line);
+        return null;
+    }
+    if (statusCode !== 200 || !responseBody) {
+        const line = `remediation_manifest_post: url=${url} status=${statusCode} bytes=${responseBody?.length ?? 0}`;
+        hookRunLog(line);
+        complianceRunnerDiag(line);
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(responseBody);
+        if (!Array.isArray(parsed.remediations)) {
+            complianceRunnerDiag('remediation_manifest_post: 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_post: 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 deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEqual(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const aKeys = Object.keys(ao);
+    const bKeys = Object.keys(bo);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const k of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(bo, k))
+            return false;
+        if (!deepEqual(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}
+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;
+}
+export const GLOBAL_CURSOR_IGNORE_SETTING_PATH = 'cursor.general.globalCursorIgnoreList';
+export function isGlobalCursorIgnoreRemediationViolation(v) {
+    return (v.setting_path ?? '').trim() === GLOBAL_CURSOR_IGNORE_SETTING_PATH;
+}
+/** Match server scan: flat VS Code key wins when present (including []). */
+export function globalCursorIgnoreListFromSettings(configJson) {
+    const flat = configJson[GLOBAL_CURSOR_IGNORE_SETTING_PATH];
+    if (Array.isArray(flat))
+        return flat;
+    const nested = getByPath(configJson, GLOBAL_CURSOR_IGNORE_SETTING_PATH);
+    if (Array.isArray(nested))
+        return nested;
+    return [];
+}
+export function persistGlobalCursorIgnoreList(configJson, list) {
+    configJson[GLOBAL_CURSOR_IGNORE_SETTING_PATH] = list;
+    setByPathNested(configJson, GLOBAL_CURSOR_IGNORE_SETTING_PATH, list);
+}
+/** Keep flat and nested global ignore lists aligned; prefer flat when it is an array. */
+function syncFlatGlobalCursorIgnoreListKey(configJson) {
+    const flat = configJson[GLOBAL_CURSOR_IGNORE_SETTING_PATH];
+    if (Array.isArray(flat)) {
+        setByPathNested(configJson, GLOBAL_CURSOR_IGNORE_SETTING_PATH, flat);
+        return;
+    }
+    const nested = getByPath(configJson, GLOBAL_CURSOR_IGNORE_SETTING_PATH);
+    if (Array.isArray(nested)) {
+        configJson[GLOBAL_CURSOR_IGNORE_SETTING_PATH] = nested;
+    }
+}
+function listForComplianceTarget(configJson, targetPath) {
+    if (targetPath === GLOBAL_CURSOR_IGNORE_SETTING_PATH) {
+        return [...globalCursorIgnoreListFromSettings(configJson)];
+    }
+    const curVal = getByPath(configJson, targetPath);
+    return Array.isArray(curVal) ? [...curVal] : [];
+}
+function writeListAtComplianceTarget(configJson, targetPath, next) {
+    if (targetPath === GLOBAL_CURSOR_IGNORE_SETTING_PATH) {
+        persistGlobalCursorIgnoreList(configJson, next);
+        return;
+    }
+    setByPath(configJson, targetPath, 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 = resolveOpsTargetPath(check.setting_path, k);
+            if (set && Object.prototype.hasOwnProperty.call(set, k)) {
+                const value = set[k];
+                if (targetPath === GLOBAL_CURSOR_IGNORE_SETTING_PATH && Array.isArray(value)) {
+                    persistGlobalCursorIgnoreList(configJson, value);
+                }
+                else {
+                    setByPath(configJson, targetPath, value);
+                }
+                continue;
+            }
+            const cur = listForComplianceTarget(configJson, targetPath);
+            const toRemove = (remove && remove[k]) ?? [];
+            const toAdd = (add && add[k]) ?? [];
+            const next = cur.filter((x) => !toRemove.some((item) => deepEqual(item, x)));
+            for (const x of toAdd) {
+                if (!next.some((item) => deepEqual(item, x))) {
+                    next.push(x);
+                }
+            }
+            writeListAtComplianceTarget(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);
+}
+// ---------------------------------------------------------------------------
+// SQLite remediation support
+// ---------------------------------------------------------------------------
+function escapeRegExpForAllowlist(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function allowlistEntryMatchesRemoveToken(entry, token) {
+    const valStr = String(entry).toLowerCase();
+    const t = token.toLowerCase().trim();
+    if (!t)
+        return false;
+    const first = valStr.trim().split(/\s+/)[0] ?? '';
+    if (first === t || valStr === t)
+        return true;
+    const pattern = new RegExp(`(^|[^a-z0-9_|])${escapeRegExpForAllowlist(t)}([^a-z0-9_|]|$)`);
+    return pattern.test(valStr);
+}
+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.
+ *   Routing matches shell hooks (`optimus-compliance-check.sh`): read `~/.optimuslabs/management/optimus_dev.env`
+ *   (then `OPTIMUS_ENVIRONMENT`), use `npx=` base for local `dist` when `environment=development`,
+ *   `@optimuslabs/harness-map-staging@latest` when `environment=staging`, else production package.
+ * - **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}/.optimuslabs/management/vscdb/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; STATIC_DEV_ENV=\"\$HOME/.optimuslabs/management/optimus_dev.env\"; ENV_LABEL=\"\"; if [ -f \"\$STATIC_DEV_ENV\" ]; then ENV_LABEL=\$(grep -E \"^(environment|ENVIRONMENT|OPTIMUS_ENVIRONMENT)=\" \"\$STATIC_DEV_ENV\" 2>/dev/null | head -1 | cut -d\"=\" -f2- | tr \"[:upper:]\" \"[:lower:]\" | xargs); fi; if [ -z \"\$ENV_LABEL\" ] && [ -n \"\${OPTIMUS_ENVIRONMENT:-}\" ]; then ENV_LABEL=\$(printf \"%s\" \"\$OPTIMUS_ENVIRONMENT\" | tr \"[:upper:]\" \"[:lower:]\" | xargs); fi; [ -z \"\$ENV_LABEL\" ] && ENV_LABEL=\"production\"; NPX_BASE=\"\"; if [ -f \"\$STATIC_DEV_ENV\" ]; then _nb=\$(grep -E \"^npx=\" \"\$STATIC_DEV_ENV\" 2>/dev/null | head -1 | cut -d\"=\" -f2- | xargs); [ -n \"\$_nb\" ] && [ -d \"\$_nb\" ] && NPX_BASE=\"\$_nb\"; fi; p=\"\${npm_config_prefix:-\${NPM_CONFIG_PREFIX:-}}\"; gp=\"\${npm_config_global_prefix:-}\"; gc=\"\${npm_config_globalconfig:-}\"; if [[ \"\$p\" == *\"/Applications/Cursor.app/\"* ]] || [[ \"\$gp\" == *\"/Applications/Cursor.app/\"* ]] || [[ \"\$gc\" == *\"/Applications/Cursor.app/\"* ]]; then unset npm_config_prefix NPM_CONFIG_PREFIX npm_config_global_prefix npm_config_globalconfig npm_node_execpath 2>/dev/null; fi; APPLY_EC=0; if [ -f \"\$REPO_ROOT/dev_npx_packages/log-llm-config/dist/apply_deferred_vscdb.js\" ]; then echo deferred_restart:apply_via_dev_npx_packages; node \"\$REPO_ROOT/dev_npx_packages/log-llm-config/dist/apply_deferred_vscdb.js\"; APPLY_EC=\$?; elif [ \"\$ENV_LABEL\" = \"development\" ] && [ -n \"\$NPX_BASE\" ] && [ -f \"\$NPX_BASE/optimuslabs/log-llm-config/dist/apply_deferred_vscdb.js\" ]; then echo deferred_restart:apply_via_optimus_npx_base; node \"\$NPX_BASE/optimuslabs/log-llm-config/dist/apply_deferred_vscdb.js\"; APPLY_EC=\$?; elif command -v npx >/dev/null 2>&1; then echo deferred_restart:apply_via_npx env=\"\$ENV_LABEL\"; cd \"\$REPO_ROOT\" || true; if [ \"\$ENV_LABEL\" = \"staging\" ]; then npx --yes --package=@optimuslabs/harness-map-staging@latest apply-deferred-vscdb-staging; APPLY_EC=\$?; else npx --yes --package=@optimuslabs/harness-map@latest apply-deferred-vscdb; APPLY_EC=\$?; fi; else echo deferred_restart:no_npx; APPLY_EC=127; 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; env -u npm_config_package -u npm_lifecycle_event -u npm_lifecycle_script -u npm_config_local_prefix 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";
+/** Legacy manifests; hooks may run with cwd under `.cursor` where `pwd` is wrong. */
+const TRUSTED_CURSOR_JSON_SETTINGS_RESTART_COMMAND_LEGACY = '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_CURSOR_JSON_SETTINGS_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 && ' +
+    "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'";
+export function isClaudeRestartCommand(cmd) {
+    return cmd.trim() === TRUSTED_CLAUDE_RESTART_COMMAND;
+}
+export function isCursorRestartCommand(cmd) {
+    const t = cmd.trim();
+    return (t === TRUSTED_CURSOR_SQLITE_DEFERRED_RESTART_COMMAND ||
+        t === TRUSTED_CURSOR_JSON_SETTINGS_RESTART_COMMAND ||
+        t === TRUSTED_CURSOR_JSON_SETTINGS_RESTART_COMMAND_LEGACY);
+}
+/**
+ * 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_CURSOR_JSON_SETTINGS_RESTART_COMMAND_LEGACY ||
+        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 = reactiveStorageItemKeyForVscdb(dbPath);
+    /** 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 || jp === 'composerState') {
+            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;
+    }
+    // Bare JSON array (e.g. cursor/disabledMcpServers): wrap under target_key so array_union_add
+    // can locate and mutate it via mergeSqliteOpIntoJson.
+    if (Array.isArray(parsed)) {
+        return { [targetKey]: 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) {
+    // Bare-array keys: root was wrapped as { [targetKey]: array } by coerceItemTableValueToObjectRoot.
+    // Unwrap back to a bare JSON array before writing.
+    const keys = Object.keys(root);
+    if (keys.length === 1 && keys[0] === targetKey && Array.isArray(root[targetKey])) {
+        return JSON.stringify(root[targetKey]);
+    }
+    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) {
+    // Array union: target_key holds a bare JSON array (e.g. cursor/disabledMcpServers).
+    // currentJson here is the coerced object root — the raw array is stored under target_key.
+    if (sqliteOp.array_union_add?.length) {
+        const key = sqliteOp.target_key;
+        const existing = currentJson[key];
+        const arr = Array.isArray(existing) ? existing : [];
+        const lowerSet = new Set(arr.map((v) => String(v).toLowerCase()));
+        for (const item of sqliteOp.array_union_add) {
+            if (!lowerSet.has(item.toLowerCase())) {
+                arr.push(item);
+                lowerSet.add(item.toLowerCase());
+            }
+        }
+        currentJson[key] = arr;
+        return;
+    }
+    if (sqliteOp.array_remove?.length) {
+        const jp = (sqliteOp.json_path ?? '').trim();
+        const removeSet = new Set(sqliteOp.array_remove.map((v) => String(v)));
+        if (!jp) {
+            const key = sqliteOp.target_key;
+            const existing = currentJson[key];
+            const arr = Array.isArray(existing) ? [...existing] : [];
+            currentJson[key] = arr.filter((x) => !removeSet.has(String(x)));
+            return;
+        }
+        const parts = jp.split('.').filter(Boolean);
+        if (parts.length === 0)
+            return;
+        let node = currentJson;
+        for (const p of parts.slice(0, -1)) {
+            if (node == null || typeof node !== 'object' || Array.isArray(node))
+                return;
+            node = node[p];
+        }
+        if (node == null || typeof node !== 'object' || Array.isArray(node))
+            return;
+        const container = node;
+        const arrayKey = parts[parts.length - 1];
+        const existing = container[arrayKey];
+        if (!Array.isArray(existing))
+            return;
+        container[arrayKey] = existing.filter((x) => !removeSet.has(String(x)));
+        return;
+    }
+    if (sqliteOp.remove_commands?.length &&
+        (sqliteOp.json_path ?? '').includes('yoloCommandAllowlist') &&
+        !sqliteOp.array_remove?.length) {
+        const jp = (sqliteOp.json_path ?? '').trim();
+        const parts = jp.split('.').filter(Boolean);
+        if (parts.length === 0)
+            return;
+        let node = currentJson;
+        for (const p of parts.slice(0, -1)) {
+            if (node == null || typeof node !== 'object' || Array.isArray(node))
+                return;
+            node = node[p];
+        }
+        if (node == null || typeof node !== 'object' || Array.isArray(node))
+            return;
+        const container = node;
+        const arrayKey = parts[parts.length - 1];
+        const existing = container[arrayKey];
+        if (!Array.isArray(existing))
+            return;
+        const tokens = sqliteOp.remove_commands.map((t) => String(t).trim()).filter(Boolean);
+        container[arrayKey] = existing.filter((entry) => !tokens.some((t) => allowlistEntryMatchesRemoveToken(entry, t)));
+        return;
+    }
+    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;
+    }
+    const updates = sqliteOp.updates ?? {};
+    let jsonPath = sqliteOp.json_path ?? '';
+    const shadowKeys = new Set(CURSOR_COMPOSER_SHADOW_KEYS);
+    if (!jsonPath.trim() && Object.keys(updates).some((k) => shadowKeys.has(k))) {
+        const nested = currentJson.composerState;
+        if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+            jsonPath = 'composerState';
+        }
+    }
+    mergeJsonAtSqlitePath(currentJson, jsonPath, updates);
+    const opForMirror = jsonPath === (sqliteOp.json_path ?? '') ? sqliteOp : { ...sqliteOp, json_path: jsonPath };
+    mirrorComposerShadowKeysToReactiveRoot(currentJson, opForMirror);
+}
+/**
+ * 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 targetKey = resolvedOp.target_key;
+    const contractKey = reactiveStorageItemKeyForVscdb();
+    const reactiveTarget = (contractKey && targetKey === contractKey) ||
+        (typeof targetKey === 'string' &&
+            targetKey.includes(REACTIVE_STORAGE_ITEM_KEY_SUFFIX) &&
+            !/['"\\]/.test(targetKey));
+    if (!reactiveTarget)
+        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 execSqlite3(sqlite3, ['-noheader', dbPath], script).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 {
+        execSqlite3(sqlite3, [dbPath], script);
+    }
+    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 = execSqlite3(sqlite3, [dbPath], script).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 {
+        let applied = 0;
+        let skippedMissing = 0;
+        for (const it of payload.items) {
+            // Workspace storage can disappear between queue and restart (Cursor GC). Skip those
+            // items instead of aborting the whole batch — other workspaces still need the write.
+            if (!existsSync(it.dbPath)) {
+                hookRunLog(`deferred_vscdb: database missing — skipping ${it.dbPath}`);
+                skippedMissing++;
+                continue;
+            }
+            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 = `INSERT OR REPLACE INTO ${it.table} (${it.key_column}, ${it.value_column}) VALUES ('${safeName}', '${safeJson}');`;
+            const changed = sqliteRunUpdateReturningChanges(it.dbPath, sql);
+            if (changed < 1) {
+                hookRunLog(`deferred_vscdb: INSERT OR REPLACE changed 0 rows key=${it.target_key} db=${it.dbPath} — keeping queue file`);
+                return false;
+            }
+            applied++;
+        }
+        hookRunLog(`deferred_vscdb: applied ${applied} queued update(s) skipped_missing=${skippedMissing}`);
+        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 = buildVscdbPostApplyRawContent(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, use
+ * {@link buildCursorJsonSettingsRestartCommand} (kill + reopen).
+ */
+export function buildDeferredCursorRestartCommand() {
+    // Prefer monorepo path when hooks run from optimus-secure-fdn; otherwise `npx --yes --package=@optimuslabs/harness-map@latest apply-deferred-vscdb`
+    // (package bin) so published installs work without a local dev_npx_packages copy.
+    return TRUSTED_CURSOR_SQLITE_DEFERRED_RESTART_COMMAND;
+}
+export function buildCursorJsonSettingsRestartCommand() {
+    return TRUSTED_CURSOR_JSON_SETTINGS_RESTART_COMMAND;
+}
+/**
+ * Cursor JSON settings are written synchronously; when local recheck passes, report verified before
+ * restart (restart only reloads disk into the running app). Deferred state.vscdb must wait until
+ * apply_deferred_vscdb runs in the trusted restart script, then the next compliance gate.
+ */
+export function cursorAutofixDefersInlineVerify(ide, restartCommandCount, deferredSqlitePending, recheckOk) {
+    if (ide !== 'cursor' || restartCommandCount === 0)
+        return false;
+    if (deferredSqlitePending)
+        return true;
+    if (recheckOk)
+        return false;
+    return true;
+}
+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;
+    }
+}
+/**
+ * Return paths to every state.vscdb found under workspaceStoragePath/<hash>/state.vscdb.
+ * Used for the apply_to_all_workspaces fallback when no specific workspace vscdb was collected.
+ * Exported so compliance_check.ts can verify workspace vscdb state during ops-based checks.
+ */
+export function discoverAllWorkspaceVscdbs(workspaceStoragePath) {
+    if (!existsSync(workspaceStoragePath))
+        return [];
+    try {
+        return readdirSync(workspaceStoragePath, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => join(workspaceStoragePath, e.name, 'state.vscdb'))
+            .filter((p) => existsSync(p));
+    }
+    catch {
+        return [];
+    }
+}
+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 ops = sqliteOps.map((c) => c.sqlite_op);
+            const firstOp = ops[0];
+            // apply_to_all_workspaces: no specific vscdb was collected — discover and patch every
+            // workspaceStorage/<hash>/state.vscdb on disk (fallback for mcp_config-linked findings).
+            if (firstOp?.apply_to_all_workspaces) {
+                const segments = firstOp.workspace_storage_path_segments ?? [
+                    'Library', 'Application Support', 'Cursor', 'User', 'workspaceStorage',
+                ];
+                const wsPath = join(homedir(), ...segments);
+                const vscdbPaths = discoverAllWorkspaceVscdbs(wsPath);
+                hookRunLog(`remediation_enforce: apply_to_all_workspaces uuid=${inst.uuid} wsPath=${wsPath} found=${vscdbPaths.length}`);
+                if (vscdbPaths.length === 0) {
+                    return fail(`no workspace vscdbs found at ${wsPath} (open Cursor in at least one project first)`);
+                }
+                let anyOk = false;
+                for (const vscdbPath of vscdbPaths) {
+                    // Queue a post-apply upload for each workspace vscdb so that after the deferred
+                    // SQLite write is applied at restart time, the updated cursor/disabledMcpServers
+                    // value is immediately sent to the server.  This closes the race condition where
+                    // the user re-enables the server between the enforcement write and the next
+                    // scheduled log-config run: the upload after the deferred apply gives the server
+                    // the authoritative disabled state without waiting for a full log-config cycle.
+                    const postApplyUpload = {
+                        file_path: `${vscdbPath}#${firstOp.target_key}`,
+                        file_type: 'cursor_workspace_vscdb',
+                    };
+                    const q = queueDeferredSqliteOpsMerged(vscdbPath, ops, postApplyUpload);
+                    if (q.ok) {
+                        anyOk = true;
+                        hookRunLog(`remediation_enforce: queued apply_to_all_workspaces op for ${vscdbPath}`);
+                    }
+                    else {
+                        hookRunLog(`remediation_enforce: skip ${vscdbPath}: ${q.reason}`);
+                    }
+                }
+                if (!anyOk) {
+                    return fail('all workspace vscdb deferred writes failed (see sqlite_update lines above)');
+                }
+                return { ok: true, deferredSqlite: true };
+            }
+            const restartRequired = !!fixSpec?.restart_required;
+            if (restartRequired) {
+                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' && fixSpec?.file_format !== 'toml') {
+            return fail(`unsupported file format: ${String(fixSpec?.file_format ?? 'undefined')}`);
+        }
+        const worktreeRoot = parseWorktreeRootFromPath(inst.config_file_path);
+        if (worktreeRoot && !existsSync(worktreeRoot)) {
+            void reportAbsentWorktrees([
+                {
+                    worktree_root: worktreeRoot,
+                    reason: 'path_missing_on_remediate',
+                    source_path: inst.config_file_path,
+                },
+            ]);
+            return fail('worktree_absent');
+        }
+        const dir = dirname(inst.config_file_path);
+        if (worktreeRoot) {
+            if (!existsSync(dir)) {
+                return fail('worktree_path_missing');
+            }
+        }
+        else if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        const isToml = fixSpec?.file_format === 'toml';
+        let configObj = {};
+        if (existsSync(inst.config_file_path)) {
+            const rawText = readFileSync(inst.config_file_path, 'utf8');
+            if (isToml) {
+                const parsed = parseTomlText(rawText);
+                if (parsed !== null) {
+                    configObj = parsed;
+                }
+                else {
+                    hookRunLog(`remediation_enforce: could not parse existing TOML file, starting fresh uuid=${inst.uuid}`);
+                }
+            }
+            else {
+                // OpenCode configs are JSONC; parse strict JSON first, then JSONC fallback so a
+                // comment-bearing opencode.json(c) keeps its existing settings instead of being reset to
+                // {} on a parse failure. NOTE: the write-back below is JSON.stringify, so comments and
+                // trailing commas in the original file are not preserved (same as every other agent's
+                // JSON config) — only the key/value settings are retained and patched.
+                const parsed = parseJsonWithJsoncFallback(rawText);
+                if (parsed !== null) {
+                    configObj = parsed;
+                }
+                else {
+                    hookRunLog(`remediation_enforce: could not parse existing file, starting fresh uuid=${inst.uuid}`);
+                }
+            }
+        }
+        for (const check of checks) {
+            applyCheck(configObj, check);
+        }
+        syncFlatGlobalCursorIgnoreListKey(configObj);
+        const content = isToml ? stringifyToml(configObj) : JSON.stringify(configObj, 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}` };
+    }
+}
+/**
+ * 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, details) {
+    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,
+    };
+    if (details?.failure_reason)
+        payload.failure_reason = details.failure_reason.slice(0, 2000);
+    if (details?.consecutive_failures != null)
+        payload.consecutive_failures = details.consecutive_failures;
+    const bodyPayload = { ...payload, signature: '' };
+    if (details?.config_snapshot_after && typeof details.config_snapshot_after === 'object') {
+        bodyPayload.config_snapshot_after = details.config_snapshot_after;
+    }
+    const signature = createSignature(payload, authKey.key);
+    const body = JSON.stringify({ ...bodyPayload, signature });
+    return executeBody(url, 'POST', body, 8000)
+        .then(({ statusCode }) => {
+        if (statusCode === 200) {
+            hookRunLog(`autofix_report: ok result=${result} uuid=${remediationUuid}`);
+        }
+        else {
+            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;
+    }
+    applyClearApplyTrackingUuids(syncResult.clear_apply_tracking_uuids);
+    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);
+    const retiredInstructions = remediations.filter((r) => removedSet.has(r.uuid));
+    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}`);
+    }
+    transferQuarantineForRetiredUuids(removed, added, retiredInstructions, overlay);
+    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}`);
+}