feat: Telegram adapter send/poll circuit breaker (Closes #573)

.env.example

@@ -105,6 +105,7 @@
 # Get your token at: https://huggingface.co/settings/tokens
 # Required permission: "Make calls to Inference Providers"
 # HF_TOKEN=
+# HF_BASE_URL=https://router.huggingface.co/v1  # Override default base URL
 # OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1  # Override default base URL
 
 # =============================================================================
@@ -411,6 +412,9 @@ IMAGE_TOOLS_DEBUG=false
 # Groq API key (free tier — used for Whisper STT in voice mode)
 # GROQ_API_KEY=
 
+# ElevenLabs API key (cloud STT/TTS — Scribe transcription)
+# ELEVENLABS_API_KEY=
+
 # =============================================================================
 # STT PROVIDER SELECTION
 # =============================================================================

.github/actions/detect-changes/action.yml

@@ -0,0 +1,62 @@
+name: Detect affected areas
+description: >-
+  Classify a PR's changed files into CI work lanes (python, frontend, site,
+  scan, deps, mcp_catalog) so the orchestrator can conditionally call only
+  the sub-workflows a PR can affect. Outputs are always "true" on push/dispatch
+  events and fail open (everything "true") when the diff cannot be computed.
+
+outputs:
+  python:
+    description: Run Python tests / ruff / ty / windows-footguns.
+    value: ${{ steps.classify.outputs.python }}
+  frontend:
+    description: Run the TypeScript typecheck matrix + desktop build.
+    value: ${{ steps.classify.outputs.frontend }}
+  docker_meta:
+    description: Docker setup and meta files have changed.
+    value: ${{ steps.classify.outputs.docker_meta }}
+  site:
+    description: Build the Docusaurus docs site.
+    value: ${{ steps.classify.outputs.site }}
+  scan:
+    description: Run the supply-chain critical-pattern scanner.
+    value: ${{ steps.classify.outputs.scan }}
+  deps:
+    description: Check pyproject.toml dependency upper bounds.
+    value: ${{ steps.classify.outputs.deps }}
+  mcp_catalog:
+    description: Require MCP catalog security review label.
+    value: ${{ steps.classify.outputs.mcp_catalog }}
+
+runs:
+  using: composite
+  steps:
+    - name: Classify changed files
+      id: classify
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+        REPO: ${{ github.repository }}
+        EVENT_NAME: ${{ github.event_name }}
+        BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      run: |
+        set -euo pipefail
+
+        # Only pull_request events are gated. Other events (push, release,
+        # dispatch) leave CHANGED empty, so the classifier fails open and every
+        # lane runs. Post-merge / on-demand validation is never weakened.
+        if [ "$EVENT_NAME" = "pull_request" ]; then
+          # Use the compare endpoint with the pinned base/head SHAs from the
+          # event payload instead of the "current PR files" endpoint. The SHAs
+          # are frozen at trigger time, so the file list is deterministic even
+          # if the PR receives a new push between trigger and detect.
+          CHANGED="$(gh api \
+            --paginate \
+            "repos/${REPO}/compare/${BASE_SHA}...${HEAD_SHA}" \
+            --jq '.files[].filename' || true)"
+        fi
+
+        echo "Changed files:"
+        printf '%s\n' "${CHANGED:-(none)}"
+        printf '%s\n' "${CHANGED:-}" | python3 scripts/ci/classify_changes.py

.github/actions/retry/action.yml

@@ -0,0 +1,50 @@
+name: Retry a flaky command
+description: >-
+  Run a shell command, retrying on non-zero exit. For dependency installs
+  (npm ci, uv sync) whose only failures are transient network/toolchain
+  flakes — a node-gyp header fetch, a registry blip — so CI self-heals
+  instead of needing a manual re-run.
+
+inputs:
+  command:
+    description: Shell command to run (and retry).
+    required: true
+  attempts:
+    description: Max attempts before giving up.
+    default: "3"
+  delay:
+    description: Seconds to wait between attempts.
+    default: "10"
+  working-directory:
+    description: Directory to run in.
+    default: "."
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      # command goes through env, never interpolated into the script body, so
+      # a command with quotes/specials can't break or inject into the runner.
+      env:
+        _CMD: ${{ inputs.command }}
+        _ATTEMPTS: ${{ inputs.attempts }}
+        _DELAY: ${{ inputs.delay }}
+      run: |
+        set -uo pipefail
+        n=0
+        while :; do
+          n=$((n + 1))
+          echo "::group::attempt $n/$_ATTEMPTS: $_CMD"
+          if bash -c "$_CMD"; then
+            echo "::endgroup::"
+            exit 0
+          fi
+          echo "::endgroup::"
+          if [ "$n" -ge "$_ATTEMPTS" ]; then
+            echo "::error::failed after $n attempts: $_CMD"
+            exit 1
+          fi
+          echo "::warning::attempt $n failed; retrying in ${_DELAY}s: $_CMD"
+          sleep "$_DELAY"
+        done

