@debugbundle/cli 1.1.2 → 1.3.0

package/dist/main.cjs

@@ -14486,25 +14486,74 @@ var CaptureProbeEventsSchema = external_exports.enum(CaptureProbeEventsValues);
 var RequestSignalClassificationValues = ["incident_signal", "context_signal"];
 var RequestSignalClassificationSchema = external_exports.enum(RequestSignalClassificationValues);
 var RECOMMENDED_IMMEDIATE_CLIENT_ERROR_STATUSES = [401, 403, 409, 422];
+var HTTP_METHOD_VALUES = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 var ImmediateClientErrorStatusSchema = external_exports.number().int().min(400).max(499);
+var HttpMethodSchema = external_exports.enum(HTTP_METHOD_VALUES);
 function normalizeImmediateClientErrorStatuses(statuses) {
   return Array.from(new Set(statuses)).sort((left, right) => left - right);
 }
 var ImmediateClientErrorStatusesSchema = external_exports.array(ImmediateClientErrorStatusSchema).max(12).transform((statuses) => normalizeImmediateClientErrorStatuses(statuses));
+function normalizePathPattern(value) {
+  return value.trim().replace(/\/{2,}/g, "/");
+}
+function isValidPathPattern(value) {
+  const normalized = normalizePathPattern(value);
+  if (!normalized.startsWith("/") || normalized.includes("?") || normalized.includes("#")) {
+    return false;
+  }
+  const wildcardIndex = normalized.indexOf("*");
+  return wildcardIndex === -1 || wildcardIndex === normalized.length - 1;
+}
+function normalizeHttpMethods(methods) {
+  if (methods === void 0 || methods.length === 0) {
+    return [];
+  }
+  const normalized = methods.map((method) => method.toUpperCase()).filter(
+    (method) => HTTP_METHOD_VALUES.includes(method)
+  );
+  return Array.from(new Set(normalized)).sort();
+}
+function normalizeImmediateClientErrorPathRules(rules) {
+  const normalized = rules.map((rule) => ({
+    status_code: rule.status_code,
+    path_pattern: normalizePathPattern(rule.path_pattern),
+    methods: normalizeHttpMethods(rule.methods)
+  }));
+  const deduped = /* @__PURE__ */ new Map();
+  for (const rule of normalized) {
+    deduped.set(`${rule.status_code}:${rule.path_pattern}:${rule.methods.join(",")}`, rule);
+  }
+  return Array.from(deduped.values()).sort((left, right) => {
+    if (left.status_code !== right.status_code) return left.status_code - right.status_code;
+    const pathComparison = left.path_pattern.localeCompare(right.path_pattern);
+    if (pathComparison !== 0) return pathComparison;
+    return left.methods.join(",").localeCompare(right.methods.join(","));
+  });
+}
+var ImmediateClientErrorPathRuleSchema = external_exports.object({
+  status_code: ImmediateClientErrorStatusSchema,
+  path_pattern: external_exports.string().min(1).max(256).transform(normalizePathPattern).refine(isValidPathPattern, {
+    message: "path_pattern must start with / and may only use a terminal * wildcard"
+  }),
+  methods: external_exports.array(HttpMethodSchema).max(7).optional().default([]).transform(normalizeHttpMethods)
+});
+var ImmediateClientErrorPathRulesSchema = external_exports.array(ImmediateClientErrorPathRuleSchema).max(25).transform((rules) => normalizeImmediateClientErrorPathRules(rules));
 var ResolvedCapturePolicySchema = external_exports.object({
   preset: CapturePresetSchema,
   capture_logs: CaptureLogsSchema,
   capture_request_events: CaptureRequestEventsSchema,
   capture_breadcrumbs: CaptureBreadcrumbsSchema,
   capture_probe_events: CaptureProbeEventsSchema,
-  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema
+  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema,
+  immediate_client_error_path_rules: ImmediateClientErrorPathRulesSchema.default([])
 });
 var CapturePolicyOverridesSchema = external_exports.object({
   capture_logs: CaptureLogsSchema.nullable(),
   capture_request_events: CaptureRequestEventsSchema.nullable(),
   capture_breadcrumbs: CaptureBreadcrumbsSchema.nullable(),
   capture_probe_events: CaptureProbeEventsSchema.nullable(),
-  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema.nullable()
+  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema.nullable(),
+  immediate_client_error_path_rules: ImmediateClientErrorPathRulesSchema.nullable().default(null)
 });
 var CapturePolicyResponseSchema = external_exports.object({
   access_mode: external_exports.enum(["manage", "preview"]),
@@ -14519,6 +14568,7 @@ var CapturePolicySchema = external_exports.object({
   capture_breadcrumbs: CaptureBreadcrumbsSchema.nullable(),
   capture_probe_events: CaptureProbeEventsSchema.nullable(),
   immediate_client_error_statuses: ImmediateClientErrorStatusesSchema.nullable(),
+  immediate_client_error_path_rules: ImmediateClientErrorPathRulesSchema.nullable().default(null),
   updated_at: external_exports.string().datetime()
 });
 var CapturePolicyUpdateSchema = external_exports.object({
@@ -14527,7 +14577,8 @@ var CapturePolicyUpdateSchema = external_exports.object({
   capture_request_events: CaptureRequestEventsSchema.nullable().optional(),
   capture_breadcrumbs: CaptureBreadcrumbsSchema.nullable().optional(),
   capture_probe_events: CaptureProbeEventsSchema.nullable().optional(),
-  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema.nullable().optional()
+  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema.nullable().optional(),
+  immediate_client_error_path_rules: ImmediateClientErrorPathRulesSchema.nullable().optional()
 });
 var PRESET_DEFAULTS = {
   minimal: {
@@ -14535,30 +14586,69 @@ var PRESET_DEFAULTS = {
     capture_request_events: "failures_only",
     capture_breadcrumbs: "local_only",
     capture_probe_events: "buffer_only",
-    immediate_client_error_statuses: []
+    immediate_client_error_statuses: [],
+    immediate_client_error_path_rules: []
   },
   balanced: {
     capture_logs: "warning",
     capture_request_events: "failures_only",
     capture_breadcrumbs: "exception_only",
     capture_probe_events: "buffer_only",
-    immediate_client_error_statuses: []
+    immediate_client_error_statuses: [],
+    immediate_client_error_path_rules: []
   },
   investigative: {
     capture_logs: "info",
     capture_request_events: "all",
     capture_breadcrumbs: "standalone",
     capture_probe_events: "standalone_when_activated",
-    immediate_client_error_statuses: [...RECOMMENDED_IMMEDIATE_CLIENT_ERROR_STATUSES]
+    immediate_client_error_statuses: [...RECOMMENDED_IMMEDIATE_CLIENT_ERROR_STATUSES],
+    immediate_client_error_path_rules: []
   }
 };
 var BALANCED_IMMEDIATE_REQUEST_STATUSES = /* @__PURE__ */ new Set([408, 423, 424, 425, 429]);
 var INVESTIGATIVE_IMMEDIATE_REQUEST_STATUSES = /* @__PURE__ */ new Set([...BALANCED_IMMEDIATE_REQUEST_STATUSES, 409]);
-var BALANCED_STANDARD_ANOMALY_STATUSES = /* @__PURE__ */ new Set([401, 403, 404, 409, 422]);
-var BALANCED_HIGH_VOLUME_ANOMALY_STATUSES = /* @__PURE__ */ new Set([400, 410]);
-var INVESTIGATIVE_ANOMALY_STATUSES = /* @__PURE__ */ new Set([...BALANCED_STANDARD_ANOMALY_STATUSES, ...BALANCED_HIGH_VOLUME_ANOMALY_STATUSES]);
+function normalizeRequestPath(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  const path = trimmed.startsWith("http://") || trimmed.startsWith("https://") ? (() => {
+    try {
+      return new URL(trimmed).pathname;
+    } catch {
+      return trimmed;
+    }
+  })() : trimmed;
+  return (path.split(/[?#]/, 1)[0] ?? path).replace(/\/{2,}/g, "/");
+}
+function pathPatternMatches(rulePattern, requestPath) {
+  const pattern = normalizePathPattern(rulePattern);
+  if (!pattern.endsWith("*")) {
+    return requestPath === pattern;
+  }
+  const prefix = pattern.slice(0, -1);
+  return requestPath.startsWith(prefix);
+}
+function matchesImmediateClientErrorPathRule(input2) {
+  const { responseStatus, immediateClientErrorPathRules = [] } = input2;
+  if (responseStatus === null || !Number.isFinite(responseStatus) || immediateClientErrorPathRules.length === 0) {
+    return false;
+  }
+  const requestPath = normalizeRequestPath(input2.requestPath);
+  if (requestPath === null) {
+    return false;
+  }
+  const httpMethod = typeof input2.httpMethod === "string" ? input2.httpMethod.toUpperCase() : null;
+  return immediateClientErrorPathRules.some(
+    (rule) => rule.status_code === responseStatus && (rule.methods.length === 0 || httpMethod !== null && rule.methods.includes(httpMethod)) && pathPatternMatches(rule.path_pattern, requestPath)
+  );
+}
 function classifyRequestStatus(input2) {
-  const { responseStatus, capturePreset, immediateClientErrorStatuses = [] } = input2;
+  const { responseStatus, capturePreset, immediateClientErrorStatuses = [], immediateClientErrorPathRules = [] } = input2;
   if (responseStatus === null || !Number.isFinite(responseStatus)) {
     return "context_signal";
   }
@@ -14568,6 +14658,14 @@ function classifyRequestStatus(input2) {
   if (immediateClientErrorStatuses.includes(responseStatus)) {
     return "incident_signal";
   }
+  if (matchesImmediateClientErrorPathRule({
+    responseStatus,
+    requestPath: input2.requestPath,
+    httpMethod: input2.httpMethod,
+    immediateClientErrorPathRules
+  })) {
+    return "incident_signal";
+  }
   if (capturePreset === "investigative") {
     return INVESTIGATIVE_IMMEDIATE_REQUEST_STATUSES.has(responseStatus) ? "incident_signal" : "context_signal";
   }
@@ -14577,31 +14675,10 @@ function classifyRequestStatus(input2) {
   return "context_signal";
 }
 function getRequestAnomalyThreshold(input2) {
-  const { responseStatus, capturePreset } = input2;
+  const { responseStatus } = input2;
   if (responseStatus === null || !Number.isFinite(responseStatus) || responseStatus < 400 || responseStatus >= 500) {
     return null;
   }
-  if (capturePreset === "minimal") {
-    return null;
-  }
-  if (capturePreset === "investigative") {
-    return INVESTIGATIVE_ANOMALY_STATUSES.has(responseStatus) ? {
-      minimum_occurrences_5m: 8,
-      minimum_ratio_5m_to_1h: 2
-    } : null;
-  }
-  if (BALANCED_STANDARD_ANOMALY_STATUSES.has(responseStatus)) {
-    return {
-      minimum_occurrences_5m: 20,
-      minimum_ratio_5m_to_1h: 3
-    };
-  }
-  if (BALANCED_HIGH_VOLUME_ANOMALY_STATUSES.has(responseStatus)) {
-    return {
-      minimum_occurrences_5m: 50,
-      minimum_ratio_5m_to_1h: 5
-    };
-  }
   return null;
 }
 
@@ -14694,7 +14771,7 @@ function isIpLikeHost(value) {
   return /^(?:\d{1,3}\.){3}\d{1,3}$/.test(host) || /^\[[0-9a-f:]+\]$/i.test(host) || host.includes(":") && /^[0-9a-f:]+$/i.test(host);
 }
 
-// ../../packages/shared-types/src/capture-rules.ts
+// ../../packages/shared-types/src/capture-rule-schemas.ts
 var CAPTURE_RULE_EVENT_TYPES = [
   "backend_exception",
   "request_event",
@@ -14722,6 +14799,7 @@ var CaptureRuleSampleEventClassSchema = external_exports.enum(CaptureRuleSampleE
 var CaptureRuleRuntimeSchema = external_exports.enum(CAPTURE_RULE_RUNTIME_VALUES);
 var CaptureRuleEventTypeSchema = external_exports.enum(CAPTURE_RULE_EVENT_TYPES);
 var BrowserEventKindSchema = external_exports.enum(["window_error", "resource_error"]);
+var CaptureRuleClientKindSchema = external_exports.enum(["human", "bot", "unknown"]);
 function normalizeOptionalTrimmedString(value) {
   const trimmed = value?.trim();
   return trimmed && trimmed.length > 0 ? trimmed : void 0;
@@ -14799,6 +14877,9 @@ var CaptureRuleMatcherSchema = external_exports.object({
   message_contains: external_exports.string().min(1).max(500).optional(),
   message_equals: external_exports.string().min(1).max(500).optional(),
   browser_event_kind: BrowserEventKindSchema.optional(),
+  browser_event_opaque: external_exports.boolean().optional(),
+  client_kind: CaptureRuleClientKindSchema.optional(),
+  bot_family: external_exports.string().min(1).max(120).optional(),
   resource_url: UrlMatcherSchema.optional(),
   request_url: UrlMatcherSchema.optional(),
   status_codes: external_exports.array(external_exports.number().int().min(100).max(599)).min(1).optional(),
@@ -14813,6 +14894,7 @@ var CaptureRuleMatcherSchema = external_exports.object({
   const errorName = normalizeOptionalTrimmedString(value.error_name);
   const messageContains = normalizeOptionalTrimmedString(value.message_contains);
   const messageEquals = normalizeOptionalTrimmedString(value.message_equals);
+  const botFamily = normalizeOptionalTrimmedString(value.bot_family);
   const statusCodes = normalizeNumberArray(value.status_codes);
   if (eventTypes !== void 0) {
     normalized.event_types = eventTypes;
@@ -14841,6 +14923,15 @@ var CaptureRuleMatcherSchema = external_exports.object({
   if (value.browser_event_kind !== void 0) {
     normalized.browser_event_kind = value.browser_event_kind;
   }
+  if (value.browser_event_opaque !== void 0) {
+    normalized.browser_event_opaque = value.browser_event_opaque;
+  }
+  if (value.client_kind !== void 0) {
+    normalized.client_kind = value.client_kind;
+  }
+  if (botFamily !== void 0) {
+    normalized.bot_family = botFamily;
+  }
   if (value.resource_url !== void 0) {
     normalized.resource_url = value.resource_url;
   }
@@ -14867,6 +14958,9 @@ var CaptureRuleMatcherSchema = external_exports.object({
     "message_contains",
     "message_equals",
     "browser_event_kind",
+    "browser_event_opaque",
+    "client_kind",
+    "bot_family",
     "resource_url",
     "request_url",
     "status_codes",
@@ -15049,6 +15143,8 @@ var CaptureRulesFileSchema = external_exports.object({
   version: external_exports.literal(1),
   rules: external_exports.array(CaptureRuleSchema)
 });
+
+// ../../packages/shared-types/src/capture-rule-evaluation.ts
 var CaptureRuleEvaluationUrlSchema = external_exports.object({
   host: external_exports.string().min(1).transform((value) => value.toLowerCase()).optional(),
   path: external_exports.string().min(1).transform((value) => value.startsWith("/") ? value : `/${value}`)
@@ -15064,11 +15160,40 @@ var CaptureRuleEvaluationContextSchema = external_exports.object({
   error_name: external_exports.string().min(1).optional(),
   message: external_exports.string().min(1).optional(),
   browser_event_kind: BrowserEventKindSchema.optional(),
+  browser_event_opaque: external_exports.boolean().optional(),
+  client_kind: CaptureRuleClientKindSchema.optional(),
+  bot_family: external_exports.string().min(1).max(120).optional(),
   resource_url: CaptureRuleEvaluationUrlSchema.optional(),
   request_url: CaptureRuleEvaluationUrlSchema.optional(),
   status_code: external_exports.number().int().min(0).max(599).optional(),
   fingerprint: CaptureRuleFingerprintSchema.optional()
 });
+function classifyCaptureRuleClientFromUserAgent(userAgent) {
+  if (userAgent === null || userAgent === void 0) {
+    return { client_kind: "unknown" };
+  }
+  const lower = userAgent.toLowerCase();
+  const knownBots = [
+    { family: "Googlebot", markers: ["googlebot", "adsbot-google", "google-inspectiontool"] },
+    { family: "Bingbot", markers: ["bingbot", "msnbot"] },
+    { family: "DuckDuckBot", markers: ["duckduckbot"] },
+    { family: "Applebot", markers: ["applebot"] },
+    { family: "YandexBot", markers: ["yandexbot"] },
+    { family: "Baiduspider", markers: ["baiduspider"] },
+    { family: "FacebookBot", markers: ["facebookexternalhit", "facebot"] },
+    { family: "LinkedInBot", markers: ["linkedinbot"] },
+    { family: "TwitterBot", markers: ["twitterbot"] },
+    { family: "Slackbot", markers: ["slackbot"] }
+  ];
+  const knownBot = knownBots.find((entry) => entry.markers.some((marker) => lower.includes(marker)));
+  if (knownBot !== void 0) {
+    return { client_kind: "bot", bot_family: knownBot.family };
+  }
+  if (["bot", "crawler", "spider", "slurp"].some((marker) => lower.includes(marker))) {
+    return { client_kind: "bot", bot_family: "OtherBot" };
+  }
+  return { client_kind: "human" };
+}
 
 // ../../packages/shared-types/src/capture-rule-suggestions.ts
 var CaptureRuleSuggestionConfidenceSchema = external_exports.enum(["high", "medium", "low"]);
@@ -15278,6 +15403,12 @@ var BrowserExceptionEventSchema = external_exports.object({
   }).strict().optional(),
   opaque: external_exports.boolean()
 }).strict();
+var FrontendRejectionReasonSchema = external_exports.object({
+  kind: external_exports.enum(["error", "string", "object", "null", "undefined", "unknown"]),
+  name: external_exports.string().min(1).optional(),
+  message: external_exports.string().min(1).optional(),
+  preview: external_exports.string().min(1).optional()
+}).strict();
 var FrontendExceptionPayloadSchema = external_exports.object({
   name: external_exports.string().min(1),
   message: external_exports.string().min(1),
@@ -15290,6 +15421,7 @@ var FrontendExceptionPayloadSchema = external_exports.object({
   breadcrumbs: external_exports.array(FrontendExceptionBreadcrumbSchema).optional(),
   device: DeviceInfoSchema.nullable().optional(),
   browser_event: BrowserExceptionEventSchema.optional(),
+  rejection_reason: FrontendRejectionReasonSchema.optional(),
   dom_context: external_exports.object({
     mode: external_exports.literal("lightweight"),
     html_excerpt: external_exports.string().min(1)
@@ -15741,7 +15873,7 @@ function buildSkill() {
     "2. Inspect the incident bundle and reproduction artifact before proposing a fix.",
     "3. Run `debugbundle analyze --type improvement --local` after local processing when you need a deterministic change plan.",
     "4. Apply the narrowest fix, then validate it with the repository test workflow from `.debugbundle/profile.json`.",
-    "5. When the fix is confirmed, or when the incident was intentionally generated for smoke, verification, or dogfooding, resolve it with `debugbundle resolve <incident-id>` or MCP `resolve_incident` so the open queue stays actionable.",
+    "5. When the fix is confirmed, or when the incident was intentionally generated for smoke, verification, or dogfooding, resolve it with `debugbundle resolve <incident-id> [incident-id ...]` or MCP `resolve_incident` / `resolve_incidents` so the open queue stays actionable.",
     "",
     "## Incident Hygiene",
     "",
@@ -15750,6 +15882,15 @@ function buildSkill() {
     "- Reopen or leave open if the failure is still present, the validation is incomplete, or the incident represents a live unresolved problem.",
     "- If a resolved incident regresses, let the platform move it back to `regressed` through normal incident lifecycle behavior.",
     "",
+    "## Noise Management",
+    "",
+    "When incident evidence shows repeated low-value operational noise rather than a product bug, evaluate whether a scoped capture rule or capture-policy path rule should handle future matches.",
+    "",
+    "- Run `debugbundle capture-rule suggest <incident-id> --json` before creating a manual rule. Apply deterministic suggestions with `debugbundle capture-rule create-from-suggestion <incident-id> --suggestion-id <id>` after confirming the scope is safe.",
+    "- Prefer project capture rules for operational noise because they are centralized, auditable, and enforced by ingestion and processing. Use SDK `beforeSend` only for app-owned local policy such as final redaction or events that must never leave the runtime.",
+    "- Scope frontend noise by structured evidence such as service, environment, `browser_event_kind`, `browser_event_opaque`, `client_kind`, `bot_family`, and message fields. Do not broadly demote generic `Unhandled promise rejection` incidents without bot-scoped or otherwise narrow evidence.",
+    "- For expected or intentionally promoted 4xx responses on known routes, use capture-policy client-error path rules instead of promoting all client errors: `debugbundle capture-policy set --client-error-path-rule <status=/path/*@GET>`.",
+    "",
     "## Profile Validation",
     "",
     "Use this task after setup or whenever architecture changes make the static profile stale.",
@@ -15812,10 +15953,21 @@ function buildCliReference() {
     "- `debugbundle explain <incident-id> [--source <local|cloud>] [--json]`",
     "- `debugbundle bundle <incident-id> [--source <local|cloud>] [--json]`",
     "- `debugbundle reproduce <incident-id> [--source <local|cloud>] [--json]`",
-    "- `debugbundle resolve <incident-id> [--source <local|cloud>] [--json]`",
-    "- `debugbundle reopen <incident-id> [--source <local|cloud>] [--json]`",
+    "- `debugbundle resolve <incident-id> [incident-id ...] [--source <local|cloud>] [--json]`",
+    "- `debugbundle reopen <incident-id> [incident-id ...] [--source <local|cloud>] [--json]`",
     "- `debugbundle analyze --type improvement --local`",
     "",
+    "## Noise Management",
+    "",
+    "- `debugbundle capture-rule suggest <incident-id> [--auth-file <path>] [--json]`",
+    "- `debugbundle capture-rule create-from-suggestion <incident-id> --suggestion-id <id> [--name <name>] [--expires-at <ISO8601>] [--auth-file <path>] [--json]`",
+    "- `debugbundle capture-rule list --project-id <id> [--auth-file <path>] [--json]`",
+    "- `debugbundle capture-rule create --project-id <id> --name <name> --action <demote|sample|drop> --matcher-json <json> [--auth-file <path>] [--json]`",
+    "- `debugbundle capture-policy get [--project <id>] [--json]`",
+    "- `debugbundle capture-policy set [--project <id>] --client-error-path-rule <404=/path/*@GET,POST> [--json]`",
+    "",
+    "Use capture-rule suggestions for repeated operational noise after inspecting an incident bundle. Use capture-policy client-error path rules for route-scoped 4xx incidents instead of promoting all client errors.",
+    "",
     "## Operational Paths",
     "",
     "- `.debugbundle/profile.json` \u2014 committed project map and agent validation state",
@@ -15846,7 +15998,7 @@ function buildCliReference() {
     "```bash",
     "debugbundle incidents --status open --json \\",
     `  | jq -r '.incidents[] | select(.title | test("smoke test|dogfood|verification|synthetic"; "i")) | .incident_id' \\`,
-    "  | xargs -n1 debugbundle resolve",
+    "  | xargs debugbundle resolve",
     "```",
     ""
   ].join("\n");
@@ -15865,19 +16017,28 @@ function buildMcpReference() {
     "- `get_incident_context` \u2014 fetch deterministic explanation context for triage.",
     "- `get_bundle` \u2014 fetch the full debug bundle before proposing a fix.",
     "- `get_reproduction` \u2014 fetch reproduction guidance before editing code.",
-    "- `resolve_incident` / `reopen_incident` \u2014 update lifecycle state after validation.",
+    "- `resolve_incident` / `resolve_incidents` / `reopen_incident` / `reopen_incidents` \u2014 update lifecycle state after validation.",
     "- `analyze` \u2014 run local agent-oriented analysis from local bundles and skill schemas.",
     "",
     "- Prefer bundle retrieval tools before reading raw repository files.",
     "- Use MCP bundle access when the current issue originated in production.",
-    "- Resolve fixed or intentionally generated incidents with `resolve_incident` so open incidents stay actionable.",
+    "- Resolve fixed or intentionally generated incidents with `resolve_incident` or `resolve_incidents` so open incidents stay actionable.",
     "- Fall back to local CLI processing when the project is local-only.",
     "",
+    "## Noise and Capture Policy Tools",
+    "",
+    "- `suggest_capture_rules_from_incident` \u2014 generate deterministic capture-rule suggestions from an incident bundle.",
+    "- `create_capture_rule_from_incident_suggestion` \u2014 apply a confirmed suggestion.",
+    "- `list_capture_rules`, `create_capture_rule`, `update_capture_rule`, `delete_capture_rule` \u2014 manage project capture rules.",
+    "- `get_capture_policy`, `update_capture_policy` \u2014 review or update capture policy, including path-scoped client-error incident rules.",
+    "",
+    "Use these tools for repeated low-value operational noise only after inspecting incident evidence. Keep frontend suppression scoped by structured browser and client signals, and use path-scoped capture policy for known 4xx routes.",
+    "",
     "## Smoke-Test Cleanup Recipe",
     "",
     '1. Call `list_incidents` with `status: "open"`.',
     "2. Filter incidents whose titles show they were intentionally generated for smoke, dogfood, verification, or synthetic checks.",
-    "3. Call `resolve_incident` for each verified synthetic incident.",
+    "3. Call `resolve_incidents` for verified synthetic incidents, or `resolve_incident` for a single incident.",
     "4. Call `list_incidents` again and confirm the open queue only contains actionable failures.",
     ""
   ].join("\n");
@@ -15997,6 +16158,16 @@ function buildSkillEvals() {
             "Leave unresolved incidents open when the failure is still live or unverified."
           ]
         },
+        {
+          name: "noise_management_guidance",
+          prompt: "The same low-value frontend incident keeps reopening. Confirm the skill tells the agent how to evaluate operational noise without hiding real bugs.",
+          expected_behavior: [
+            "Inspect incident evidence before creating a rule.",
+            "Use capture-rule suggestions for repeated operational noise.",
+            "Keep generic frontend suppression narrow with structured browser or bot signals.",
+            "Use capture-policy path rules for known route-scoped 4xx incidents."
+          ]
+        },
         {
           name: "artifact_path_discovery",
           prompt: "The user reports an unknown local runtime error. Confirm the skill tells the agent which DebugBundle paths and commands to inspect first.",
@@ -17011,6 +17182,33 @@ function buildRedactionRecord(bundleBody) {
     notes: readString(redaction["notes"])
   };
 }
+function buildBrowserSignalRecord(bundleBody) {
+  const bundle = isRecord2(bundleBody) ? bundleBody : {};
+  const context = isRecord2(bundle["context"]) ? bundle["context"] : {};
+  const frontend = isRecord2(context["frontend"]) ? context["frontend"] : {};
+  const exceptions = Array.isArray(frontend["exceptions"]) ? frontend["exceptions"] : [];
+  let exception;
+  for (let index = exceptions.length - 1; index >= 0; index -= 1) {
+    const candidate = exceptions[index];
+    if (isRecord2(candidate) && isRecord2(candidate["browser_event"])) {
+      exception = candidate;
+      break;
+    }
+  }
+  const browserEvent = isRecord2(exception) && isRecord2(exception["browser_event"]) ? exception["browser_event"] : null;
+  const device = isRecord2(context["device"]) ? context["device"] : {};
+  const client = classifyCaptureRuleClientFromUserAgent(readString(device["user_agent"]) ?? void 0);
+  if (browserEvent === null && client.client_kind === "unknown") {
+    return null;
+  }
+  return {
+    browser_event_kind: readString(browserEvent?.["kind"]),
+    browser_event_opaque: readBoolean(browserEvent?.["opaque"]),
+    browser_event_message: readString(browserEvent?.["message"]),
+    client_kind: client.client_kind,
+    bot_family: client.bot_family ?? null
+  };
+}
 function buildVisibilityRecord(input2) {
   const routeTarget = input2.primarySignal.route_template ?? input2.primarySignal.request_path;
   const matchedFields = input2.incident.matched_fields.length === 0 ? "none" : input2.incident.matched_fields.join(", ");
@@ -17048,6 +17246,14 @@ function buildSuggestedNextChecks(input2) {
   if (input2.deploy.regression_window === true || input2.incident.status === "regressed") {
     suggestions.push("Compare this incident against the most recent deploy and recent regressions.");
   }
+  if (input2.browserSignal?.browser_event_opaque === true) {
+    suggestions.push("Treat the browser event as opaque; inspect CSP, cross-origin scripts, resource loading, and framework error boundaries before changing application code.");
+  }
+  if (input2.browserSignal?.client_kind === "bot") {
+    suggestions.push(
+      `Review whether ${input2.browserSignal.bot_family ?? "bot"} traffic is operational noise before applying a bot-scoped capture rule.`
+    );
+  }
   if (input2.reproduction.status === "pending") {
     suggestions.push("Recheck reproduction guidance after the reproduction artifact is ready.");
   }
@@ -17068,6 +17274,7 @@ function buildIncidentContextRecord(input2) {
     primarySignal
   });
   const redaction = buildRedactionRecord(bundleBody);
+  const browserSignal = buildBrowserSignalRecord(bundleBody);
   return {
     incident: input2.incident,
     incident_reason: incidentReason,
@@ -17083,13 +17290,15 @@ function buildIncidentContextRecord(input2) {
     },
     visibility,
     redaction,
+    browser_signal: browserSignal,
     suggested_next_checks: buildSuggestedNextChecks({
       incident: input2.incident,
       bundle: input2.bundle,
       reproduction: input2.reproduction,
       logs,
       primarySignal,
-      deploy
+      deploy,
+      browserSignal
     })
   };
 }
@@ -17631,7 +17840,7 @@ function getRequestResponseStatus(payload) {
   const status = payload?.["response_status"];
   return typeof status === "number" && Number.isFinite(status) ? status : null;
 }
-function classifyEvent(eventType, logLevel, probeActivationId, payload, capturePreset = "minimal", immediateClientErrorStatuses = []) {
+function classifyEvent(eventType, logLevel, probeActivationId, payload, capturePreset = "minimal", immediateClientErrorStatuses = [], immediateClientErrorPathRules = []) {
   switch (eventType) {
     case "backend_exception":
     case "frontend_exception":
@@ -17643,7 +17852,14 @@ function classifyEvent(eventType, logLevel, probeActivationId, payload, captureP
       return "context_signal";
     case "request_event": {
       const responseStatus = getRequestResponseStatus(payload);
-      return classifyRequestStatus({ responseStatus, capturePreset, immediateClientErrorStatuses });
+      return classifyRequestStatus({
+        responseStatus,
+        requestPath: payload?.["path"],
+        httpMethod: payload?.["method"],
+        capturePreset,
+        immediateClientErrorStatuses,
+        immediateClientErrorPathRules
+      });
     }
     case "frontend_breadcrumb":
     case "deploy_metadata":
@@ -17981,6 +18197,7 @@ var STORAGE_BOOTSTRAP_STATEMENTS = [
       capture_breadcrumbs text,
       capture_probe_events text,
       immediate_client_error_statuses jsonb,
+      immediate_client_error_path_rules jsonb,
       updated_at timestamptz NOT NULL DEFAULT now()
     )
   `,
@@ -19336,6 +19553,13 @@ var STORAGE_SCHEMA_MIGRATIONS = [
         ON plan_cleanup_tasks (completed_at, next_attempt_at, created_at)
       `
     ]
+  }),
+  defineStorageSchemaMigration({
+    id: "202606080001_add_capture_policy_client_error_path_rules",
+    description: "Add path-scoped client error incident promotion rules to capture policies.",
+    statements: [
+      "ALTER TABLE capture_policies ADD COLUMN IF NOT EXISTS immediate_client_error_path_rules jsonb"
+    ]
   })
 ];
 
@@ -29036,7 +29260,7 @@ var CLI_USAGE_LINES = [
   "  debugbundle weekly-report update <channel-id> [--day-of-week <day>] [--hour-of-day <0-23>] [--timezone <iana>] [--config-json <json>] [--is-enabled <true|false>] [--auth-file <path>] [--json]",
   "  debugbundle weekly-report delete <channel-id> [--auth-file <path>] [--json]",
   "  debugbundle capture-policy get --project <id> [--auth-file <path>] [--json]",
-  "  debugbundle capture-policy set --project <id> [--preset <minimal|balanced|investigative>] [--override <key=value>] [--client-error-incidents <preset-default|none|recommended|custom>] [--client-error-statuses <400,401,...>] [--auth-file <path>] [--json]",
+  "  debugbundle capture-policy set --project <id> [--preset <minimal|balanced|investigative>] [--override <key=value>] [--client-error-incidents <preset-default|none|recommended|custom>] [--client-error-statuses <400,401,...>] [--client-error-path-rule <404=/path/*@GET,POST>] [--client-error-path-rules-json <json|null>] [--auth-file <path>] [--json]",
   "  debugbundle capture-rule list --project-id <id> [--auth-file <path>] [--json]",
   "  debugbundle capture-rule suggest <incident-id> [--auth-file <path>] [--json]",
   "  debugbundle capture-rule create-from-suggestion <incident-id> --suggestion-id <id> [--name <name>] [--description <text>] [--enabled <true|false>] [--expires-at <ISO8601>] [--auth-file <path>] [--json]",
@@ -32016,6 +32240,18 @@ function statusesEqual(left, right) {
 function formatStatusList(statuses) {
   return statuses.length === 0 ? "none" : statuses.join(", ");
 }
+function formatClientErrorPathRules(response) {
+  const rawOverride = response.overrides.immediate_client_error_path_rules ?? null;
+  const rules = rawOverride ?? response.policy.immediate_client_error_path_rules ?? [];
+  if (rules.length === 0) {
+    return rawOverride === null ? "preset default (none)" : "none (explicit)";
+  }
+  const formatted = rules.map((rule) => {
+    const methods = rule.methods.length === 0 ? "" : `@${rule.methods.join(",")}`;
+    return `${rule.status_code}=${rule.path_pattern}${methods}`;
+  });
+  return `${rawOverride === null ? "preset default" : "custom"} (${formatted.join("; ")})`;
+}
 function formatClientErrorIncidents(response) {
   const rawOverride = response.overrides.immediate_client_error_statuses;
   if (rawOverride === null) {
@@ -32037,7 +32273,8 @@ function formatPolicy(response) {
     `capture_request_events: ${policy.capture_request_events}`,
     `capture_breadcrumbs: ${policy.capture_breadcrumbs}`,
     `capture_probe_events: ${policy.capture_probe_events}`,
-    `client_error_incidents: ${formatClientErrorIncidents(response)}`
+    `client_error_incidents: ${formatClientErrorIncidents(response)}`,
+    `client_error_path_rules: ${formatClientErrorPathRules(response)}`
   ].join("\n");
 }
 async function getCapturePolicyCommand(input2, api) {
@@ -32274,18 +32511,44 @@ function mapErrorToExitCode12(error) {
   }
   return 1;
 }
-function formatMatcher(rule) {
+function formatMatcherFromValue(matcher) {
   const parts = [];
-  const matcher = rule.matcher;
   if (matcher.event_types !== void 0) {
     parts.push(`event_types=${matcher.event_types.join(",")}`);
   }
   if (matcher.browser_event_kind !== void 0) {
     parts.push(`browser_event_kind=${matcher.browser_event_kind}`);
   }
+  if (matcher.browser_event_opaque !== void 0) {
+    parts.push(`browser_event_opaque=${String(matcher.browser_event_opaque)}`);
+  }
+  if (matcher.client_kind !== void 0) {
+    parts.push(`client_kind=${matcher.client_kind}`);
+  }
+  if (matcher.bot_family !== void 0) {
+    parts.push(`bot_family=${matcher.bot_family}`);
+  }
+  if (matcher.services !== void 0) {
+    parts.push(`services=${matcher.services.join(",")}`);
+  }
+  if (matcher.environments !== void 0) {
+    parts.push(`environments=${matcher.environments.join(",")}`);
+  }
+  if (matcher.message_equals !== void 0) {
+    parts.push(`message_equals=${JSON.stringify(matcher.message_equals)}`);
+  }
+  if (matcher.message_contains !== void 0) {
+    parts.push(`message_contains=${JSON.stringify(matcher.message_contains)}`);
+  }
+  if (matcher.error_name !== void 0) {
+    parts.push(`error_name=${matcher.error_name}`);
+  }
   if (matcher.resource_url?.host !== void 0) {
     parts.push(`resource_host=${matcher.resource_url.host}`);
   }
+  if (matcher.resource_url?.path_equals !== void 0) {
+    parts.push(`resource_path=${matcher.resource_url.path_equals}`);
+  }
   if (matcher.request_url?.path_equals !== void 0) {
     parts.push(`request_path=${matcher.request_url.path_equals}`);
   }
@@ -32297,6 +32560,9 @@ function formatMatcher(rule) {
   }
   return parts.length > 0 ? parts.join(" ") : "matcher=custom";
 }
+function formatMatcher(rule) {
+  return formatMatcherFromValue(rule.matcher);
+}
 function formatRule(rule) {
   const action = rule.action === "sample" ? `${rule.action}:${rule.sample_rate ?? "?"}:${rule.sample_event_class ?? "?"}` : rule.action;
   return [
@@ -32317,7 +32583,10 @@ function formatSuggestionResponse(response) {
   return response.suggestions.map(
     (suggestion) => [
       `${suggestion.suggestion_id} ${suggestion.recommended_action} ${suggestion.confidence} ${suggestion.label}`,
-      suggestion.reason
+      suggestion.reason,
+      `matcher: ${formatMatcherFromValue(suggestion.rule.matcher)}`,
+      `requires_confirmation: ${String(suggestion.requires_confirmation)}`,
+      `apply: debugbundle capture-rule create-from-suggestion <incident-id> --suggestion-id ${suggestion.suggestion_id}`
     ].join("\n")
   ).join("\n\n");
 }
@@ -32810,6 +33079,31 @@ async function handleCapturePolicyCommand(parsedArgv, dependencies) {
     }
     return normalized;
   }
+  function parseClientErrorPathRuleOption(value) {
+    const separatorIndex = value.indexOf("=");
+    if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
+      throw new CliInputError("Invalid value for --client-error-path-rule.");
+    }
+    const status = Number(value.slice(0, separatorIndex));
+    if (!Number.isInteger(status) || status < 400 || status > 499) {
+      throw new CliInputError("Invalid value for --client-error-path-rule.");
+    }
+    const ruleValue = value.slice(separatorIndex + 1);
+    const methodSeparatorIndex = ruleValue.lastIndexOf("@");
+    const pathPattern = methodSeparatorIndex === -1 ? ruleValue : ruleValue.slice(0, methodSeparatorIndex);
+    const methods = methodSeparatorIndex === -1 ? [] : ruleValue.slice(methodSeparatorIndex + 1).split(",").map((method) => method.trim().toUpperCase()).filter((method) => method.length > 0);
+    const parsed = ImmediateClientErrorPathRulesSchema.safeParse([
+      {
+        status_code: status,
+        path_pattern: pathPattern,
+        methods
+      }
+    ]);
+    if (!parsed.success || parsed.data[0] === void 0) {
+      throw new CliInputError("Invalid value for --client-error-path-rule.");
+    }
+    return parsed.data[0];
+  }
   const action = requirePositional(parsedArgv, 1, "action");
   if (action === "get") {
     expectNoUnknownOptions(parsedArgv, ["auth-file", "json", "project"]);
@@ -32830,7 +33124,9 @@ async function handleCapturePolicyCommand(parsedArgv, dependencies) {
       "preset",
       "override",
       "client-error-incidents",
-      "client-error-statuses"
+      "client-error-statuses",
+      "client-error-path-rule",
+      "client-error-path-rules-json"
     ]);
     ensureNoExtraPositionals(parsedArgv, 2);
     const projectId = readStringOption(parsedArgv, "project");
@@ -32857,9 +33153,14 @@ async function handleCapturePolicyCommand(parsedArgv, dependencies) {
     }
     const clientErrorIncidents = readStringOption(parsedArgv, "client-error-incidents");
     const clientErrorStatuses = readStringOption(parsedArgv, "client-error-statuses");
+    const clientErrorPathRuleOptions = readStringListOption(parsedArgv, "client-error-path-rule") ?? [];
+    const clientErrorPathRulesJson = readJsonOption(parsedArgv, "client-error-path-rules-json");
     if (clientErrorStatuses !== void 0 && clientErrorIncidents !== "custom") {
       throw new CliInputError("Use --client-error-statuses only with --client-error-incidents custom.");
     }
+    if (clientErrorPathRuleOptions.length > 0 && clientErrorPathRulesJson !== void 0) {
+      throw new CliInputError("Use either --client-error-path-rule or --client-error-path-rules-json, not both.");
+    }
     if (clientErrorIncidents !== void 0) {
       switch (clientErrorIncidents) {
         case "preset-default":
@@ -32881,6 +33182,22 @@ async function handleCapturePolicyCommand(parsedArgv, dependencies) {
           throw new CliInputError("Invalid value for --client-error-incidents.");
       }
     }
+    if (clientErrorPathRulesJson !== void 0) {
+      if (clientErrorPathRulesJson === null) {
+        update.immediate_client_error_path_rules = null;
+      } else {
+        const parsed = ImmediateClientErrorPathRulesSchema.safeParse(clientErrorPathRulesJson);
+        if (!parsed.success) {
+          throw new CliInputError("Invalid value for --client-error-path-rules-json.");
+        }
+        update.immediate_client_error_path_rules = parsed.data;
+      }
+    }
+    if (clientErrorPathRuleOptions.length > 0) {
+      update.immediate_client_error_path_rules = ImmediateClientErrorPathRulesSchema.parse(
+        clientErrorPathRuleOptions.map(parseClientErrorPathRuleOption)
+      );
+    }
     if (Object.keys(update).length === 0) {
       throw new CliInputError("At least one capture policy field must be provided.");
     }
@@ -34586,7 +34903,7 @@ async function handleCaptureRuleCommand2(parsedArgv, dependencies) {
 // package.json
 var package_default = {
   name: "@debugbundle/cli",
-  version: "1.1.2",
+  version: "1.3.0",
   private: false,
   description: "Command-line interface for DebugBundle",
   license: "AGPL-3.0-only",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugbundle/cli",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "private": false,
   "description": "Command-line interface for DebugBundle",
   "license": "AGPL-3.0-only",