@unbrained/pm-cli 2026.5.1 → 2026.5.3-5

package/dist/core/telemetry/runtime.js

@@ -2,16 +2,24 @@ import crypto from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { appendLineAtomic, readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
+import { resolveTelemetryErrorCategory } from "../shared/constants.js";
+import { nowIso } from "../shared/time.js";
 import { resolveGlobalPmRoot } from "../store/paths.js";
 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_SCHEMA_VERSION = 1;
 const TELEMETRY_FLUSH_BATCH_SIZE = 100;
 const TELEMETRY_MAX_RETRY_DELAY_MS = 3_600_000;
 const TELEMETRY_RETRY_BASE_DELAY_MS = 30_000;
-const TELEMETRY_HTTP_TIMEOUT_MS = 2_500;
+const TELEMETRY_HTTP_TIMEOUT_MS = 5_000;
 const MILLISECONDS_PER_DAY = 86_400_000;
+const TELEMETRY_MAX_EVENT_BYTES = 65_536;
+const TELEMETRY_SANITIZE_MAX_DEPTH = 6;
+const TELEMETRY_SANITIZE_MAX_ARRAY_ITEMS = 20;
+const TELEMETRY_MAX_QUEUE_ENTRY_ATTEMPTS = 15;
+const TELEMETRY_RESULT_PREVIEW_MAX_BYTES = 8_192;
 const OTEL_TRACES_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
 const OTEL_BASE_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_ENDPOINT";
 const OTEL_SERVICE_NAME_ENV = "OTEL_SERVICE_NAME";
@@ -21,6 +29,11 @@ const PM_TELEMETRY_OTEL_DISABLED_ENV = "PM_TELEMETRY_OTEL_DISABLED";
 const PM_TELEMETRY_OTEL_DISABLED_VALUES = new Set(["1", "true", "yes", "on"]);
 const PM_TELEMETRY_SOURCE_CONTEXT_ENV = "PM_TELEMETRY_SOURCE_CONTEXT";
 const PM_TELEMETRY_SOURCE_CONTEXT_VALUES = ["user", "automation", "test", "dogfood", "audit_smoke"];
+let _lastFlushPromise = Promise.resolve();
+/** Wait for the most recent background flush to settle. Test-only helper. */
+export function waitForPendingFlush() {
+    return _lastFlushPromise;
+}
 const PM_TELEMETRY_SOURCE_CONTEXT_SET = new Set(PM_TELEMETRY_SOURCE_CONTEXT_VALUES);
 const BOOLEAN_TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
 const PROCESS_SESSION_ID = crypto.randomUUID();
@@ -41,9 +54,9 @@ const SENSITIVE_INLINE_KEY_PATTERN = "(?:token|secret|password|passwd|api[_-]?ke
 const INLINE_SENSITIVE_ASSIGNMENT_PATTERN = new RegExp(`\\b(${SENSITIVE_INLINE_KEY_PATTERN})\\s*([:=])\\s*([^\\s,;]+)`, "giu");
 const INLINE_SENSITIVE_FLAG_PATTERN = new RegExp(`(--${SENSITIVE_INLINE_KEY_PATTERN})(=|\\s+)([^\\s,;]+)`, "giu");
 const ABSOLUTE_PATH_TOKEN_PATTERN = /(^|[\s"'`(=])\/(?:[^\s"'`),;]+)/g;
-function nowIso() {
-    return new Date().toISOString();
-}
+const EMAIL_PATTERN = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/giu;
+const BEARER_TOKEN_PATTERN = /bearer\s+[a-z0-9._=-]+/giu;
+const PRIVATE_IP_PATTERN = /\b(?:10\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)|172\.(?:1[6-9]|2\d|3[01])\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)|192\.168\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d))\b/g;
 function queuePath(globalPmRoot) {
     return path.join(globalPmRoot, TELEMETRY_QUEUE_RELATIVE_PATH);
 }