.github/workflows/ci.yml

@@ -0,0 +1,146 @@
+name: CI
+
+# Orchestrator workflow. Runs ``detect-changes`` once, then conditionally
+# calls the sub-workflows that a PR can actually affect. A final
+# ``all-checks-pass`` gate job aggregates results so branch protection only
+# needs to require a single check.
+#
+# Sub-workflows are triggered via ``workflow_call`` and keep their own job
+# definitions, matrices, and concurrency settings. They no longer have
+# ``push:`` / ``pull_request:`` triggers of their own — everything flows
+# through this file.
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write # needed by lint (PR comment) + supply-chain (PR comment)
+  actions: read # needed by osv-scanner (SARIF upload)
+  security-events: write # needed by osv-scanner (SARIF upload)
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # ─────────────────────────────────────────────────────────────────────
+  # detect: run the classifier once. Every downstream job reads its outputs
+  # to decide whether to run. On push/dispatch the classifier fails open
+  # (all lanes true) so post-merge validation is never weakened.
+  # ─────────────────────────────────────────────────────────────────────
+  detect:
+    runs-on: ubuntu-latest
+    outputs:
+      python: ${{ steps.classify.outputs.python }}
+      frontend: ${{ steps.classify.outputs.frontend }}
+      site: ${{ steps.classify.outputs.site }}
+      scan: ${{ steps.classify.outputs.scan }}
+      deps: ${{ steps.classify.outputs.deps }}
+      docker_meta: ${{ steps.classify.outputs.docker_meta }}
+      mcp_catalog: ${{ steps.classify.outputs.mcp_catalog }}
+      event_name: ${{ github.event_name }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Detect affected areas
+        id: classify
+        uses: ./.github/actions/detect-changes
+
+  # ─────────────────────────────────────────────────────────────────────
+  # Lane-gated sub-workflows. Each runs in parallel after detect finishes.
+  # Skipped workflows (if condition is false) don't spin up runners.
+  # ─────────────────────────────────────────────────────────────────────
+  tests:
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/tests.yml
+
+  lint:
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/lint.yml
+    with:
+      event_name: ${{ needs.detect.outputs.event_name }}
+
+  typecheck:
+    needs: detect
+    if: needs.detect.outputs.frontend == 'true'
+    uses: ./.github/workflows/typecheck.yml
+
+  docs-site:
+    needs: detect
+    if: needs.detect.outputs.site == 'true'
+    uses: ./.github/workflows/docs-site-checks.yml
+
+  history-check:
+    needs: detect
+    if: needs.detect.outputs.event_name == 'pull_request'
+    uses: ./.github/workflows/history-check.yml
+
+  contributor-check:
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/contributor-check.yml
+
+  uv-lockfile:
+    needs: detect
+    uses: ./.github/workflows/uv-lockfile-check.yml
+
+  docker-lint:
+    needs: detect
+    if: needs.detect.outputs.docker_meta == 'true'
+    uses: ./.github/workflows/docker-lint.yml
+
+  supply-chain:
+    needs: detect
+    if: needs.detect.outputs.event_name == 'pull_request' && (needs.detect.outputs.scan == 'true' || needs.detect.outputs.deps == 'true' || needs.detect.outputs.mcp_catalog == 'true')
+    uses: ./.github/workflows/supply-chain-audit.yml
+    with:
+      event_name: ${{ needs.detect.outputs.event_name }}
+      scan: ${{ needs.detect.outputs.scan == 'true' }}
+      deps: ${{ needs.detect.outputs.deps == 'true' }}
+      mcp_catalog: ${{ needs.detect.outputs.mcp_catalog == 'true' }}
+
+  osv-scanner:
+    needs: detect
+    uses: ./.github/workflows/osv-scanner.yml
+
+  # ─────────────────────────────────────────────────────────────────────
+  # Gate: runs after everything. ``if: always()`` ensures it reports a
+  # status even when some deps were skipped. Only actual ``failure``
+  # results cause it to fail; ``skipped`` is treated as success.
+  #
+  # Branch protection should require ONLY this check.
+  # ─────────────────────────────────────────────────────────────────────
+  all-checks-pass:
+    name: All required checks pass
+    needs:
+      - tests
+      - lint
+      - typecheck
+      - docs-site
+      - history-check
+      - contributor-check
+      - uv-lockfile
+      - docker-lint
+      - supply-chain
+      - osv-scanner
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate job results
+        env:
+          RESULTS: ${{ toJSON(needs.*.result) }}
+        run: |
+          echo "$RESULTS" | python3 -c "
+          import json, sys
+          results = json.load(sys.stdin)
+          failed = [r for r in results if r == 'failure']
+          if failed:
+              print(f'::error::{len(failed)} job(s) failed')
+              sys.exit(1)
+          print('All checks passed (or were skipped)')
+          "