@unbrained/pm-cli 2026.6.12 → 2026.6.16

package/dist/core/telemetry/runtime.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8431b32d-4a71-59da-ace6-b292ce6d0a3a")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0499331c-7c90-573a-9b07-2437c7ac8072")}catch(e){}}();
 import crypto from "node:crypto";
 import { spawn } from "node:child_process";
 import { mkdirSync, rmSync, statSync } from "node:fs";
@@ -15,6 +15,14 @@ import { readSettings, writeSettings } from "../store/settings.js";
 import { deriveTelemetryCommandResolution, deriveTelemetryCommandTaxonomy, inferTelemetryErrorCode, } from "./observability.js";
 const TELEMETRY_QUEUE_RELATIVE_PATH = path.join("runtime", "telemetry", "events.jsonl");
 const TELEMETRY_STATE_RELATIVE_PATH = path.join("runtime", "telemetry", "state.json");
+const TELEMETRY_OTEL_SPANS_RELATIVE_PATH = path.join("runtime", "telemetry", "otel-spans.jsonl");
+// Kept small so a worst-case batch against a blackholed collector
+// (TELEMETRY_OTEL_SPANS_FLUSH_BATCH_SIZE * TELEMETRY_HTTP_TIMEOUT_MS plus the
+// preceding event flush) stays well under TELEMETRY_FLUSH_LOCK_STALE_MS (60s).
+// Otherwise a later command could treat the still-held flush lock as stale and
+// start a second concurrent worker.
+const TELEMETRY_OTEL_SPANS_FLUSH_BATCH_SIZE = 8;
+const TELEMETRY_OTEL_SPANS_MAX_PENDING = 500;
 export const TELEMETRY_SCHEMA_VERSION = 1;
 const TELEMETRY_CLIENT_SCHEMA_VERSION = 1;
 const TELEMETRY_FLUSH_BATCH_SIZE = 100;
@@ -42,7 +50,7 @@ const PM_TELEMETRY_OTEL_DISABLED_VALUES = new Set(["1", "true", "yes", "on"]);
 const PM_TELEMETRY_INLINE_FLUSH_ENV = "PM_TELEMETRY_INLINE_FLUSH";
 const PM_TELEMETRY_FLUSH_CHILD_ENV = "PM_TELEMETRY_FLUSH_CHILD";
 const PM_TELEMETRY_SOURCE_CONTEXT_ENV = "PM_TELEMETRY_SOURCE_CONTEXT";
-const PM_TELEMETRY_SOURCE_CONTEXT_VALUES = ["user", "automation", "test", "dogfood", "audit_smoke"];
+export const PM_TELEMETRY_SOURCE_CONTEXT_VALUES = ["user", "automation", "test", "dogfood", "audit_smoke"];
 let _lastFlushPromise = Promise.resolve();
 let _queueMutationPromise = Promise.resolve();
 /** Wait for the most recent background flush to settle. Test-only helper. */
@@ -75,6 +83,9 @@ const PRIVATE_IP_PATTERN = /\b(?:10\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]
 function queuePath(globalPmRoot) {
     return path.join(globalPmRoot, TELEMETRY_QUEUE_RELATIVE_PATH);
 }
+function otelSpansQueuePath(globalPmRoot) {
+    return path.join(globalPmRoot, TELEMETRY_OTEL_SPANS_RELATIVE_PATH);
+}
 function telemetryRuntimeDirectory(globalPmRoot) {
     return path.dirname(queuePath(globalPmRoot));
 }
