@matt82198/aesop 0.1.0-beta.4 → 0.1.0-beta.5

package/tools/CLAUDE.md

@@ -4,40 +4,36 @@ Local-only Python (stdlib only, no external deps), bash (POSIX, CRLF-safe). Neve
 
 ## FILES
 
-**Locking & atomicity**:
-- `lock.mjs` — Fail-closed atomic lock acquisition (exponential backoff + stale-lock detection) for PROPOSALS.md and related single-writer operations
-
-**Secret scanning & compliance**:
-- `secret_scan.py` — Pre-push secret/credential detection gate; scans staged, history, or paths by regex + filename patterns
-- `scanner_selftest.py` — Regression harness for secret_scan.py; validates TP/FP vectors and self-scan cleanliness
-- `prepublish_scan.py` — Pre-publish gate running full git history + staged-changes scans; exit 0 only if CLEAR-TO-PUBLISH
-
-**Browser-level verification (CI gates)**:
-- `verify_dash.py` — Browser proof for realtime SSE dashboard; validates console errors, backlog rendering, live SSE updates (use `--allow-skip` in browserless environments)
-- `verify_submit_encoding.py` — Browser proof for /submit UTF-8 inbox bootstrap; validates encoding on Windows and real CSRF flow (use `--allow-skip` in browserless environments)
-
-**CI/merge operations**:
-- `ci_merge_wait.py` — CI-gated merge helper; polls gh pr view until checks conclude (SUCCESS/FAILURE), then merges ONLY if SUCCESS (structurally unreachable otherwise)
-
-**Orchestration infrastructure**:
-- `proposals.mjs` — Proposal lifecycle manager (list/accept/reject); uses fail-closed locking for atomic state updates
-- `power_selftest.py` — Health check harness for /power bootstrap; validates hooks, brain, heartbeats, decisions, and scanner
-- `buildlog.py` — Uniform BUILDLOG.md appender; ensures consistent timestamp + message + git HEAD ref formatting
-- `ensure_state.py` — Scaffold STATE.md and BUILDLOG.md templates in state directory if missing
-- `fleet_ledger.py` — Append-only ledger of agent runs, resource use, and verdicts; supports harvest (scan tasks) and rotate (archive)
-- `heartbeat.py` — Single-instance loop liveness registry; write beats to state/.heartbeats/<name>, check staleness across fleet
-- `stall_check.py` — Automated silent-hang detector; scans agent transcript mtimes to identify stalled agents, feeds watchdog monitoring
-- `inbox_drain.py` — Drain UI inbox submissions; tracks processed dashboard work items (queue while no session running)
-- `orchestrator_status.py` — Atomic writer for state/orchestrator-status.json (set/clear activity+phase); feeds the dashboard status panel
-
-**Repository operations**:
-- `reconstitute.sh` — Clone or fetch repos from config (tab/space-delimited); validates clone targets against fleet-root (physical paths, security)
-- `eod_sweep.py` — End-of-day safety check; scans repos for dirty trees, unpushed commits, untracked files; optional auto-push
-
-**Utilities**:
-- `agent-forensics.sh` — Incident forensics / behavior reconstruction; read-only git plumbing to snapshot or diff behavior-controlling files
-- `launch_tui.py` — Spawn bash TUI script in detached terminal; finds terminal (Git Bash → Windows Terminal), idempotent via pidfile
-- `rotate_logs.py` — Log rotation utility; archives oldest lines when file exceeds size/line thresholds; ensures no data loss
+- `lock.mjs` — Fail-closed atomic lock acquisition (exponential backoff + stale-lock detection)
+- `secret_scan.py` — Pre-push secret/credential detection gate
+- `scanner_selftest.py` — Regression harness for secret_scan.py
+- `prepublish_scan.py` — Pre-publish full history + staged-changes scan gate
+- `metrics_gate.py` — PR gate for hard numeric claims in markdown
+- `self_stats.py` — Git-derived metrics counter + README block generator
+- `verify_dash.py` — Browser proof for realtime SSE dashboard
+- `verify_submit_encoding.py` — Browser proof for /submit UTF-8 inbox bootstrap
+- `ci_merge_wait.py` — CI-gated merge helper (polls gh pr view until SUCCESS)
+- `alert_bridge.py` — Slack/Discord webhook bridge for SECURITY-ALERTS
+- `proposals.mjs` — Proposal lifecycle manager (list/accept/reject)
+- `power_selftest.py` — Health check harness for /power bootstrap
+- `healthcheck.py` — Fleet health aggregator (heartbeat/alert/orchestrator status)
+- `buildlog.py` — Uniform BUILDLOG.md appender
+- `ensure_state.py` — Scaffold STATE.md and BUILDLOG.md templates
+- `fleet_ledger.py` — Append-only cost ledger with harvest/rotate
+- `heartbeat.py` — Single-instance loop liveness registry
+- `stall_check.py` — Automated agent transcript stall detector
+- `inbox_drain.py` — Drain UI inbox submissions
+- `orchestrator_status.py` — Atomic orchestrator status updates
+- `reconstitute.sh` — Clone/fetch repos from config with security validation
+- `eod_sweep.py` — End-of-day safety check (dirty trees, unpushed commits)
+- `agent-forensics.sh` — Incident forensics / behavior reconstruction
+- `launch_tui.py` — Spawn bash TUI script in detached terminal
+- `rotate_logs.py` — Log rotation utility with size/line thresholds
+- `session_usage_summary.py` — Aggregate token usage across session transcripts
+- `transcript_replay.py` — Replay post-commit edits from transcripts to recover work
+- `transcript_timeline.py` — Extract Write/Edit/Read timeline from transcripts
+- `fleet_prompt_extractor.py` — Extract and deduplicate Agent/Task spawn prompts
+- `svg_to_png.mjs` — Rasterize SVG to PNG via @resvg/resvg-js (with lazy import error handling)
 
 ## secret_scan.py — Pre-push secret/credential detection gate
 
