@optimuslabs/harness-map-staging 1.5.16

package/dist/log_config_files/readers/vscdb_reader.js

@@ -0,0 +1,337 @@
+import { existsSync } from 'node:fs';
+import { execSqlite3, resolveSqlite3Binary } from '../runtime/sqlite_binary.js';
+import { mergeCursorShadowKeyValue, mergeShadowKeysIntoComposerState, shadowKeysFromReadQueries, } from './composer_shadow_merge.js';
+import { composerShadowKeysFromContract, reactiveStorageItemKeyForVscdb, } from './vscdb_reactive_storage.js';
+import { readFileCollectionVscdbContract, sanitizeFileCollectionVscdbContract, writeFileCollectionVscdbContract, } from '../runtime/management_storage.js';
+/**
+ * ItemTable keys that store a bare JSON boolean; compliance paths use `${key}.${field}`.
+ * Kept in sync with `coerceItemTableValueToObjectRoot` / `serializeItemTableValueForWrite` in remediation_sync.
+ */
+export const CURSOR_SCALAR_ITEMTABLE_FIELDS = {
+    'cursor/thirdPartyExtensibilityEnabled': 'thirdPartyExtensibilityEnabled',
+    'cursorai/donotchange/privacyMode': 'privacyMode',
+    'cursor/autoOpenLocalhostUrls': 'autoOpenLocalhostUrls',
+};
+function querySqlite(dbPath, key) {
+    const bin = resolveSqlite3Binary();
+    if (!bin)
+        throw new Error('sqlite3 not found');
+    const safe = key.replace(/'/g, "''");
+    const script = `.timeout 60000\nSELECT value FROM ItemTable WHERE key='${safe}';\n`;
+    return execSqlite3(bin, ['-noheader', dbPath], script).trim();
+}
+/**
+ * Cursor keeps live agent settings (e.g. yoloCommandAllowlist) on nested composerState inside
+ * the reactive blob while the legacy ItemTable `composerState` row is often stale/partial.
+ * Merge nested fields so compliance/autofix match policy scans on uploaded reactive data.
+ */
+function mergeLegacyComposerStateWithReactiveNested(dbPath, reactiveKey, legacyComposerState) {
+    try {
+        const reactive = querySqlite(dbPath, reactiveKey);
+        if (!reactive)
+            return legacyComposerState;
+        const root = JSON.parse(reactive);
+        const nested = root.composerState;
+        if (nested === null || typeof nested !== 'object' || Array.isArray(nested)) {
+            return legacyComposerState;
+        }
+        return { ...legacyComposerState, ...nested };
+    }
+    catch {
+        return legacyComposerState;
+    }
+}
+/**
+ * Fallback if the API omits vscdb_composer_contract (older server): derive from vscdb_read_queries.
+ */
+export function parseVscdbComposerContractFromReadQueries(queries) {
+    const empty = {
+        version: 1,
+        reactive_storage_item_key: undefined,
+        composer_shadow_keys: [],
+    };
+    if (!queries?.length)
+        return empty;
+    for (const step of queries) {
+        if (step.value_kind === 'composer_with_include' && step.state_key === 'composerState') {
+            const keys = step.item_table_keys ?? [];
+            return {
+                version: 1,
+                reactive_storage_item_key: keys[0],
+                composer_shadow_keys: [...(step.include_keys ?? [])],
+            };
+        }
+    }
+    return empty;
+}
+export function normalizeVscdbComposerContractFromPatternsResponse(resp) {
+    const c = resp.vscdb_composer_contract;
+    const hasKey = c != null &&
+        ((typeof c.reactive_storage_item_key === 'string' && c.reactive_storage_item_key.trim() !== '') ||
+            (c.composer_shadow_keys?.length ?? 0) > 0);
+    if (hasKey && c) {
+        return sanitizeFileCollectionVscdbContract({
+            version: 1,
+            reactive_storage_item_key: c.reactive_storage_item_key ?? undefined,
+            composer_shadow_keys: [...(c.composer_shadow_keys ?? [])],
+        }) ?? { version: 1, reactive_storage_item_key: undefined, composer_shadow_keys: [] };
+    }
+    return parseVscdbComposerContractFromReadQueries(resp.vscdb_read_queries);
+}
+/** Persist backend-derived contract next to remediation_instructions.json. */
+export function persistVscdbComposerContractFromPatternsResponse(resp) {
+    const norm = normalizeVscdbComposerContractFromPatternsResponse(resp);
+    const existing = readFileCollectionVscdbContract();
+    const merged = {
+        version: 1,
+        reactive_storage_item_key: norm.reactive_storage_item_key ?? existing?.reactive_storage_item_key ?? undefined,
+        composer_shadow_keys: norm.composer_shadow_keys.length > 0
+            ? norm.composer_shadow_keys
+            : [...(existing?.composer_shadow_keys ?? [])],
+    };
+    if (merged.reactive_storage_item_key || merged.composer_shadow_keys.length > 0) {
+        writeFileCollectionVscdbContract(merged);
+    }
+}
+/**
+ * Read one ItemTable JSON blob (e.g. key `composerState`) and return `{ [itemKey]: object }` so
+ * dot-paths like `composerState.modes4.agent.autoRun` (or legacy numeric `modes4.0`) work in compliance checks. Empty / missing value
+ * yields `{ [itemKey]: {} }`. Returns null if the DB is missing, sqlite3 is unavailable, or JSON parse fails.
+ *
+ * When `file_collection_vscdb_contract.json` lists `reactive_storage_item_key`, a missing legacy `composerState` row
+ * falls back to nested `composerState` inside that reactive blob (paths from the backend API only).
+ */
+export function readVscdbItemTableJson(dbPath, itemKey) {
+    try {
+        if (!dbPath || !existsSync(dbPath))
+            return null;
+        if (!resolveSqlite3Binary())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    try {
+        const raw = querySqlite(dbPath, itemKey);
+        const reactiveKey = reactiveStorageItemKeyForVscdb(dbPath) ?? '';
+        if (itemKey === 'composerState' && (!raw || raw === '{}') && reactiveKey) {
+            const reactive = querySqlite(dbPath, reactiveKey);
+            if (reactive) {
+                const root = JSON.parse(reactive);
+                const cs = root.composerState;
+                if (cs !== null && typeof cs === 'object' && !Array.isArray(cs)) {
+                    return { composerState: cs };
+                }
+            }
+        }
+        if (!raw) {
+            return { [itemKey]: {} };
+        }
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            if (itemKey === 'composerState' && reactiveKey) {
+                const merged = mergeLegacyComposerStateWithReactiveNested(dbPath, reactiveKey, parsed);
+                return { [itemKey]: merged };
+            }
+            return { [itemKey]: parsed };
+        }
+        // Bare JSON arrays (e.g. cursor/disabledMcpServers) — wrap under itemKey so ops-based
+        // compliance checks can locate the array via getByPath(itemKey).
+        if (Array.isArray(parsed)) {
+            return { [itemKey]: parsed };
+        }
+        // Bare JSON primitives. Scalar toggles must be wrapped so getByPath(key.field) works in compliance checks.
+        // Match coerceScalarForItemTableField in remediation_sync: Cursor may store toggles as JSON 0/1, not only booleans.
+        if (typeof parsed === 'boolean' || typeof parsed === 'number' || typeof parsed === 'string') {
+            const field = CURSOR_SCALAR_ITEMTABLE_FIELDS[itemKey];
+            if (field) {
+                if (typeof parsed === 'boolean') {
+                    return { [itemKey]: { [field]: parsed } };
+                }
+                if (typeof parsed === 'number' && !Number.isNaN(parsed)) {
+                    return { [itemKey]: { [field]: parsed !== 0 } };
+                }
+                if (typeof parsed === 'string') {
+                    const lower = parsed.trim().toLowerCase();
+                    return {
+                        [itemKey]: { [field]: lower === 'true' || lower === '1' || lower === 'yes' },
+                    };
+                }
+            }
+            return { [itemKey]: parsed };
+        }
+        return { [itemKey]: {} };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cursor stores web-tool toggles on the reactive blob root and nested `composerState`.
+ * Merge root shadow keys into nested composerState (matches policy_engine.scan_targets).
+ */
+export function mergeComposerShadowKeysFromReactiveBlob(dbPath, merged) {
+    const reactiveKey = reactiveStorageItemKeyForVscdb(dbPath)?.trim();
+    const shadowKeys = composerShadowKeysFromContract();
+    if (!reactiveKey || shadowKeys.length === 0)
+        return;
+    const reactiveWrapped = readVscdbItemTableJson(dbPath, reactiveKey);
+    if (reactiveWrapped === null)
+        return;
+    const blob = reactiveWrapped[reactiveKey];
+    if (!blob || typeof blob !== 'object' || Array.isArray(blob))
+        return;
+    const root = blob;
+    let cs = merged.composerState;
+    if (!cs || typeof cs !== 'object' || Array.isArray(cs)) {
+        const nested = root.composerState;
+        if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+            cs = { ...nested };
+        }
+        else {
+            cs = {};
+        }
+        merged.composerState = cs;
+    }
+    const composerState = cs;
+    const nestedRoot = root.composerState && typeof root.composerState === 'object' && !Array.isArray(root.composerState)
+        ? root.composerState
+        : undefined;
+    for (const key of shadowKeys) {
+        const value = mergeCursorShadowKeyValue(key, root, nestedRoot ?? composerState);
+        if (value !== undefined) {
+            composerState[key] = value;
+        }
+    }
+}
+/**
+ * After a deferred state.vscdb write, upload the live reactive blob (not stale legacy composerState row).
+ * Return the full blob so the server can apply per-key shadow merge (same as log-config ingest).
+ */
+export function buildVscdbPostApplyRawContent(dbPath, itemKeyFromPath) {
+    if (itemKeyFromPath === 'composerState') {
+        const reactiveKey = reactiveStorageItemKeyForVscdb(dbPath);
+        if (reactiveKey) {
+            const reactiveWrapped = readVscdbItemTableJson(dbPath, reactiveKey);
+            const blob = reactiveWrapped?.[reactiveKey];
+            if (blob && typeof blob === 'object' && !Array.isArray(blob)) {
+                return { ...blob };
+            }
+        }
+        return readVscdbItemTableJson(dbPath, itemKeyFromPath);
+    }
+    return readVscdbItemTableJson(dbPath, itemKeyFromPath);
+}
+function setNested(obj, dotPath, value) {
+    const parts = dotPath.split('.');
+    const safe = (k) => k !== '__proto__' && k !== 'constructor' && k !== 'prototype';
+    if (!parts.every(safe))
+        return;
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const p = parts[i];
+        if (!(p in cur) || typeof cur[p] !== 'object')
+            cur[p] = Object.create(null);
+        cur = cur[p];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+function runOneStep(dbPath, stateData, step) {
+    for (const key of step.item_table_keys) {
+        try {
+            const result = querySqlite(dbPath, key);
+            if (!result)
+                continue;
+            if (step.value_kind === 'boolean') {
+                const lower = result.toLowerCase();
+                setNested(stateData, step.state_key, lower === 'true' || lower === '1' || lower === 'yes');
+                return;
+            }
+            const parsed = JSON.parse(result);
+            if (step.value_kind === 'composer_with_include') {
+                if (!parsed || typeof parsed !== 'object')
+                    continue;
+                const obj = parsed;
+                const composerState = (obj.composerState ?? obj);
+                if (composerState && typeof composerState === 'object') {
+                    stateData.composerState = composerState;
+                }
+                if (step.include_keys?.length) {
+                    const nested = composerState && typeof composerState === 'object' && !Array.isArray(composerState)
+                        ? composerState
+                        : undefined;
+                    if (!nested)
+                        return;
+                    for (const k of step.include_keys) {
+                        const merged = mergeCursorShadowKeyValue(k, obj, nested);
+                        if (merged !== undefined) {
+                            nested[k] = merged;
+                        }
+                    }
+                }
+                return;
+            }
+            if (step.value_kind === 'json_array_or_object') {
+                if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    setNested(stateData, step.state_key, Object.keys(parsed));
+                }
+                else if (Array.isArray(parsed)) {
+                    setNested(stateData, step.state_key, parsed);
+                }
+                return;
+            }
+            if (step.value_kind === 'json') {
+                if (parsed !== null && typeof parsed === 'object') {
+                    setNested(stateData, step.state_key, parsed);
+                }
+                return;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+}
+function mergeFromComposerState(stateData, mergeKeys) {
+    const composer = stateData.composerState;
+    if (!composer || typeof composer !== 'object')
+        return;
+    const composerState = composer;
+    for (const key of mergeKeys) {
+        if (key in stateData && stateData[key] !== undefined)
+            continue;
+        if (key in composerState && composerState[key] !== undefined) {
+            stateData[key] = composerState[key];
+        }
+    }
+}
+/**
+ * Read state from a vscdb file using backend-driven queries only (no hardcoded keys).
+ * dbPath must be provided (e.g. from API client_path_constants via getVscdbPath); no default path.
+ * Constants come from API vscdb_read_queries and vscdb_merge_from_composer_state (backend utils/queries.py).
+ */
+export function readVSCDBState(dbPath, readQueries, mergeFromComposerStateKeys) {
+    try {
+        if (!dbPath || !existsSync(dbPath))
+            return null;
+        if (!resolveSqlite3Binary()) {
+            console.warn('sqlite3 command not found; skipping vscdb reading');
+            return null;
+        }
+        if (!readQueries?.length)
+            return null;
+        const stateData = {};
+        for (const step of readQueries) {
+            runOneStep(dbPath, stateData, step);
+        }
+        if (mergeFromComposerStateKeys?.length) {
+            mergeFromComposerState(stateData, mergeFromComposerStateKeys);
+        }
+        mergeShadowKeysIntoComposerState(stateData, shadowKeysFromReadQueries(readQueries));
+        return Object.keys(stateData).length > 0 ? stateData : null;
+    }
+    catch (error) {
+        console.error(`Error reading vscdb:`, error instanceof Error ? error.message : String(error));
+        return null;
+    }
+}

package/dist/log_config_files/runtime/client_event_reporter.js

@@ -0,0 +1,347 @@
+/**
+ * Fire-and-forget client telemetry → POST /endpoint_security/api/client-event/.
+ *
+ * Reports HookRun / FunctionalRun / Flow so the backend has visibility into what ran and
+ * what failed — even when a unit fails locally before any happy-path object exists.
+ *
+ * Guarantees the event is never lost AND never breaks the hook:
+ * - All calls are best-effort and never throw.
+ * - On send failure (backend down / network / no auth) the event is appended to a durable
+ *   JSONL buffer and flushed on the next successful send (atomic-rename claim, like tool-call).
+ * - The backend accepts uuid-keyed reports without a valid signature, so auth failures report too.
+ */
+import { existsSync, mkdirSync, appendFileSync, readFileSync, renameSync, unlinkSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { OPTIMUSLABS_MANAGEMENT_REL } from '../../bootstrap_constants.js';
+import { executeBody } from '../../endpoint_client/http_transport.js';
+import { loadEndpointBase } from '../sender/endpoint_config.js';
+import { createSignature } from '../sender/signing.js';
+import { readStoredAuthKey } from '../auth/auth_key_store.js';
+import { resolveHardwareUuid } from './hardware_uuid.js';
+import { buildLogMetadataObject } from './log_metadata.js';
+const CLIENT_EVENT_PATH = '/endpoint_security/api/client-event/';
+const SEND_TIMEOUT_MS = 4000;
+const BUFFER_BASENAME = 'client_events.jsonl';
+const MAX_BUFFER_BYTES = 1 * 1024 * 1024;
+const MAX_FLUSH_EVENTS = 50;
+function bufferPath() {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    if (!home)
+        return null;
+    return path.join(home, OPTIMUSLABS_MANAGEMENT_REL, 'telemetry', BUFFER_BASENAME);
+}
+/** Keep filename-safe chars only — must match optimus_sanitize_id in optimus-hook-common.sh. */
+function sanitizeId(v) {
+    return v.replace(/[^A-Za-z0-9._-]/g, '');
+}
+/** File start-every-prompt overwrites each submit with this prompt's story id (short-lived handoff). */
+function storyFilePath() {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    if (!home)
+        return null;
+    const telemetryDir = path.join(home, OPTIMUSLABS_MANAGEMENT_REL, 'telemetry');
+    const session = sanitizeId((process.env.OPTIMUS_SESSION_ID || '').trim());
+    if (session) {
+        const agent = sanitizeId((process.env.OPTIMUS_HOOK_TYPE || process.env.OPTIMUS_AGENT || 'claude').trim()) || 'claude';
+        return path.join(telemetryDir, `current_story.${agent}.${session}.id`);
+    }
+    return path.join(telemetryDir, 'current_story.id');
+}
+/** Match shell OPTIMUS_STORY_FILE_MAX_AGE_SEC — ignore stale ids from a prior prompt. */
+const STORY_FILE_MAX_AGE_MS = 180_000;
+function readStoryIdFromFileIfFresh(filePath) {
+    try {
+        const st = statSync(filePath);
+        if (Date.now() - st.mtimeMs > STORY_FILE_MAX_AGE_MS)
+            return null;
+        const fromFile = readFileSync(filePath, 'utf8').trim();
+        return fromFile || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Map a functional unit to the shell hook that runs it (every npm command belongs to one hook). */
+const UNIT_HOOK = {
+    inventory: 'start_every_prompt',
+    auth_version: 'start_every_prompt',
+    compliance: 'compliance_check',
+    tool_call: 'tool_call',
+    install: 'install',
+};
+/**
+ * story_id groups all hooks + npm of one prompt submit. Resolution order:
+ *   1. OPTIMUS_STORY_ID env (when the hook successfully exported it), then
+ *   2. current_story.id if mtime is fresh (same temp handoff the shell hooks use), then
+ *   3. a fresh id (standalone / manually-run command).
+ * Cached on the env for the rest of this process.
+ */
+export function getStoryId() {
+    const fromEnv = (process.env.OPTIMUS_STORY_ID || '').trim();
+    if (fromEnv)
+        return fromEnv;
+    const p = storyFilePath();
+    if (p) {
+        const fromFile = readStoryIdFromFileIfFresh(p);
+        if (fromFile) {
+            process.env.OPTIMUS_STORY_ID = fromFile;
+            return fromFile;
+        }
+    }
+    const id = randomUUID();
+    process.env.OPTIMUS_STORY_ID = id;
+    return id;
+}
+/** The shell hook this process runs under: env, else derived from the unit. */
+function resolveHookName(unit) {
+    const fromEnv = (process.env.OPTIMUS_HOOK_NAME || '').trim();
+    if (fromEnv)
+        return fromEnv;
+    if (unit && UNIT_HOOK[unit])
+        return UNIT_HOOK[unit];
+    return '';
+}
+/** File written by optimus_hook_begin for this hook invocation (gate + runner share it). */
+function hookRunFilePath() {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    if (!home)
+        return null;
+    return path.join(home, OPTIMUSLABS_MANAGEMENT_REL, 'telemetry', 'current_hook_run.id');
+}
+/**
+ * hook_run_id: one uuid per shell hook invocation.
+ *   1. OPTIMUS_HOOK_RUN_ID env
+ *   2. current_hook_run.id (same hook process tree)
+ *   3. `${story_id}::${hook_name}` legacy fallback only
+ */
+export function getHookRunId(unit) {
+    const fromEnv = (process.env.OPTIMUS_HOOK_RUN_ID || '').trim();
+    if (fromEnv)
+        return fromEnv;
+    const hp = hookRunFilePath();
+    if (hp) {
+        try {
+            const fromFile = readFileSync(hp, 'utf8').trim();
+            if (fromFile) {
+                process.env.OPTIMUS_HOOK_RUN_ID = fromFile;
+                return fromFile;
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    const hook = resolveHookName(unit);
+    return hook ? `${getStoryId()}::${hook}` : getStoryId();
+}
+function agentFromEnv() {
+    const v = (process.env.OPTIMUS_AGENT || process.env.OPTIMUS_HOOK_TYPE || '').trim().toLowerCase();
+    return v || 'unknown';
+}
+function enrich(kind, fields, unit) {
+    return {
+        kind,
+        story_id: fields.story_id ?? getStoryId(),
+        hook_run_id: fields.hook_run_id ?? getHookRunId(unit),
+        outcome: fields.outcome,
+        exit_code: fields.exit_code ?? null,
+        message: fields.message ?? '',
+        detail: fields.detail ?? '',
+        metadata: { ...buildLogMetadataObject(), ...(fields.metadata ?? {}) },
+    };
+}
+function appendToBuffer(events) {
+    const p = bufferPath();
+    if (!p)
+        return;
+    try {
+        const dir = path.dirname(p);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (existsSync(p) && statSync(p).size > MAX_BUFFER_BYTES)
+            return; // cap; drop rather than grow unbounded
+        appendFileSync(p, events.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Atomically claim + read buffered events so a concurrent hook won't double-send. */
+function claimBufferedEvents() {
+    const p = bufferPath();
+    if (!p || !existsSync(p))
+        return [];
+    const claimed = `${p}.sending.${process.pid}`;
+    try {
+        renameSync(p, claimed);
+    }
+    catch {
+        return [];
+    }
+    try {
+        const lines = readFileSync(claimed, 'utf8').split('\n').filter((l) => l.trim());
+        unlinkSync(claimed);
+        return lines
+            .slice(0, MAX_FLUSH_EVENTS)
+            .map((l) => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((e) => e !== null);
+    }
+    catch {
+        return [];
+    }
+}
+async function postEvents(events) {
+    if (events.length === 0)
+        return true;
+    let hardwareUuid;
+    try {
+        hardwareUuid = resolveHardwareUuid();
+    }
+    catch {
+        return false;
+    }
+    const base = loadEndpointBase().replace(/\/+$/, '');
+    const url = `${base}${CLIENT_EVENT_PATH}`;
+    const signingPayload = { hardware_uuid: hardwareUuid, events };
+    let signature = '';
+    try {
+        const authKey = readStoredAuthKey();
+        if (authKey?.key)
+            signature = createSignature(signingPayload, authKey.key);
+    }
+    catch {
+        // unsigned is fine — backend stores signature_valid=false and still records
+    }
+    const body = JSON.stringify({ ...signingPayload, signature });
+    try {
+        const res = await executeBody(url, 'POST', body, SEND_TIMEOUT_MS);
+        return res.statusCode >= 200 && res.statusCode < 300;
+    }
+    catch {
+        return false;
+    }
+}
+/** Core: send these events + opportunistically flush the buffer; buffer on failure. Never throws. */
+async function send(events) {
+    try {
+        const buffered = claimBufferedEvents();
+        const all = [...buffered, ...events];
+        const ok = await postEvents(all);
+        if (!ok)
+            appendToBuffer(all);
+    }
+    catch {
+        appendToBuffer(events);
+    }
+}
+/**
+ * Each report* returns the send promise but never rejects. Callers on a hot path ignore it
+ * (fire-and-forget); callers on a process-exit path `await` it so the POST lands before exit.
+ */
+export function reportHookRun(fields) {
+    try {
+        const hook_name = fields.hook_name;
+        return send([
+            {
+                ...enrich('hook_run', { ...fields, hook_run_id: fields.hook_run_id ?? getHookRunId(undefined) }),
+                agent: fields.agent ?? agentFromEnv(),
+                hook_name,
+            },
+        ]);
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
+export function reportFunctionalRun(fields) {
+    try {
+        return send([
+            {
+                ...enrich('functional_run', fields, fields.unit),
+                unit: fields.unit,
+                command: fields.command ?? '',
+                hook_name: fields.hook_name ?? resolveHookName(fields.unit),
+                log_text: fields.log_text ?? '',
+            },
+        ]);
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
+/**
+ * Append a functional run to the durable buffer WITHOUT an inline POST. For latency-critical
+ * paths (the compliance gate blocks prompt submit) — the next background run flushes it.
+ */
+export function bufferFunctionalRun(fields) {
+    try {
+        appendToBuffer([
+            {
+                ...enrich('functional_run', fields, fields.unit),
+                unit: fields.unit,
+                command: fields.command ?? '',
+                hook_name: fields.hook_name ?? resolveHookName(fields.unit),
+                log_text: fields.log_text ?? '',
+            },
+        ]);
+    }
+    catch {
+        /* never throw */
+    }
+}
+/** Convenience for catch blocks: report a functional-unit failure with stack. */
+export function reportFunctionalFailure(unit, command, err, extra) {
+    const message = extra?.message ?? (err instanceof Error ? `${err.name}: ${err.message}` : String(err));
+    const detail = err instanceof Error && err.stack ? err.stack : String(err);
+    reportFunctionalRun({
+        unit,
+        command,
+        outcome: 'failed',
+        message,
+        detail,
+        exit_code: extra?.exit_code ?? null,
+    });
+}
+/**
+ * Awaitable failure report for the fatal-exit path (so the POST completes before process.exit).
+ * Falls back to the durable buffer if the send fails. Never throws.
+ */
+export async function reportFunctionalFailureAwait(unit, command, err, extra) {
+    try {
+        const message = extra?.message ?? (err instanceof Error ? `${err.name}: ${err.message}` : String(err));
+        const detail = err instanceof Error && err.stack ? err.stack : String(err);
+        const event = {
+            ...enrich('functional_run', { outcome: 'failed', message, detail, exit_code: extra?.exit_code ?? null }, unit),
+            unit,
+            command,
+            hook_name: resolveHookName(unit),
+            log_text: '',
+        };
+        await send([event]);
+    }
+    catch {
+        /* never throw on the exit path */
+    }
+}
+/** Flush any buffered events (call opportunistically at the start of a run). Never throws. */
+export async function flushBufferedClientEvents() {
+    try {
+        const buffered = claimBufferedEvents();
+        if (buffered.length === 0)
+            return;
+        const ok = await postEvents(buffered);
+        if (!ok)
+            appendToBuffer(buffered);
+    }
+    catch {
+        /* best-effort */
+    }
+}