@optimuslabs/harness-map-staging 1.5.16

package/dist/log_config_files/runtime/main_runner.js

@@ -0,0 +1,376 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const HOME_DIR = homedir();
+import { getFileCollectionPatterns, FILE_PATH_REGISTRY_FILE_PATTERNS_PATH } from '../../endpoint_client/index.js';
+import { OPTIMUSLABS_LOGS_REL, LOG_GROUP_AUDIT } from '../../bootstrap_constants.js';
+import { runSensitivePathsAudit } from '../../log_sensitive_paths_audit.js';
+import { loadEndpointBase, getEndpointSource } from '../sender/endpoint_config.js';
+import { hookLogReplace, hookRunLog, hookLogError, readHookLog } from './hook_logger.js';
+import { getStoryId, flushBufferedClientEvents, reportFunctionalRun, reportFunctionalFailureAwait, } from './client_event_reporter.js';
+import { resolveHookTypeFromEnv } from './hook_type_for_request.js';
+import { resolveHardwareUuid } from './hardware_uuid.js';
+import { ensureAuthentication } from '../auth/auth_flow.js';
+import { readJSONFile, readMarkdownFile } from '../readers/file_readers.js';
+import { isVscdbVirtualPath, tryReadVscdbVirtualFile, summarizeComposerPayloadForDiagnostics, } from '../readers/vscdb_config_builder.js';
+import { persistVscdbComposerContractFromPatternsResponse } from '../readers/vscdb_reader.js';
+import { collectConfigFilesFromPatterns, collectMcpToolFiles, collectConfigFilesFromInstalledPlugins, collectPluginCacheMcpFiles, collectMcpFromClaudeJsonProjects, collectClaudeTokenUsage, collectCopilotTokenUsage, collectOpencodeTokenUsage, collectCodexTokenUsage, collectCursorTokenUsage, collectHermesTokenUsage, collectOpenclawTokenUsage, collectPiTokenUsage, collectCoworkDesktopVersion, collectGrokCliVersion, collectClaudeDesktopExtensionManifests, collectClaudeDesktopExtensionSettingsFiles, enrichClaudeDesktopExtensionsInstallationsUpload, determineFileTypeFromPath, } from '../collection/config_collector.js';
+import { ensureCursorUserSettingsSnapshotInBatch } from '../collection/ensure_cursor_user_settings_snapshot.js';
+import { collectSkillsCliInstalled } from '../collection/skills_cli_collector.js';
+import { collectWorkspaceVscdbs } from '../collection/mcp_tool_collector.js';
+import { collectCursorProjectWorkspaceMcpConfigs } from '../collection/cursor_project_mcp_collector.js';
+import { normalizePathSkipPrefixes } from '../paths/pattern_resolver.js';
+import { sendConfigFile, sendConfigFilesBatch, sendHookRequestCreate, sendHookRequestUpdateManifest, sendIngestSessionStart, sendIngestSessionFinish, BATCH_CHUNK_SIZE } from '../sender/batch_sender.js';
+import { canonicalCursorUserStateVscdbPath } from './remediation_config_path.js';
+import { ensureWorkspaceRepoEnv, resolveProjectRoot } from './workspace_repo.js';
+import { scanActiveWorktrees, activeWorktreeRootSet, filterConfigFilesToActiveWorktrees, } from './worktree_scanner.js';
+import { createSignature, canonicalizePayload } from '../sender/signing.js';
+const PROJECT_ROOT = resolveProjectRoot();
+async function collectAllConfigFiles(endpointBase) {
+    const patternsUrl = `${endpointBase.replace(/\/+$/, '')}${FILE_PATH_REGISTRY_FILE_PATTERNS_PATH}`;
+    hookRunLog(`fetching patterns from ${patternsUrl}`);
+    const patternsResponse = await getFileCollectionPatterns(endpointBase);
+    const n = patternsResponse?.patterns?.length ?? 0;
+    hookRunLog(`patterns: ${n} pattern(s) received`);
+    if (!patternsResponse?.patterns?.length) {
+        const msg = 'File collection requires patterns from the API; none received. Check endpoint and file-path-registry.';
+        hookRunLog(msg);
+        throw new Error(msg);
+    }
+    persistVscdbComposerContractFromPatternsResponse(patternsResponse);
+    hookRunLog(`scanning config files`);
+    const configFiles = collectConfigFilesFromPatterns(patternsResponse.patterns, PROJECT_ROOT, hookRunLog, {
+        vscdbEntrySpecs: patternsResponse.vscdb_entry_specs,
+        vscdb_read_queries: patternsResponse.vscdb_read_queries,
+        vscdb_merge_from_composer_state: patternsResponse.vscdb_merge_from_composer_state,
+        client_path_constants: patternsResponse.client_path_constants,
+        path_resolution_specs: patternsResponse.path_resolution_specs,
+        home_recurse_skip_dirs: patternsResponse.home_recurse_skip_dirs,
+        absolute_path_prefixes: patternsResponse.absolute_path_prefixes,
+        mcp_tool_glob_spec: patternsResponse.mcp_tool_glob_spec ?? null,
+    });
+    hookRunLog(`scanning MCP tool cache`);
+    const mcpToolGlobPattern = patternsResponse.patterns.find((p) => p.path_resolution === 'mcp_tool_glob');
+    const mcpToolSkipPrefixes = normalizePathSkipPrefixes(mcpToolGlobPattern?.path_skip_prefixes);
+    const existingPaths = new Set(configFiles.map((c) => `${c.file_type}\t${c.file_path}`));
+    for (const m of collectMcpToolFiles(mcpToolSkipPrefixes, patternsResponse.client_path_constants)) {
+        const key = `${m.file_type}\t${m.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(m);
+        }
+    }
+    hookRunLog(`scanning Cursor project workspace MCP configs (~/.cursor/projects/*/mcp-cache.json)`);
+    for (const m of collectCursorProjectWorkspaceMcpConfigs(mcpToolSkipPrefixes, patternsResponse.client_path_constants, patternsResponse.workspace_vscdb_spec, HOME_DIR)) {
+        const key = `${m.file_type}\t${m.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(m);
+        }
+    }
+    if (patternsResponse.workspace_vscdb_spec) {
+        hookRunLog(`scanning Cursor workspace vscdb files`);
+        for (const m of collectWorkspaceVscdbs(patternsResponse.workspace_vscdb_spec)) {
+            const key = `${m.file_type}\t${m.file_path}`;
+            if (!existingPaths.has(key)) {
+                existingPaths.add(key);
+                configFiles.push(m);
+            }
+        }
+    }
+    hookRunLog(`scanning installed plugins`);
+    if (!patternsResponse.client_path_constants)
+        throw new Error('client_path_constants required from API response');
+    configFiles.push(...collectConfigFilesFromInstalledPlugins(patternsResponse.client_path_constants));
+    hookRunLog(`scanning Claude plugin cache MCP manifests`);
+    for (const entry of collectPluginCacheMcpFiles(patternsResponse.client_path_constants, HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`scanning Claude known projects from ~/.claude.json`);
+    for (const entry of collectMcpFromClaudeJsonProjects(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`aggregating Claude token usage from ~/.claude/projects transcripts`);
+    for (const entry of collectClaudeTokenUsage(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`aggregating Copilot token usage from ~/.copilot/session-state transcripts`);
+    for (const entry of collectCopilotTokenUsage(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`aggregating OpenCode token usage from ~/.local/share/opencode/opencode.db`);
+    for (const entry of collectOpencodeTokenUsage(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`aggregating Codex token usage from ~/.codex/sessions rollouts`);
+    for (const entry of collectCodexTokenUsage(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`aggregating Cursor token usage from state.vscdb`);
+    for (const entry of collectCursorTokenUsage(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`aggregating Hermes token usage from ~/.hermes/state.db`);
+    for (const entry of collectHermesTokenUsage(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`aggregating OpenClaw token usage from ~/.openclaw/agents/*/sessions/sessions.json`);
+    for (const entry of collectOpenclawTokenUsage(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`aggregating Pi token usage from ~/.pi/agent/sessions transcripts`);
+    for (const entry of collectPiTokenUsage(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`reading Claude Desktop app version for Cowork's Agent Profile`);
+    for (const entry of collectCoworkDesktopVersion(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`reading Grok CLI version`);
+    for (const entry of collectGrokCliVersion(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    hookRunLog(`merging disk-only Claude Desktop extensions into extensions-installations.json`);
+    const diskExtMerge = enrichClaudeDesktopExtensionsInstallationsUpload(configFiles, HOME_DIR);
+    hookRunLog(`claude desktop extensions: merged=${diskExtMerge.mergedCount} had_registry_upload=${diskExtMerge.hadRegistryUpload}`);
+    for (const entry of collectClaudeDesktopExtensionSettingsFiles(HOME_DIR)) {
+        const key = `${entry.file_type}\t${entry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(entry);
+        }
+    }
+    if (!diskExtMerge.hadRegistryUpload && diskExtMerge.mergedCount > 0) {
+        hookRunLog(`scanning Claude Desktop extension manifests on disk (no registry upload in batch)`);
+        for (const entry of collectClaudeDesktopExtensionManifests(HOME_DIR)) {
+            const key = `${entry.file_type}\t${entry.file_path}`;
+            if (!existingPaths.has(key)) {
+                existingPaths.add(key);
+                configFiles.push(entry);
+            }
+        }
+    }
+    const skillsCliEntry = collectSkillsCliInstalled(PROJECT_ROOT, hookRunLog);
+    if (skillsCliEntry) {
+        const key = `${skillsCliEntry.file_type}\t${skillsCliEntry.file_path}`;
+        if (!existingPaths.has(key)) {
+            existingPaths.add(key);
+            configFiles.push(skillsCliEntry);
+        }
+    }
+    const worktreeReport = scanActiveWorktrees(PROJECT_ROOT, HOME_DIR);
+    const activeRoots = activeWorktreeRootSet(worktreeReport);
+    const beforeFilter = configFiles.length;
+    const filtered = filterConfigFilesToActiveWorktrees(configFiles, activeRoots);
+    hookRunLog(`worktree_scan: active=${worktreeReport.length} config_files ${beforeFilter}→${filtered.length}`);
+    return { configFiles: filtered, worktreeReport };
+}
+async function addSensitivePathsAudit(endpointBase, configFiles) {
+    hookRunLog(`running sensitive paths audit`);
+    const auditOutputDir = join(homedir(), OPTIMUSLABS_LOGS_REL, LOG_GROUP_AUDIT);
+    try {
+        const auditResult = await runSensitivePathsAudit(endpointBase, auditOutputDir, PROJECT_ROOT);
+        hookRunLog(`sensitive_paths_audit: ${auditResult.paths.length} path(s)`);
+        configFiles.push({ file_type: 'sensitive_paths_audit', file_path: 'sensitive_paths_audit.txt', raw_content: { paths: auditResult.paths } });
+    }
+    catch (err) {
+        hookRunLog(`sensitive_paths_audit_error: ${err instanceof Error ? err.message : String(err)}`);
+        hookLogError('sensitive_paths_audit', err, { endpoint: endpointBase, output_dir: auditOutputDir });
+        configFiles.push({ file_type: 'sensitive_paths_audit', file_path: 'sensitive_paths_audit.txt', raw_content: { paths: [] } });
+    }
+}
+async function sendAllConfigFiles(configFiles, worktreeReport, hardwareUuid, authKey) {
+    const hookType = resolveHookTypeFromEnv();
+    const manifest = configFiles.map((c) => canonicalCursorUserStateVscdbPath(c.file_path));
+    const workspaceRepo = ensureWorkspaceRepoEnv(manifest);
+    const hookRequestId = await sendHookRequestCreate(hardwareUuid, authKey, hookType, workspaceRepo);
+    hookRunLog(`hook-request id=${hookRequestId ?? 'none'}`);
+    const ingestSessionId = await sendIngestSessionStart(hardwareUuid, authKey);
+    hookRunLog(`ingest-session id=${ingestSessionId ?? 'none'}`);
+    const estimatedRequests = Math.ceil(configFiles.length / BATCH_CHUNK_SIZE);
+    hookRunLog(`config send: batch ${configFiles.length} file(s) in ~${estimatedRequests} request(s)${hookRequestId != null ? ` hook_request_id=${hookRequestId}` : ''}${ingestSessionId ? ` ingest_session_id=${ingestSessionId}` : ''}`);
+    const batchResult = await sendConfigFilesBatch(configFiles, hardwareUuid, authKey, hookRequestId ?? undefined, ingestSessionId ?? undefined);
+    hookRunLog(`config files ${batchResult.accepted}/${configFiles.length} logged (batch)`);
+    if (batchResult.failed > 0)
+        hookRunLog(`config_failed: ${batchResult.failed} item(s) in batch`);
+    if (hookRequestId != null) {
+        const hookLogContent = readHookLog();
+        const ok = await sendHookRequestUpdateManifest(hardwareUuid, authKey, hookRequestId, manifest, hookLogContent || undefined);
+        hookRunLog(`hook-request update manifest result=${ok ? 'ok' : 'fail'}`);
+    }
+    // Finish ingest session: failed_uploads hold set, worktree prune, config prune-on-absence, and scans.
+    // Run finish whenever a session was started — even if every upload failed — so worktree
+    // cleanup still runs for machines with only stale worktrees on disk.
+    if (ingestSessionId) {
+        const ok = await sendIngestSessionFinish(hardwareUuid, authKey, ingestSessionId, batchResult.failedArtifacts, worktreeReport);
+        hookRunLog(`ingest-session finish result=${ok ? 'ok' : 'fail'}`
+            + (batchResult.failedArtifacts.length > 0
+                ? ` held=${batchResult.failedArtifacts.length} failed upload(s)`
+                : ''));
+    }
+    // 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;
+    const failedCount = configFiles.length - batchResult.accepted;
+    hookRunLog(`summary: exit=${exitCode} collected=${configFiles.length} sent=${batchResult.accepted} failed=${failedCount} hook_id=${hookRequestId ?? 'n/a'}`);
+    hookRunLog(`done`);
+    // Inventory telemetry — awaited so the POST lands before process.exit.
+    const outcome = exitCode === 0 ? (failedCount > 0 ? 'partial' : 'ok') : 'failed';
+    await reportFunctionalRun({
+        unit: 'inventory',
+        command: 'log_config_files',
+        outcome,
+        exit_code: exitCode,
+        message: `collected=${configFiles.length} sent=${batchResult.accepted} failed=${failedCount}`,
+        metadata: hookRequestId != null ? { hook_request_id: String(hookRequestId) } : undefined,
+    });
+    process.exit(exitCode);
+}
+async function main() {
+    hookLogReplace();
+    getStoryId();
+    void flushBufferedClientEvents();
+    const hardwareUuid = resolveHardwareUuid();
+    const endpointBase = loadEndpointBase();
+    hookRunLog(`start endpoint=${endpointBase} hardware_uuid=${hardwareUuid}`);
+    hookRunLog(`endpoint_source=${getEndpointSource()} cwd=${process.cwd()}`);
+    const envForLog = (v) => (v && v.trim() ? v.trim() : 'unset');
+    hookRunLog(`env: OPTIMUS_HOOK_TYPE=${envForLog(process.env.OPTIMUS_HOOK_TYPE)} OPTIMUS_PROJECT_DIR=${envForLog(process.env.OPTIMUS_PROJECT_DIR)} OPTIMUS_WORKSPACE_REPO=${envForLog(process.env.OPTIMUS_WORKSPACE_REPO)} OPTIMUS_ENDPOINT=${envForLog(process.env.OPTIMUS_ENDPOINT)}`);
+    let authKey;
+    try {
+        authKey = await ensureAuthentication(hardwareUuid);
+    }
+    catch (err) {
+        hookRunLog(`auth: failed ${err instanceof Error ? err.message : String(err)}`);
+        // Auth failure is its own functional unit; report (awaited) then exit so we don't
+        // also surface it as a generic inventory failure via the cli catch.
+        await reportFunctionalFailureAwait('auth_version', 'ensureAuthentication', err);
+        process.exit(1);
+    }
+    let configFiles;
+    let worktreeReport = [];
+    try {
+        const collected = await collectAllConfigFiles(endpointBase);
+        configFiles = collected.configFiles;
+        worktreeReport = collected.worktreeReport;
+    }
+    catch (err) {
+        hookRunLog(`patterns_error: ${err instanceof Error ? err.message : String(err)}`);
+        throw err;
+    }
+    await addSensitivePathsAudit(endpointBase, configFiles);
+    ensureCursorUserSettingsSnapshotInBatch(configFiles);
+    const fileTypes = [...new Set(configFiles.map((c) => c.file_type))].join(', ');
+    hookRunLog(`collected ${configFiles.length} config file(s) file_types=${fileTypes}`);
+    for (const c of configFiles) {
+        if (!c.file_path.replace(/\\/g, '/').includes('#composerState'))
+            continue;
+        const tail = c.file_path.length > 120 ? `…${c.file_path.slice(-120)}` : c.file_path;
+        hookRunLog(`diag pre-upload #composerState ${summarizeComposerPayloadForDiagnostics(c.raw_content)} path=${tail}`);
+    }
+    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(', ')}`);
+    else
+        hookRunLog(`claude_settings in batch: 0 (none collected)`);
+    if (configFiles.length === 0) {
+        hookRunLog('no config files found, exiting');
+        process.exit(0);
+    }
+    await sendAllConfigFiles(configFiles, worktreeReport, hardwareUuid, authKey);
+}
+async function logSingleFile(filePath) {
+    const hardwareUuid = resolveHardwareUuid();
+    const authKey = await ensureAuthentication(hardwareUuid);
+    const patternsResponse = await getFileCollectionPatterns(loadEndpointBase());
+    const isVscdb = isVscdbVirtualPath(filePath, patternsResponse ?? null);
+    if (!existsSync(filePath) && !isVscdb) {
+        console.error(`File not found: ${filePath}`);
+        return false;
+    }
+    const patterns = patternsResponse?.patterns ?? [];
+    let rawContent = null;
+    let fileType = determineFileTypeFromPath(filePath, patterns) ?? undefined;
+    if (isVscdb) {
+        const vscdbResult = tryReadVscdbVirtualFile(filePath, patternsResponse ?? null);
+        if (!vscdbResult) {
+            console.error(`Could not read vscdb virtual file: ${filePath}`);
+            return false;
+        }
+        rawContent = vscdbResult.rawContent;
+        fileType = vscdbResult.fileType;
+    }
+    else {
+        rawContent = readJSONFile(filePath);
+        if (!rawContent) {
+            const markdown = readMarkdownFile(filePath);
+            if (markdown !== null) {
+                rawContent = { content: markdown, source: 'file' };
+                if (!fileType)
+                    fileType = determineFileTypeFromPath(filePath, patterns) ?? undefined;
+            }
+        }
+    }
+    if (!rawContent) {
+        console.error(`Could not read file: ${filePath}`);
+        return false;
+    }
+    if (!fileType) {
+        fileType = determineFileTypeFromPath(filePath, patterns) ?? undefined;
+        if (!fileType) {
+            console.error(`Could not determine file type for: ${filePath}`);
+            return false;
+        }
+    }
+    return sendConfigFile({ file_type: fileType, file_path: filePath, raw_content: rawContent }, hardwareUuid, authKey);
+}
+export { main, logSingleFile, createSignature, canonicalizePayload, sendConfigFile, sendConfigFilesBatch, BATCH_CHUNK_SIZE };

package/dist/log_config_files/runtime/management_storage.js

@@ -0,0 +1,144 @@
+/**
+ * Paths and JSON persistence for ~/.optimuslabs/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 { OPTIMUSLABS_MANAGEMENT_REL, OPTIMUSLABS_LOGS_REL } from '../../bootstrap_constants.js';
+export const REMEDIATION_INSTRUCTIONS_BASENAME = 'remediation_instructions.json';
+/** Pending state.vscdb writes applied after Cursor exits (IDE holds the DB locked). */
+export const DEFERRED_VSCDB_APPLY_BASENAME = 'optimus_deferred_vscdb_apply.json';
+/**
+ * Shell stdout/stderr from the trusted deferred restart pipeline (apply_deferred_vscdb + open Cursor).
+ * Co-located in the root vscdb/ folder next to the apply-queue + contract it operates on — the whole
+ * deferred-vscdb-restart subsystem lives together, so there is no separate logs/vscdb/.
+ */
+export const DEFERRED_VSCDB_RESTART_LOG_BASENAME = 'deferred_vscdb_restart.log';
+/**
+ * Cached subset of GET file-patterns: reactive ItemTable key + composer shadow keys from the backend.
+ * Written when patterns are fetched; remediations and vscdb reads use this so the npm package stays free
+ * of hardcoded Cursor paths.
+ */
+export const FILE_COLLECTION_VSCDB_CONTRACT_BASENAME = 'file_collection_vscdb_contract.json';
+/** User preferences for Optimus macOS dialogs (hook-driven). */
+export const DIALOG_PREFERENCES_BASENAME = 'optimus_dialog_preferences.json';
+export function sanitizeReactiveStorageItemKey(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.length > 512)
+        return undefined;
+    if (/['"\\]/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+function sanitizeComposerShadowKeys(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+export function sanitizeFileCollectionVscdbContract(contract) {
+    if (!contract || contract.version !== 1)
+        return null;
+    return {
+        version: 1,
+        reactive_storage_item_key: sanitizeReactiveStorageItemKey(contract.reactive_storage_item_key),
+        composer_shadow_keys: sanitizeComposerShadowKeys(contract.composer_shadow_keys),
+    };
+}
+export function getManagementDir() {
+    return join(homedir(), OPTIMUSLABS_MANAGEMENT_REL);
+}
+/** Root of the grouped hook log subtree (~/.optimuslabs/management/logs). */
+export function getLogsDir() {
+    return join(homedir(), OPTIMUSLABS_LOGS_REL);
+}
+/**
+ * Directory for vscdb state/contract files (~/.optimuslabs/management/vscdb), keeping the
+ * several generated vscdb artifacts grouped instead of dangling at the management root.
+ * Includes deferred_vscdb_restart.log (detached restart pipeline output).
+ */
+export function getVscdbStateDir() {
+    return join(getManagementDir(), 'vscdb');
+}
+/**
+ * Directory for non-log remediation state (~/.optimuslabs/management/remediation):
+ * remediation_instructions.json (what to fix) and remediation_apply_tracking.json
+ * (quarantine + verify-failure history that escapes the autofix restart loop).
+ * Remediation session logs live under logs/compliance/.
+ */
+export function getRemediationStateDir() {
+    return join(getManagementDir(), 'remediation');
+}
+export function getRemediationInstructionsPath() {
+    return join(getRemediationStateDir(), REMEDIATION_INSTRUCTIONS_BASENAME);
+}
+export function getDeferredVscdbApplyPath() {
+    return join(getVscdbStateDir(), DEFERRED_VSCDB_APPLY_BASENAME);
+}
+export function getDeferredVscdbRestartLogPath() {
+    return join(getVscdbStateDir(), DEFERRED_VSCDB_RESTART_LOG_BASENAME);
+}
+export function getFileCollectionVscdbContractPath() {
+    return join(getVscdbStateDir(), FILE_COLLECTION_VSCDB_CONTRACT_BASENAME);
+}
+/** Directory for macOS dialog assets/state (~/.optimuslabs/management/dialog): prefs + cached icon. */
+export function getDialogStateDir() {
+    return join(getManagementDir(), 'dialog');
+}
+export function getDialogPreferencesPath() {
+    return join(getDialogStateDir(), DIALOG_PREFERENCES_BASENAME);
+}
+export function readFileCollectionVscdbContract() {
+    const path = getFileCollectionVscdbContractPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return sanitizeFileCollectionVscdbContract(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeFileCollectionVscdbContract(contract) {
+    const sanitized = sanitizeFileCollectionVscdbContract(contract);
+    if (!sanitized)
+        return;
+    atomicWriteJson(getFileCollectionVscdbContractPath(), sanitized);
+}
+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/ops_target_path.js

@@ -0,0 +1,18 @@
+/**
+ * Map ops.add/set/remove keys to JSON dot-paths for apply + verify.
+ *
+ * Server may use either the leaf key (e.g. `deny`) or the full setting_path
+ * (e.g. `cursor.general.globalCursorIgnoreList`) as the op map key.
+ */
+export function resolveOpsTargetPath(settingPath, opKey) {
+    const parts = settingPath.split('.');
+    const leafKey = parts[parts.length - 1] ?? '';
+    const parentPath = parts.slice(0, -1).join('.');
+    if (opKey === settingPath || opKey === leafKey) {
+        return settingPath;
+    }
+    if (opKey.includes('.')) {
+        return opKey;
+    }
+    return parentPath ? `${parentPath}.${opKey}` : opKey;
+}