feat(notifications): add sf-telegram-notifier Lambda for all 3 alpha-engine SFs

[cipher813]

Summary

• New infrastructure/lambdas/sf-telegram-notifier/ Lambda subscribes to EventBridge Step Functions Execution Status Change events for the saturday / weekday / eod pipelines and forwards human-readable summaries to the alpha-engine Telegram bot via alpha_engine_lib.telegram.send_message.
• Purely additive — existing SNS → email path on every SF (NotifyComplete success + HandleFailure failure branches) is unchanged. The new EventBridge rule subscribes to the same status changes in parallel; zero blast radius on the trade-decision pipeline.
• One rule covers all five status transitions: RUNNING (silent, avoids 5:45 AM PT daily phone-buzz), SUCCEEDED, FAILED, TIMED_OUT, ABORTED (all push). FAILED enriches the message with the error+cause snippet via best-effort states:DescribeExecution.

Why

Brian asked for Telegram coverage on SF launches, errors, and successes, with email staying as-is. The EventBridge SF-status-change source is the cleanest pickup point — single rule, no SF JSON edits, trivially extensible to future SFs.

Telegram credentials reuse the SSM parameters already provisioned for the executor notifier.py arc (ROADMAP L1067, 2026-05-13) — /alpha-engine/TELEGRAM_BOT_TOKEN + /alpha-engine/TELEGRAM_CHAT_ID. No new secret material.

Architecture

SF status transition (RUNNING / SUCCEEDED / FAILED / TIMED_OUT / ABORTED)
       │
       ▼
EventBridge default bus
   (aws.states / Step Functions Execution Status Change,
    filtered to the 3 alpha-engine SF ARNs)
       │
       ▼
alpha-engine-sf-telegram-notifier  ──►  alpha_engine_lib.telegram.send_message
                                                │
                                                ▼
                                       Telegram bot API

Deploy

Operator-deployed (matches spot-orphan-reaper / changelog-cloudwatch-mirror convention to keep the OIDC role's blast radius narrow). After merge:

# First-time bootstrap (creates IAM role, Lambda, EventBridge rule, permission)
bash infrastructure/lambdas/sf-telegram-notifier/deploy.sh --bootstrap

# Optional smoke (synthetic SUCCEEDED event → verifies live Telegram reach)
bash infrastructure/lambdas/sf-telegram-notifier/deploy.sh --smoke

Subsequent code changes use the default zero-arg invocation.

Test plan

• 12 new unit tests cover all 5 status transitions, FAILED cause-fetch + fail-soft path, duration formatting edge cases, unknown-SF ARN fallback, and send_message failure surfacing
• Full repo test suite still passes: 1399 passed, 1 skipped (no regressions)
• deploy.sh --dry-run exercises syntax check + unit tests + pip-install-to-target + zip packaging (22 MB final zip — well under the 50 MB Lambda limit)
• Post-merge: run --bootstrap then --smoke to verify live wiring (manual; first SF status change after bootstrap will be the real validation)
• Post-merge wind-down: confirm Telegram delivery on next Saturday SF run (2026-05-23) — expect 5 messages over the day's ~4h execution (1 RUNNING + 1 per terminal status / branch)

🤖 Generated with Claude Code