@@ -337,7 +348,7 @@ function parseBooleanTrueLike(value) {
     return BOOLEAN_TRUE_VALUES.has((value ?? "").trim().toLowerCase());
 }
 function normalizePmVersion(value) {
-    const trimmed = value?.trim() ?? "";
+    const trimmed = typeof value === "string" ? value.trim() : "";
     return trimmed.length > 0 ? trimmed : "0.0.0";
 }
 function normalizeTelemetryErrorCode(value) {
@@ -346,7 +357,7 @@ function normalizeTelemetryErrorCode(value) {
 }
 function normalizeTelemetryExitCode(exitCode, ok) {
     if (Number.isFinite(exitCode)) {
-        return Math.max(0, Math.trunc(exitCode ?? 0));
+        return Math.max(0, Math.trunc(exitCode));
     }
     return ok ? 0 : 1;
 }
@@ -428,8 +439,9 @@ function hashCommandArgs(installationId, args) {
     };
 }
 function hashTelemetryErrorFingerprint(installationId, command, errorCode, errorMessage) {
-    const normalizedMessage = sanitizeString(errorMessage ?? "", "redacted");
-    const fingerprintSource = `${command}\u0000${errorCode ?? "unknown_error"}\u0000${normalizedMessage}`;
+    const normalizedMessage = sanitizeString(typeof errorMessage === "string" ? errorMessage : "", "redacted");
+    const normalizedCode = typeof errorCode === "string" && errorCode.length > 0 ? errorCode : "unknown_error";
+    const fingerprintSource = `${command}\u0000${normalizedCode}\u0000${normalizedMessage}`;
     return hashWithInstallationId(installationId, fingerprintSource);
 }
 function telemetryDisabledByEnvironment() {
@@ -488,14 +500,21 @@ function otlpIntAttribute(key, value) {
         value: { intValue: String(Math.max(0, Math.trunc(value))) },
     };
 }
-async function exportLocalOtelSpan(activeCommand, outcome, finishedAtIso, durationMs) {
+/**
+ * Build the OTLP trace-export request for a finished command without performing
+ * any network I/O. Returns `null` when OTLP export is not configured (no traces
+ * endpoint / trace ids). The actual POST is deferred to the detached flush worker
+ * via {@link enqueuePendingOtelSpan} so the foreground command never blocks on a
+ * connecting socket (GH-209).
+ */
+function buildOtelSpanRequest(activeCommand, outcome, finishedAtIso, durationMs) {
     if (typeof activeCommand.otel_traces_endpoint !== "string" ||
         activeCommand.otel_traces_endpoint.trim().length === 0 ||
         typeof activeCommand.otel_trace_id !== "string" ||
         activeCommand.otel_trace_id.length === 0 ||
         typeof activeCommand.otel_span_id !== "string" ||
         activeCommand.otel_span_id.length === 0) {
-        return;
+        return null;
     }
     const serviceNameCandidate = sanitizeString((process.env[OTEL_SERVICE_NAME_ENV] ?? "").trim());
     const serviceName = serviceNameCandidate.length > 0 ? serviceNameCandidate : "pm-cli";
@@ -551,7 +570,9 @@ async function exportLocalOtelSpan(activeCommand, outcome, finishedAtIso, durati
                                 attributes,
                                 status: {
                                     code: outcome.ok ? 1 : 2,
-                                    message: outcome.ok ? "" : sanitizeString(outcome.error ?? "command_failed"),
+                                    message: outcome.ok
+                                        ? ""
+                                        : sanitizeString(typeof outcome.error === "string" ? outcome.error : "command_failed"),
                                 },
                             },
                         ],
@@ -560,17 +581,7 @@ async function exportLocalOtelSpan(activeCommand, outcome, finishedAtIso, durati
             },
         ],
     };
