@indigoai-us/hq-cli 5.129.0 → 5.130.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.130.0] — 2026-09-22
+
+### Fixed
+
+- Hook-timeout reports remain visible as warning events with stable grouping and
+  diagnostic tags. Repeated reports are rate-limited while the next capture
+  records the suppressed count.
+
 ## [5.129.0] — 2026-09-22
 
 ### Added

package/dist/commands/core.js

@@ -483,7 +483,13 @@ export function registerCoreCommands(program) {
         .action(async (options) => {
         const stdin = await readSentryReportStdin(process.stdin);
         const timeoutMs = options.timeoutMs === undefined ? undefined : Number(options.timeoutMs);
-        const result = await reportSentryEvent(stdin ?? "", { dryRun: options.dryRun, timeoutMs });
+        const scope = core.opts();
+        const hqRoot = scope.hqRoot ? resolveLiveRoot({ hqRoot: scope.hqRoot }) : undefined;
+        const result = await reportSentryEvent(stdin ?? "", {
+            dryRun: options.dryRun,
+            timeoutMs,
+            hqRoot,
+        });
         if (result.code !== 0)
             process.exitCode = result.code;
     });

package/dist/lib/core-utils/sentry-report.d.ts

@@ -3,14 +3,17 @@
  *
  * 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 and never reads a
- * hook payload or the process environment. The owner-approved `hook_path`
+ * 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 rather
- * than truncated. Unknown scalar metadata is dropped instead: the allowlist,
- * not a caller version match, determines what may leave the machine.
+ * 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 * as Sentry from "@sentry/node";
 import type { CaptureContext, SeverityLevel } from "@sentry/node";
@@ -24,9 +27,15 @@ export declare const MAX_SENTRY_REPORT_METADATA_VALUE_BYTES = 256;
  * 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 declare const ALLOWED_SENTRY_REPORT_METADATA_KEYS: readonly ["hook_name", "hook_path", "hook_event", "tool_name", "session_id", "declared_timeout_ms", "elapsed_ms", "remaining_ms", "watchdog_timeout_ms", "hook_timeout_ms", "hq_version", "platform", "load_average"];
+export declare const ALLOWED_SENTRY_REPORT_METADATA_KEYS: readonly ["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", "exit_code", "final_elapsed_ms", "bash_env_set", "cwd_kind", "shell", "nproc", "hook_sequence"];
 export declare const MAX_SENTRY_REPORT_METADATA_KEYS: number;
-export type SentryReportMetadata = Record<string, string | number | boolean>;
+export type HookSequenceEntry = {
+    script: string;
+    event: string;
+    ms: number;
+};
+export type SentryReportMetadataValue = string | number | boolean | HookSequenceEntry[];
+export type SentryReportMetadata = Record<string, SentryReportMetadataValue>;
 export type SentryReportEvent = {
     type: string;
     message: string;
@@ -38,15 +47,26 @@ export type SentryReportOptions = {
     dryRun?: boolean;
     /** Total time reserved for the report flush after validation. */
     timeoutMs?: number;
+    /** Explicit live HQ root supplied by `hq core --hq-root`. */
+    hqRoot?: string;
+    /** Test seam for the bounded timeout-report stamp store. */
+    rateLimitDirectory?: string;
+    /** Test seam for deterministic rate-limit windows. */
+    rateLimitNow?: () => number;
 };
 export type SentryReportDependencies = {
     sentry: {
         captureMessage: (message: string, context?: CaptureContext | SeverityLevel) => string;
+        addBreadcrumb: (breadcrumb: Parameters<typeof Sentry.addBreadcrumb>[0]) => void;
         metrics: Pick<typeof Sentry.metrics, "count">;
         flush: (timeout?: number) => PromiseLike<boolean>;
     };
     stdout: Pick<NodeJS.WriteStream, "write">;
     stderr: Pick<NodeJS.WriteStream, "write">;
+    /** Test seam; production resolves the live HQ workspace tmp directory. */
+    rateLimitDirectory?: string;
+    /** Test seam; production uses Date.now. */
+    rateLimitNow?: () => number;
 };
 export type SentryReportResult = {
     code: 0 | 1;

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

@@ -3,17 +3,26 @@
  *
  * 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 and never reads a
- * hook payload or the process environment. The owner-approved `hook_path`
+ * 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 rather
- * than truncated. Unknown scalar metadata is dropped instead: the allowlist,
- * not a caller version match, determines what may leave the machine.
+ * 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 * as Sentry from "@sentry/node";
+import { CLI_VERSION } from "../../cli-version.js";
 import { beforeSend } from "../../sentry-before-send.js";
+import { resolveLiveRoot } from "../../utils/hq-roots.js";
 export const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
 export const MAX_SENTRY_REPORT_TIMEOUT_MS = 5_000;
 export const MAX_SENTRY_REPORT_PAYLOAD_BYTES = 2_048;
@@ -30,8 +39,17 @@ const SENTRY_REPORT_LEVELS = new Set([
     "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 HOOK_TIMEOUT_EXCEEDED_FINGERPRINT = "hook-timeout-exceeded";
+const HOOK_TIMEOUT_WARNING_FINGERPRINT = "hook-timeout";
+const MAX_HOOK_SEQUENCE_ENTRIES = 20;
+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;
 /**
  * The only hook diagnostics that can be attached as metadata. The list omits
  * command text, prompts, payloads, company names, and repositories. `hook_path`
@@ -42,6 +60,7 @@ export const ALLOWED_SENTRY_REPORT_METADATA_KEYS = [
     "hook_name",
     "hook_path",
     "hook_event",
+    "hook_script",
     "tool_name",
     "session_id",
     "declared_timeout_ms",
@@ -52,6 +71,13 @@ export const ALLOWED_SENTRY_REPORT_METADATA_KEYS = [
     "hq_version",
     "platform",
     "load_average",
+    "exit_code",
+    "final_elapsed_ms",
+    "bash_env_set",
+    "cwd_kind",
+    "shell",
+    "nproc",
+    "hook_sequence",
 ];
 const ALLOWED_METADATA_KEYS = new Set(ALLOWED_SENTRY_REPORT_METADATA_KEYS);
 const SENTRY_REPORT_METADATA_KEY_HEADROOM = 2;
@@ -96,7 +122,34 @@ function isScalarMetadataValue(value) {
         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 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 (!isScalarMetadataValue(value))
         return false;
     if (key === "tool_name" || key === "session_id" || key === "hook_path") {
@@ -157,15 +210,18 @@ export function parseSentryReportEvent(stdin) {
     const metadata = {};
     let droppedMetadataKeys = 0;
     for (const key of metadataKeys) {
-        if (!isScalarMetadataValue(rawMetadata[key]))
-            return invalidInput();
         if (!ALLOWED_METADATA_KEYS.has(key)) {
+            if (!isScalarMetadataValue(rawMetadata[key]))
+                return invalidInput();
             droppedMetadataKeys++;
             continue;
         }
         if (!isAllowedMetadataValue(key, rawMetadata[key]))
             return invalidInput();
-        metadata[key] = rawMetadata[key];
+        metadata[key] =
+            key === "hook_sequence"
+                ? boundedHookSequence(rawMetadata[key])
+                : rawMetadata[key];
     }
     return {
         code: 0,
@@ -185,11 +241,139 @@ function resolveTimeout(timeoutMs) {
         return null;
     return timeout;
 }
-function sentryEnvelope(event, overrides) {
+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 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 bashEnvTag(metadata) {
+    const value = metadata.bash_env_set;
+    if (value === true || value === "set")
+        return "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 = metadata.load_average;
+    return {
+        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"),
+        load_bucket: typeof loadAverage === "number" ? loadBucket(loadAverage) : "unknown",
+        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 ?? [event.fingerprint],
-        tags: { sentry_event_type: event.type },
+        fingerprint: overrides?.fingerprint ?? [safeTagValue(event.fingerprint)],
+        tags: {
+            sentry_event_type: safeTagValue(event.type),
+            ...(isHookTimeoutEvent(event) ? hookTimeoutTags(event) : {}),
+            ...additionalTags,
+        },
         extra: event.metadata,
     };
 }
@@ -201,25 +385,23 @@ function scrubbedSentryEnvelope(event, overrides) {
     }, {});
 }
 /**
- * The watchdog's relative threshold fires before the declared timeout and
- * clamps remaining_ms at zero, so its real warnings stay on the metric path.
- * Keep a defensive branch for a genuine exceeded payload from another
- * producer without restoring per-hook grouping.
+ * Keep timeout faults visible at warning level while grouping them by the
+ * hook event and installation-independent script basename. A genuine
+ * exceeded or late-finish payload gets its own stable condition group.
  */
 function hookTimeoutExceededOverrides(event) {
-    if (event.type !== HOOK_TIMEOUT_WARNING_TYPE)
-        return undefined;
-    const elapsedMs = event.metadata.elapsed_ms;
-    const declaredTimeoutMs = event.metadata.declared_timeout_ms;
-    if (typeof elapsedMs !== "number" ||
-        typeof declaredTimeoutMs !== "number" ||
-        elapsedMs < declaredTimeoutMs) {
+    const eventName = hookEvent(event.metadata);
+    if (!isHookTimeoutEvent(event))
         return undefined;
+    if (hookTimeoutKind(event) === "warning") {
+        return {
+            level: "warning",
+            fingerprint: [HOOK_TIMEOUT_WARNING_FINGERPRINT, eventName, hookScript(event.metadata)],
+        };
     }
-    const hookEvent = typeof event.metadata.hook_event === "string" ? event.metadata.hook_event : "unknown";
     return {
         level: "warning",
-        fingerprint: [HOOK_TIMEOUT_EXCEEDED_FINGERPRINT, hookEvent],
+        fingerprint: [HOOK_TIMEOUT_EXCEEDED_FINGERPRINT, eventName, hookScript(event.metadata)],
     };
 }
 /**
@@ -240,6 +422,202 @@ async function flushWithin(sentry, timeoutMs) {
         });
     });
 }
+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 key = `${sessionId}\0${hookEvent(event.metadata)}\0${hookScript(event.metadata)}\0${kind}`;
+    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) {
+    return Object.fromEntries(Object.entries(metadata)
+        .filter(([, value]) => isScalarMetadataValue(value))
+        .map(([key, value]) => [key, typeof value === "string" ? safeTagValue(value) : value]));
+}
+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
@@ -266,15 +644,37 @@ export async function reportSentryEvent(stdin, options = {}, dependencies = defa
             dependencies.stdout.write(`${JSON.stringify(scrubbed)}\n`);
         return result;
     }
-    if (result.event.type === HOOK_TIMEOUT_WARNING_TYPE && !overrides) {
+    if (isHookTimeoutEvent(result.event)) {
+        addHookSequenceBreadcrumbs(result.event, dependencies);
+        const kind = hookTimeoutKind(result.event);
+        let rateLimit;
         try {
-            dependencies.sentry.metrics.count(HOOK_TIMEOUT_WARNING_METRIC, 1, {
-                attributes: result.event.metadata,
-            });
+            rateLimit = timeoutRateLimitLease(result.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, result.event, timeoutMs, dependencies, kind);
+        }
+        const tags = rateLimit.suppressedSinceLast > 0
+            ? { suppressed_since_last: String(rateLimit.suppressedSinceLast) }
+            : {};
+        const envelope = sentryEnvelope(result.event, overrides, tags);
+        try {
+            dependencies.sentry.captureMessage(result.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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.129.0",
+  "version": "5.130.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {