@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/core-utils/sentry-report.js

@@ -0,0 +1,1055 @@
+/**
+ * `hq core sentry report` — constrained diagnostic transport for HQ hooks.
+ *
+ * The stdin event schema is deliberately closed. Hook payloads can contain
+ * commands, prompts, source content, transcript locations, and credentials, so
+ * this module accepts only a small set of scalar diagnostics plus bounded hook
+ * history and never reads a hook payload or the process environment. The
+ * owner-approved `hook_path`
+ * diagnostic is the narrow exception: it names the slow hook script and may
+ * include its company directory, but never carries the hook payload itself.
+ *
+ * Invalid top-level input and structurally rich metadata are rejected. The
+ * bounded hook sequence is the deliberate exception: it keeps only the most
+ * recent entries so diagnostics cannot expand the transport payload. Unknown
+ * scalar metadata is dropped instead: the allowlist, not a caller version
+ * match, determines what may leave the machine.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { gte as semverGte, valid as validSemver } from "semver";
+import { CLI_VERSION } from "../../cli-version.js";
+import { beforeSend } from "../../sentry-before-send.js";
+import { resolveLiveRoot } from "../../utils/hq-roots.js";
+import { hookTimeoutDebugContextEnabled } from "./hook-timeout-debug-context-flag.js";
+const requireSentry = createRequire(import.meta.url);
+let sentryModule;
+function loadSentryModule() {
+    sentryModule ??= requireSentry("@sentry/node");
+    return sentryModule;
+}
+export const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
+const MAX_SENTRY_REPORT_TIMEOUT_MS = 5_000;
+export const MAX_SENTRY_REPORT_PAYLOAD_BYTES = 2_048;
+export const MAX_SENTRY_REPORT_METADATA_VALUE_BYTES = 256;
+const MAX_SENTRY_REPORT_TYPE_BYTES = 64;
+const MAX_SENTRY_REPORT_MESSAGE_BYTES = 1_024;
+const MAX_SENTRY_REPORT_FINGERPRINT_BYTES = 128;
+const SENTRY_REPORT_LEVELS = new Set([
+    "fatal",
+    "error",
+    "warning",
+    "log",
+    "info",
+    "debug",
+]);
+const HOOK_TIMEOUT_WARNING_TYPE = "hook_timeout_warning";
+const HOOK_TIMEOUT_EXCEEDED_TYPE = "hook_timeout_exceeded";
+const HOOK_LATE_FINISH_TYPE = "hook_late_finish";
+const HOOK_TIMEOUT_WARNING_METRIC = "hq.hook_timeout_warning";
+const HOOK_TIMEOUT_EXCEEDED_METRIC = "hq.hook_timeout_exceeded";
+const MAX_HOOK_SEQUENCE_ENTRIES = 20;
+const MAX_HOOK_TIMEOUT_DEBUG_PHASES = 24;
+const MAX_HOOK_TIMEOUT_DEBUG_MS = 86_400_000;
+// This is the hqVersion embedded in the first hq-core tag whose master-hook
+// replaces BASH_ENV with /dev/null before reading it (tag v15.0.157-beta.2).
+// Earlier cores only report whether BASH_ENV is non-empty, which is ambiguous.
+const BASH_ENV_NEUTRALIZED_CORE_VERSION = "15.0.157-beta.2";
+const HOOK_TIMEOUT_RATE_LIMIT_WINDOW_MS = 10 * 60 * 1_000;
+const RATE_LIMIT_LOCK_WAIT_MS = 500;
+const RATE_LIMIT_LOCK_POLL_MS = 5;
+const RATE_LIMIT_LOCK_STALE_MS = 5_000;
+const KNOWN_HOOK_SCRIPTS = new Set([
+    "master-hook.sh",
+    "hook-gate.sh",
+    "hook-timeout-watchdog.sh",
+    "check-hq-update.sh",
+    "block-core-writes-bash.sh",
+    "block-core-writes.sh",
+    "block-hq-worktree-session.sh",
+    "inject-policy-on-trigger.sh",
+    "inject-local-context.sh",
+    "session-title.sh",
+    "45-lanes-senior-monitor.sh",
+    "lanes-senior-monitor-stop-gate.sh",
+]);
+const DEBUG_CONTEXT_HOOK_NAMES = new Set([
+    ...KNOWN_HOOK_SCRIPTS,
+    "reindex.sh",
+]);
+const DEBUG_CONTEXT_CHILD_NAMES = new Set([
+    ...DEBUG_CONTEXT_HOOK_NAMES,
+    "bash",
+    "bash.exe",
+    "sh",
+    "cmd",
+    "cmd.exe",
+    "powershell",
+    "powershell.exe",
+    "wmic.exe",
+    "jq",
+    "jq.exe",
+    "node",
+    "node.exe",
+    "git",
+    "git.exe",
+    "python",
+    "python.exe",
+    "python3",
+    "python3.exe",
+    "true",
+    "sleep",
+    "cat",
+    "grep",
+    "sed",
+    "awk",
+    "find",
+    "timeout",
+    "curl",
+    "gh",
+    "hq",
+    "npm",
+    "pnpm",
+    "npx",
+]);
+const DEBUG_CONTEXT_HOOK_EVENTS = new Set([
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "SessionStart",
+    "SessionEnd",
+    "Stop",
+    "PreCompact",
+    "Notification",
+    "PermissionRequest",
+    "SubagentStart",
+    "SubagentStop",
+    "TaskCompleted",
+    "TeammateIdle",
+]);
+const DEBUG_CONTEXT_PHASES = new Set([
+    "startup",
+    "source",
+    "config_load",
+    "policy_load",
+    "external_command",
+    "output_write",
+    "wait",
+    "child_wait",
+    "probe",
+    "parse",
+]);
+/**
+ * The only hook diagnostics that can be attached as metadata. The list omits
+ * command text, prompts, payloads, company names, and repositories. `hook_path`
+ * is owner-approved telemetry for the exact hook script and may include a
+ * company directory; it is never a substitute for hook input or a transcript.
+ */
+export const ALLOWED_SENTRY_REPORT_METADATA_KEYS = [
+    "hook_name",
+    "hook_path",
+    "hook_event",
+    "hook_script",
+    "tool_name",
+    "session_id",
+    "declared_timeout_ms",
+    "elapsed_ms",
+    "remaining_ms",
+    "watchdog_timeout_ms",
+    "hook_timeout_ms",
+    "hq_version",
+    "platform",
+    "load_average",
+    "spawn_ms",
+    "slow_child",
+    "slow_child_ms",
+    "exit_code",
+    "final_elapsed_ms",
+    "bash_env_set",
+    "cwd_kind",
+    "shell",
+    "nproc",
+    "hook_sequence",
+    "hook_timeout_debug_context",
+];
+const ALLOWED_METADATA_KEYS = new Set(ALLOWED_SENTRY_REPORT_METADATA_KEYS);
+const SENTRY_REPORT_METADATA_KEY_HEADROOM = 2;
+// This tracks the schema rather than a separately-maintained literal. A caller
+// can send every recognised key with room for two later recognised fields,
+// while unknown keys are deliberately dropped.
+export const MAX_SENTRY_REPORT_METADATA_KEYS = ALLOWED_SENTRY_REPORT_METADATA_KEYS.length + SENTRY_REPORT_METADATA_KEY_HEADROOM;
+const defaultDependencies = {
+    sentry: {
+        captureMessage(message, context) {
+            return loadSentryModule().captureMessage(message, context);
+        },
+        addBreadcrumb(breadcrumb) {
+            loadSentryModule().addBreadcrumb(breadcrumb);
+        },
+        metrics: {
+            count(name, value, options) {
+                loadSentryModule().metrics.count(name, value, options);
+            },
+        },
+        flush(timeout) {
+            return loadSentryModule().flush(timeout);
+        },
+    },
+    stdout: process.stdout,
+    stderr: process.stderr,
+    timeoutDebugContextEnabled: (signal) => hookTimeoutDebugContextEnabled({}, signal),
+};
+/**
+ * Read no more than the accepted event size. Returning early keeps a malformed
+ * pipe from making a watchdog retain an unbounded hook payload in memory.
+ */
+export async function readSentryReportStdin(stdin) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+        totalBytes += bytes.length;
+        if (totalBytes > MAX_SENTRY_REPORT_PAYLOAD_BYTES)
+            return null;
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function isBoundedString(value, maxBytes) {
+    return typeof value === "string" && value.length > 0 && byteLength(value) <= maxBytes;
+}
+function isScalarMetadataValue(value) {
+    if (typeof value === "string")
+        return byteLength(value) <= MAX_SENTRY_REPORT_METADATA_VALUE_BYTES;
+    if (typeof value === "boolean")
+        return true;
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isHookSequenceEntry(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.script === "string" &&
+        value.script.length > 0 &&
+        byteLength(value.script) <= MAX_SENTRY_REPORT_METADATA_VALUE_BYTES &&
+        typeof value.event === "string" &&
+        value.event.length > 0 &&
+        byteLength(value.event) <= MAX_SENTRY_REPORT_METADATA_VALUE_BYTES &&
+        typeof value.ms === "number" &&
+        Number.isFinite(value.ms) &&
+        value.ms >= 0);
+}
+function boundedDebugName(value, known) {
+    if (typeof value !== "string" || value.length === 0)
+        return "other";
+    return known.has(basenameFromPath(value)) ? basenameFromPath(value) : "other";
+}
+function boundedDebugPhase(value) {
+    return typeof value === "string" && DEBUG_CONTEXT_PHASES.has(value) ? value : "other";
+}
+function boundedDebugHookEvent(value) {
+    return typeof value === "string" && DEBUG_CONTEXT_HOOK_EVENTS.has(value) ? value : "other";
+}
+function boundedDebugMilliseconds(value, allowNegative = false) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    const bounded = allowNegative
+        ? Math.abs(value) <= MAX_HOOK_TIMEOUT_DEBUG_MS
+        : value >= 0 && value <= MAX_HOOK_TIMEOUT_DEBUG_MS;
+    return bounded ? value : null;
+}
+function boundedDebugProbe(value) {
+    if (value === "unavailable")
+        return value;
+    return boundedDebugMilliseconds(value) ?? undefined;
+}
+function boundedDebugPhaseTimings(value) {
+    if (!Array.isArray(value) || value.length > MAX_HOOK_TIMEOUT_DEBUG_PHASES)
+        return null;
+    const timings = [];
+    for (const entry of value) {
+        if (!isRecord(entry))
+            return null;
+        const elapsed = boundedDebugMilliseconds(entry.elapsed_ms);
+        if (elapsed === null)
+            return null;
+        const timing = {
+            phase: boundedDebugPhase(entry.phase),
+            elapsed_ms: elapsed,
+        };
+        timings.push(timing);
+    }
+    return timings;
+}
+/** Return only the closed, bounded shell-to-CLI context shape. */
+function boundedHookTimeoutDebugContext(value) {
+    if (!isRecord(value))
+        return null;
+    const budget = boundedDebugMilliseconds(value.budget_ms);
+    const elapsed = boundedDebugMilliseconds(value.elapsed_ms);
+    const remaining = boundedDebugMilliseconds(value.remaining_ms, true);
+    const childElapsed = boundedDebugMilliseconds(value.waiting_child_elapsed_ms);
+    const phaseTimings = boundedDebugPhaseTimings(value.phase_timings);
+    if (budget === null ||
+        elapsed === null ||
+        remaining === null ||
+        childElapsed === null ||
+        phaseTimings === null) {
+        return null;
+    }
+    const loadAverage = boundedDebugProbe(value.load_average);
+    const spawnMs = boundedDebugProbe(value.spawn_ms);
+    const processCount = boundedDebugProbe(value.process_count);
+    const hasLoadAverage = typeof loadAverage === "number";
+    const hasWindowsProbe = spawnMs !== undefined && processCount !== undefined;
+    if (!hasLoadAverage && !hasWindowsProbe)
+        return null;
+    if (typeof processCount === "number" &&
+        (!Number.isInteger(processCount) || processCount > 1_000_000)) {
+        return null;
+    }
+    return {
+        hook_name: boundedDebugName(value.hook_name, DEBUG_CONTEXT_HOOK_NAMES),
+        hook_event: boundedDebugHookEvent(value.hook_event),
+        budget_ms: budget,
+        elapsed_ms: elapsed,
+        remaining_ms: remaining,
+        phase_timings: phaseTimings,
+        wait_point: boundedDebugPhase(value.wait_point),
+        waiting_child_basename: boundedDebugName(value.waiting_child_basename, DEBUG_CONTEXT_CHILD_NAMES),
+        waiting_child_elapsed_ms: childElapsed,
+        ...(loadAverage !== undefined ? { load_average: loadAverage } : {}),
+        ...(spawnMs !== undefined ? { spawn_ms: spawnMs } : {}),
+        ...(processCount !== undefined ? { process_count: processCount } : {}),
+    };
+}
+function boundedHookSequence(value) {
+    if (!Array.isArray(value))
+        return null;
+    const recent = value.slice(-MAX_HOOK_SEQUENCE_ENTRIES);
+    if (!recent.every(isHookSequenceEntry))
+        return null;
+    return recent.map((entry) => ({
+        script: basenameFromPath(entry.script),
+        event: entry.event,
+        ms: entry.ms,
+    }));
+}
+function isAllowedMetadataValue(key, value) {
+    if (key === "hook_sequence")
+        return boundedHookSequence(value) !== null;
+    if (key === "hook_timeout_debug_context")
+        return boundedHookTimeoutDebugContext(value) !== null;
+    if (!isScalarMetadataValue(value))
+        return false;
+    if (key === "tool_name" || key === "session_id" || key === "hook_path") {
+        return typeof value === "string";
+    }
+    return true;
+}
+/** Unknown metadata is ignored before this cap is evaluated. */
+export function exceedsSentryReportMetadataKeyCap(keys) {
+    let recognisedKeys = 0;
+    for (const key of keys) {
+        if (!ALLOWED_METADATA_KEYS.has(key))
+            continue;
+        recognisedKeys++;
+        if (recognisedKeys > MAX_SENTRY_REPORT_METADATA_KEYS)
+            return true;
+    }
+    return false;
+}
+function invalidInput() {
+    return { code: 1 };
+}
+/**
+ * Parse and validate the closed report schema without touching Sentry. The
+ * function intentionally returns an ordinary result instead of throwing so a
+ * hook can ignore the CLI exit code without creating an unhandled rejection.
+ */
+function parseSentryReportEvent(stdin) {
+    if (byteLength(stdin) > MAX_SENTRY_REPORT_PAYLOAD_BYTES)
+        return invalidInput();
+    let parsed;
+    try {
+        parsed = JSON.parse(stdin);
+    }
+    catch {
+        return invalidInput();
+    }
+    if (!isRecord(parsed))
+        return invalidInput();
+    const allowedTopLevel = new Set(["type", "message", "fingerprint", "level", "metadata"]);
+    if (Object.keys(parsed).some((key) => !allowedTopLevel.has(key)))
+        return invalidInput();
+    if (!isBoundedString(parsed.type, MAX_SENTRY_REPORT_TYPE_BYTES))
+        return invalidInput();
+    if (!isBoundedString(parsed.message, MAX_SENTRY_REPORT_MESSAGE_BYTES))
+        return invalidInput();
+    if (!isBoundedString(parsed.fingerprint, MAX_SENTRY_REPORT_FINGERPRINT_BYTES))
+        return invalidInput();
+    if (typeof parsed.level !== "string" || !SENTRY_REPORT_LEVELS.has(parsed.level)) {
+        return invalidInput();
+    }
+    const rawMetadata = "metadata" in parsed ? parsed.metadata : {};
+    if (!isRecord(rawMetadata))
+        return invalidInput();
+    const metadataKeys = Object.keys(rawMetadata);
+    if (exceedsSentryReportMetadataKeyCap(metadataKeys))
+        return invalidInput();
+    const metadata = {};
+    let droppedMetadataKeys = 0;
+    for (const key of metadataKeys) {
+        if (!ALLOWED_METADATA_KEYS.has(key)) {
+            if (!isScalarMetadataValue(rawMetadata[key]))
+                return invalidInput();
+            droppedMetadataKeys++;
+            continue;
+        }
+        if (!isAllowedMetadataValue(key, rawMetadata[key]))
+            return invalidInput();
+        metadata[key] = key === "hook_sequence"
+            ? boundedHookSequence(rawMetadata[key])
+            : key === "hook_timeout_debug_context"
+                ? boundedHookTimeoutDebugContext(rawMetadata[key])
+                : rawMetadata[key];
+    }
+    if (typeof metadata.slow_child === "string") {
+        metadata.slow_child = safeSlowChild(metadata);
+    }
+    return {
+        code: 0,
+        event: {
+            type: parsed.type,
+            message: parsed.message,
+            fingerprint: parsed.fingerprint,
+            level: parsed.level,
+            metadata,
+        },
+        droppedMetadataKeys,
+    };
+}
+function resolveTimeout(timeoutMs) {
+    const timeout = timeoutMs ?? DEFAULT_SENTRY_REPORT_TIMEOUT_MS;
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > MAX_SENTRY_REPORT_TIMEOUT_MS)
+        return null;
+    return timeout;
+}
+function isHookTimeoutEvent(event) {
+    return (event.type === HOOK_TIMEOUT_WARNING_TYPE ||
+        event.type === HOOK_TIMEOUT_EXCEEDED_TYPE ||
+        event.type === HOOK_LATE_FINISH_TYPE);
+}
+function stringMetadata(metadata, key, fallback = "unknown") {
+    const value = metadata[key];
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+function basenameFromPath(value) {
+    const normalized = value.replaceAll("\\", "/");
+    const last = normalized.slice(normalized.lastIndexOf("/") + 1);
+    return last || "unknown";
+}
+const SAFE_TAG_TEXT = /^[A-Za-z0-9][A-Za-z0-9._:/+() -]{0,127}$/;
+const SAFE_HOOK_EVENT = /^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/;
+const SAFE_HOOK_SCRIPT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const SAFE_EXIT_CODE = /^(?:-?[0-9]+|running)$/;
+const SAFE_NPROC = /^[0-9]+$/;
+function safeTagValue(value, pattern = SAFE_TAG_TEXT) {
+    return pattern.test(value) ? value : "unknown";
+}
+function safeMetadataTag(metadata, key, pattern = SAFE_TAG_TEXT) {
+    const value = metadata[key];
+    return typeof value === "string" && value.length > 0 ? safeTagValue(value, pattern) : "unknown";
+}
+function hookEvent(metadata) {
+    return safeMetadataTag(metadata, "hook_event", SAFE_HOOK_EVENT);
+}
+function hookScript(metadata) {
+    const explicit = stringMetadata(metadata, "hook_script", "");
+    const path = explicit || stringMetadata(metadata, "hook_path", "");
+    return path ? safeTagValue(basenameFromPath(path), SAFE_HOOK_SCRIPT) : "unknown";
+}
+function timeoutElapsedMs(metadata) {
+    const finalElapsed = metadata.final_elapsed_ms;
+    if (typeof finalElapsed === "number" && Number.isFinite(finalElapsed))
+        return finalElapsed;
+    const elapsed = metadata.elapsed_ms;
+    return typeof elapsed === "number" && Number.isFinite(elapsed) ? elapsed : undefined;
+}
+function formatNumber(value) {
+    return value.toFixed(2).replace(/\.00$|(?<=\.[0-9])0$/, "");
+}
+function elapsedBucket(elapsedMs) {
+    if (elapsedMs === undefined)
+        return "unknown";
+    if (elapsedMs < 5_000)
+        return "<5s";
+    if (elapsedMs < 10_000)
+        return "5-10s";
+    if (elapsedMs < 20_000)
+        return "10-20s";
+    if (elapsedMs < 60_000)
+        return "20-60s";
+    return ">=60s";
+}
+function remainingBucket(remainingMs) {
+    return remainingMs < 0
+        ? `overdue-${elapsedBucket(Math.abs(remainingMs))}`
+        : elapsedBucket(remainingMs);
+}
+function loadBucket(loadAverage) {
+    if (loadAverage === undefined)
+        return "unknown";
+    if (loadAverage < 2)
+        return "<2";
+    if (loadAverage < 5)
+        return "2-5";
+    if (loadAverage < 10)
+        return "5-10";
+    if (loadAverage < 20)
+        return "10-20";
+    return ">=20";
+}
+function parsedLoadAverage(metadata) {
+    const value = metadata.load_average;
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+        return value;
+    if (typeof value !== "string")
+        return undefined;
+    if (value === "unavailable")
+        return "unavailable";
+    const match = /^\s*\{?\s*([0-9]+(?:\.[0-9]+)?)/.exec(value);
+    if (!match)
+        return undefined;
+    const parsed = Number(match[1]);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function operatingSystemName(metadata) {
+    const platform = stringMetadata(metadata, "platform", "").toLowerCase();
+    if (/windows|win32|mingw|msys|cygwin/.test(platform))
+        return "windows";
+    if (/darwin|macos|mac os/.test(platform))
+        return "macos";
+    if (/linux/.test(platform))
+        return "linux";
+    return "other";
+}
+function spawnMsBucket(metadata) {
+    const value = metadata.spawn_ms;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return "unavailable";
+    if (value < 100)
+        return "<100ms";
+    if (value < 500)
+        return "100-499ms";
+    if (value < 1_000)
+        return "500-999ms";
+    return ">=1000ms";
+}
+function debugSpawnMsBucket(value) {
+    if (typeof value !== "number")
+        return "unavailable";
+    if (value < 100)
+        return "<100ms";
+    if (value < 500)
+        return "100-499ms";
+    if (value < 1_000)
+        return "500-999ms";
+    return ">=1000ms";
+}
+function processCountBucket(value) {
+    if (typeof value !== "number")
+        return "unavailable";
+    if (value < 5)
+        return "0-4";
+    if (value < 17)
+        return "5-16";
+    if (value < 65)
+        return "17-64";
+    return "65+";
+}
+function hookTimeoutDebugContextTags(context) {
+    const tags = {
+        timeout_debug_hook_name: context.hook_name,
+        timeout_debug_hook_event: context.hook_event,
+        timeout_debug_budget_bucket: elapsedBucket(context.budget_ms),
+        timeout_debug_elapsed_bucket: elapsedBucket(context.elapsed_ms),
+        timeout_debug_remaining_bucket: remainingBucket(context.remaining_ms),
+        timeout_debug_wait_point: context.wait_point,
+        timeout_debug_waiting_child: context.waiting_child_basename,
+        timeout_debug_waiting_child_elapsed_bucket: elapsedBucket(context.waiting_child_elapsed_ms),
+        timeout_debug_load_bucket: context.load_average === "unavailable"
+            ? "unavailable"
+            : loadBucket(context.load_average),
+        timeout_debug_spawn_ms_bucket: debugSpawnMsBucket(context.spawn_ms),
+        timeout_debug_process_count_bucket: processCountBucket(context.process_count),
+    };
+    const phaseElapsed = new Map();
+    for (const timing of context.phase_timings) {
+        phaseElapsed.set(timing.phase, Math.max(phaseElapsed.get(timing.phase) ?? 0, timing.elapsed_ms));
+    }
+    for (const [phase, elapsedMs] of phaseElapsed) {
+        tags[`timeout_debug_phase_${phase}_bucket`] = elapsedBucket(elapsedMs);
+    }
+    return tags;
+}
+function safeSlowChild(metadata) {
+    const value = metadata.slow_child;
+    const slowChildMs = metadata.slow_child_ms;
+    const bashEnv = bashEnvTag(metadata);
+    const hasMeasuredChild = typeof slowChildMs === "number" && Number.isFinite(slowChildMs) && slowChildMs >= 0;
+    if (metadata.hook_event === "SessionStart" &&
+        (bashEnv === "profile" || bashEnv === "set") &&
+        !hasMeasuredChild &&
+        (typeof value !== "string" || value.length === 0 || value === "other")) {
+        return "entry-bash-startup";
+    }
+    if (typeof value !== "string" || !SAFE_HOOK_SCRIPT.test(value))
+        return "other";
+    return value;
+}
+function isMachineWideHookSlowness(metadata) {
+    const spawnMs = metadata.spawn_ms;
+    if (typeof spawnMs === "number" && Number.isFinite(spawnMs) && spawnMs >= 500)
+        return true;
+    if (!Array.isArray(metadata.hook_sequence))
+        return false;
+    const slowScripts = new Set();
+    for (const entry of metadata.hook_sequence) {
+        if (entry.ms < 20_000 || !SAFE_HOOK_SCRIPT.test(entry.script))
+            continue;
+        slowScripts.add(entry.script);
+    }
+    return slowScripts.size >= 3;
+}
+function bashEnvTag(metadata) {
+    const value = metadata.bash_env_set;
+    if (value === "profile" || value === "devnull")
+        return value;
+    if (value === true || value === "set") {
+        const coreVersion = metadata.hq_version;
+        const parsedCoreVersion = typeof coreVersion === "string" ? validSemver(coreVersion) : null;
+        if (!parsedCoreVersion)
+            return "unknown";
+        return semverGte(parsedCoreVersion, BASH_ENV_NEUTRALIZED_CORE_VERSION) ? "devnull" : "set";
+    }
+    if (value === false || value === "unset")
+        return "unset";
+    return "unknown";
+}
+function hookTimeoutTags(event) {
+    const metadata = event.metadata;
+    const elapsedMs = timeoutElapsedMs(metadata);
+    const declaredTimeoutMs = typeof metadata.declared_timeout_ms === "number" && Number.isFinite(metadata.declared_timeout_ms)
+        ? metadata.declared_timeout_ms
+        : undefined;
+    const ratio = elapsedMs !== undefined && declaredTimeoutMs !== undefined && declaredTimeoutMs > 0
+        ? Math.round((elapsedMs / declaredTimeoutMs) * 4) / 4
+        : undefined;
+    const shell = stringMetadata(metadata, "shell");
+    const nproc = metadata.nproc;
+    const loadAverage = parsedLoadAverage(metadata);
+    const slowChildMs = metadata.slow_child_ms;
+    return {
+        hook_timeout_kind: hookTimeoutKind(event),
+        hook_event: hookEvent(metadata),
+        hook_script: hookScript(metadata),
+        elapsed_bucket: elapsedBucket(elapsedMs),
+        declared_timeout_s: declaredTimeoutMs === undefined ? "unknown" : formatNumber(declaredTimeoutMs / 1_000),
+        watchdog_ratio: ratio === undefined ? "unknown" : formatNumber(ratio),
+        exit_code: typeof metadata.exit_code === "string" || typeof metadata.exit_code === "number"
+            ? safeTagValue(String(metadata.exit_code), SAFE_EXIT_CODE)
+            : "unknown",
+        platform: safeMetadataTag(metadata, "platform"),
+        hq_cli_version: CLI_VERSION,
+        hq_core_version: safeMetadataTag(metadata, "hq_version"),
+        shell: safeTagValue(shell),
+        bash_env: bashEnvTag(metadata),
+        cwd_kind: safeMetadataTag(metadata, "cwd_kind"),
+        os_name: operatingSystemName(metadata),
+        load_bucket: loadAverage === "unavailable" ? "unavailable" : loadBucket(loadAverage),
+        spawn_ms_bucket: spawnMsBucket(metadata),
+        slow_child: safeSlowChild(metadata),
+        slow_child_ms_bucket: typeof slowChildMs === "number" && Number.isFinite(slowChildMs)
+            ? elapsedBucket(slowChildMs)
+            : "unknown",
+        machine_wide: isMachineWideHookSlowness(metadata) ? "true" : "false",
+        nproc: typeof nproc === "number" || typeof nproc === "string"
+            ? safeTagValue(String(nproc), SAFE_NPROC)
+            : "unknown",
+        tool_name: safeMetadataTag(metadata, "tool_name"),
+    };
+}
+function hookTimeoutKind(event) {
+    if (event.type === HOOK_TIMEOUT_EXCEEDED_TYPE || event.type === HOOK_LATE_FINISH_TYPE) {
+        return "exceeded";
+    }
+    const elapsedMs = event.metadata.elapsed_ms;
+    const declaredTimeoutMs = event.metadata.declared_timeout_ms;
+    return typeof elapsedMs === "number" &&
+        typeof declaredTimeoutMs === "number" &&
+        elapsedMs >= declaredTimeoutMs
+        ? "exceeded"
+        : "warning";
+}
+function sentryEnvelope(event, overrides, additionalTags = {}) {
+    return {
+        level: overrides?.level ?? event.level,
+        fingerprint: overrides?.fingerprint ?? [safeTagValue(event.fingerprint)],
+        tags: {
+            sentry_event_type: safeTagValue(event.type),
+            ...(isHookTimeoutEvent(event) ? hookTimeoutTags(event) : {}),
+            ...additionalTags,
+        },
+        extra: event.metadata,
+    };
+}
+/** Build the same scrubbed event projection that the live SDK path uses. */
+function scrubbedSentryEnvelope(event, overrides, additionalTags = {}) {
+    return beforeSend({
+        message: event.message,
+        ...sentryEnvelope(event, overrides, additionalTags),
+    }, {});
+}
+/** Group hook-timeout conditions by normalized kind while retaining triage tags. */
+function hookTimeoutExceededOverrides(event) {
+    if (!isHookTimeoutEvent(event))
+        return undefined;
+    return {
+        level: "warning",
+        fingerprint: ["hook-timeout", hookTimeoutKind(event)],
+    };
+}
+/**
+ * Resolve true only when the local transport queue drains within the budget.
+ * This does not confirm that the ingest service accepted the event.
+ */
+async function flushWithin(sentry, timeoutMs) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), timeoutMs);
+        void Promise.resolve()
+            .then(() => sentry.flush(timeoutMs))
+            .then((flushed) => {
+            clearTimeout(timer);
+            resolve(flushed === true);
+        }, () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+    });
+}
+function rateLimitDirectory(options, dependencies) {
+    if (options.rateLimitDirectory)
+        return options.rateLimitDirectory;
+    if (options.hqRoot)
+        return join(options.hqRoot, "workspace", "tmp", "sentry-hook-timeouts");
+    if (dependencies.rateLimitDirectory)
+        return dependencies.rateLimitDirectory;
+    try {
+        return join(resolveLiveRoot(), "workspace", "tmp", "sentry-hook-timeouts");
+    }
+    catch {
+        dependencies.stderr.write("Sentry timeout rate limit root unavailable; using process temp.\n");
+        return join(tmpdir(), "hq-cli-sentry-hook-timeouts");
+    }
+}
+function rateLimitStatePath(directory, key) {
+    const digest = createHash("sha256").update(key).digest("hex");
+    return join(directory, `${digest}.json`);
+}
+function readRateLimitState(statePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(statePath, "utf8"));
+        if (typeof parsed.lastCapturedAt !== "number" ||
+            !Number.isFinite(parsed.lastCapturedAt) ||
+            typeof parsed.suppressedCount !== "number" ||
+            !Number.isInteger(parsed.suppressedCount) ||
+            parsed.suppressedCount < 0) {
+            throw new Error("invalid timeout rate limit state");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error("Unable to read the timeout rate limit state", { cause: error });
+    }
+}
+function writeRateLimitState(statePath, state) {
+    mkdirSync(dirname(statePath), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(temporaryPath, `${JSON.stringify(state)}\n`, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporaryPath, statePath);
+}
+function sleepForRateLimitLock(milliseconds) {
+    const signal = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(signal, 0, 0, milliseconds);
+}
+function releaseRateLimitLock(lockPath) {
+    try {
+        rmdirSync(lockPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function acquireRateLimitLock(directory) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const lockPath = join(directory, ".lock");
+    const deadline = Date.now() + RATE_LIMIT_LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            mkdirSync(lockPath, { mode: 0o700 });
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                releaseRateLimitLock(lockPath);
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs >= RATE_LIMIT_LOCK_STALE_MS) {
+                    releaseRateLimitLock(lockPath);
+                    continue;
+                }
+            }
+            catch (statError) {
+                if (statError.code !== "ENOENT")
+                    throw statError;
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error("Timed out acquiring the Sentry timeout rate limit lock");
+            sleepForRateLimitLock(RATE_LIMIT_LOCK_POLL_MS);
+        }
+    }
+}
+function pruneExpiredRateLimitState(directory, now, protectedStatePath) {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const statePath = join(directory, entry.name);
+        if (statePath === protectedStatePath)
+            continue;
+        const state = readRateLimitState(statePath);
+        if (state &&
+            now >= state.lastCapturedAt &&
+            now - state.lastCapturedAt >= HOOK_TIMEOUT_RATE_LIMIT_WINDOW_MS) {
+            try {
+                unlinkSync(statePath);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    }
+}
+function timeoutRateLimitLease(event, kind, options, dependencies) {
+    const sessionId = stringMetadata(event.metadata, "session_id");
+    const machineWide = isMachineWideHookSlowness(event.metadata);
+    const classification = machineWide
+        ? `machine-wide\0${operatingSystemName(event.metadata)}`
+        : `per-script\0${hookScript(event.metadata)}`;
+    const key = `${sessionId}\0${hookEvent(event.metadata)}\0${kind}\0${classification}`;
+    const directory = rateLimitDirectory(options, dependencies);
+    const statePath = rateLimitStatePath(directory, key);
+    const releaseLock = acquireRateLimitLock(directory);
+    const now = options.rateLimitNow?.() ?? dependencies.rateLimitNow?.() ?? Date.now();
+    try {
+        pruneExpiredRateLimitState(directory, now, statePath);
+        const current = readRateLimitState(statePath);
+        if (current &&
+            now >= current.lastCapturedAt &&
+            now - current.lastCapturedAt < HOOK_TIMEOUT_RATE_LIMIT_WINDOW_MS) {
+            writeRateLimitState(statePath, {
+                lastCapturedAt: current.lastCapturedAt,
+                suppressedCount: current.suppressedCount + 1,
+            });
+            releaseLock();
+            return {
+                capture: false,
+                suppressedSinceLast: 0,
+                commitCapture: () => undefined,
+                release: () => undefined,
+            };
+        }
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            releaseLock();
+        };
+        let committed = false;
+        return {
+            capture: true,
+            suppressedSinceLast: current?.suppressedCount ?? 0,
+            commitCapture: () => {
+                if (committed)
+                    return;
+                if (released)
+                    throw new Error("Sentry timeout rate limit lease was released before capture");
+                writeRateLimitState(statePath, { lastCapturedAt: now, suppressedCount: 0 });
+                committed = true;
+                release();
+            },
+            release,
+        };
+    }
+    catch (error) {
+        releaseLock();
+        throw error;
+    }
+}
+function metricAttributes(metadata) {
+    const attributes = Object.fromEntries(Object.entries(metadata)
+        .filter(([, value]) => isScalarMetadataValue(value))
+        .map(([key, value]) => [key, typeof value === "string" ? safeTagValue(value) : value]));
+    if (Object.hasOwn(metadata, "bash_env_set")) {
+        attributes.bash_env_set = bashEnvTag(metadata);
+    }
+    return attributes;
+}
+function addHookSequenceBreadcrumbs(event, dependencies) {
+    const sequence = event.metadata.hook_sequence;
+    if (!Array.isArray(sequence))
+        return;
+    for (const entry of sequence) {
+        dependencies.sentry.addBreadcrumb({
+            category: "hq.hook",
+            message: `${entry.script} ${entry.event} ${entry.ms}ms`,
+        });
+    }
+}
+async function reportSuppressedTimeout(result, event, timeoutMs, dependencies, kind) {
+    const metricName = kind === "exceeded" ? HOOK_TIMEOUT_EXCEEDED_METRIC : HOOK_TIMEOUT_WARNING_METRIC;
+    try {
+        dependencies.sentry.metrics.count(metricName, 1, {
+            attributes: metricAttributes(event.metadata),
+        });
+        if (await flushWithin(dependencies.sentry, timeoutMs))
+            return result;
+    }
+    catch {
+        // Report failure below without exposing event fields or transport details.
+    }
+    dependencies.stderr.write("Sentry report failed.\n");
+    return invalidInput();
+}
+/**
+ * Capture one validated Sentry message and wait only for the supplied bounded
+ * flush budget. A zero result means the event entered the local transport and
+ * its queue drained in time, not that ingest accepted it. Normal reports are
+ * silent on stdout; dry-runs print the same scrubbed event projection used by
+ * the live path. All failures use a generic stderr line so malformed input and
+ * transport errors cannot echo event data back to a hook.
+ */
+export async function reportSentryEvent(stdin, options = {}, dependencies = defaultDependencies) {
+    const timeoutMs = resolveTimeout(options.timeoutMs);
+    const result = parseSentryReportEvent(stdin);
+    if (timeoutMs === null || result.code !== 0 || !result.event) {
+        dependencies.stderr.write("Invalid Sentry report input.\n");
+        return invalidInput();
+    }
+    if (result.droppedMetadataKeys) {
+        const noun = result.droppedMetadataKeys === 1 ? "key" : "keys";
+        dependencies.stderr.write(`Dropped ${result.droppedMetadataKeys} unsupported Sentry report metadata ${noun}.\n`);
+    }
+    let event = result.event;
+    let debugContextTags = {};
+    const debugContext = event.metadata.hook_timeout_debug_context;
+    if (debugContext && isHookTimeoutEvent(event)) {
+        let enabled;
+        try {
+            enabled =
+                (await dependencies.timeoutDebugContextEnabled?.(options.signal)) ?? false;
+        }
+        catch {
+            // An optional diagnostic flag read must never suppress the base report.
+            enabled = false;
+        }
+        if (enabled) {
+            debugContextTags = hookTimeoutDebugContextTags(debugContext);
+        }
+        else {
+            const metadata = { ...event.metadata };
+            delete metadata.hook_timeout_debug_context;
+            event = { ...event, metadata };
+        }
+    }
+    else if (debugContext) {
+        const metadata = { ...event.metadata };
+        delete metadata.hook_timeout_debug_context;
+        event = { ...event, metadata };
+    }
+    result.event = event;
+    const overrides = hookTimeoutExceededOverrides(event);
+    if (options.dryRun) {
+        const scrubbed = scrubbedSentryEnvelope(event, overrides, debugContextTags);
+        if (scrubbed)
+            dependencies.stdout.write(`${JSON.stringify(scrubbed)}\n`);
+        return result;
+    }
+    if (isHookTimeoutEvent(event)) {
+        addHookSequenceBreadcrumbs(event, dependencies);
+        const kind = hookTimeoutKind(event);
+        let rateLimit;
+        try {
+            rateLimit = timeoutRateLimitLease(event, kind, options, dependencies);
+        }
+        catch {
+            dependencies.stderr.write("Sentry timeout rate limit state unavailable; sending without rate limiting.\n");
+            rateLimit = {
+                capture: true,
+                suppressedSinceLast: 0,
+                commitCapture: () => undefined,
+                release: () => undefined,
+            };
+        }
+        if (!rateLimit.capture) {
+            return reportSuppressedTimeout(result, event, timeoutMs, dependencies, kind);
+        }
+        const tags = rateLimit.suppressedSinceLast > 0
+            ? { suppressed_since_last: String(rateLimit.suppressedSinceLast) }
+            : {};
+        const envelope = sentryEnvelope(event, overrides, { ...debugContextTags, ...tags });
+        try {
+            dependencies.sentry.captureMessage(event.message, envelope);
+            rateLimit.commitCapture();
+            if (await flushWithin(dependencies.sentry, timeoutMs))
+                return result;
+        }
+        catch {
+            rateLimit.release();
+            // Report failure below without exposing event fields or transport details.
+        }
+        dependencies.stderr.write("Sentry report failed.\n");
+        return invalidInput();
+    }
+    const envelope = sentryEnvelope(event, overrides, debugContextTags);
+    try {
+        dependencies.sentry.captureMessage(event.message, envelope);
+        if (await flushWithin(dependencies.sentry, timeoutMs))
+            return result;
+    }
+    catch {
+        // Report failure below without exposing event fields or transport details.
+    }
+    dependencies.stderr.write("Sentry report failed.\n");
+    return invalidInput();
+}
+//# sourceMappingURL=sentry-report.js.map