@misterhuydo/sentinel 1.4.66 → 1.4.67

package/python/sentinel/notify.py

@@ -1,331 +1,376 @@
-"""
-notify.py — Best-effort Slack alerts from any Sentinel module.
-
-Uses the Slack Web API directly (no Bolt / Socket Mode required).
-Calls never raise — failures are logged and silently dropped.
-"""
-
-import logging
-import re
-import time
-
-import requests
-
-logger = logging.getLogger(__name__)
-
-# ── Rate-limit / auth-failure detector ────────────────────────────────────────
-
-_RATE_LIMIT_RE = re.compile(
-    r"rate.?limit|usage.?limit|too many requests|quota.?exceeded"
-    r"|overloaded|credit.?balance|billing|529"
-    r"|not.?authenticated|invalid.?api.?key|authentication.?fail"
-    r"|claude\.ai subscription|pro.?plan|login required",
-    re.IGNORECASE,
-)
-
-
-def is_rate_limited(text: str) -> bool:
-    """Return True if the text contains a rate-limit or auth-failure signal."""
-    return bool(_RATE_LIMIT_RE.search(text))
-
-
-# ── Circuit breaker ────────────────────────────────────────────────────────────
-#
-# Prevents alert storms when Claude is persistently rate-limited.
-# Each `source` string gets its own independent circuit:
-#   CLOSED → normal; alerts pass through immediately
-#   OPEN   → suppressed; one re-alert every CIRCUIT_COOLDOWN_SECONDS
-#
-# On recovery (first non-rate-limited output after OPEN):
-#   → post "resolved" to Slack, close the circuit
-
-CIRCUIT_COOLDOWN_SECONDS = 3600   # 1 h between repeat alerts while open
-
-# source → {opened_at, last_alerted_at, count}
-_circuits: dict[str, dict] = {}
-
-
-def get_circuit_status() -> dict:
-    """
-    Return a snapshot of all open circuits.
-    Used by the `check_auth_status` Boss tool.
-
-    Returns:
-        { source: { state, opened_at, open_for_seconds, alert_count } }
-        Only open circuits are included; an empty dict means everything is healthy.
-    """
-    now = time.time()
-    return {
-        src: {
-            "state": "open",
-            "opened_at": c["opened_at"],
-            "open_for_seconds": int(now - c["opened_at"]),
-            "alert_count": c["count"],
-        }
-        for src, c in _circuits.items()
-    }
-
-
-def _open_or_repeat(bot_token: str, channel: str, source: str, output: str) -> None:
-    """Open circuit on first hit; re-alert after cooldown if still failing."""
-    now = time.time()
-    circuit = _circuits.get(source)
-
-    if circuit is None:
-        # First occurrence — open and alert immediately
-        _circuits[source] = {"opened_at": now, "last_alerted_at": now, "count": 1}
-        logger.error("Circuit opened for %s: %s", source, output[:200])
-        slack_alert(bot_token, channel, rate_limit_message(source, output))
-        return
-
-    circuit["count"] += 1
-    elapsed = now - circuit["last_alerted_at"]
-    if elapsed >= CIRCUIT_COOLDOWN_SECONDS:
-        # Still failing after cooldown — remind admins once per hour
-        circuit["last_alerted_at"] = now
-        open_mins = int((now - circuit["opened_at"]) / 60)
-        msg = (
-            f":warning: *Sentinel — Claude usage/auth problem still active ({source})*\n"
-            f"Still failing after {open_mins} minutes. Total occurrences: {circuit['count']}.\n"
-            f"Last error:\n```{output.strip()[:300]}```\n"
-            f"Run `check_auth_status` in Slack to see the full picture."
-        )
-        logger.error("Circuit still open for %s (count=%d)", source, circuit["count"])
-        slack_alert(bot_token, channel, msg)
-    # else: within cooldown window — suppress
-
-
-def _close_if_open(bot_token: str, channel: str, source: str) -> None:
-    """If circuit was open, close it and post a recovery alert."""
-    circuit = _circuits.pop(source, None)
-    if circuit is None:
-        return
-    duration_mins = int((time.time() - circuit["opened_at"]) / 60)
-    msg = (
-        f":white_check_mark: *Sentinel — Claude auth restored ({source})*\n"
-        f"Fixed after {duration_mins} min. Total failures during outage: {circuit['count']}."
-    )
-    logger.info("Circuit closed for %s after %d min, %d failures", source, duration_mins, circuit["count"])
-    slack_alert(bot_token, channel, msg)
-
-
-def rate_limit_message(source: str, raw: str) -> str:
-    """Produce a human-readable Slack alert for a rate-limit / auth event (first occurrence)."""
-    snippet = raw.strip()[:300].replace("\n", " ")
-    return (
-        f":warning: *Sentinel — Claude usage/auth problem ({source})*\n"
-        f"Claude returned an error that requires admin attention:\n"
-        f"```{snippet}```\n"
-        f"*What to check:*\n"
-        f"• API key: verify `ANTHROPIC_API_KEY` in `sentinel.properties` is valid and has credit\n"
-        f"• Claude Pro: run `claude login` on the server to refresh the OAuth session\n"
-        f"• Both: Sentinel tries both methods — at least one must be working\n"
-        f"Repeat alerts will be suppressed for 1 hour. "
-        f"Run `check_auth_status` in Slack to see current state."
-    )
-
-
-# ── Alert dispatcher ──────────────────────────────────────────────────────────
-
-def slack_alert(bot_token: str, channel: str, text: str) -> None:
-    """
-    Post a plain-text alert to a Slack channel.
-    Best-effort: logs on failure, never raises.
-    """
-    if not bot_token or not channel:
-        logger.debug("slack_alert: no token/channel configured — logging only: %s", text[:120])
-        return
-    try:
-        resp = requests.post(
-            "https://slack.com/api/chat.postMessage",
-            headers={
-                "Authorization": f"Bearer {bot_token}",
-                "Content-Type": "application/json",
-            },
-            json={"channel": channel, "text": text},
-            timeout=10,
-        )
-        data = resp.json()
-        if not data.get("ok"):
-            logger.warning("slack_alert: Slack API error: %s", data.get("error"))
-    except Exception as exc:
-        logger.warning("slack_alert: failed to post: %s", exc)
-
-
-
-def slack_dm(bot_token: str, user_id: str, text: str) -> None:
-    """
-    Send a direct message to a specific Slack user.
-    Opens a DM channel via conversations.open, then posts.
-    Best-effort: logs on failure, never raises.
-    """
-    if not bot_token or not user_id:
-        logger.debug("slack_dm: no token/user_id — skipping DM")
-        return
-    try:
-        resp = requests.post(
-            "https://slack.com/api/conversations.open",
-            headers={"Authorization": f"Bearer {bot_token}", "Content-Type": "application/json"},
-            json={"users": user_id},
-            timeout=10,
-        )
-        data = resp.json()
-        if not data.get("ok"):
-            logger.warning("slack_dm: conversations.open failed: %s", data.get("error"))
-            return
-        dm_channel = data["channel"]["id"]
-        slack_alert(bot_token, dm_channel, text)
-    except Exception as exc:
-        logger.warning("slack_dm: failed to DM %s: %s", user_id, exc)
-
-
-def notify_fix_blocked(
-    cfg,
-    source: str,
-    message: str,
-    reason: str,
-    repo_name: str = "",
-    submitter_user_id: str = "",
-) -> None:
-    """
-    Notify that a fix needs human intervention.
-
-    - If submitter_user_id is known: DM that person directly.
-    - Otherwise: @channel in the configured Slack channel.
-    - Always: email admins via reporter.send_failure_notification.
-    """
-    short_reason = (reason or "Claude could not determine a safe fix.")[:600]
-    repo_line = f"\n*Repo:* {repo_name}" if repo_name else ""
-
-    slack_text = (
-        f":hand: *Fix blocked — human intervention needed*\n"
-        f"*Source:* {source}\n"
-        f"*Issue:* {message[:200]}{repo_line}\n"
-        f"*Reason:*\n{short_reason}"
-    )
-
-    if submitter_user_id:
-        if getattr(cfg, "slack_dm_submitter", True):
-            slack_dm(cfg.slack_bot_token, submitter_user_id, slack_text)
-        slack_alert(cfg.slack_bot_token, cfg.slack_channel, f"<@{submitter_user_id}> {slack_text}")
-    else:
-        # No known submitter — broadcast to the whole channel
-        slack_alert(
-            cfg.slack_bot_token,
-            cfg.slack_channel,
-            f"<!channel> {slack_text}",
-        )
-
-    # Always email admins
-    try:
-        from .reporter import send_failure_notification
-        send_failure_notification(cfg, {
-            "source":    source,
-            "message":   message,
-            "repo_name": repo_name,
-            "reason":    f"Needs human intervention: {short_reason[:200]}",
-            "body":      reason,
-        })
-    except Exception as exc:
-        logger.warning("notify_fix_blocked: email notification failed: %s", exc)
-
-
-def notify_tool_installing(cfg, tool: str, repo_name: str, source: str) -> None:
-    """
-    Post a brief Slack notice that Sentinel is auto-installing a whitelisted build tool.
-    Called before the install begins so admins know what's happening.
-    """
-    repo_line = f" for *{repo_name}*" if repo_name else ""
-    slack_alert(
-        cfg.slack_bot_token,
-        cfg.slack_channel,
-        f":gear: *Auto-installing `{tool}`{repo_line}*\n"
-        f"`{tool}` is required to run tests but not found on this server. "
-        f"It's a known safe build tool — installing automatically. "
-        f"Will retry the fix once done.",
-    )
-
-
-def notify_missing_tool(
-    cfg,
-    tool: str,
-    repo_name: str,
-    source: str,
-    submitter_user_id: str = "",
-) -> None:
-    """
-    Notify admins that a build tool is missing on this server.
-    Prompts them to ask Boss to install it.
-    """
-    repo_line = f" for *{repo_name}*" if repo_name else ""
-    slack_text = (
-        f":wrench: *Build tool missing{repo_line}*\n"
-        f"*Source:* {source}\n"
-        f"The fix was generated but tests couldn't run because `{tool}` is not installed on this server.\n\n"
-        f"Ask me to install it:\n"
-        f"> @Sentinel install {tool}\n\n"
-        f"Once installed, re-raise the issue to apply the fix."
-    )
-    if submitter_user_id:
-        if getattr(cfg, "slack_dm_submitter", True):
-            slack_dm(cfg.slack_bot_token, submitter_user_id, slack_text)
-        slack_alert(cfg.slack_bot_token, cfg.slack_channel, f"<@{submitter_user_id}> {slack_text}")
-    else:
-        slack_alert(cfg.slack_bot_token, cfg.slack_channel, f"<!channel> {slack_text}")
-
-
-def notify_fix_applied(
-    cfg,
-    source: str,
-    message: str,
-    repo_name: str,
-    branch: str,
-    pr_url: str,
-    submitter_user_id: str = "",
-) -> None:
-    """
-    DM the submitter (if known) that their issue was fixed.
-    Falls back to posting in the Slack channel if no submitter.
-    """
-    repo_line = f" in *{repo_name}*" if repo_name else ""
-    if pr_url:
-        action_line = f":arrow_right: <{pr_url}|Review PR>"
-    elif branch:
-        action_line = f":arrow_right: Pushed to `{branch}`"
-    else:
-        action_line = ""
-
-    slack_text = (
-        f":white_check_mark: *Fix applied{repo_line}*\n"
-        f"*Issue:* {message[:200]}\n"
-        + (f"{action_line}\n" if action_line else "")
-    ).rstrip()
-
-    if submitter_user_id:
-        if getattr(cfg, "slack_dm_submitter", True):
-            slack_dm(cfg.slack_bot_token, submitter_user_id, slack_text)
-        channel_text = f"<@{submitter_user_id}> {slack_text}"
-        slack_alert(cfg.slack_bot_token, cfg.slack_channel, channel_text)
-    else:
-        slack_alert(cfg.slack_bot_token, cfg.slack_channel, slack_text)
-
-
-def alert_if_rate_limited(
-    bot_token: str,
-    channel: str,
-    source: str,
-    output: str,
-) -> bool:
-    """
-    Check output for rate-limit / auth signals and manage the circuit breaker.
-
-    - Rate limited  → open/keep-open circuit, alert (with cooldown suppression)
-    - Not limited   → close circuit if it was open (recovery alert), return False
-
-    Returns True if a rate-limit signal was found.
-    """
-    if not is_rate_limited(output):
-        _close_if_open(bot_token, channel, source)
-        return False
-    _open_or_repeat(bot_token, channel, source, output)
-    return True
+"""
+notify.py — Best-effort Slack alerts from any Sentinel module.
+
+Uses the Slack Web API directly (no Bolt / Socket Mode required).
+Calls never raise — failures are logged and silently dropped.
+"""
+
+import logging
+import re
+import time
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# ── Rate-limit / auth-failure detector ────────────────────────────────────────
+
+_RATE_LIMIT_RE = re.compile(
+    r"rate.?limit|usage.?limit|too many requests|quota.?exceeded"
+    r"|overloaded|credit.?balance|billing|529"
+    r"|not.?authenticated|invalid.?api.?key|authentication.?fail"
+    r"|claude\.ai subscription|pro.?plan|login required",
+    re.IGNORECASE,
+)
+
+
+def is_rate_limited(text: str) -> bool:
+    """Return True if the text contains a rate-limit or auth-failure signal."""
+    return bool(_RATE_LIMIT_RE.search(text))
+
+
+# ── Circuit breaker ────────────────────────────────────────────────────────────
+#
+# Prevents alert storms when Claude is persistently rate-limited.
+# Each `source` string gets its own independent circuit:
+#   CLOSED → normal; alerts pass through immediately
+#   OPEN   → suppressed; one re-alert every CIRCUIT_COOLDOWN_SECONDS
+#
+# On recovery (first non-rate-limited output after OPEN):
+#   → post "resolved" to Slack, close the circuit
+
+CIRCUIT_COOLDOWN_SECONDS = 3600   # 1 h between repeat alerts while open
+
+# source → {opened_at, last_alerted_at, count}
+_circuits: dict[str, dict] = {}
+
+
+def get_circuit_status() -> dict:
+    """
+    Return a snapshot of all open circuits.
+    Used by the `check_auth_status` Boss tool.
+
+    Returns:
+        { source: { state, opened_at, open_for_seconds, alert_count } }
+        Only open circuits are included; an empty dict means everything is healthy.
+    """
+    now = time.time()
+    return {
+        src: {
+            "state": "open",
+            "opened_at": c["opened_at"],
+            "open_for_seconds": int(now - c["opened_at"]),
+            "alert_count": c["count"],
+        }
+        for src, c in _circuits.items()
+    }
+
+
+def _open_or_repeat(bot_token: str, channel: str, source: str, output: str) -> None:
+    """Open circuit on first hit; re-alert after cooldown if still failing."""
+    now = time.time()
+    circuit = _circuits.get(source)
+
+    if circuit is None:
+        # First occurrence — open and alert immediately
+        _circuits[source] = {"opened_at": now, "last_alerted_at": now, "count": 1}
+        logger.error("Circuit opened for %s: %s", source, output[:200])
+        slack_alert(bot_token, channel, rate_limit_message(source, output))
+        return
+
+    circuit["count"] += 1
+    elapsed = now - circuit["last_alerted_at"]
+    if elapsed >= CIRCUIT_COOLDOWN_SECONDS:
+        # Still failing after cooldown — remind admins once per hour
+        circuit["last_alerted_at"] = now
+        open_mins = int((now - circuit["opened_at"]) / 60)
+        msg = (
+            f":warning: *Sentinel — Claude usage/auth problem still active ({source})*\n"
+            f"Still failing after {open_mins} minutes. Total occurrences: {circuit['count']}.\n"
+            f"Last error:\n```{output.strip()[:300]}```\n"
+            f"Run `check_auth_status` in Slack to see the full picture."
+        )
+        logger.error("Circuit still open for %s (count=%d)", source, circuit["count"])
+        slack_alert(bot_token, channel, msg)
+    # else: within cooldown window — suppress
+
+
+def _close_if_open(bot_token: str, channel: str, source: str) -> None:
+    """If circuit was open, close it and post a recovery alert."""
+    circuit = _circuits.pop(source, None)
+    if circuit is None:
+        return
+    duration_mins = int((time.time() - circuit["opened_at"]) / 60)
+    msg = (
+        f":white_check_mark: *Sentinel — Claude auth restored ({source})*\n"
+        f"Fixed after {duration_mins} min. Total failures during outage: {circuit['count']}."
+    )
+    logger.info("Circuit closed for %s after %d min, %d failures", source, duration_mins, circuit["count"])
+    slack_alert(bot_token, channel, msg)
+
+
+def rate_limit_message(source: str, raw: str) -> str:
+    """Produce a human-readable Slack alert for a rate-limit / auth event (first occurrence)."""
+    snippet = raw.strip()[:300].replace("\n", " ")
+    return (
+        f":warning: *Sentinel — Claude usage/auth problem ({source})*\n"
+        f"Claude returned an error that requires admin attention:\n"
+        f"```{snippet}```\n"
+        f"*What to check:*\n"
+        f"• API key: verify `ANTHROPIC_API_KEY` in `sentinel.properties` is valid and has credit\n"
+        f"• Claude Pro: run `claude login` on the server to refresh the OAuth session\n"
+        f"• Both: Sentinel tries both methods — at least one must be working\n"
+        f"Repeat alerts will be suppressed for 1 hour. "
+        f"Run `check_auth_status` in Slack to see current state."
+    )
+
+
+# ── Alert dispatcher ──────────────────────────────────────────────────────────
+
+def slack_alert(bot_token: str, channel: str, text: str) -> None:
+    """
+    Post a plain-text alert to a Slack channel.
+    Best-effort: logs on failure, never raises.
+    """
+    if not bot_token or not channel:
+        logger.debug("slack_alert: no token/channel configured — logging only: %s", text[:120])
+        return
+    try:
+        resp = requests.post(
+            "https://slack.com/api/chat.postMessage",
+            headers={
+                "Authorization": f"Bearer {bot_token}",
+                "Content-Type": "application/json",
+            },
+            json={"channel": channel, "text": text},
+            timeout=10,
+        )
+        data = resp.json()
+        if not data.get("ok"):
+            logger.warning("slack_alert: Slack API error: %s", data.get("error"))
+    except Exception as exc:
+        logger.warning("slack_alert: failed to post: %s", exc)
+
+
+
+def slack_dm(bot_token: str, user_id: str, text: str) -> None:
+    """
+    Send a direct message to a specific Slack user.
+    Opens a DM channel via conversations.open, then posts.
+    Best-effort: logs on failure, never raises.
+    """
+    if not bot_token or not user_id:
+        logger.debug("slack_dm: no token/user_id — skipping DM")
+        return
+    try:
+        resp = requests.post(
+            "https://slack.com/api/conversations.open",
+            headers={"Authorization": f"Bearer {bot_token}", "Content-Type": "application/json"},
+            json={"users": user_id},
+            timeout=10,
+        )
+        data = resp.json()
+        if not data.get("ok"):
+            logger.warning("slack_dm: conversations.open failed: %s", data.get("error"))
+            return
+        dm_channel = data["channel"]["id"]
+        slack_alert(bot_token, dm_channel, text)
+    except Exception as exc:
+        logger.warning("slack_dm: failed to DM %s: %s", user_id, exc)
+
+
+def notify_fix_blocked(
+    cfg,
+    source: str,
+    message: str,
+    reason: str,
+    repo_name: str = "",
+    submitter_user_id: str = "",
+) -> None:
+    """
+    Notify that a fix needs human intervention.
+
+    - If submitter_user_id is known: DM that person directly.
+    - Otherwise: @channel in the configured Slack channel.
+    - Always: email admins via reporter.send_failure_notification.
+    """
+    short_reason = (reason or "Claude could not determine a safe fix.")[:600]
+    repo_line = f"\n*Repo:* {repo_name}" if repo_name else ""
+
+    slack_text = (
+        f":hand: *Fix blocked — human intervention needed*\n"
+        f"*Source:* {source}\n"
+        f"*Issue:* {message[:200]}{repo_line}\n"
+        f"*Reason:*\n{short_reason}"
+    )
+
+    if submitter_user_id:
+        if getattr(cfg, "slack_dm_submitter", True):
+            slack_dm(cfg.slack_bot_token, submitter_user_id, slack_text)
+        slack_alert(cfg.slack_bot_token, cfg.slack_channel, f"<@{submitter_user_id}> {slack_text}")
+    else:
+        # No known submitter — broadcast to the whole channel
+        slack_alert(
+            cfg.slack_bot_token,
+            cfg.slack_channel,
+            f"<!channel> {slack_text}",
+        )
+
+    # Always email admins
+    try:
+        from .reporter import send_failure_notification
+        send_failure_notification(cfg, {
+            "source":    source,
+            "message":   message,
+            "repo_name": repo_name,
+            "reason":    f"Needs human intervention: {short_reason[:200]}",
+            "body":      reason,
+        })
+    except Exception as exc:
+        logger.warning("notify_fix_blocked: email notification failed: %s", exc)
+
+
+def notify_tool_installing(cfg, tool: str, repo_name: str, source: str) -> None:
+    """
+    Post a brief Slack notice that Sentinel is auto-installing a whitelisted build tool.
+    Called before the install begins so admins know what's happening.
+    """
+    repo_line = f" for *{repo_name}*" if repo_name else ""
+    slack_alert(
+        cfg.slack_bot_token,
+        cfg.slack_channel,
+        f":gear: *Auto-installing `{tool}`{repo_line}*\n"
+        f"`{tool}` is required to run tests but not found on this server. "
+        f"It's a known safe build tool — installing automatically. "
+        f"Will retry the fix once done.",
+    )
+
+
+def notify_missing_tool(
+    cfg,
+    tool: str,
+    repo_name: str,
+    source: str,
+    submitter_user_id: str = "",
+) -> None:
+    """
+    Notify admins that a build tool is missing on this server.
+    Prompts them to ask Boss to install it.
+    """
+    repo_line = f" for *{repo_name}*" if repo_name else ""
+    slack_text = (
+        f":wrench: *Build tool missing{repo_line}*\n"
+        f"*Source:* {source}\n"
+        f"The fix was generated but tests couldn't run because `{tool}` is not installed on this server.\n\n"
+        f"Ask me to install it:\n"
+        f"> @Sentinel install {tool}\n\n"
+        f"Once installed, re-raise the issue to apply the fix."
+    )
+    if submitter_user_id:
+        if getattr(cfg, "slack_dm_submitter", True):
+            slack_dm(cfg.slack_bot_token, submitter_user_id, slack_text)
+        slack_alert(cfg.slack_bot_token, cfg.slack_channel, f"<@{submitter_user_id}> {slack_text}")
+    else:
+        slack_alert(cfg.slack_bot_token, cfg.slack_channel, f"<!channel> {slack_text}")
+
+
+def notify_fix_applied(
+    cfg,
+    source: str,
+    message: str,
+    repo_name: str,
+    branch: str,
+    pr_url: str,
+    submitter_user_id: str = "",
+) -> None:
+    """
+    DM the submitter (if known) that their issue was fixed.
+    Falls back to posting in the Slack channel if no submitter.
+    """
+    repo_line = f" in *{repo_name}*" if repo_name else ""
+    if pr_url:
+        action_line = f":arrow_right: <{pr_url}|Review PR>"
+    elif branch:
+        action_line = f":arrow_right: Pushed to `{branch}`"
+    else:
+        action_line = ""
+
+    slack_text = (
+        f":white_check_mark: *Fix applied{repo_line}*\n"
+        f"*Issue:* {message[:200]}\n"
+        + (f"{action_line}\n" if action_line else "")
+    ).rstrip()
+
+    if submitter_user_id:
+        if getattr(cfg, "slack_dm_submitter", True):
+            slack_dm(cfg.slack_bot_token, submitter_user_id, slack_text)
+        channel_text = f"<@{submitter_user_id}> {slack_text}"
+        slack_alert(cfg.slack_bot_token, cfg.slack_channel, channel_text)
+    else:
+        slack_alert(cfg.slack_bot_token, cfg.slack_channel, slack_text)
+
+
+def notify_cascade_started(
+    cfg,
+    artifact_id: str,
+    new_version: str,
+    target_repos: list,
+    user_id: str = "",
+) -> None:
+    """Notify that a dependency cascade is starting."""
+    repo_list = ", ".join(f"`{r}`" for r in target_repos) if target_repos else "none found"
+    text = (
+        f":arrows_counterclockwise: *Dependency cascade started*\n"
+        f"Updating `{artifact_id}` \u2192 `{new_version}` in {len(target_repos)} repo(s): {repo_list}"
+    )
+    if user_id:
+        slack_alert(cfg.slack_bot_token, cfg.slack_channel, f"<@{user_id}> {text}")
+    else:
+        slack_alert(cfg.slack_bot_token, cfg.slack_channel, text)
+
+
+def notify_cascade_result(
+    cfg,
+    artifact_id: str,
+    new_version: str,
+    results: list,
+    user_id: str = "",
+) -> None:
+    """Notify success/failure for each repo in a dependency cascade."""
+    lines = []
+    for r in results:
+        if r.success:
+            action = f"<{r.pr_url}|PR opened>" if r.pr_url else f"pushed to `{r.branch}`"
+            lines.append(f":white_check_mark: *{r.repo_name}* \u2014 {r.old_version} \u2192 {new_version} ({action})")
+        else:
+            lines.append(f":x: *{r.repo_name}* \u2014 failed: {r.error}")
+
+    ok = sum(1 for r in results if r.success)
+    fail = len(results) - ok
+    summary = f":package: *Cascade complete* \u2014 `{artifact_id}` `{new_version}`: {ok} updated, {fail} failed"
+    text = summary + "\n" + "\n".join(lines)
+    if user_id:
+        slack_alert(cfg.slack_bot_token, cfg.slack_channel, f"<@{user_id}> {text}")
+    else:
+        slack_alert(cfg.slack_bot_token, cfg.slack_channel, text)
+
+
+def alert_if_rate_limited(
+    bot_token: str,
+    channel: str,
+    source: str,
+    output: str,
+) -> bool:
+    """
+    Check output for rate-limit / auth signals and manage the circuit breaker.
+
+    - Rate limited  → open/keep-open circuit, alert (with cooldown suppression)
+    - Not limited   → close circuit if it was open (recovery alert), return False
+
+    Returns True if a rate-limit signal was found.
+    """
+    if not is_rate_limited(output):
+        _close_if_open(bot_token, channel, source)
+        return False
+    _open_or_repeat(bot_token, channel, source, output)
+    return True