@@ -64,121 +60,6 @@ Read-only git plumbing; reconstructs agent behavior snapshot or diffs behavior-c
 
 Exit: 0=success, 1=error (never raw git traces). Requires: git, head, tail, wc, grep.
 
-## launch_tui.py — Spawn bash TUI script in detached terminal
-
-Finds terminal (prefer Git Bash → Windows Terminal wt.exe), spawns script detached, idempotent via pidfile.
-
-- `python launch_tui.py --script <path> [--title <title>] [--pidfile <path>]`
-
-Exit: 0=success, 1=error. Output: exactly one line (`spawned (pid N)` or `already running (pid N)` or ERROR).
-
-## power_selftest.py — Health check harness for /power bootstrap
-
-Validates hooks (settings.json), brain (git status), heartbeats (state/ beat files), decisions/inbox counts, and secret scanner.
-
-- `python power_selftest.py` — run all checks and print summary line + bullets for non-OK items
-
-Configuration via `aesop.config.json` or env vars: `BRAIN_ROOT`, `AESOP_STATE_ROOT`, `SCRIPTS_ROOT`.
-Gracefully degrades when targets don't exist (reports `n/a` instead of crashing).
-
-Exit: 0=OK/DEGRADED, 1=FAIL. Output: `POWER-SELFTEST: OK|DEGRADED|FAIL — <checks>` + optional bullets.
-
-## inbox_drain.py — Drain UI inbox submissions
-
-Tracks processed dashboard submissions (work items queued while no session was running).
-
-- `python inbox_drain.py pending` — list unprocessed inbox items
-- `python inbox_drain.py mark <ISO-ts>` — mark one item processed
-- `python inbox_drain.py mark-all` — mark all pending items processed
-
-Configuration via `aesop.config.json` or env vars: `AESOP_INBOX_PATH`, `AESOP_INBOX_SEEN_PATH`, `AESOP_STATE_ROOT`.
-Gracefully handles missing inbox/seen files (no crash).
-
-Exit: 0 always. Output: `pending` lists items one per line; `mark`/`mark-all` prints summary to stderr.
-
-## heartbeat.py — Single-instance loop liveness registry
-
-Fleet-wide heartbeat tracking for monitoring loop freshness. Write heartbeat "beat" to registry, check all beats for staleness.
-
-- `heartbeat.py beat <name> [status] [--state-dir DIR] [--brain]` — write epoch to state/.heartbeats/<name> (or ~/.claude/.heartbeats with --brain)
-- `heartbeat.py check [--max-age SEC] [--state-dir DIR]` — check all beats, exit 0 if all alive
-
-## stall_check.py — Automated silent-hang detector for agent transcripts
-
-Scans agent transcript files (agent-*.jsonl) by mtime to detect stalled/silent-hanging agents.
-
-- `stall_check.py [--transcripts-root DIR] [--threshold-seconds SEC] [--json] [--exit-nonzero-on-stall]`
-
-Options:
-- `--transcripts-root DIR` — Root directory to scan; defaults to AESOP_TRANSCRIPTS_ROOT env var or ~/.claude/projects
-- `--threshold-seconds SEC` — Max age (seconds) for a "fresh" transcript (default: 600); transcripts older are flagged as stalled
-- `--json` — Output as JSON list of {agent_id, age_seconds, stalled, last_mtime} instead of human table
-- `--exit-nonzero-on-stall` — Exit 1 if any agent is stalled (for CI/monitor integration); default always exits 0
-
-Exit: 0 always (or 1 if --exit-nonzero-on-stall + stalls found). Output: human table or JSON; reports "no transcripts found" gracefully.
-
-## buildlog.py — Uniform BUILDLOG entry appender
-
-Ensures consistent BUILDLOG.md formatting across orchestrated work: timestamp + message + optional git HEAD ref.
-
-- `buildlog.py "<message>" [--state-dir DIR] [--head] [--repo-path PATH]` — append entry to state/BUILDLOG.md
-
-## ensure_state.py — Scaffold checkpointing directories
-
-Creates STATE.md and BUILDLOG.md templates in state directory if missing.
-
-- `ensure_state.py --state-dir DIR` — scaffold templates
-
-## fleet_ledger.py — Outcome audit trail for dispatched agents
-
-Append-only ledger of agent runs, resource use, and verdicts. Supports harvest (scan temp tasks) and rotate (archive old lines).
-
-- `fleet_ledger.py append <ts> <agent_type> <model> <dur_sec> <tokens_in> <tokens_out> [verdict]`
-- `fleet_ledger.py harvest` — scan session tasks and append missing outcomes
-- `fleet_ledger.py rotate` — archive old lines when ledger exceeds ~200 lines
-
-## scanner_selftest.py — Regression harness for secret_scan.py
-
-Validates scanner against TP/FP test vectors. Ensures self-scan is clean (no pragma reliance).
-
-- `python scanner_selftest.py [--temp-dir DIR]` — run full test suite, exit 0 only if all pass
-
-## prepublish_scan.py — Pre-publish gate (history + staged)
-
-Runs full git history and staged-changes scans before public release. Both must pass.
-
-- `prepublish_scan.py [--repo PATH]` — scan full history + staged changes, exit 0 only if CLEAR-TO-PUBLISH
-
-## eod_sweep.py — End-of-day repository safety check
-
-Scans listed repos for: dirty working tree, unpushed commits, untracked files. Optional auto-push on safe repos.
-
-- `eod_sweep.py [--repos PATHS] [--readonly-repos PATHS] [--fix-push]` — check repo health, optionally push
-
-## orchestrator_status.py — Atomic orchestrator status updates (wave-8+)
-
-Manages orchestrator heartbeat and activity tracking for SSE status section and wave-9+ multi-orchestrator coordination.
-
-- `python orchestrator_status.py set --activity "dispatching wave-8" --phase audit [--id main --role orchestrator]` — atomically write status
-- `python orchestrator_status.py clear` — remove status file
-
-Writes `state/orchestrator-status.json` atomically (temp+replace). Forward-compatible with bare-object → list normalization in serve.py. Exit: 0=success, 1=error.
-
-## ci_merge_wait.py — CI-gated merge helper
-
-Polls gh pr view until all status checks conclude (SUCCESS/FAILURE), then merges ONLY if all checks pass. The `gh pr merge` call is STRUCTURALLY UNREACHABLE unless CI status is SUCCESS — this prevents merge-on-CI-failure edge cases (e.g., wave-7 PR #80).
-
-- `python ci_merge_wait.py <PR-number> [--timeout SECONDS] [--poll SECONDS] [--merge-method merge|squash|rebase]`
-
-Exit codes:
-- 0 = PR merged successfully
-- 2 = CI checks failed (do NOT merge, prints which check failed)
-- 3 = Timeout waiting for CI to conclude
-- 4 = PR not mergeable or has merge conflicts
-
-Requires: `gh` CLI available on PATH. Gracefully exits with error if gh is missing.
-
-Implementation note: This is the reusable form of the orchestrator's merge-gating discipline (buildsystem Phase 1). Core invariant: the merge call is STRUCTURALLY UNREACHABLE on any status other than SUCCESS.
 
 ## Invariants
 

package/tools/alert_bridge.py

@@ -0,0 +1,449 @@
+#!/usr/bin/env python3
+"""
+Aesop Alert Bridge — Slack/Discord webhook integration for fleet alerts.
+
+Bridges SECURITY-ALERTS.log and watchdog heartbeat stalls to Slack/Discord webhooks.
+Modes:
+  --scan           Check SECURITY-ALERTS.log and heartbeat, send alerts (default)
+  --test-message   Send a test ping to webhook
+  --dry-run        Print masked payload instead of posting
+
+Configuration: reads from aesop.config.json at runtime (not imported at module load).
+  alerts: {
+    webhook_url: null,         # If null/absent: no-op exit 0 (feature opt-in)
+    provider: "slack"|"discord",
+    min_severity: "LOW"|"MEDIUM"|"HIGH"|"CRITICAL",
+    heartbeat_stall_s: 600     # Check heartbeat staleness; null = skip
+  }
+
+Idempotency: cursor file (state/.alert-bridge-cursor) tracks last sent line.
+Never logs or echoes webhook URL (masked to last 6 chars in output).
+
+Stdlib-only (urllib, json, sys, os, pathlib, time).
+"""
+
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+from pathlib import Path
+
+
+# ==============================================================================
+# Configuration Loading
+# ==============================================================================
+
+
+def load_config():
+    """Load aesop.config.json from current directory, return config dict."""
+    config_file = Path("aesop.config.json")
+    if not config_file.exists():
+        return {}
+    try:
+        with open(config_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        print(f"[alert_bridge] Failed to load config: {e}", file=sys.stderr)
+        return {}
+
+
+def get_alerts_config(config):
+    """Extract alerts config from aesop.config.json."""
+    alerts = config.get("alerts", {})
+    if not isinstance(alerts, dict):
+        return {}
+    return alerts
+
+
+def get_state_root(config):
+    """Get state directory from config or default to ./state."""
+    return Path(config.get("state_root", "./state"))
+
+
+# ==============================================================================
+# Severity Levels
+# ==============================================================================
+
+
+SEVERITY_ORDER = {"LOW": 0, "MEDIUM": 1, "HIGH": 2, "CRITICAL": 3}
+
+
+def parse_severity(text):
+    """Extract severity from alert text (e.g., 'HIGH: ...' or '[2026-01-15] HIGH: ...') or return None."""
+    text = text.strip()
+    # Handle timestamps like "[2026-01-15 10:30]" at start
+    if text.startswith("["):
+        end_bracket = text.find("]")
+        if end_bracket >= 0:
+            text = text[end_bracket + 1:].strip()
+
+    # Now check for severity prefix
+    for severity in SEVERITY_ORDER.keys():
+        if text.startswith(severity + ":"):
+            return severity
+    return None
+
+
+def should_send_alert(alert_text, min_severity):
+    """Check if alert meets minimum severity threshold."""
+    severity = parse_severity(alert_text)
+    if severity is None:
+        return False  # Unknown severity format
+    min_level = SEVERITY_ORDER.get(min_severity, 0)
+    return SEVERITY_ORDER.get(severity, 0) >= min_level
+
+
+# ==============================================================================
+# Cursor Management (Idempotency)
+# ==============================================================================
+
+
+def get_cursor_path(state_root):
+    """Return cursor file path."""
+    return state_root / ".alert-bridge-cursor"
+
+
+def read_cursor(state_root):
+    """Read last sent line number from cursor file (default 0)."""
+    cursor_file = get_cursor_path(state_root)
+    if not cursor_file.exists():
+        return 0
+    try:
+        return int(cursor_file.read_text(encoding="utf-8").strip())
+    except (ValueError, IOError):
+        return 0
+
+
+def write_cursor(state_root, line_number):
+    """Write line number to cursor file."""
+    cursor_file = get_cursor_path(state_root)
+    state_root.mkdir(parents=True, exist_ok=True)
+    try:
+        cursor_file.write_text(str(line_number), encoding="utf-8")
+    except IOError as e:
+        print(f"[alert_bridge] Failed to write cursor: {e}", file=sys.stderr)
+
+
+# ==============================================================================
+# Alert Collection
+# ==============================================================================
+
+
+def collect_new_alerts(state_root, min_severity, since_line):
+    """
+    Read SECURITY-ALERTS.log, filter by severity, return new alerts since cursor.
+
+    Returns: (new_alerts: list[str], total_lines: int)
+    """
+    alerts_file = state_root / "SECURITY-ALERTS.log"
+    if not alerts_file.exists():
+        return [], 0
+
+    try:
+        content = alerts_file.read_text(encoding="utf-8")
+    except IOError:
+        return [], 0
+
+    lines = content.strip().split("\n") if content.strip() else []
+    new_alerts = []
+
+    for i, line in enumerate(lines, start=1):
+        # Skip if before cursor
+        if i <= since_line:
+            continue
+        line = line.strip()
+        if not line:
+            continue
+        # Skip marked entries
+        if "NOTE:" in line or "RESOLVED-FP" in line:
+            continue
+        # Check severity
+        if should_send_alert(line, min_severity):
+            new_alerts.append(line)
+
+    return new_alerts, len(lines)
+
+
+# ==============================================================================
+# Heartbeat Staleness Check
+# ==============================================================================
+
+
+def check_heartbeat_staleness(state_root, stall_threshold_s):
+    """
+    Check if watchdog heartbeat is stale.
+
+    Returns: (is_stale: bool, heartbeat_info: str or None)
+    """
+    if stall_threshold_s is None:
+        return False, None
+
+    hb_file = state_root / ".watchdog-heartbeat"
+    if not hb_file.exists():
+        return True, "Watchdog heartbeat missing"
+
+    try:
+        timestamp = int(hb_file.read_text(encoding="utf-8").strip())
+    except (ValueError, IOError):
+        return True, "Watchdog heartbeat unreadable"
+
+    age_seconds = int(time.time()) - timestamp
+    if age_seconds >= stall_threshold_s:
+        return True, f"Watchdog heartbeat stale ({age_seconds}s >= {stall_threshold_s}s)"
+
+    return False, None
+
+
+# ==============================================================================
+# Payload Formatting
+# ==============================================================================
+
+
+def format_slack_payload(alerts, heartbeat_info):
+    """Format Slack block-kit payload."""
+    blocks = []
+
+    # Header block
+    blocks.append(
+        {
+            "type": "header",
+            "text": {"type": "plain_text", "text": "🚨 Aesop Fleet Alert"},
+        }
+    )
+
+    # Section for alerts
+    if alerts:
+        alert_text = "\n".join([f"• {alert}" for alert in alerts[:10]])
+        blocks.append(
+            {
+                "type": "section",
+                "text": {"type": "mrkdwn", "text": alert_text},
+            }
+        )
+
+    # Section for heartbeat
+    if heartbeat_info:
+        blocks.append(
+            {
+                "type": "section",
+                "text": {
+                    "type": "mrkdwn",
+                    "text": f"⚠️  *Heartbeat*: {heartbeat_info}",
+                },
+            }
+        )
+
+    return {"blocks": blocks}
+
+
+def format_discord_payload(alerts, heartbeat_info):
+    """Format Discord embed payload."""
+    embeds = []
+
+    description_parts = []
+    if alerts:
+        for alert in alerts[:10]:
+            description_parts.append(alert)
+    if heartbeat_info:
+        description_parts.append(f"⚠️  **Heartbeat**: {heartbeat_info}")
+
+    embed = {
+        "title": "🚨 Aesop Fleet Alert",
+        "description": "\n".join(description_parts) or "Alert triggered",
+        "color": 16711680,  # Red
+    }
+
+    embeds.append(embed)
+    return {"embeds": embeds}
+
+
+# ==============================================================================
+# Webhook Sending
+# ==============================================================================
+
+
+def mask_webhook_url(webhook_url):
+    """Mask webhook URL to last 6 chars for logging."""
+    if not webhook_url or len(webhook_url) < 6:
+        return "***"
+    return "***" + webhook_url[-6:]
+
+
+def send_webhook(webhook_url, payload):
+    """POST payload to webhook URL. Returns (success: bool, status_code: int or None)."""
+    if not webhook_url:
+        return False, None
+
+    try:
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            webhook_url,
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        response = urllib.request.urlopen(req, timeout=10)
+        status_code = response.getcode()
+        return status_code in (200, 204), status_code
+    except urllib.error.HTTPError as e:
+        return False, e.code
+    except Exception as e:
+        print(
+            f"[alert_bridge] Failed to send webhook: {e}",
+            file=sys.stderr,
+        )
+        return False, None
+
+
+# ==============================================================================
+# Main Modes
+# ==============================================================================
+
+
+def mode_scan(config):
+    """Scan SECURITY-ALERTS.log and heartbeat, send alerts if new."""
+    alerts_config = get_alerts_config(config)
+    state_root = get_state_root(config)
+
+    webhook_url = alerts_config.get("webhook_url")
+    provider = alerts_config.get("provider", "slack")
+    min_severity = alerts_config.get("min_severity", "HIGH")
+    heartbeat_stall_s = alerts_config.get("heartbeat_stall_s")
+
+    # No-op if webhook disabled
+    if not webhook_url:
+        return 0
+
+    # Read cursor
+    cursor = read_cursor(state_root)
+
+    # Collect new alerts
+    new_alerts, total_lines = collect_new_alerts(state_root, min_severity, cursor)
+
+    # Check heartbeat staleness
+    is_stale, heartbeat_info = check_heartbeat_staleness(state_root, heartbeat_stall_s)
+
+    # Nothing to send
+    if not new_alerts and not is_stale:
+        return 0
+
+    # Format payload
+    if provider == "discord":
+        payload = format_discord_payload(new_alerts, heartbeat_info)
+    else:  # slack or default
+        payload = format_slack_payload(new_alerts, heartbeat_info)
+
+    # Send webhook
+    success, status_code = send_webhook(webhook_url, payload)
+    if success:
+        # Update cursor only on success
+        write_cursor(state_root, total_lines)
+        print(
+            f"[alert_bridge] Sent {len(new_alerts)} alert(s) to {mask_webhook_url(webhook_url)} (status: {status_code})"
+        )
+        return 0
+    else:
+        print(
+            f"[alert_bridge] Failed to send webhook (status: {status_code})",
+            file=sys.stderr,
+        )
+        return 1
+
+
+def mode_test_message(config):
+    """Send a test ping to webhook."""
+    alerts_config = get_alerts_config(config)
+    webhook_url = alerts_config.get("webhook_url")
+    provider = alerts_config.get("provider", "slack")
+
+    if not webhook_url:
+        print("[alert_bridge] Webhook URL not configured (no-op)", file=sys.stderr)
+        return 0
+
+    # Format test message
+    if provider == "discord":
+        payload = {"embeds": [{"title": "✅ Alert Bridge Test", "description": "Connection OK"}]}
+    else:  # slack or default
+        payload = {
+            "blocks": [
+                {"type": "header", "text": {"type": "plain_text", "text": "✅ Alert Bridge Test"}},
+                {
+                    "type": "section",
+                    "text": {"type": "mrkdwn", "text": "Connection OK"},
+                },
+            ]
+        }
+
+    success, status_code = send_webhook(webhook_url, payload)
+    if success:
+        print(f"[alert_bridge] Test message sent to {mask_webhook_url(webhook_url)} (status: {status_code})")
+        return 0
+    else:
+        print(
+            f"[alert_bridge] Test message failed (status: {status_code})",
+            file=sys.stderr,
+        )
+        return 1
+
+
+def mode_dry_run(config):
+    """Print masked payload without sending."""
+    alerts_config = get_alerts_config(config)
+    state_root = get_state_root(config)
+
+    webhook_url = alerts_config.get("webhook_url")
+    provider = alerts_config.get("provider", "slack")
+    min_severity = alerts_config.get("min_severity", "HIGH")
+    heartbeat_stall_s = alerts_config.get("heartbeat_stall_s")
+
+    if not webhook_url:
+        print("[alert_bridge] Webhook URL not configured (no-op)", file=sys.stderr)
+        return 0
+
+    cursor = read_cursor(state_root)
+    new_alerts, _ = collect_new_alerts(state_root, min_severity, cursor)
+    is_stale, heartbeat_info = check_heartbeat_staleness(state_root, heartbeat_stall_s)
+
+    if not new_alerts and not is_stale:
+        print(f"[alert_bridge] No alerts to send (webhook: {mask_webhook_url(webhook_url)})")
+        return 0
+
+    # Format payload
+    if provider == "discord":
+        payload = format_discord_payload(new_alerts, heartbeat_info)
+    else:  # slack or default
+        payload = format_slack_payload(new_alerts, heartbeat_info)
+
+    print(f"[alert_bridge] DRY-RUN payload (webhook: {mask_webhook_url(webhook_url)})")
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+# ==============================================================================
+# Entry Point
+# ==============================================================================
+
+
+def main(args=None):
+    """Main entry point."""
+    if args is None:
+        args = sys.argv[1:]
+
+    mode = "--scan"  # default
+    if args:
+        mode = args[0]
+
+    config = load_config()
+
+    if mode == "--test-message":
+        return mode_test_message(config)
+    elif mode == "--dry-run":
+        return mode_dry_run(config)
+    else:  # --scan or default
+        return mode_scan(config)
+
+
+if __name__ == "__main__":
+    sys.exit(main())