@@ -94,10 +107,14 @@ function redactInlineSensitiveAssignments(input) {
 function redactAbsolutePathTokens(input) {
     return input.replaceAll(ABSOLUTE_PATH_TOKEN_PATTERN, (_match, prefix) => `${prefix}[redacted_path]`);
 }
+function sanitizeCommonSensitiveTokens(input) {
+    const withoutEmails = input.replaceAll(EMAIL_PATTERN, "[redacted_email]");
+    const withoutBearer = withoutEmails.replaceAll(BEARER_TOKEN_PATTERN, "bearer [redacted_token]");
+    return withoutBearer.replaceAll(PRIVATE_IP_PATTERN, "[redacted_ip]");
+}
 function sanitizeStringRedacted(input) {
-    const withoutEmails = input.replaceAll(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/giu, "[redacted_email]");
-    const withoutBearer = withoutEmails.replaceAll(/bearer\s+[a-z0-9._=-]+/giu, "bearer [redacted_token]");
-    const withoutInlineSecrets = redactInlineSensitiveAssignments(withoutBearer);
+    const withoutCommonSensitiveTokens = sanitizeCommonSensitiveTokens(input);
+    const withoutInlineSecrets = redactInlineSensitiveAssignments(withoutCommonSensitiveTokens);
     const withoutAbsolutePaths = redactAbsolutePathTokens(withoutInlineSecrets);
     const trimmed = withoutAbsolutePaths.trim();
     if (trimmed.startsWith("/") && trimmed.length > 1) {
@@ -109,12 +126,17 @@ function sanitizeStringRedacted(input) {
     return withoutAbsolutePaths;
 }
 function sanitizeStringMax(input) {
-    const withoutBearer = input.replaceAll(/bearer\s+[a-z0-9._=-]+/giu, "bearer [redacted_token]");
-    const withoutInlineSecrets = redactInlineSensitiveAssignments(withoutBearer);
-    if (withoutInlineSecrets.length > 2048) {
-        return `${withoutInlineSecrets.slice(0, 2045)}...`;
+    const withoutCommonSensitiveTokens = sanitizeCommonSensitiveTokens(input);
+    const withoutInlineSecrets = redactInlineSensitiveAssignments(withoutCommonSensitiveTokens);
+    const withoutAbsolutePaths = redactAbsolutePathTokens(withoutInlineSecrets);
+    const trimmed = withoutAbsolutePaths.trim();
+    if (trimmed.startsWith("/") && trimmed.length > 1) {
+        return "[redacted_path]";
     }
-    return withoutInlineSecrets;
+    if (withoutAbsolutePaths.length > 2048) {
+        return `${withoutAbsolutePaths.slice(0, 2045)}...`;
+    }
+    return withoutAbsolutePaths;
 }
 function sanitizeString(input, captureLevel = "redacted") {
     if (captureLevel === "max") {
@@ -122,7 +144,7 @@ function sanitizeString(input, captureLevel = "redacted") {
     }
     return sanitizeStringRedacted(input);
 }
-function sanitizeValue(value, keyHint, captureLevel = "redacted") {
+function sanitizeValue(value, keyHint, captureLevel = "redacted", depth = 0) {
     if (keyHint && isSensitiveKey(keyHint)) {
         return "[redacted]";
     }
@@ -135,14 +157,17 @@ function sanitizeValue(value, keyHint, captureLevel = "redacted") {
     if (typeof value === "number" || typeof value === "boolean") {
         return value;
     }
+    if (depth >= TELEMETRY_SANITIZE_MAX_DEPTH) {
+        return "[depth_truncated]";
+    }
     if (Array.isArray(value)) {
-        return value.map((entry) => sanitizeValue(entry, undefined, captureLevel));
+        return value.slice(0, TELEMETRY_SANITIZE_MAX_ARRAY_ITEMS).map((entry) => sanitizeValue(entry, undefined, captureLevel, depth + 1));
     }
     if (typeof value === "object") {
         const record = value;
         const sanitized = {};
         for (const [key, nested] of Object.entries(record)) {
-            sanitized[key] = sanitizeValue(nested, key, captureLevel);
+            sanitized[key] = sanitizeValue(nested, key, captureLevel, depth + 1);
         }
         return sanitized;
     }
@@ -196,6 +221,28 @@ function normalizePmVersion(value) {
     const trimmed = value?.trim() ?? "";
     return trimmed.length > 0 ? trimmed : "0.0.0";
 }
+function normalizeTelemetryErrorCode(value) {
+    const normalized = value?.trim();
+    return normalized && normalized.length > 0 ? normalized : undefined;
+}
+function normalizeTelemetryExitCode(exitCode, ok) {
+    if (Number.isFinite(exitCode)) {
+        return Math.max(0, Math.trunc(exitCode ?? 0));
+    }
+    return ok ? 0 : 1;
+}
+function normalizeTelemetryErrorCategory(params) {
+    if (params.ok) {
+        return undefined;
+    }
+    if (typeof params.errorCategory === "string" && params.errorCategory.trim().length > 0) {
+        return params.errorCategory;
+    }
+    if (typeof params.errorCode === "string" && params.errorCode.trim().length > 0) {
+        return resolveTelemetryErrorCategory(params.errorCode);
+    }
+    return "unknown";
+}
 function resolveTelemetrySourceContext(globalOptions) {
     const override = (process.env[PM_TELEMETRY_SOURCE_CONTEXT_ENV] ?? "").trim().toLowerCase();
     if (PM_TELEMETRY_SOURCE_CONTEXT_SET.has(override)) {
@@ -228,6 +275,44 @@ function resolveTelemetrySourceContext(globalOptions) {
 function hashWithInstallationId(installationId, value) {
     return crypto.createHash("sha256").update(`${installationId}:${value}`).digest("hex");
 }
+function normalizeForHash(value, depth = 0) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    if (depth >= TELEMETRY_SANITIZE_MAX_DEPTH) {
+        return "[depth_truncated]";
+    }
+    if (Array.isArray(value)) {
+        return value.slice(0, TELEMETRY_SANITIZE_MAX_ARRAY_ITEMS).map((entry) => normalizeForHash(entry, depth + 1));
+    }
+    if (typeof value === "object") {
+        const record = value;
+        const normalized = {};
+        const sortedKeys = Object.keys(record).sort((left, right) => left.localeCompare(right));
+        for (const key of sortedKeys) {
+            normalized[key] = normalizeForHash(record[key], depth + 1);
+        }
+        return normalized;
+    }
+    return String(value);
+}
+function hashTelemetryValue(installationId, value) {
+    return hashWithInstallationId(installationId, JSON.stringify(normalizeForHash(value)));
+}
+function hashCommandArgs(installationId, args) {
+    return {
+        hashes: args.map((arg) => hashWithInstallationId(installationId, arg)),
+        digest: hashWithInstallationId(installationId, args.join("\u0000")),
+    };
+}
+function hashTelemetryErrorFingerprint(installationId, command, errorCode, errorMessage) {
+    const normalizedMessage = sanitizeString(errorMessage ?? "", "redacted");
+    const fingerprintSource = `${command}\u0000${errorCode ?? "unknown_error"}\u0000${normalizedMessage}`;
+    return hashWithInstallationId(installationId, fingerprintSource);
+}
 function telemetryDisabledByEnvironment() {
     return PM_TELEMETRY_DISABLED_VALUES.has((process.env[PM_TELEMETRY_DISABLED_ENV] ?? "").trim().toLowerCase());
 }
@@ -294,6 +379,13 @@ async function exportLocalOtelSpan(activeCommand, outcome, finishedAtIso, durati
     }
     const serviceNameCandidate = sanitizeString((process.env[OTEL_SERVICE_NAME_ENV] ?? "").trim());
     const serviceName = serviceNameCandidate.length > 0 ? serviceNameCandidate : "pm-cli";
+    const normalizedExitCode = normalizeTelemetryExitCode(outcome.exit_code, outcome.ok);
+    const normalizedErrorCode = normalizeTelemetryErrorCode(outcome.error_code);
+    const normalizedErrorCategory = normalizeTelemetryErrorCategory({
+        ok: outcome.ok,
+        errorCode: normalizedErrorCode,
+        errorCategory: outcome.error_category,
+    });
     const attributes = [
         otlpStringAttribute("pm.command", sanitizeString(activeCommand.command)),
         otlpStringAttribute("pm.version", activeCommand.pm_version),
@@ -304,8 +396,15 @@ async function exportLocalOtelSpan(activeCommand, outcome, finishedAtIso, durati
         otlpStringAttribute("pm.pm_root_hash", activeCommand.pm_root_hash),
         otlpStringAttribute("pm.cwd_hash", activeCommand.cwd_hash),
         otlpBoolAttribute("pm.ok", outcome.ok),
+        otlpIntAttribute("pm.exit_code", normalizedExitCode),
         otlpIntAttribute("pm.duration_ms", durationMs),
     ];
+    if (typeof normalizedErrorCode === "string") {
+        attributes.push(otlpStringAttribute("pm.error_code", normalizedErrorCode));
+    }
+    if (typeof normalizedErrorCategory === "string") {
+        attributes.push(otlpStringAttribute("pm.error_category", normalizedErrorCategory));
+    }
     if (typeof outcome.error === "string" && outcome.error.trim().length > 0) {
         attributes.push(otlpStringAttribute("pm.error", sanitizeString(outcome.error)));
     }
@@ -374,8 +473,16 @@ function summarizeResult(result, captureLevel = "redacted") {
         const record = result;
         const keys = Object.keys(record).sort((left, right) => left.localeCompare(right));
         const sanitized = {};
+        let previewBytes = 0;
         for (const key of keys.slice(0, 25)) {
-            sanitized[key] = sanitizeValue(record[key], key, captureLevel);
+            const sanitizedValue = sanitizeValue(record[key], key, captureLevel);
+            const entrySize = JSON.stringify(sanitizedValue)?.length ?? 0;
+            if (previewBytes + entrySize > TELEMETRY_RESULT_PREVIEW_MAX_BYTES) {
+                sanitized[key] = "[preview_truncated]";
+                break;
+            }
+            previewBytes += entrySize;
+            sanitized[key] = sanitizedValue;
         }
         return {
             type: "object",
@@ -388,21 +495,37 @@ function summarizeResult(result, captureLevel = "redacted") {
 }
 function buildCommandStartPayload(params) {
     const { captureLevel, context, pmVersion, sourceContext, pmRootHash, cwdHash, installationId } = params;
+    const commandTaxonomy = deriveTelemetryCommandTaxonomy(context.command);
+    const hashedArgs = hashCommandArgs(installationId, context.args);
+    const commandInvocationDigest = hashWithInstallationId(installationId, `${context.command}\u0000${context.args.join("\u0000")}`);
+    const commandOptionsDigest = hashTelemetryValue(installationId, context.options);
+    const globalOptionsDigest = hashTelemetryValue(installationId, context.global);
     if (captureLevel === "minimal") {
         return {
             capture_level: captureLevel,
             pm_version: pmVersion,
             source_context: sourceContext.source_context,
             source_context_source: sourceContext.source_context_source,
+            command_taxonomy: commandTaxonomy,
+            command_args_digest: hashedArgs.digest,
+            command_invocation_digest: commandInvocationDigest,
+            command_options_digest: commandOptionsDigest,
+            global_options_digest: globalOptionsDigest,
         };
     }
     return {
         pm_version: pmVersion,
         source_context: sourceContext.source_context,
         source_context_source: sourceContext.source_context_source,
+        command_taxonomy: commandTaxonomy,
         command_args: sanitizeCommandArgs(context.args, captureLevel),
+        command_args_hashes: hashedArgs.hashes,
+        command_args_digest: hashedArgs.digest,
+        command_invocation_digest: commandInvocationDigest,
         command_options: sanitizeValue(context.options, undefined, captureLevel),
+        command_options_digest: commandOptionsDigest,
         global_options: sanitizeValue(context.global, undefined, captureLevel),
+        global_options_digest: globalOptionsDigest,
         pm_root_hash: pmRootHash,
         cwd_hash: cwdHash,
         capture_level: captureLevel,
@@ -417,15 +540,25 @@ function buildCommandStartPayload(params) {
     };
 }
 function buildCommandFinishPayload(params) {
-    const { captureLevel, pmVersion, sourceContext, outcome, durationMs, startedAt } = params;
+    const { captureLevel, pmVersion, sourceContext, outcome, durationMs, startedAt, command, installationId, commandTaxonomy, exitCode, errorCode, errorCategory, commandResolution, resolutionStage, } = params;
+    const errorFingerprint = outcome.ok === false
+        ? hashTelemetryErrorFingerprint(installationId, command, errorCode, outcome.error)
+        : undefined;
     if (captureLevel === "minimal") {
         return {
             capture_level: captureLevel,
             pm_version: pmVersion,
             source_context: sourceContext.source_context,
             source_context_source: sourceContext.source_context_source,
+            command_taxonomy: commandTaxonomy,
+            command_resolution: commandResolution,
+            resolution_stage: resolutionStage,
             ok: outcome.ok,
+            exit_code: exitCode,
+            error_code: errorCode,
+            error_category: errorCategory,
             error: outcome.error ? sanitizeString(outcome.error, "redacted") : undefined,
+            error_fingerprint: errorFingerprint,
             duration_ms: durationMs,
         };
     }
@@ -434,13 +567,77 @@ function buildCommandFinishPayload(params) {
         pm_version: pmVersion,
         source_context: sourceContext.source_context,
         source_context_source: sourceContext.source_context_source,
+        command_taxonomy: commandTaxonomy,
+        command_resolution: commandResolution,
+        resolution_stage: resolutionStage,
         ok: outcome.ok,
+        exit_code: exitCode,
+        error_code: errorCode,
+        error_category: errorCategory,
         error: outcome.error ? sanitizeString(outcome.error, captureLevel) : undefined,
+        error_fingerprint: errorFingerprint,
         duration_ms: durationMs,
         started_at: startedAt,
         result_summary: summarizeResult(outcome.result, captureLevel),
     };
 }
+function buildCommandErrorPayload(params) {
+    const { captureLevel, pmVersion, sourceContext, command, commandTaxonomy, commandResolution, resolutionStage, args, options, pmRootHash, cwdHash, installationId, errorCode, errorMessage, errorCategory, exitCode, } = params;
+    const attemptedArgHashes = hashCommandArgs(installationId, args);
+    const attemptedCommandDigest = hashWithInstallationId(installationId, command);
+    const attemptedOptionsDigest = hashTelemetryValue(installationId, options);
+    const errorFingerprint = hashTelemetryErrorFingerprint(installationId, command, errorCode, errorMessage);
+    if (captureLevel === "minimal") {
+        return {
+            capture_level: captureLevel,
+            pm_version: pmVersion,
+            source_context: sourceContext.source_context,
+            source_context_source: sourceContext.source_context_source,
+            command_taxonomy: commandTaxonomy,
+            command_resolution: commandResolution,
+            resolution_stage: resolutionStage,
+            attempted_command_digest: attemptedCommandDigest,
+            attempted_args_digest: attemptedArgHashes.digest,
+            attempted_options_digest: attemptedOptionsDigest,
+            error_code: errorCode,
+            error_category: errorCategory,
+            exit_code: exitCode,
+            error: sanitizeString(errorMessage, "redacted"),
+            error_fingerprint: errorFingerprint,
+        };
+    }
+    return {
+        capture_level: captureLevel,
+        pm_version: pmVersion,
+        source_context: sourceContext.source_context,
+        source_context_source: sourceContext.source_context_source,
+        command_taxonomy: commandTaxonomy,
+        command_resolution: commandResolution,
+        resolution_stage: resolutionStage,
+        attempted_command: sanitizeString(command, captureLevel),
+        attempted_command_digest: attemptedCommandDigest,
+        attempted_args: sanitizeCommandArgs(args, captureLevel),
+        attempted_args_hashes: attemptedArgHashes.hashes,
+        attempted_args_digest: attemptedArgHashes.digest,
+        attempted_options: sanitizeValue(options, undefined, captureLevel),
+        attempted_options_digest: attemptedOptionsDigest,
+        error_code: errorCode,
+        error_category: errorCategory,
+        exit_code: exitCode,
+        error: sanitizeString(errorMessage, captureLevel),
+        error_fingerprint: errorFingerprint,
+        pm_root_hash: pmRootHash,
+        cwd_hash: cwdHash,
+        runtime: {
+            node: process.version,
+            platform: process.platform,
+            arch: process.arch,
+            hostname_hash: hashWithInstallationId(installationId, os.hostname()),
+            stdin_tty: process.stdin.isTTY === true,
+            stdout_tty: process.stdout.isTTY === true,
+        },
+    };
+}
 async function ensureInstallationId(globalPmRoot) {
     const settings = await readSettings(globalPmRoot);
     let changed = false;
@@ -462,7 +659,13 @@ async function enqueueTelemetryEvent(globalPmRoot, event) {
         event,
         attempts: 0,
     };
-    await appendLineAtomic(queuePath(globalPmRoot), JSON.stringify(queued));
+    let serialized = JSON.stringify(queued);
+    if (serialized.length > TELEMETRY_MAX_EVENT_BYTES) {
+        const trimmed = { ...event, payload: { ...event.payload, result_summary: { truncated: true, reason: "payload_size_exceeded", original_bytes: serialized.length } } };
+        const trimmedQueued = { event: trimmed, attempts: 0 };
+        serialized = JSON.stringify(trimmedQueued);
+    }
+    await appendLineAtomic(queuePath(globalPmRoot), serialized);
 }
 function parseQueueLines(raw) {
     const entries = [];
@@ -521,7 +724,9 @@ function pruneExpiredQueueEntries(entries, retentionDays) {
     const retained = [];
     let prunedCount = 0;
     for (const entry of entries) {
-        if (isExpiredQueueEntry(entry, cutoffMs)) {
+        const serializedSize = JSON.stringify(entry).length;
+        const oversized = serializedSize > TELEMETRY_MAX_EVENT_BYTES;
+        if (oversized || isExpiredQueueEntry(entry, cutoffMs) || entry.attempts >= TELEMETRY_MAX_QUEUE_ENTRY_ATTEMPTS) {
             prunedCount += 1;
             continue;
         }
@@ -578,12 +783,17 @@ async function flushQueue(globalPmRoot, endpoint, retentionDays) {
     }
     const dueIds = new Set(dueEntries.map((entry) => entry.event.event_id));
     const attemptTime = nowIso();
+    const requestHeaders = {
+        "content-type": "application/json",
+    };
+    const ingestKey = process.env.PM_TELEMETRY_INGEST_KEY?.trim();
+    if (ingestKey) {
+        requestHeaders["x-pm-telemetry-key"] = ingestKey;
+    }
     try {
         const response = await fetch(normalizedEndpoint, {
             method: "POST",
-            headers: {
-                "content-type": "application/json",
-            },
+            headers: requestHeaders,
             body: JSON.stringify({
                 schema_version: TELEMETRY_SCHEMA_VERSION,
                 events: dueEntries.map((entry) => entry.event),
@@ -670,11 +880,13 @@ export async function startTelemetryCommand(context) {
             }),
         };
         await enqueueTelemetryEvent(globalPmRoot, event);
-        await flushQueue(globalPmRoot, endpoint, retentionDays);
+        _lastFlushPromise = flushQueue(globalPmRoot, endpoint, retentionDays).catch(() => { });
+        const commandTaxonomy = deriveTelemetryCommandTaxonomy(context.command);
         return {
             started_at: occurredAt,
             started_at_ms: Date.now(),
             command: context.command,
+            command_taxonomy: commandTaxonomy,
             pm_version: pmVersion,
             source_context: sourceContext.source_context,
             source_context_source: sourceContext.source_context_source,
@@ -702,6 +914,25 @@ export async function finishTelemetryCommand(activeCommand, outcome) {
     try {
         const finishedAt = nowIso();
         const durationMs = Math.max(0, Date.now() - activeCommand.started_at_ms);
+        const normalizedErrorCode = normalizeTelemetryErrorCode(inferTelemetryErrorCode({
+            ok: outcome.ok,
+            errorCode: outcome.error_code,
+            errorMessage: outcome.error,
+            exitCode: outcome.exit_code,
+        }));
+        const normalizedErrorCategory = normalizeTelemetryErrorCategory({
+            ok: outcome.ok,
+            errorCode: normalizedErrorCode,
+            errorCategory: outcome.error_category,
+        });
+        const normalizedExitCode = normalizeTelemetryExitCode(outcome.exit_code, outcome.ok);
+        const commandResolution = outcome.command_resolution ??
+            deriveTelemetryCommandResolution({
+                ok: outcome.ok,
+                errorCode: normalizedErrorCode,
+                errorCategory: normalizedErrorCategory,
+            });
+        const resolutionStage = outcome.resolution_stage ?? "execute";
         const event = {
             schema_version: TELEMETRY_SCHEMA_VERSION,
             event_id: crypto.randomUUID(),
@@ -720,11 +951,92 @@ export async function finishTelemetryCommand(activeCommand, outcome) {
                 outcome,
                 durationMs,
                 startedAt: activeCommand.started_at,
+                command: activeCommand.command,
+                installationId: activeCommand.installation_id,
+                commandTaxonomy: activeCommand.command_taxonomy,
+                exitCode: normalizedExitCode,
+                errorCode: normalizedErrorCode,
+                errorCategory: normalizedErrorCategory,
+                commandResolution,
+                resolutionStage,
             }),
         };
         await enqueueTelemetryEvent(activeCommand.global_pm_root, event);
-        await flushQueue(activeCommand.global_pm_root, activeCommand.endpoint, activeCommand.retention_days);
-        await exportLocalOtelSpan(activeCommand, outcome, finishedAt, durationMs);
+        _lastFlushPromise = flushQueue(activeCommand.global_pm_root, activeCommand.endpoint, activeCommand.retention_days).catch(() => { });
+        void exportLocalOtelSpan(activeCommand, {
+            ...outcome,
+            exit_code: normalizedExitCode,
+            error_code: normalizedErrorCode,
+            error_category: normalizedErrorCategory,
+        }, finishedAt, durationMs).catch(() => { });
+    }
+    catch {
+        // Telemetry must never block command execution.
+    }
+}
+export async function emitTelemetryErrorEvent(context) {
+    if (telemetryDisabledByEnvironment()) {
+        return;
+    }
+    try {
+        const globalPmRoot = resolveGlobalPmRoot(process.cwd());
+        const settings = await readSettings(globalPmRoot);
+        if (!settings.telemetry.enabled) {
+            return;
+        }
+        const captureLevel = normalizeCaptureLevel(settings.telemetry.capture_level);
+        const { installationId, endpoint, retentionDays } = await ensureInstallationId(globalPmRoot);
+        const pmVersion = normalizePmVersion(context.pm_version);
+        const sourceContext = resolveTelemetrySourceContext(context.global);
+        const pmRootHash = hashWithInstallationId(installationId, context.pm_root);
+        const cwdHash = hashWithInstallationId(installationId, process.cwd());
+        const occurredAt = nowIso();
+        const normalizedErrorCode = normalizeTelemetryErrorCode(inferTelemetryErrorCode({
+            ok: false,
+            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>";
+        const commandTaxonomy = deriveTelemetryCommandTaxonomy(normalizedCommand);
+        const commandResolution = context.command_resolution ??
+            deriveTelemetryCommandResolution({
+                ok: false,
+                errorCode: normalizedErrorCode,
+                errorCategory: normalizedErrorCategory,
+            });
+        const resolutionStage = context.resolution_stage ?? "unknown";
+        const event = {
+            schema_version: TELEMETRY_SCHEMA_VERSION,
+            event_id: crypto.randomUUID(),
+            event_type: "command_error",
+            occurred_at: occurredAt,
+            installation_id: installationId,
+            session_id: PROCESS_SESSION_ID,
+            command: sanitizeString(normalizedCommand, "redacted"),
+            payload: buildCommandErrorPayload({
+                captureLevel,
+                pmVersion,
+                sourceContext,
+                command: normalizedCommand,
+                commandTaxonomy,
+                commandResolution,
+                resolutionStage,
+                args: context.args,
+                options: context.options,
+                pmRootHash,
+                cwdHash,
+                installationId,
+                errorCode: normalizedErrorCode,
+                errorCategory: normalizedErrorCategory,
+                exitCode: normalizedExitCode,
+                errorMessage: context.error_message,
+            }),
+        };
+        await enqueueTelemetryEvent(globalPmRoot, event);
+        _lastFlushPromise = flushQueue(globalPmRoot, endpoint, retentionDays).catch(() => { });
     }
     catch {
         // Telemetry must never block command execution.