-    const response = await fetch(activeCommand.otel_traces_endpoint, {
-        method: "POST",
-        headers: {
-            "content-type": "application/json",
-        },
-        body: JSON.stringify(payload),
-        signal: AbortSignal.timeout(TELEMETRY_HTTP_TIMEOUT_MS),
-    });
-    if (!response.ok) {
-        throw new Error(`local_otel_export_http_${response.status}`);
-    }
+    return { endpoint: activeCommand.otel_traces_endpoint, payload };
 }
 function summarizeResult(result, captureLevel = "redacted") {
     if (result === null || result === undefined) {
@@ -596,7 +607,7 @@ function summarizeResult(result, captureLevel = "redacted") {
         let previewBytes = 0;
         for (const key of keys.slice(0, 25)) {
             const sanitizedValue = sanitizeValue(record[key], key, captureLevel);
-            const entrySize = JSON.stringify(sanitizedValue)?.length ?? 0;
+            const entrySize = JSON.stringify(sanitizedValue).length;
             if (previewBytes + entrySize > TELEMETRY_RESULT_PREVIEW_MAX_BYTES) {
                 sanitized[key] = "[preview_truncated]";
                 break;
@@ -823,16 +834,19 @@ function nextRetryIso(attempts) {
     const delay = Math.min(TELEMETRY_RETRY_BASE_DELAY_MS * 2 ** Math.max(attempts - 1, 0), TELEMETRY_MAX_RETRY_DELAY_MS);
     return new Date(Date.now() + delay).toISOString();
 }
-function isDueForRetry(entry) {
-    if (typeof entry.next_attempt_after !== "string" || entry.next_attempt_after.trim().length === 0) {
+function isDueForRetryAt(nextAttemptAfter) {
+    if (typeof nextAttemptAfter !== "string" || nextAttemptAfter.trim().length === 0) {
         return true;
     }
-    const dueAtMs = Date.parse(entry.next_attempt_after);
+    const dueAtMs = Date.parse(nextAttemptAfter);
     if (Number.isNaN(dueAtMs)) {
         return true;
     }
     return dueAtMs <= Date.now();
 }
+function isDueForRetry(entry) {
+    return isDueForRetryAt(entry.next_attempt_after);
+}
 function retentionCutoffMs(retentionDays) {
     const normalizedDays = Number.isFinite(retentionDays) ? Math.max(1, Math.trunc(retentionDays)) : 1;
     return Date.now() - normalizedDays * MILLISECONDS_PER_DAY;
@@ -892,6 +906,238 @@ function sleep(milliseconds) {
         setTimeout(resolve, milliseconds);
     });
 }
+/**
+ * Append a built OTLP span request to the bounded pending-spans queue. The
+ * detached flush worker drains and POSTs these so the foreground command never
+ * performs OTLP network I/O (GH-209). Best effort: a write failure never blocks
+ * the command, and the span is simply not exported.
+ */
+async function enqueuePendingOtelSpan(globalPmRoot, request) {
+    const pending = {
+        id: crypto.randomUUID(),
+        endpoint: request.endpoint,
+        payload: request.payload,
+        enqueued_at: nowIso(),
+        attempts: 0,
+    };
+    const serialized = JSON.stringify(pending);
+    // Drop oversized spans rather than poison the queue; they would never flush.
+    if (serialized.length > TELEMETRY_MAX_EVENT_BYTES) {
+        return;
+    }
+    await withQueueMutation(async () => {
+        await appendLineAtomic(otelSpansQueuePath(globalPmRoot), serialized);
+    });
+}
+/**
+ * Derive a stable id for a legacy id-less pending span from its identity fields.
+ * Deterministic so the same on-disk line yields the same id across reads, which
+ * is what lets reconciliation remove/update it after a flush.
+ */
+function backfillPendingOtelSpanId(entry) {
+    const material = JSON.stringify([entry.endpoint, entry.enqueued_at, entry.payload]);
+    return crypto.createHash("sha256").update(material).digest("hex").slice(0, 32);
+}
+function parsePendingOtelSpanLines(raw) {
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed &&
+                typeof parsed === "object" &&
+                typeof parsed.endpoint === "string" &&
+                parsed.endpoint.trim().length > 0 &&
+                "payload" in parsed &&
+                typeof parsed.attempts === "number" &&
+                Number.isFinite(parsed.attempts)) {
+                // Backfill an id for legacy entries written before id tracking existed.
+                // It MUST be deterministic from the entry's content so the post-flush
+                // re-read derives the same id and reconciliation can address the entry;
+                // a random id would differ between reads and strand the span.
+                if (typeof parsed.id !== "string" || parsed.id.length === 0) {
+                    parsed.id = backfillPendingOtelSpanId(parsed);
+                }
+                entries.push(parsed);
+            }
+        }
+        catch {
+            // Drop malformed lines to preserve forward progress.
+        }
+    }
+    return entries;
+}
+function isExpiredPendingOtelSpan(entry, cutoffMs) {
+    if (typeof entry.enqueued_at !== "string" || entry.enqueued_at.trim().length === 0) {
+        return false;
+    }
+    const enqueuedAtMs = Date.parse(entry.enqueued_at);
+    if (Number.isNaN(enqueuedAtMs)) {
+        return false;
+    }
+    return enqueuedAtMs < cutoffMs;
+}
+function prunePendingOtelSpans(entries, retentionDays) {
+    const cutoffMs = retentionCutoffMs(retentionDays);
+    const retained = [];
+    let prunedCount = 0;
+    for (const entry of entries) {
+        const oversized = JSON.stringify(entry).length > TELEMETRY_MAX_EVENT_BYTES;
+        if (oversized || isExpiredPendingOtelSpan(entry, cutoffMs) || entry.attempts >= TELEMETRY_MAX_QUEUE_ENTRY_ATTEMPTS) {
+            prunedCount += 1;
+            continue;
+        }
+        retained.push(entry);
+    }
+    if (retained.length > TELEMETRY_OTEL_SPANS_MAX_PENDING) {
+        const overflow = retained.length - TELEMETRY_OTEL_SPANS_MAX_PENDING;
+        prunedCount += overflow;
+        // Keep the most recently enqueued spans; oldest beyond the cap are dropped.
+        return { entries: retained.slice(overflow), prunedCount };
+    }
+    return { entries: retained, prunedCount };
+}
+async function rewritePendingOtelSpans(globalPmRoot, entries) {
+    const serialized = entries.map((entry) => JSON.stringify(entry)).join("\n");
+    const contents = serialized.length > 0 ? `${serialized}\n` : "";
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await writeFileAtomic(otelSpansQueuePath(globalPmRoot), contents);
+            return;
+        }
+        catch (error) {
+            const retryDelay = TELEMETRY_QUEUE_REWRITE_RETRY_DELAYS_MS[attempt];
+            if (retryDelay === undefined || !isRetryableQueueRewriteError(error)) {
+                throw error;
+            }
+            await sleep(retryDelay);
+        }
+    }
+}
+/**
+ * Drain the pending OTLP span queue and POST due spans to their traces endpoint.
+ * Runs only inside the flush worker (detached child) or the inline test path, so
+ * the foreground command never makes OTLP network calls. Failures increment
+ * per-span attempts with backoff and are retried by a later flush; runtime state
+ * records OTLP export diagnostics for `pm health` (GH-205).
+ */
+/**
+ * Re-read the spans queue under the mutation serializer and rewrite it with the
+ * processed spans removed/updated by id, preserving any spans a concurrent
+ * foreground process appended during the (network) flush window. `succeededIds`
+ * are dropped; `failedUpdates` patch attempts/next_attempt_after by id; all other
+ * (incl. newly-appended) entries are retained, then pruned. Returns the count of
+ * spans left in the queue. Mirrors removeFlushedEntriesFromCurrentQueue.
+ */
+async function reconcilePendingOtelSpansAfterFlush(globalPmRoot, retentionDays, succeededIds, failedUpdates) {
+    return withQueueMutation(async () => {
+        const raw = await readFileIfExists(otelSpansQueuePath(globalPmRoot));
+        const current = raw === null ? [] : parsePendingOtelSpanLines(raw);
+        const reconciled = [];
+        for (const entry of current) {
+            if (succeededIds.has(entry.id)) {
+                continue;
+            }
+            const failure = failedUpdates.get(entry.id);
+            reconciled.push(failure ? { ...entry, attempts: failure.attempts, next_attempt_after: failure.next_attempt_after } : entry);
+        }
+        const { entries: retained } = prunePendingOtelSpans(reconciled, retentionDays);
+        await rewritePendingOtelSpans(globalPmRoot, retained);
+        return retained.length;
+    });
+}
+async function flushPendingOtelSpans(globalPmRoot, retentionDays) {
+    const raw = await readFileIfExists(otelSpansQueuePath(globalPmRoot));
+    if (raw === null || raw.trim().length === 0) {
+        await writeRuntimeState(globalPmRoot, { pending_otel_spans: 0 });
+        return;
+    }
+    const entries = parsePendingOtelSpanLines(raw);
+    const { entries: retained, prunedCount } = prunePendingOtelSpans(entries, retentionDays);
+    const due = retained.filter((entry) => isDueForRetryAt(entry.next_attempt_after)).slice(0, TELEMETRY_OTEL_SPANS_FLUSH_BATCH_SIZE);
+    if (due.length === 0) {
+        // Nothing to POST. Still reconcile so pruning persists, but only if pruning
+        // actually changed the on-disk set (avoids a redundant rewrite each command).
+        const remaining = prunedCount > 0 ? await reconcilePendingOtelSpansAfterFlush(globalPmRoot, retentionDays, new Set(), new Map()) : retained.length;
+        await writeRuntimeState(globalPmRoot, { pending_otel_spans: remaining });
+        return;
+    }
+    const attemptTime = nowIso();
+    const succeededIds = new Set();
+    const failedUpdates = new Map();
+    let succeededCount = 0;
+    let lastError;
+    // Export the batch concurrently so a slow/blackholed collector caps the worker
+    // at one TELEMETRY_HTTP_TIMEOUT_MS rather than batch-size x timeout — keeping it
+    // well within the flush-lock TTL. The Set/Map/counter mutations are synchronous
+    // and safe under Node's single-threaded event loop.
+    await Promise.all(due.map(async (span) => {
+        try {
+            const response = await fetch(span.endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(span.payload),
+                signal: AbortSignal.timeout(TELEMETRY_HTTP_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                throw new Error(`local_otel_export_http_${response.status}`);
+            }
+            succeededIds.add(span.id);
+            succeededCount += 1;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? sanitizeString(error.message, "redacted") : "local_otel_export_failed";
+            const nextAttempts = span.attempts + 1;
+            failedUpdates.set(span.id, { attempts: nextAttempts, next_attempt_after: nextRetryIso(nextAttempts) });
+        }
+    }));
+    const remaining = await reconcilePendingOtelSpansAfterFlush(globalPmRoot, retentionDays, succeededIds, failedUpdates);
+    const statePatch = {
+        pending_otel_spans: remaining,
+        last_otel_attempt_at: attemptTime,
+    };
+    if (succeededCount > 0) {
+        statePatch.last_otel_success_at = attemptTime;
+    }
+    if (lastError !== undefined) {
+        statePatch.last_otel_failure_at = attemptTime;
+        statePatch.last_otel_failure_error = lastError;
+    }
+    else if (remaining === 0) {
+        // Only clear the failure diagnostic once the queue is fully drained. A
+        // clean batch while other (not-yet-due) spans still wait could be hiding
+        // earlier failures; keep the last known failure until nothing is pending.
+        statePatch.last_otel_failure_at = undefined;
+        statePatch.last_otel_failure_error = undefined;
+    }
+    await writeRuntimeState(globalPmRoot, statePatch);
+}
+/**
+ * Flush both telemetry artifacts under the same worker invocation: the event
+ * ingest queue and the pending OTLP span queue. Used by the detached flush
+ * worker and the inline (test) path so OTLP export always happens off the
+ * foreground command's critical path.
+ */
+async function flushTelemetryArtifacts(globalPmRoot, endpoint, retentionDays) {
+    // Isolate the two artifacts: a failure flushing the event queue (e.g. a corrupt
+    // queue file) must not strand the OTLP span flush in the same pass, and vice
+    // versa. Both are best effort and retried on the next dispatch.
+    try {
+        await flushQueue(globalPmRoot, endpoint, retentionDays);
+    }
+    catch {
+        // Best effort; event-queue flush is retried on the next dispatch.
+    }
+    try {
+        await flushPendingOtelSpans(globalPmRoot, retentionDays);
+    }
+    catch {
+        // Best effort; span flush is retried on the next dispatch.
+    }
+}
 async function cleanupTelemetryQueueTempOrphans(globalPmRoot, maxAgeMs = TELEMETRY_QUEUE_TMP_ORPHAN_MAX_AGE_MS) {
     try {
         const dirPath = telemetryRuntimeDirectory(globalPmRoot);
@@ -912,8 +1158,12 @@ async function cleanupTelemetryQueueTempOrphans(globalPmRoot, maxAgeMs = TELEMET
     }
 }
 async function withQueueMutation(operation) {
-    const run = _queueMutationPromise.catch(() => { }).then(operation);
-    _queueMutationPromise = run.catch(() => { });
+    const run = _queueMutationPromise.catch(
+    /* c8 ignore next */
+    () => { }).then(operation);
+    _queueMutationPromise = run.catch(
+    /* c8 ignore next */
+    () => { });
     return run;
 }
 async function readCurrentQueueEntries(globalPmRoot) {
@@ -976,9 +1226,7 @@ async function flushQueue(globalPmRoot, endpoint, retentionDays) {
     }
     const { entries: retainedEntries, prunedCount } = pruneExpiredQueueEntries(queueEntries, retentionDays);
     if (retainedEntries.length === 0) {
-        if (prunedCount > 0) {
-            await rewriteQueue(globalPmRoot, []);
-        }
+        await rewriteQueue(globalPmRoot, []);
         await writeRuntimeState(globalPmRoot, {
             endpoint: normalizedEndpoint,
             queue_entries: 0,
@@ -1046,6 +1294,7 @@ async function flushQueue(globalPmRoot, endpoint, retentionDays) {
             last_failed_flush_at: undefined,
             last_failed_flush_error: undefined,
         });
+        /* c8 ignore start */
     }
     catch (error) {
         const errorMessage = (() => {
@@ -1063,6 +1312,7 @@ async function flushQueue(globalPmRoot, endpoint, retentionDays) {
             last_failed_flush_error: errorMessage,
         });
     }
+    /* c8 ignore stop */
 }
 async function acquireTelemetryFlushLock(globalPmRoot) {
     const lockPath = flushLockPath(globalPmRoot);
@@ -1126,6 +1376,7 @@ function createDirectoryLock(lockPath) {
             return false;
         }
     }
+    /* c8 ignore start */
     try {
         mkdirSync(path.dirname(lockPath), { recursive: true });
         mkdirSync(lockPath);
@@ -1134,6 +1385,7 @@ function createDirectoryLock(lockPath) {
     catch {
         return false;
     }
+    /* c8 ignore stop */
 }
 function acquireTelemetryFlushSpawnGate(globalPmRoot) {
     if (isFreshDirectoryLock(flushLockPath(globalPmRoot), TELEMETRY_FLUSH_LOCK_STALE_MS)) {
@@ -1158,9 +1410,67 @@ function releaseTelemetryFlushSpawnGate(globalPmRoot) {
 }
 export const _testOnly = {
     acquireTelemetryFlushSpawnGate,
+    acquireTelemetryFlushLock,
+    buildCommandErrorPayload,
+    buildCommandFinishPayload,
+    buildCommandStartPayload,
+    buildOtelSpanRequest,
+    createDirectoryLock,
+    enqueuePendingOtelSpan,
+    enqueueTelemetryEvent,
+    errorCode,
+    flushPendingOtelSpans,
+    flushQueue,
+    flushQueueWithProcessLock,
+    flushTelemetryArtifacts,
+    hashTelemetryErrorFingerprint,
+    hashTelemetryValue,
+    isEmailDomainCharacter,
+    isEmailLocalCharacter,
+    isExpiredPendingOtelSpan,
+    isExpiredQueueEntry,
+    isFreshDirectoryLock,
+    isDueForRetry,
+    isDueForRetryAt,
+    isRetryableQueueRewriteError,
+    looksLikeEmailToken,
+    otelSpansQueuePath,
+    parseBooleanTrueLike,
+    parsePendingOtelSpanLines,
+    prunePendingOtelSpans,
+    reconcilePendingOtelSpansAfterFlush,
+    retentionCutoffMs,
+    resolveOtelTracesEndpoint,
+    rewritePendingOtelSpans,
+    normalizeForHash,
+    normalizeCaptureLevel,
+    normalizePmVersion,
+    normalizeTelemetryErrorCategory,
+    normalizeTelemetryErrorCode,
+    normalizeTelemetryExitCode,
+    parseQueueLines,
+    pruneExpiredQueueEntries,
+    readRuntimeState,
+    readCurrentQueueEntries,
     releaseTelemetryFlushSpawnGate,
+    removeFlushedEntriesFromCurrentQueue,
+    removeDirectoryLockBestEffort,
+    resolveTelemetrySourceContext,
+    rewriteQueue,
+    sanitizeCommandArgs,
+    sanitizeStringMax,
+    sanitizeStringRedacted,
+    sanitizeValue,
+    scheduleTelemetryFlush,
+    shouldFlushInline,
+    sleep,
+    summarizeResult,
+    telemetryFlushRunnerPath,
+    withQueueMutation,
     flushLockPath,
     flushSpawnLockPath,
+    runtimeStatePath,
+    writeRuntimeState,
 };
 async function flushQueueWithProcessLock(globalPmRoot, endpoint, retentionDays) {
     const acquired = await acquireTelemetryFlushLock(globalPmRoot);
@@ -1169,16 +1479,21 @@ async function flushQueueWithProcessLock(globalPmRoot, endpoint, retentionDays)
         return;
     }
     try {
-        await flushQueue(globalPmRoot, endpoint, retentionDays);
+        await flushTelemetryArtifacts(globalPmRoot, endpoint, retentionDays);
     }
     finally {
-        await rm(flushLockPath(globalPmRoot), { recursive: true, force: true }).catch(() => { });
+        try {
+            await rm(flushLockPath(globalPmRoot), { recursive: true, force: true });
+        }
+        catch {
+            // Best effort lock cleanup; stale locks are recovered by TTL checks.
+        }
     }
 }
 function scheduleTelemetryFlush(globalPmRoot, endpoint, retentionDays) {
     if (shouldFlushInline()) {
         const previousFlush = _lastFlushPromise;
-        const nextFlush = flushQueue(globalPmRoot, endpoint, retentionDays).catch(() => { });
+        const nextFlush = flushTelemetryArtifacts(globalPmRoot, endpoint, retentionDays);
         _lastFlushPromise = Promise.allSettled([previousFlush, nextFlush]).then(() => { });
         return;
     }
@@ -1342,13 +1657,19 @@ export async function finishTelemetryCommand(activeCommand, outcome) {
             }),
         };
         await enqueueTelemetryEvent(activeCommand.global_pm_root, event);
-        scheduleTelemetryFlush(activeCommand.global_pm_root, activeCommand.endpoint, activeCommand.retention_days);
-        void exportLocalOtelSpan(activeCommand, {
+        const otelRequest = buildOtelSpanRequest(activeCommand, {
             ...outcome,
             exit_code: normalizedExitCode,
             error_code: normalizedErrorCode,
             error_category: normalizedErrorCategory,
-        }, finishedAt, durationMs).catch(() => { });
+        }, finishedAt, durationMs);
+        if (otelRequest) {
+            // Persist the span for the detached worker; never POST inline so the
+            // foreground command exits promptly even if the traces endpoint is
+            // unreachable (GH-209).
+            await enqueuePendingOtelSpan(activeCommand.global_pm_root, otelRequest);
+        }
+        scheduleTelemetryFlush(activeCommand.global_pm_root, activeCommand.endpoint, activeCommand.retention_days);
     }
     catch {
         // Telemetry must never block command execution.
@@ -1376,7 +1697,7 @@ export async function emitTelemetryErrorEvent(context) {
             errorCode: context.error_code,
             errorMessage: context.error_message,
             exitCode: context.exit_code,
-        })) ?? "unknown_error";
+        }));
         const normalizedErrorCategory = context.error_category ?? resolveTelemetryErrorCategory(normalizedErrorCode);
         const normalizedExitCode = normalizeTelemetryExitCode(context.exit_code, false);
         const normalizedCommand = context.command.trim().length > 0 ? context.command : "<unknown>";
@@ -1423,4 +1744,4 @@ export async function emitTelemetryErrorEvent(context) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=8431b32d-4a71-59da-ace6-b292ce6d0a3a
+//# debugId=0499331c-7c90-573a-9b07-2437c7ac8072