log-llm-config 1.1.0 → 1.2.0

package/dist/compliance_check_runner.js

@@ -0,0 +1,10 @@
+import { runComplianceCheck } from './log_config_files/runtime/compliance_check.js';
+(async () => {
+    try {
+        await runComplianceCheck();
+    }
+    catch (err) {
+        process.stderr.write(`compliance_check_runner error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+})();

package/dist/compliance_prompt_gate.js

@@ -0,0 +1,100 @@
+/**
+ * Synchronous pre-prompt gate: local compliance only (stdout = single JSON line for IDE hooks).
+ * stderr must stay clean; logs go via hookRunLog (file).
+ */
+import { applyAutofixViolations, runLocalRemediationComplianceCheck } from './log_config_files/runtime/compliance_check.js';
+import { existsSync, statSync } from 'node:fs';
+import { getRemediationInstructionsPath } from './log_config_files/runtime/management_storage.js';
+const MANIFEST_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+function parseIde() {
+    const eq = process.argv.find((a) => a.startsWith('--ide='));
+    if (eq) {
+        const v = eq.slice('--ide='.length).toLowerCase();
+        return v === 'claude' ? 'claude' : 'cursor';
+    }
+    if (process.argv.includes('--claude'))
+        return 'claude';
+    return 'cursor';
+}
+function printAllow(ide) {
+    if (ide === 'claude')
+        console.log('{}');
+    else
+        console.log(JSON.stringify({ continue: true }));
+}
+function printAllowWithAdvisory(ide, advisoryMessage) {
+    if (ide === 'claude') {
+        console.log(JSON.stringify({ __optimus_advisory: true, advisory_message: advisoryMessage }));
+    }
+    else {
+        console.log(JSON.stringify({
+            continue: true,
+            __optimus_advisory: true,
+            advisory_message: advisoryMessage,
+        }));
+    }
+}
+function blockPayload(ide, violationMessage) {
+    const prefix = 'Prompt blocked by Optimus: ';
+    const text = prefix + violationMessage;
+    if (ide === 'claude') {
+        return JSON.stringify({ decision: 'block', reason: text, systemMessage: text });
+    }
+    return JSON.stringify({ continue: false, user_message: text });
+}
+function getManifestStalenessMs() {
+    try {
+        const path = getRemediationInstructionsPath();
+        if (!existsSync(path))
+            return null;
+        const st = statSync(path);
+        return Date.now() - st.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+const ide = parseIde();
+async function run() {
+    const status = runLocalRemediationComplianceCheck();
+    if (status.status === 'fail' && status.violations.length > 0) {
+        const staleMs = getManifestStalenessMs();
+        if (staleMs !== null && staleMs > MANIFEST_STALE_MS) {
+            const staleDays = Math.floor(staleMs / (24 * 60 * 60 * 1000));
+            const advisory = `Remediation enforcement suspended: local remediation manifest is stale (${staleDays} days old). ` +
+                'Please reconnect to sync latest policy state.';
+            printAllowWithAdvisory(ide, advisory);
+            return;
+        }
+        const { fixed, restartCommands, failedViolations, reportPromises } = applyAutofixViolations(status.violations);
+        if (fixed > 0) {
+            // Wait for all server reports before exiting so the POST lands.
+            await Promise.allSettled(reportPromises);
+            const recheck = runLocalRemediationComplianceCheck();
+            if (recheck.status === 'ok' || recheck.violations.length === 0) {
+                const fixedViolations = status.violations.filter((v) => v.autofix_allowed);
+                const lines = fixedViolations.map((v) => `• [${v.finding_formatted_id}] ${v.description}`);
+                const autofixMessage = `Optimus Security auto-fixed ${fixed} compliance violation(s):\n${lines.join('\n')}`;
+                const payload = { __optimus_autofix: true, autofix_message: autofixMessage };
+                if (restartCommands.length > 0)
+                    payload.restart_commands = restartCommands;
+                console.log(JSON.stringify(payload));
+                return;
+            }
+            const msg = recheck.violations[0]?.message ?? 'A security policy violation has been detected.';
+            console.log(blockPayload(ide, msg));
+            return;
+        }
+        if (failedViolations.length > 0) {
+            const ids = failedViolations.map((v) => `[${v.finding_formatted_id}]`).join(', ');
+            const msg = `Auto-fix failed for ${ids} — please fix manually or contact your security team.\n\n${failedViolations[0]?.message ?? ''}`;
+            console.log(blockPayload(ide, msg));
+            return;
+        }
+        const msg = status.violations[0]?.message ?? 'A security policy violation has been detected.';
+        console.log(blockPayload(ide, msg));
+        return;
+    }
+    printAllow(ide);
+}
+run().catch(() => printAllow(ide)).finally(() => process.exit(0));

package/dist/log_config_files/runtime/compliance_check.js

@@ -0,0 +1,188 @@
+/**
+ * Compliance check: types and check runner entry point.
+ *
+ * Prompt gate: compliance_prompt_gate runs runLocalRemediationComplianceCheck (local files only).
+ * Background: compliance_check_runner runs syncRemediations (network) then the same local check.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { readRemediationInstructionsFile, writeRemediationInstructionsFile } from './management_storage.js';
+import { hookRunLog } from './hook_logger.js';
+import { loadEndpointBase } from '../sender/endpoint_config.js';
+import { resolveHardwareUuid } from './hardware_uuid.js';
+import { enforceRemediation, fetchSync, reportAutofixApplied, syncRemediations } from './remediation_sync.js';
+import { sendConfigFile } from '../sender/batch_sender.js';
+import { readStoredAuthKey } from '../auth/auth_key_store.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** 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;
+}
+/** Deep-equal comparison via JSON serialisation (handles booleans, strings, numbers, null). */
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+// ---------------------------------------------------------------------------
+// Check runner — Section 6: real per-check evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate current on-disk configs against remediation_instructions.json only (no server).
+ * Writes compliance.json and returns the status for prompt gating.
+ * Logs `compliance_check: local_file_check_wall_ms=<n>` — instruction + config reads and comparisons only (not sync/remediate).
+ */
+export function runLocalRemediationComplianceCheck() {
+    try {
+        const { remediations: rawEntries } = readRemediationInstructionsFile();
+        const entries = rawEntries;
+        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 = [];
+        for (const entry of entries) {
+            const compliance = entry.compliance;
+            if (!compliance)
+                continue;
+            if (compliance.file_format !== 'json') {
+                hookRunLog(`compliance_check: skipping non-json entry uuid=${entry.uuid}`);
+                continue;
+            }
+            const checks = compliance.checks ?? [];
+            if (checks.length === 0)
+                continue;
+            if (!existsSync(entry.config_file_path)) {
+                hookRunLog(`compliance_check: config file not found, skipping uuid=${entry.uuid}`);
+                continue;
+            }
+            let configJson;
+            try {
+                configJson = JSON.parse(readFileSync(entry.config_file_path, 'utf8'));
+            }
+            catch {
+                hookRunLog(`compliance_check: could not parse config file, skipping uuid=${entry.uuid}`);
+                continue;
+            }
+            for (const check of checks) {
+                const currentValue = getByPath(configJson, check.setting_path);
+                const leafKey = check.setting_path.split('.').pop();
+                const expectedValue = check.after[leafKey];
+                if (!deepEqual(currentValue, expectedValue)) {
+                    hookRunLog(`compliance_check: VIOLATION uuid=${entry.uuid} path=${check.setting_path} current=${JSON.stringify(currentValue)} expected=${JSON.stringify(expectedValue)}`);
+                    violations.push({
+                        uuid: entry.uuid,
+                        finding_formatted_id: compliance.finding_formatted_id,
+                        setting_path: check.setting_path,
+                        description: check.description,
+                        severity: compliance.severity,
+                        autofix_allowed: compliance.autofix_allowed,
+                        config_file_path: entry.config_file_path,
+                        expected_value: expectedValue,
+                        message: `[${compliance.finding_formatted_id}] ${entry.finding_title ?? compliance.description}\nDescription: ${entry.finding_description ?? compliance.description}\nHow to fix: Set ${check.setting_path} to ${JSON.stringify(expectedValue)} in ${entry.config_file_path}`,
+                    });
+                }
+            }
+        }
+        const status = {
+            status: violations.length > 0 ? 'fail' : 'ok',
+            checked_at: new Date().toISOString(),
+            manifest_uuids: uuids,
+            violations,
+        };
+        hookRunLog(`compliance_check: done — status=${status.status} violations=${violations.length} uuids=${uuids.length}`);
+        return status;
+    }
+    catch (err) {
+        hookRunLog(`compliance_check: unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+        const fallback = {
+            status: 'ok',
+            checked_at: new Date().toISOString(),
+            manifest_uuids: [],
+            violations: [],
+        };
+        return fallback;
+    }
+}
+export function applyAutofixViolations(violations) {
+    const autofixable = violations.filter((v) => v.autofix_allowed);
+    if (autofixable.length === 0)
+        return { fixed: 0, restartCommands: [], failedViolations: [], reportPromises: [] };
+    const { remediations } = readRemediationInstructionsFile();
+    const byUuid = new Map(remediations.map((r) => [r.uuid, r]));
+    let fixed = 0;
+    const seen = new Set();
+    const restartCommands = [];
+    const failedViolations = [];
+    const reportPromises = [];
+    const oneTimeAppliedUuids = new Set();
+    for (const violation of autofixable) {
+        if (seen.has(violation.uuid))
+            continue;
+        const instruction = byUuid.get(violation.uuid);
+        if (!instruction) {
+            hookRunLog(`autofix: no instruction found for uuid=${violation.uuid}, skipping`);
+            failedViolations.push(violation);
+            continue;
+        }
+        const inst = instruction;
+        const ok = enforceRemediation(inst);
+        if (ok) {
+            seen.add(violation.uuid);
+            fixed++;
+            hookRunLog(`autofix: applied uuid=${inst.uuid} path=${inst.config_file_path}`);
+            reportPromises.push(reportAutofixApplied(inst.uuid, 'success'));
+            if (inst.file_type) {
+                const authKey = readStoredAuthKey();
+                if (authKey) {
+                    reportPromises.push(sendConfigFile({ file_type: inst.file_type, file_path: inst.config_file_path, raw_content: inst.recommended_settings }, resolveHardwareUuid(), authKey).then((ok) => {
+                        hookRunLog(`autofix: re-sent updated file uuid=${inst.uuid} ok=${ok}`);
+                    }));
+                }
+            }
+            const compliance = inst.compliance;
+            if (compliance?.restart_required && compliance.restart_command) {
+                hookRunLog(`autofix: restart required uuid=${inst.uuid} command=${compliance.restart_command}`);
+                restartCommands.push(compliance.restart_command);
+            }
+            if (!inst.is_enforced) {
+                oneTimeAppliedUuids.add(inst.uuid);
+            }
+        }
+        else {
+            failedViolations.push(violation);
+        }
+    }
+    if (oneTimeAppliedUuids.size > 0) {
+        const remaining = remediations.filter((r) => !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).
+        const remainingUuids = remaining.map((r) => r.uuid);
+        reportPromises.push(fetchSync(loadEndpointBase(), resolveHardwareUuid(), remainingUuids)
+            .then(() => hookRunLog(`autofix: post-autofix heartbeat sent uuids=${remainingUuids.length}`))
+            .catch(() => undefined));
+    }
+    if (fixed > 0) {
+        hookRunLog(`autofix: total_applied=${fixed}`);
+    }
+    return { fixed, restartCommands, failedViolations, reportPromises };
+}
+/** Background refresh: server sync for latest instructions, then local evaluation and latch write. */
+export async function runComplianceCheck() {
+    try {
+        await syncRemediations(loadEndpointBase(), resolveHardwareUuid());
+    }
+    catch (err) {
+        hookRunLog(`compliance_check: remediation_sync unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    runLocalRemediationComplianceCheck();
+}

package/dist/log_config_files/runtime/main_runner.js

@@ -84,13 +84,15 @@ async function sendAllConfigFiles(configFiles, hardwareUuid, authKey) {
         const ok = await sendHookRequestUpdateManifest(hardwareUuid, authKey, hookRequestId, manifest);
         hookRunLog(`hook-request update manifest result=${ok ? 'ok' : 'fail'}`);
     }
-    const exitCode = batchResult.accepted === configFiles.length ? 0 : 1;
+    // Exit 0 if anything was persisted so the shell hook keeps last_log and throttles. Exit 1 only when
+    // every item failed (e.g. SQLite locked on server) — otherwise partial success used to return 1,
+    // the hook deleted last_log, and the next prompt re-uploaded all files every time.
+    const exitCode = batchResult.accepted > 0 ? 0 : 1;
     hookRunLog(`summary: exit=${exitCode} collected=${configFiles.length} sent=${batchResult.accepted} failed=${configFiles.length - batchResult.accepted} hook_id=${hookRequestId ?? 'n/a'}`);
     hookRunLog(`done`);
     process.exit(exitCode);
 }
 async function main() {
-    const startMs = Date.now();
     hookLogReplace();
     const hardwareUuid = resolveHardwareUuid();
     const endpointBase = loadEndpointBase();
@@ -105,7 +107,6 @@ async function main() {
         hookRunLog(`auth: failed ${err instanceof Error ? err.message : String(err)}`);
         throw err;
     }
-    const collectStartMs = Date.now();
     let configFiles;
     try {
         configFiles = await collectAllConfigFiles(endpointBase);
@@ -115,9 +116,8 @@ async function main() {
         throw err;
     }
     await addSensitivePathsAudit(endpointBase, configFiles);
-    const collectMs = Date.now() - collectStartMs;
     const fileTypes = [...new Set(configFiles.map((c) => c.file_type))].join(', ');
-    hookRunLog(`collected ${configFiles.length} config file(s) collect_ms=${collectMs} file_types=${fileTypes}`);
+    hookRunLog(`collected ${configFiles.length} config file(s) file_types=${fileTypes}`);
     const claudeSettings = configFiles.filter((c) => c.file_type === 'claude_settings');
     if (claudeSettings.length > 0)
         hookRunLog(`claude_settings in batch: ${claudeSettings.length} path(s): ${claudeSettings.map((c) => c.file_path).join(', ')}`);
@@ -127,8 +127,6 @@ async function main() {
         hookRunLog('no config files found, exiting');
         process.exit(0);
     }
-    const totalMs = Date.now() - startMs;
-    hookRunLog(`total setup ms=${totalMs}`);
     await sendAllConfigFiles(configFiles, hardwareUuid, authKey);
 }
 async function logSingleFile(filePath) {

package/dist/log_config_files/runtime/management_storage.js

@@ -0,0 +1,46 @@
+/**
+ * Paths and JSON persistence for ~/opt-ai-sec/management:
+ * - remediation_instructions.json (remediations[])
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { OPT_AI_SEC_MANAGEMENT_REL } from '../../bootstrap_constants.js';
+export const REMEDIATION_INSTRUCTIONS_BASENAME = 'remediation_instructions.json';
+export function getManagementDir() {
+    return join(homedir(), OPT_AI_SEC_MANAGEMENT_REL);
+}
+export function getRemediationInstructionsPath() {
+    return join(getManagementDir(), REMEDIATION_INSTRUCTIONS_BASENAME);
+}
+export function atomicWriteJson(filePath, data) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${filePath}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+    renameSync(tmp, filePath);
+}
+function parseInstructionsRaw(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.remediations) ? parsed : { remediations: [] };
+    }
+    catch {
+        return { remediations: [] };
+    }
+}
+export function writeRemediationInstructionsFile(file) {
+    atomicWriteJson(getRemediationInstructionsPath(), file);
+}
+export function readRemediationInstructionsFile() {
+    const path = getRemediationInstructionsPath();
+    if (!existsSync(path))
+        return { remediations: [] };
+    try {
+        return parseInstructionsRaw(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return { remediations: [] };
+    }
+}

package/dist/log_config_files/runtime/remediation_sync.js

@@ -0,0 +1,276 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { executeGet, executeBody } from '../../endpoint_client/http_transport.js';
+import { hookRunLog } from './hook_logger.js';
+import { getRemediationInstructionsPath, readRemediationInstructionsFile, writeRemediationInstructionsFile, } from './management_storage.js';
+import { readStoredAuthKey } from '../auth/auth_key_store.js';
+import { createSignature } from '../sender/signing.js';
+import { loadEndpointBase } from '../sender/endpoint_config.js';
+import { resolveHardwareUuid } from './hardware_uuid.js';
+// ---------------------------------------------------------------------------
+// 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);
+    }
+    const missing = [...want].filter((u) => !byUuid.has(u));
+    if (missing.length > 0) {
+        try {
+            const fetched = await fetchManifest(endpointBase, machineUuid, missing);
+            if (fetched) {
+                for (const inst of fetched) {
+                    if (want.has(inst.uuid))
+                        byUuid.set(inst.uuid, inst);
+                }
+            }
+        }
+        catch (err) {
+            hookRunLog(`remediation_manifest_backfill_error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const stillMissing = [...want].filter((u) => !byUuid.has(u));
+        if (stillMissing.length > 0) {
+            hookRunLog(`remediation_manifest_backfill_incomplete: uuids=${stillMissing.join(',')}`);
+        }
+    }
+    const remediations = [...byUuid.values()].sort((a, b) => a.uuid.localeCompare(b.uuid));
+    const payload = { remediations };
+    const nextJson = JSON.stringify(payload, null, 2);
+    const path = getRemediationInstructionsPath();
+    let prev = '';
+    if (existsSync(path)) {
+        try {
+            prev = readFileSync(path, 'utf8');
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (prev !== nextJson) {
+        writeInstructions(payload);
+    }
+}
+// ---------------------------------------------------------------------------
+// API helpers
+// ---------------------------------------------------------------------------
+function resolveOrigin(endpointBase) {
+    try {
+        return new URL(endpointBase).origin;
+    }
+    catch {
+        return endpointBase.replace(/\/+$/, '');
+    }
+}
+export async function fetchSync(endpointBase, machineUuid, activeUuids, timeoutMs = 8000) {
+    const uuidsParam = activeUuids.join(',');
+    const url = `${resolveOrigin(endpointBase)}/api/findings/remediations/sync/?machine_uuid=${encodeURIComponent(machineUuid)}&active_uuids=${encodeURIComponent(uuidsParam)}`;
+    const { statusCode, body } = await executeGet(url, timeoutMs);
+    if (statusCode !== 200 || !body)
+        return null;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchManifest(endpointBase, machineUuid, uuids, timeoutMs = 8000) {
+    const url = `${resolveOrigin(endpointBase)}/api/findings/remediations/manifest/?machine_uuid=${encodeURIComponent(machineUuid)}&uuids=${encodeURIComponent(uuids.join(','))}`;
+    const { statusCode, body } = await executeGet(url, timeoutMs);
+    if (statusCode !== 200 || !body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        return Array.isArray(parsed.remediations) ? parsed.remediations : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Enforce / remove
+// ---------------------------------------------------------------------------
+export function enforceRemediation(instruction) {
+    try {
+        const dir = dirname(instruction.config_file_path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const content = JSON.stringify(instruction.recommended_settings, null, 2);
+        const tmp = `${instruction.config_file_path}.tmp`;
+        writeFileSync(tmp, content, 'utf8');
+        renameSync(tmp, instruction.config_file_path);
+        return true;
+    }
+    catch (err) {
+        hookRunLog(`remediation_enforce_error: uuid=${instruction.uuid} err=${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Autofix reporting
+// ---------------------------------------------------------------------------
+/**
+ * Fire-and-forget: notify the server that this machine applied an autofix for the given
+ * remediation UUID. Creates one EnforcementLog row on the server for the audit trail.
+ * Never throws — any failure is logged and silently swallowed so it cannot block the
+ * autofix flow.
+ */
+export function reportAutofixApplied(remediationUuid, result) {
+    const authKey = readStoredAuthKey();
+    if (!authKey) {
+        hookRunLog(`autofix_report: no auth key available, skipping report for uuid=${remediationUuid}`);
+        return Promise.resolve();
+    }
+    const hardwareUuid = resolveHardwareUuid();
+    const endpointBase = loadEndpointBase();
+    const url = `${resolveOrigin(endpointBase)}/endpoint_security/api/autofix-applied/`;
+    const payload = { hardware_uuid: hardwareUuid, remediation_uuid: remediationUuid, result };
+    const signature = createSignature(payload, authKey.key);
+    const body = JSON.stringify({ ...payload, signature });
+    return executeBody(url, 'POST', body, 8000)
+        .then(({ statusCode }) => {
+        if (statusCode !== 200) {
+            hookRunLog(`autofix_report: server returned ${statusCode} for uuid=${remediationUuid}`);
+        }
+    })
+        .catch((err) => {
+        hookRunLog(`autofix_report: request failed for uuid=${remediationUuid}: ${err instanceof Error ? err.message : String(err)}`);
+    });
+}
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+export async function syncRemediations(endpointBase, machineUuid) {
+    let remediations = readInstructions().remediations;
+    const activeUuids = remediations.map((r) => r.uuid);
+    let syncResult;
+    try {
+        syncResult = await fetchSync(endpointBase, machineUuid, activeUuids);
+    }
+    catch (err) {
+        hookRunLog(`remediation_sync_error: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    if (!syncResult) {
+        hookRunLog(`remediation_sync: no response from server, skipping`);
+        return;
+    }
+    if (syncResult.status === 'unchanged') {
+        hookRunLog(`remediation_sync: unchanged enforced=${activeUuids.length}`);
+        const want = new Set(activeUuids);
+        const have = new Map(remediations.map((r) => [r.uuid, r]));
+        const needBackfill = activeUuids.some((u) => !have.has(u));
+        const haveOrphan = remediations.some((r) => !want.has(r.uuid));
+        const path = getRemediationInstructionsPath();
+        if (activeUuids.length > 0) {
+            if (needBackfill || 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}`);
+    const removedSet = new Set(removed);
+    let removedCount = 0;
+    remediations = remediations.filter((r) => {
+        if (removedSet.has(r.uuid)) {
+            removedCount++;
+            hookRunLog(`remediation_remove: uuid=${r.uuid} path=${r.config_file_path}`);
+            return false;
+        }
+        return true;
+    });
+    let manifest = null;
+    if (added.length > 0) {
+        try {
+            manifest = await fetchManifest(endpointBase, machineUuid, added);
+        }
+        catch (err) {
+            hookRunLog(`remediation_manifest_error: ${err instanceof Error ? err.message : String(err)}`);
+            if (removedCount > 0) {
+                remediations.sort((a, b) => a.uuid.localeCompare(b.uuid));
+                writeInstructions({ remediations });
+            }
+            return;
+        }
+        if (!manifest) {
+            hookRunLog(`remediation_sync: manifest fetch failed, skipping`);
+            if (removedCount > 0) {
+                remediations.sort((a, b) => a.uuid.localeCompare(b.uuid));
+                writeInstructions({ remediations });
+            }
+            return;
+        }
+    }
+    const existingUuids = new Set(remediations.map((r) => r.uuid));
+    const addedSet = new Set(added);
+    const overlay = [];
+    for (const instruction of manifest ?? []) {
+        if (!addedSet.has(instruction.uuid))
+            continue;
+        if (existingUuids.has(instruction.uuid)) {
+            // Enforced remediations are always in `added`; overwrite local copy with fresh server data.
+            const idx = remediations.findIndex((r) => r.uuid === instruction.uuid);
+            if (idx >= 0)
+                remediations[idx] = instruction;
+        }
+        else {
+            remediations.push(instruction);
+            existingUuids.add(instruction.uuid);
+        }
+        overlay.push(instruction);
+        hookRunLog(`remediation_instructions_saved: uuid=${instruction.uuid} path=${instruction.config_file_path}`);
+    }
+    const addedCount = overlay.length;
+    if (removedCount > 0 || addedCount > 0) {
+        remediations.sort((a, b) => a.uuid.localeCompare(b.uuid));
+        writeInstructions({ remediations });
+        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}`);
+}