@optimuslabs/harness-map-staging 1.5.16

package/dist/log_config_files/runtime/compliance_check.js

@@ -0,0 +1,1013 @@
+/**
+ * Compliance check: types and check runner entry point.
+ *
+ * Compliance is in-memory only (no compliance.json): runLocalRemediationComplianceCheck returns
+ * ComplianceStatus; the prompt gate and tests use that return value. Autofix may write config files
+ * and remediation_instructions.json via applyAutofixViolations / enforceRemediation.
+ *
+ * Prompt gate: compliance_prompt_gate runs runLocalRemediationComplianceCheck then applyAutofixViolations.
+ * Background: compliance_check_runner runs syncRemediations (network) then the same local check.
+ * Apply (autofix) is intentionally left to the gate on the next prompt — the background pass only
+ * downloads the latest manifest so the gate has fresh data to act on.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parseJsonWithJsoncFallback, parseTomlText } from '../readers/file_readers.js';
+import { mergeComposerShadowKeysFromReactiveBlob, readVscdbItemTableJson, } from '../readers/vscdb_reader.js';
+import { readRemediationInstructionsFile, writeRemediationInstructionsFile, } from './management_storage.js';
+import { resolveRemediationConfigPath, resolveRemediationUploadFileType } from './remediation_config_path.js';
+import { resolveOpsTargetPath } from './ops_target_path.js';
+import { isRemediationQuarantined, markRemediationApplyPendingVerification, markRemediationApplyVerified, processPendingPostRestartVerifications, readRemediationApplyTrackingFile, writeRemediationApplyTrackingFile, } from './remediation_apply_tracking.js';
+import { complianceRunnerDiag, hookRunLog, logRemediationApplyFailure } from './hook_logger.js';
+import { isEnvBackedSecretValue, scanJsonForHardcodedSecrets, } from './secret_regex_scan.js';
+import { loadEndpointBase } from '../sender/endpoint_config.js';
+import { resolveHardwareUuid, tryResolveHardwareUuid } from './hardware_uuid.js';
+import { buildDeferredCursorRestartCommand, discoverAllWorkspaceVscdbs, enforceRemediation, fetchSync, globalCursorIgnoreListFromSettings, GLOBAL_CURSOR_IGNORE_SETTING_PATH, isTrustedRestartCommandForAutofix, remediationFixSpec, reportAutofixApplied, syncRemediations, } from './remediation_sync.js';
+import { sendConfigFile } from '../sender/batch_sender.js';
+import { ensureAuthentication } from '../auth/auth_flow.js';
+/** Normalize manifest/env/CLI agent tokens to a known Agent, or '' if unrecognized. */
+export function normalizeAgentToken(raw) {
+    if (typeof raw !== 'string')
+        return '';
+    const s = raw.trim().toLowerCase();
+    if (!s)
+        return '';
+    if (s === 'claude-desktop')
+        return 'claude_desktop';
+    if (s === 'claude_desktop')
+        return 'claude_desktop';
+    if (s === 'claude')
+        return 'claude';
+    if (s === 'cursor')
+        return 'cursor';
+    if (s === 'copilot')
+        return 'copilot';
+    if (s === 'opencode')
+        return 'opencode';
+    if (s === 'codex')
+        return 'codex';
+    return '';
+}
+function currentAgentFromEnv() {
+    // Allow explicit override for debugging / special launchers.
+    const override = normalizeAgentToken(process.env.OPTIMUS_AGENT);
+    if (override)
+        return override;
+    // Backwards-compatible: hook wrappers set OPTIMUS_HOOK_TYPE to cursor|claude|copilot|opencode.
+    const hookType = normalizeAgentToken(process.env.OPTIMUS_HOOK_TYPE);
+    if (hookType === 'cursor')
+        return 'cursor';
+    if (hookType === 'copilot')
+        return 'copilot';
+    if (hookType === 'opencode')
+        return 'opencode';
+    if (hookType === 'codex')
+        return 'codex';
+    return 'claude';
+}
+function targetsCurrentAgent(entry, agent) {
+    // Prefer top-level manifest field; fall back to embedded fix payload for older local files.
+    const embedded = (entry.fix && typeof entry.fix === 'object'
+        ? entry.fix.target_agent
+        : null) ??
+        (entry.compliance && typeof entry.compliance === 'object'
+            ? entry.compliance.target_agent
+            : null);
+    const t = entry.target_agent ?? embedded;
+    // Backwards compat: missing/empty target_agent means "applies to all agents".
+    if (t === null || t === undefined)
+        return true;
+    if (typeof t !== 'string') {
+        complianceRunnerDiag(`Ignoring remediation with non-string target_agent: ${String(t)}`);
+        return false;
+    }
+    if (!t.trim())
+        return true;
+    const normalized = normalizeAgentToken(t);
+    if (!normalized) {
+        complianceRunnerDiag(`Ignoring remediation with unknown target_agent: ${t}`);
+        return false;
+    }
+    return normalized === agent;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * ItemTable keys use slashes (e.g. cursorai/donotchange/privacyMode) and do not contain dots.
+ * Compliance setting_path is `${itemKey}.${nested.path}` — take the segment before the first `.`.
+ */
+export function itemTableKeyFromSettingPath(settingPath) {
+    const i = settingPath.indexOf('.');
+    return i === -1 ? settingPath : settingPath.slice(0, i);
+}
+/**
+ * Compliance reads the live config at `config_file_path` (#itemKey), but sqlite apply may target
+ * a different ItemTable row. Verify against the manifest path's item key, not the apply target.
+ */
+export function canonicalComplianceSettingPath(configFilePath, check) {
+    const settingPath = check.setting_path;
+    const applyKey = check.sqlite_op?.target_key?.trim();
+    if (!applyKey || applyKey === settingPath)
+        return settingPath;
+    const hashIdx = configFilePath.indexOf('#');
+    if (hashIdx < 0)
+        return settingPath;
+    const verifyKey = configFilePath.slice(hashIdx + 1).trim();
+    if (!verifyKey || applyKey === verifyKey)
+        return settingPath;
+    const prefix = `${applyKey}.`;
+    if (settingPath === applyKey)
+        return verifyKey;
+    if (settingPath.startsWith(prefix))
+        return `${verifyKey}${settingPath.slice(applyKey.length)}`;
+    return settingPath;
+}
+/** Traverse a JSON object using dot-notation path. Returns undefined if any segment is missing. */
+export function getByPath(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        // Cursor composerState.modes4: non-numeric segment indexes by mode id (agent row is not always [0]).
+        if (Array.isArray(current) && !/^\d+$/.test(part)) {
+            const idx = current.findIndex((item) => item !== null &&
+                typeof item === 'object' &&
+                item.id === part);
+            current = idx >= 0 ? current[idx] : undefined;
+            continue;
+        }
+        current = current[part];
+    }
+    return current;
+}
+/** Key-order-independent deep-equal comparison (handles primitives, arrays, plain objects). */
+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 isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Match Cursor yolo allowlist entries (same boundary idea as server filter_yolo_allowlist_entries). */
+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_|])${escapeRegExp(t)}([^a-z0-9_|]|$)`);
+    return pattern.test(valStr);
+}
+/**
+ * MCP secret remediations deploy ops.set to ${env:KEY}. Local compliance passes when the
+ * user picks any env reference, not only the exact string from the manifest.
+ */
+function remediationSetOpSatisfied(current, expected) {
+    if (deepEqual(current, expected))
+        return true;
+    if (typeof expected === 'string' &&
+        isEnvBackedSecretValue(expected) &&
+        isEnvBackedSecretValue(current)) {
+        return true;
+    }
+    return false;
+}
+function violationFromSecretScanFinding(entry, compliance, finding) {
+    return {
+        uuid: entry.uuid,
+        finding_formatted_id: compliance.finding_formatted_id,
+        setting_path: finding.path,
+        description: compliance.description,
+        finding_title: entry.finding_title,
+        finding_description: entry.finding_description,
+        ruleset_name: entry.ruleset_name,
+        severity: compliance.severity,
+        autofix_allowed: compliance.autofix_allowed,
+        config_file_path: entry.config_file_path,
+        expected_value: { op: 'secret_scan', path: finding.path, secret_type: finding.secretType },
+        message: `[${compliance.finding_formatted_id}] ${entry.finding_title ?? compliance.description}\nDescription: ${entry.finding_description ?? compliance.description}\nHow to fix: Remove the hardcoded ${finding.secretType} from ${finding.path} in ${entry.config_file_path}`,
+    };
+}
+function currentArrayAtComplianceTarget(configJson, targetPath) {
+    if (configJson &&
+        typeof configJson === 'object' &&
+        !Array.isArray(configJson) &&
+        targetPath === GLOBAL_CURSOR_IGNORE_SETTING_PATH) {
+        return globalCursorIgnoreListFromSettings(configJson);
+    }
+    const cur = getByPath(configJson, targetPath);
+    return Array.isArray(cur) ? cur : [];
+}
+function verifyOpsApplied(configJson, settingPath, ops) {
+    const parts = settingPath.split('.');
+    const leafKey = parts[parts.length - 1] ?? '';
+    const parentPath = parts.slice(0, -1).join('.');
+    const set = ops.set ?? {};
+    const add = ops.add ?? {};
+    const remove = ops.remove ?? {};
+    const keys = new Set([...Object.keys(set), ...Object.keys(add), ...Object.keys(remove)]);
+    for (const k of keys) {
+        const targetPath = resolveOpsTargetPath(settingPath, k);
+        if (Object.prototype.hasOwnProperty.call(set, k)) {
+            const expected = set[k];
+            const currentForSet = targetPath === GLOBAL_CURSOR_IGNORE_SETTING_PATH
+                ? globalCursorIgnoreListFromSettings(configJson)
+                : getByPath(configJson, targetPath);
+            if (!remediationSetOpSatisfied(currentForSet, expected)) {
+                return { ok: false, expected: { op: 'set', path: targetPath, value: expected } };
+            }
+            continue;
+        }
+        const curArr = currentArrayAtComplianceTarget(configJson, targetPath);
+        const toAdd = add[k] ?? [];
+        const toRemove = remove[k] ?? [];
+        const isYoloAllowlist = leafKey === 'yoloCommandAllowlist' || targetPath.endsWith('.yoloCommandAllowlist');
+        for (const item of toRemove) {
+            if (isYoloAllowlist) {
+                if (curArr.some((entry) => allowlistEntryMatchesRemoveToken(entry, String(item)))) {
+                    return { ok: false, expected: { op: 'remove', path: targetPath, value: item } };
+                }
+                continue;
+            }
+            if (curArr.some((curItem) => deepEqual(curItem, item))) {
+                return { ok: false, expected: { op: 'remove', path: targetPath, value: item } };
+            }
+        }
+        for (const item of toAdd) {
+            if (!curArr.some((curItem) => deepEqual(curItem, item))) {
+                return { ok: false, expected: { op: 'add', path: targetPath, value: item } };
+            }
+        }
+    }
+    return { ok: true, expected: null };
+}
+function shouldMergeComposerShadowKeys(itemKeyFromPath, checkSettingPaths) {
+    if (itemKeyFromPath === 'composerState')
+        return true;
+    return checkSettingPaths.some((p) => p === 'composerState' || p.startsWith('composerState.'));
+}
+/** @deprecated Import from vscdb_reader — re-export for existing tests. */
+export { mergeComposerShadowKeysFromReactiveBlob } from '../readers/vscdb_reader.js';
+/** Plain JSON/TOML file or virtual `…/state.vscdb#itemKey` path for ItemTable-backed settings. */
+function loadRemediationConfigJson(configFilePath, checkSettingPaths = []) {
+    const resolvedPath = resolveRemediationConfigPath(configFilePath);
+    const hashIdx = resolvedPath.indexOf('#');
+    if (hashIdx >= 0) {
+        const dbPath = resolvedPath.slice(0, hashIdx);
+        const itemKeyFromPath = resolvedPath.slice(hashIdx + 1).trim();
+        if (!itemKeyFromPath)
+            return { ok: false, reason: 'empty_vscdb_key' };
+        if (!existsSync(dbPath))
+            return { ok: false, reason: 'db_not_found' };
+        const keys = new Set([itemKeyFromPath, ...checkSettingPaths.map(itemTableKeyFromSettingPath)].filter(Boolean));
+        const merged = {};
+        for (const k of keys) {
+            const wrapped = readVscdbItemTableJson(dbPath, k);
+            if (wrapped === null)
+                return { ok: false, reason: 'vscdb_read_failed' };
+            Object.assign(merged, wrapped);
+        }
+        if (shouldMergeComposerShadowKeys(itemKeyFromPath, checkSettingPaths)) {
+            mergeComposerShadowKeysFromReactiveBlob(dbPath, merged);
+        }
+        return { ok: true, json: merged };
+    }
+    if (!existsSync(resolvedPath))
+        return { ok: false, reason: 'file_not_found' };
+    const rawText = readFileSync(resolvedPath, 'utf8');
+    if (resolvedPath.toLowerCase().endsWith('.toml')) {
+        const parsedToml = parseTomlText(rawText);
+        if (parsedToml === null)
+            return { ok: false, reason: 'parse_error' };
+        return { ok: true, json: parsedToml };
+    }
+    // OpenCode configs are JSONC (comments / trailing commas); parse strict JSON first, then
+    // fall back to JSONC sanitization so comment-bearing files are not skipped as parse_error.
+    const parsed = parseJsonWithJsoncFallback(rawText);
+    if (parsed === null)
+        return { ok: false, reason: 'parse_error' };
+    return { ok: true, json: parsed };
+}
+function isSupportedTextConfigFormat(fileFormat) {
+    return fileFormat === 'json' || fileFormat === 'toml';
+}
+/**
+ * Evaluate all checks in a secondary group against the group's config file.
+ * Returns true only if every check passes (ops-based). Non-ops checks are treated as failing.
+ */
+function evaluateSecondaryGroup(group) {
+    const loaded = loadRemediationConfigJson(group.config_file_path, group.checks.map((c) => c.setting_path));
+    if (!loaded.ok) {
+        hookRunLog(`evaluateSecondaryGroup: could not load secondary file path=${group.config_file_path} reason=${loaded.reason}`);
+        return false;
+    }
+    for (const check of group.checks) {
+        if (!check.ops)
+            return false;
+        const { ok } = verifyOpsApplied(loaded.json, check.setting_path, check.ops);
+        if (!ok)
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Check runner — Section 6: real per-check evaluation
+// ---------------------------------------------------------------------------
+function violationFromCheck(entry, compliance, check, expected) {
+    return {
+        uuid: entry.uuid,
+        finding_formatted_id: compliance.finding_formatted_id,
+        setting_path: check.setting_path,
+        description: check.description,
+        finding_title: entry.finding_title,
+        finding_description: entry.finding_description,
+        ruleset_name: entry.ruleset_name,
+        severity: compliance.severity,
+        autofix_allowed: compliance.autofix_allowed,
+        config_file_path: entry.config_file_path,
+        expected_value: expected,
+        message: `[${compliance.finding_formatted_id}] ${entry.finding_title ?? compliance.description}\nDescription: ${entry.finding_description ?? compliance.description}\nHow to fix: Apply remediation ops for ${check.setting_path} in ${entry.config_file_path}`,
+    };
+}
+/** Evaluate one manifest row against on-disk config (used by gate + post-restart verify). */
+export function evaluateManifestEntryCompliance(entry) {
+    const compliance = entry.fix ?? entry.compliance;
+    if (!compliance || !isSupportedTextConfigFormat(compliance.file_format))
+        return { violations: [] };
+    const checks = compliance.checks ?? [];
+    if (checks.length === 0)
+        return { violations: [] };
+    const loaded = loadRemediationConfigJson(entry.config_file_path, checks.map((c) => c.setting_path));
+    if (!loaded.ok)
+        return { violations: [] };
+    const configJson = loaded.json;
+    if (compliance.requires_secret_scan === true) {
+        const secretFindings = scanJsonForHardcodedSecrets(configJson);
+        return secretFindings.length === 0
+            ? { violations: [] }
+            : {
+                violations: secretFindings.map((f) => violationFromSecretScanFinding(entry, compliance, f)),
+            };
+    }
+    const entryViolations = [];
+    for (const check of checks) {
+        const effectivePath = canonicalComplianceSettingPath(entry.config_file_path, check);
+        if (check.sqlite_op?.apply_to_all_workspaces && check.ops) {
+            const segments = check.sqlite_op.workspace_storage_path_segments ?? [
+                'Library', 'Application Support', 'Cursor', 'User', 'workspaceStorage',
+            ];
+            const wsPath = join(homedir(), ...segments);
+            const vscdbPaths = discoverAllWorkspaceVscdbs(wsPath);
+            if (vscdbPaths.length === 0)
+                continue;
+            let violated = false;
+            let expectedForViolation = null;
+            for (const dbPath of vscdbPaths) {
+                const wrapped = readVscdbItemTableJson(dbPath, check.sqlite_op.target_key ?? '');
+                if (wrapped === null) {
+                    violated = true;
+                    expectedForViolation = { op: 'read_failed', db: dbPath };
+                    break;
+                }
+                const { ok, expected } = verifyOpsApplied(wrapped, check.setting_path, check.ops);
+                if (!ok) {
+                    violated = true;
+                    expectedForViolation = expected;
+                    break;
+                }
+            }
+            if (violated) {
+                entryViolations.push(violationFromCheck(entry, compliance, check, expectedForViolation));
+            }
+            continue;
+        }
+        if (check.ops) {
+            const { ok, expected } = verifyOpsApplied(configJson, effectivePath, check.ops);
+            if (!ok) {
+                entryViolations.push(violationFromCheck(entry, compliance, { ...check, setting_path: effectivePath }, expected));
+            }
+            continue;
+        }
+        const currentValue = getByPath(configJson, effectivePath);
+        const leafKey = effectivePath.split('.').pop();
+        const expectedValue = check.after?.[leafKey];
+        if (expectedValue === undefined)
+            continue;
+        if (!deepEqual(currentValue, expectedValue)) {
+            entryViolations.push(violationFromCheck(entry, compliance, { ...check, setting_path: effectivePath }, expectedValue));
+        }
+    }
+    if (entryViolations.length === 0)
+        return { violations: [] };
+    const secondaryGroups = compliance.secondary_checks ?? [];
+    const passingGroup = secondaryGroups.length > 0 ? secondaryGroups.find((g) => evaluateSecondaryGroup(g)) : undefined;
+    if (passingGroup) {
+        return {
+            violations: [],
+            secondarySatisfied: {
+                uuid: entry.uuid,
+                config_file_path: passingGroup.config_file_path,
+                file_type: passingGroup.file_type,
+            },
+        };
+    }
+    return { violations: entryViolations };
+}
+export function collectManifestEntryViolations(entry) {
+    return evaluateManifestEntryCompliance(entry).violations;
+}
+/**
+ * Evaluate current on-disk configs against remediation_instructions.json only (no server).
+ * Returns status for prompt gating / callers; does not persist compliance.json.
+ */
+export function runLocalRemediationComplianceCheck(agent = 'cursor') {
+    try {
+        const { remediations: rawEntries } = readRemediationInstructionsFile();
+        const entries = rawEntries.filter((e) => targetsCurrentAgent(e, agent));
+        if (entries.length === 0) {
+            hookRunLog('compliance_check: no remediation instructions present');
+            return { status: 'ok', checked_at: new Date().toISOString(), manifest_uuids: [], violations: [] };
+        }
+        const uuids = entries.map((e) => e.uuid);
+        const violations = [];
+        const secondarySatisfied = [];
+        let skippedNoCompliance = 0;
+        let skippedNonJson = 0;
+        let skippedNoChecks = 0;
+        let skippedUnreadable = 0;
+        for (const entry of entries) {
+            const compliance = entry.fix ?? entry.compliance;
+            if (!compliance) {
+                skippedNoCompliance++;
+                continue;
+            }
+            if (!isSupportedTextConfigFormat(compliance.file_format)) {
+                skippedNonJson++;
+                hookRunLog(`compliance_check: skipping unsupported file_format=${compliance.file_format} uuid=${entry.uuid}`);
+                continue;
+            }
+            if ((compliance.checks ?? []).length === 0) {
+                skippedNoChecks++;
+                continue;
+            }
+            const loaded = loadRemediationConfigJson(entry.config_file_path, (compliance.checks ?? []).map((c) => c.setting_path));
+            if (!loaded.ok) {
+                skippedUnreadable++;
+                const msg = loaded.reason === 'file_not_found'
+                    ? `compliance_check: config file not found, skipping uuid=${entry.uuid}`
+                    : loaded.reason === 'db_not_found'
+                        ? `compliance_check: vscdb file not found, skipping uuid=${entry.uuid}`
+                        : loaded.reason === 'vscdb_read_failed'
+                            ? `compliance_check: could not read vscdb (sqlite3 missing or invalid JSON?), skipping uuid=${entry.uuid}`
+                            : loaded.reason === 'empty_vscdb_key'
+                                ? `compliance_check: invalid vscdb path (empty # key), skipping uuid=${entry.uuid}`
+                                : `compliance_check: could not parse config file, skipping uuid=${entry.uuid}`;
+                hookRunLog(msg);
+                logRemediationApplyFailure('compliance_check_config_unreadable', {
+                    uuid: entry.uuid,
+                    config_file_path: entry.config_file_path,
+                    finding_formatted_id: compliance.finding_formatted_id,
+                    load_reason: loaded.reason,
+                    reason: 'cannot read config for compliance verify — remediation may not run until path/db is valid',
+                });
+                continue;
+            }
+            const { violations: entryViolations, secondarySatisfied: entrySecondary } = evaluateManifestEntryCompliance(entry);
+            for (const v of entryViolations) {
+                hookRunLog(`compliance_check: VIOLATION uuid=${entry.uuid} path=${v.setting_path} expected=${JSON.stringify(v.expected_value)}`);
+            }
+            if (entrySecondary) {
+                hookRunLog(`compliance_check: secondary check satisfied uuid=${entry.uuid} — skipping primary violation(s)`);
+                secondarySatisfied.push(entrySecondary);
+            }
+            else if (entryViolations.length > 0) {
+                violations.push(...entryViolations);
+            }
+        }
+        const status = {
+            status: violations.length > 0 ? 'fail' : 'ok',
+            checked_at: new Date().toISOString(),
+            manifest_uuids: uuids,
+            violations,
+            secondarySatisfied: secondarySatisfied.length > 0 ? secondarySatisfied : undefined,
+        };
+        const skipParts = [];
+        if (skippedNoCompliance)
+            skipParts.push(`no_fix=${skippedNoCompliance}`);
+        if (skippedNonJson)
+            skipParts.push(`non_json=${skippedNonJson}`);
+        if (skippedNoChecks)
+            skipParts.push(`no_checks=${skippedNoChecks}`);
+        if (skippedUnreadable)
+            skipParts.push(`unreadable_config=${skippedUnreadable}`);
+        const skipSummary = skipParts.length > 0 ? ` skipped{${skipParts.join(' ')}}` : '';
+        hookRunLog(`compliance_check: done — status=${status.status} violations=${violations.length} manifest_entries=${uuids.length}${skipSummary}`);
+        if (skippedUnreadable > 0) {
+            complianceRunnerDiag(`compliance_check: ${skippedUnreadable} manifest row(s) skipped — vscdb/config unreadable (often DB locked while Cursor runs, or sqlite3/PATH). Autofix cannot evaluate until read succeeds.`);
+        }
+        return status;
+    }
+    catch (err) {
+        const emsg = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error ? err.stack : undefined;
+        hookRunLog(`compliance_check: unexpected error: ${emsg}`);
+        logRemediationApplyFailure('compliance_check_exception', {
+            reason: 'runLocalRemediationComplianceCheck threw',
+            error: emsg,
+            stack: stack ?? '',
+        });
+        const fallback = {
+            status: 'ok',
+            checked_at: new Date().toISOString(),
+            manifest_uuids: [],
+            violations: [],
+        };
+        return fallback;
+    }
+}
+/**
+ * After restart, verify pending remediations and report outcomes to the server.
+ */
+export function reportPostRestartVerificationOutcomes(violations) {
+    const { remediations } = readRemediationInstructionsFile();
+    const entriesByUuid = new Map(remediations.map((entry) => [entry.uuid, entry]));
+    const outcomes = processPendingPostRestartVerifications((uuid) => {
+        const entry = entriesByUuid.get(uuid);
+        if (entry && collectManifestEntryViolations(entry).length > 0)
+            return true;
+        return violations.some((v) => v.uuid === uuid);
+    });
+    const reportPromises = outcomes.map((o) => {
+        if (o.status === 'quarantined' || o.status === 'verification_failed') {
+            logRemediationApplyFailure('post_restart_verification_failed', {
+                uuid: o.uuid,
+                reason: o.reason ?? 'Setting unchanged after apply',
+                status: o.status,
+                consecutive_failures: o.consecutive_failures,
+            });
+        }
+        return reportAutofixApplied(o.uuid, o.status, {
+            failure_reason: o.reason,
+            consecutive_failures: o.consecutive_failures,
+        });
+    });
+    return { outcomes, reportPromises };
+}
+/**
+ * After deferred vscdb apply (`apply_deferred_vscdb.ts`): confirm pending remediations and POST
+ * outcomes before the user's next prompt.
+ */
+export async function runPostApplyVerification(agent = 'cursor') {
+    const status = runLocalRemediationComplianceCheck(agent);
+    const { outcomes, reportPromises } = reportPostRestartVerificationOutcomes(status.violations);
+    if (outcomes.length > 0) {
+        await Promise.allSettled(reportPromises);
+    }
+    return outcomes;
+}
+/**
+ * Immediate autofix succeeded (inline recheck OK or Claude stale-recheck tolerance).
+ * Clear pending verification locally and report verified so the next prompt does not POST
+ * verification_failed while the user already saw a successful fix.
+ */
+export function confirmAppliedAutofixVerified(appliedViolations, reportPromises) {
+    for (const v of appliedViolations) {
+        markRemediationApplyVerified(v.uuid);
+        reportPromises.push(reportAutofixApplied(v.uuid, 'verified'));
+    }
+}
+export function applyAutofixViolations(violations, agent = 'cursor') {
+    for (const v of violations) {
+        if (!v.autofix_allowed) {
+            logRemediationApplyFailure('autofix_skipped_not_allowed', {
+                uuid: v.uuid,
+                finding_formatted_id: v.finding_formatted_id,
+                config_file_path: v.config_file_path,
+                setting_path: v.setting_path,
+                reason: 'autofix_allowed is false — policy/manual fix required',
+            });
+        }
+    }
+    const autofixable = violations.filter((v) => v.autofix_allowed);
+    if (autofixable.length === 0)
+        return {
+            fixed: 0,
+            appliedViolations: [],
+            restartCommands: [],
+            failedViolations: [],
+            reportPromises: [],
+        };
+    const { remediations } = readRemediationInstructionsFile();
+    const scopedRemediations = remediations.filter((e) => targetsCurrentAgent(e, agent));
+    const byUuid = new Map(scopedRemediations.map((r) => [r.uuid, r]));
+    let fixed = 0;
+    const appliedViolations = [];
+    const seen = new Set();
+    const restartCommands = [];
+    const failedViolations = [];
+    const reportPromises = [];
+    const oneTimeAppliedUuids = new Set();
+    let deferredSqlitePending = false;
+    for (const violation of autofixable) {
+        if (seen.has(violation.uuid))
+            continue;
+        if (isRemediationQuarantined(violation.uuid)) {
+            hookRunLog(`autofix: skipped quarantined uuid=${violation.uuid}`);
+            logRemediationApplyFailure('autofix_skipped_quarantined', {
+                uuid: violation.uuid,
+                finding_formatted_id: violation.finding_formatted_id,
+                config_file_path: violation.config_file_path,
+                setting_path: violation.setting_path,
+                reason: 'Auto-fix paused after repeated post-restart verification failures — agent config may have changed',
+            });
+            failedViolations.push(violation);
+            continue;
+        }
+        const instruction = byUuid.get(violation.uuid);
+        if (!instruction) {
+            hookRunLog(`autofix: no instruction found for uuid=${violation.uuid}, skipping`);
+            logRemediationApplyFailure('autofix_no_local_instruction', {
+                uuid: violation.uuid,
+                finding_formatted_id: violation.finding_formatted_id,
+                config_file_path: violation.config_file_path,
+                setting_path: violation.setting_path,
+                reason: 'violation UUID not present in remediation_instructions.json remediations[]',
+            });
+            failedViolations.push(violation);
+            continue;
+        }
+        const inst = instruction;
+        const configPathForDisk = resolveRemediationConfigPath(inst.config_file_path);
+        complianceRunnerDiag(`autofix: calling enforceRemediation uuid=${inst.uuid} path=${configPathForDisk}`);
+        const er = enforceRemediation(inst);
+        if (!er.ok) {
+            failedViolations.push(violation);
+            continue;
+        }
+        if (er.deferredSqlite)
+            deferredSqlitePending = true;
+        seen.add(violation.uuid);
+        fixed++;
+        appliedViolations.push(violation);
+        hookRunLog(`autofix: applied uuid=${inst.uuid} path=${configPathForDisk}`);
+        reportPromises.push(reportAutofixApplied(inst.uuid, 'success'));
+        // Every successful autofix (Cursor + Claude, restart or immediate JSON) awaits verification on
+        // the next compliance check so we can quarantine stuck applies and stop restart/retry loops.
+        markRemediationApplyPendingVerification(inst.uuid);
+        const spec = remediationFixSpec(inst);
+        if (er.deferredSqlite && configPathForDisk.includes('#')) {
+            hookRunLog(`autofix: skip immediate vscdb upload (deferred until after restart) uuid=${inst.uuid}`);
+        }
+        else {
+            let updatedContent;
+            if (configPathForDisk.includes('#')) {
+                const hi = configPathForDisk.indexOf('#');
+                const dbPath = configPathForDisk.slice(0, hi);
+                const itemKey = configPathForDisk.slice(hi + 1).trim();
+                updatedContent = itemKey ? (readVscdbItemTableJson(dbPath, itemKey) ?? undefined) : undefined;
+            }
+            else {
+                updatedContent =
+                    parseJsonWithJsoncFallback(readFileSync(configPathForDisk, 'utf8')) ?? undefined;
+            }
+            if (updatedContent !== undefined) {
+                const fileType = resolveRemediationUploadFileType(inst.config_file_path, inst.file_type ?? undefined);
+                if (fileType) {
+                    const hw = tryResolveHardwareUuid();
+                    if (hw) {
+                        // Do not rely on the bulk uploader (start-every-prompt throttles at 1800s).
+                        // Always attempt to upload the single remediated file immediately.
+                        reportPromises.push(ensureAuthentication(hw)
+                            .then((authKey) => sendConfigFile({ file_type: fileType, file_path: configPathForDisk, raw_content: updatedContent }, hw, authKey))
+                            .then((sentOk) => {
+                            hookRunLog(`autofix: uploaded remediated file uuid=${inst.uuid} path=${configPathForDisk} ok=${sentOk}`);
+                        })
+                            .catch((err) => {
+                            hookRunLog(`autofix: upload failed uuid=${inst.uuid} path=${configPathForDisk} err=${err instanceof Error ? err.message : String(err)}`);
+                        }));
+                    }
+                    else {
+                        hookRunLog(`autofix: skip upload uuid=${inst.uuid} (hardware UUID unavailable)`);
+                    }
+                }
+                else {
+                    hookRunLog(`autofix: skip upload uuid=${inst.uuid} — remediation_instructions.json missing file_type (re-sync manifest)`);
+                    logRemediationApplyFailure('autofix_post_apply_upload_skipped', {
+                        uuid: inst.uuid,
+                        config_file_path: inst.config_file_path,
+                        reason: 'file_type missing on instruction — server sync/manifest will not see applied file',
+                    });
+                }
+            }
+        }
+        if (spec?.restart_required && spec.restart_command) {
+            if (!er.deferredSqlite) {
+                if (isTrustedRestartCommandForAutofix(spec.restart_command)) {
+                    hookRunLog(`autofix: restart required uuid=${inst.uuid} command=${spec.restart_command}`);
+                    restartCommands.push(spec.restart_command);
+                }
+                else {
+                    hookRunLog(`autofix: restart command rejected (not an allowlisted template) uuid=${inst.uuid}`);
+                }
+            }
+        }
+        if (!inst.is_enforced) {
+            oneTimeAppliedUuids.add(inst.uuid);
+        }
+    }
+    if (deferredSqlitePending) {
+        restartCommands.length = 0;
+        restartCommands.push(buildDeferredCursorRestartCommand());
+        hookRunLog('autofix: deferred vscdb — restart command runs apply_deferred_vscdb.js then open -a Cursor');
+    }
+    if (oneTimeAppliedUuids.size > 0) {
+        // Only prune one-time remediations for this agent; keep other-agent remediations intact.
+        const remaining = remediations.filter((r) => {
+            if (!targetsCurrentAgent(r, agent))
+                return true;
+            return !oneTimeAppliedUuids.has(r.uuid);
+        });
+        writeRemediationInstructionsFile({ remediations: remaining });
+        hookRunLog(`autofix: removed ${oneTimeAppliedUuids.size} one-time remediation(s) from local store`);
+        // Send a post-autofix heartbeat so the server sees the updated (reduced) UUID set immediately,
+        // without waiting for the background runner (which may be locked out).
+        // Heartbeat should reflect the full local file state (including other-agent remediations that remain).
+        const remainingUuids = remaining.map((r) => r.uuid);
+        const hwHeartbeat = tryResolveHardwareUuid();
+        if (hwHeartbeat) {
+            reportPromises.push(fetchSync(loadEndpointBase(), hwHeartbeat, remainingUuids)
+                .then(() => hookRunLog(`autofix: post-autofix heartbeat sent uuids=${remainingUuids.length}`))
+                .catch(() => undefined));
+        }
+        else {
+            hookRunLog('autofix: skip post-autofix heartbeat (hardware UUID unavailable)');
+        }
+    }
+    if (fixed > 0) {
+        hookRunLog(`autofix: total_applied=${fixed}`);
+    }
+    return { fixed, appliedViolations, restartCommands, failedViolations, reportPromises, deferredSqlitePending };
+}
+/**
+ * Remove satisfied one-time remediations from local remediation_instructions.json.
+ *
+ * This handles the case where a user (or another tool) manually applied the change, so the
+ * instruction no longer needs to persist locally. Enforced remediations are never pruned.
+ *
+ * Returns number removed and any async report promises (heartbeat).
+ */
+export function pruneSatisfiedOneTimeRemediations(agent = 'cursor') {
+    const { remediations } = readRemediationInstructionsFile();
+    if (!Array.isArray(remediations) || remediations.length === 0)
+        return { removed: 0, reportPromises: [] };
+    const remaining = [];
+    let removed = 0;
+    for (const raw of remediations) {
+        const inst = raw;
+        if (!targetsCurrentAgent(inst, agent)) {
+            remaining.push(raw);
+            continue;
+        }
+        if (inst.is_enforced) {
+            remaining.push(raw);
+            continue;
+        }
+        const spec = remediationFixSpec(inst);
+        const checks = isSupportedTextConfigFormat(spec?.file_format) ? (spec?.checks ?? []) : [];
+        if (checks.length === 0) {
+            remaining.push(raw);
+            continue;
+        }
+        const prLoaded = loadRemediationConfigJson(inst.config_file_path, checks.map((c) => c.setting_path));
+        if (!prLoaded.ok) {
+            remaining.push(raw);
+            continue;
+        }
+        const configJson = prLoaded.json;
+        if (spec?.requires_secret_scan === true) {
+            if (scanJsonForHardcodedSecrets(configJson).length === 0) {
+                removed++;
+                hookRunLog(`remediation_prune: satisfied secret-scan uuid=${inst.uuid} path=${inst.config_file_path}`);
+            }
+            else {
+                remaining.push(raw);
+            }
+            continue;
+        }
+        // Only prune when every check is ops-based and currently satisfied.
+        let okAll = true;
+        for (const check of checks) {
+            if (!check.ops) {
+                okAll = false;
+                break;
+            }
+            // apply_to_all_workspaces: verify against workspace vscdbs, not the loaded config file.
+            if (check.sqlite_op?.apply_to_all_workspaces) {
+                const segments = check.sqlite_op.workspace_storage_path_segments ?? [
+                    'Library', 'Application Support', 'Cursor', 'User', 'workspaceStorage',
+                ];
+                const wsPath = join(homedir(), ...segments);
+                const vscdbPaths = discoverAllWorkspaceVscdbs(wsPath);
+                if (vscdbPaths.length === 0) {
+                    okAll = false;
+                    break;
+                }
+                for (const dbPath of vscdbPaths) {
+                    const wrapped = readVscdbItemTableJson(dbPath, check.sqlite_op.target_key ?? '');
+                    if (wrapped === null || !verifyOpsApplied(wrapped, check.setting_path, check.ops).ok) {
+                        okAll = false;
+                        break;
+                    }
+                }
+                if (!okAll)
+                    break;
+                continue;
+            }
+            const res = verifyOpsApplied(configJson, check.setting_path, check.ops);
+            if (!res.ok) {
+                okAll = false;
+                break;
+            }
+        }
+        if (!okAll) {
+            const secondaryGroups = spec?.secondary_checks ?? [];
+            if (secondaryGroups.length > 0 && secondaryGroups.some((g) => evaluateSecondaryGroup(g))) {
+                okAll = true;
+                hookRunLog(`remediation_prune: secondary check satisfied uuid=${inst.uuid}`);
+            }
+        }
+        if (okAll) {
+            removed++;
+            hookRunLog(`remediation_prune: satisfied one-time uuid=${inst.uuid} path=${inst.config_file_path}`);
+        }
+        else {
+            remaining.push(raw);
+        }
+    }
+    if (removed === 0)
+        return { removed: 0, reportPromises: [] };
+    writeRemediationInstructionsFile({ remediations: remaining });
+    hookRunLog(`remediation_prune: removed=${removed} remaining=${remaining.length}`);
+    const remainingUuids = remaining.map((r) => r.uuid);
+    const hw = tryResolveHardwareUuid();
+    const reportPromises = [];
+    if (hw) {
+        reportPromises.push(fetchSync(loadEndpointBase(), hw, remainingUuids)
+            .then(() => hookRunLog(`remediation_prune: post-prune heartbeat sent uuids=${remainingUuids.length}`))
+            .catch(() => undefined));
+    }
+    else {
+        hookRunLog('remediation_prune: skip post-prune heartbeat (hardware UUID unavailable)');
+    }
+    return { removed, reportPromises };
+}
+/** Throttle satisfied-manifest uploads (disk already matches ops; autofix did not run). */
+const SATISFIED_MANIFEST_UPLOAD_COOLDOWN_MS = 5 * 60 * 1000;
+/**
+ * When local compliance already passes, autofix is skipped — so settings never reach the server.
+ * Upload satisfied JSON remediations (throttled) so scan can resolve findings.
+ */
+export function uploadSatisfiedManifestConfigs(agent = 'cursor') {
+    const { remediations } = readRemediationInstructionsFile();
+    const entries = remediations.filter((e) => targetsCurrentAgent(e, agent));
+    const promises = [];
+    for (const entry of entries) {
+        const { violations } = evaluateManifestEntryCompliance(entry);
+        if (violations.length > 0)
+            continue;
+        const inst = entry;
+        const uploadFileType = resolveRemediationUploadFileType(entry.config_file_path, inst.file_type ?? undefined);
+        if (!uploadFileType)
+            continue;
+        const diskPath = resolveRemediationConfigPath(entry.config_file_path);
+        if (diskPath.includes('#'))
+            continue;
+        const tracking = readRemediationApplyTrackingFile();
+        const prev = tracking.entries[entry.uuid];
+        const lastUpload = prev?.last_satisfied_upload_at;
+        if (lastUpload) {
+            const elapsed = Date.now() - Date.parse(lastUpload);
+            if (!Number.isNaN(elapsed) && elapsed < SATISFIED_MANIFEST_UPLOAD_COOLDOWN_MS) {
+                continue;
+            }
+        }
+        const rawContent = parseJsonWithJsoncFallback(readFileSync(diskPath, 'utf8'));
+        if (rawContent === null) {
+            hookRunLog(`satisfied_upload: could not read path=${diskPath} uuid=${entry.uuid}`);
+            continue;
+        }
+        const hw = tryResolveHardwareUuid();
+        if (!hw) {
+            hookRunLog(`satisfied_upload: skip uuid=${entry.uuid} (hardware UUID unavailable)`);
+            continue;
+        }
+        const uploadPath = entry.config_file_path.trim() || diskPath;
+        const shouldReportVerified = !prev?.pending_post_restart_verify && !prev?.server_verified_at;
+        promises.push(ensureAuthentication(hw)
+            .then((authKey) => sendConfigFile({ file_type: uploadFileType, file_path: uploadPath, raw_content: rawContent }, hw, authKey))
+            .then(async (sentOk) => {
+            hookRunLog(`satisfied_upload: uuid=${entry.uuid} path=${uploadPath} ok=${sentOk}`);
+            if (!sentOk)
+                return;
+            const file = readRemediationApplyTrackingFile();
+            const ent = file.entries[entry.uuid] ?? { consecutive_verify_failures: 0, quarantined: false };
+            ent.last_satisfied_upload_at = new Date().toISOString();
+            file.entries[entry.uuid] = ent;
+            writeRemediationApplyTrackingFile(file);
+            if (shouldReportVerified) {
+                await reportAutofixApplied(entry.uuid, 'verified', {
+                    config_snapshot_after: rawContent,
+                });
+                markRemediationApplyVerified(entry.uuid);
+                hookRunLog(`satisfied_upload: reported verified uuid=${entry.uuid}`);
+            }
+        })
+            .catch((err) => {
+            hookRunLog(`satisfied_upload: failed uuid=${entry.uuid} err=${err instanceof Error ? err.message : String(err)}`);
+        }));
+    }
+    return promises;
+}
+/**
+ * When disk already matches remediation ops but autofix never ran, POST verified so the UI
+ * leaves Pending (EnforcementLog) even if satisfied_upload is throttled.
+ */
+export function reportCompliantRemediationVerifiedStatus(agent = 'cursor') {
+    const { remediations } = readRemediationInstructionsFile();
+    const entries = remediations.filter((e) => targetsCurrentAgent(e, agent));
+    const promises = [];
+    for (const entry of entries) {
+        const { violations } = evaluateManifestEntryCompliance(entry);
+        if (violations.length > 0)
+            continue;
+        const tracking = readRemediationApplyTrackingFile();
+        const prev = tracking.entries[entry.uuid];
+        if (prev?.pending_post_restart_verify || prev?.server_verified_at)
+            continue;
+        const diskPath = resolveRemediationConfigPath(entry.config_file_path);
+        if (diskPath.includes('#'))
+            continue;
+        const rawContent = parseJsonWithJsoncFallback(readFileSync(diskPath, 'utf8'));
+        if (rawContent === null)
+            continue;
+        promises.push(reportAutofixApplied(entry.uuid, 'verified', { config_snapshot_after: rawContent }).then(() => {
+            markRemediationApplyVerified(entry.uuid);
+            hookRunLog(`compliance_check: reported verified (already compliant) uuid=${entry.uuid}`);
+        }));
+    }
+    return promises;
+}
+/**
+ * Background refresh: server sync for latest instructions, then the same local evaluation as the hook.
+ * Apply (autofix) is intentionally deferred to the gate on the next prompt — this pass only downloads
+ * a fresh manifest so the gate has up-to-date data when it runs.
+ */
+export async function runComplianceCheck(agentOverride) {
+    const agent = agentOverride ?? currentAgentFromEnv();
+    try {
+        await syncRemediations(loadEndpointBase(), resolveHardwareUuid());
+    }
+    catch (err) {
+        hookRunLog(`compliance_check: remediation_sync unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const status = runLocalRemediationComplianceCheck(agent);
+    if (status.status === 'ok' || status.violations.length === 0) {
+        const pruned = pruneSatisfiedOneTimeRemediations(agent);
+        if (pruned.removed > 0) {
+            await Promise.allSettled(pruned.reportPromises);
+        }
+        await Promise.allSettled(uploadSatisfiedManifestConfigs(agent));
+    }
+}