feed-the-machine 1.6.1 → 1.7.0

package/ftm-git/references/protocols/REMEDIATION.md

@@ -1,139 +1,139 @@
-# Remediation Protocol — Auto-Fix Steps
-
-Detailed remediation steps for secrets found during Phase 1–2 scanning. Apply in sequence for each finding.
-
----
-
-## Phase 3: Auto-Remediate
-
-For each finding, apply the appropriate fix automatically. The goal is to make the code safe without breaking functionality.
-
-### Step 1: Ensure .env infrastructure exists
-
-Check for a `.env` file in the project root. If it doesn't exist, create one with a header comment:
-
-```
-# Environment variables — DO NOT COMMIT THIS FILE
-# Copy .env.example for the template, fill in real values locally
-```
-
-Check `.gitignore` for `.env` coverage. If missing, add:
-```
-# Environment files with secrets
-.env
-.env.local
-.env.production
-.env.staging
-.env.*.local
-```
-
-### Step 2: Extract secrets to .env
-
-For each finding:
-
-1. **Choose an env var name** — derive it from the context. If the code says `STRIPE_API_KEY = "sk_live_..."`, the env var is `STRIPE_API_KEY`. If it says `api_key: "AIza..."`, infer from the file/service context (e.g., `GOOGLE_API_KEY`). Use SCREAMING_SNAKE_CASE.
-
-2. **Add to .env** — append `VAR_NAME=<actual-secret-value>` to `.env`. If the var already exists, don't duplicate it.
-
-3. **Add to .env.example** — create or update `.env.example` with `VAR_NAME=your-value-here` so other developers know the variable exists without seeing the real value.
-
-### Step 3: Refactor source files
-
-Replace the hardcoded secret with an env var reference. Match the language/framework:
-
-| Language | Pattern |
-|---|---|
-| Python | `os.environ["VAR_NAME"]` or `os.getenv("VAR_NAME")` (match existing style in file) |
-| JavaScript/TypeScript | `process.env.VAR_NAME` |
-| Ruby | `ENV["VAR_NAME"]` or `ENV.fetch("VAR_NAME")` |
-| Go | `os.Getenv("VAR_NAME")` |
-| Java | `System.getenv("VAR_NAME")` |
-| Shell/Bash | `$VAR_NAME` or `${VAR_NAME}` |
-| YAML/JSON config | `${VAR_NAME}` (if the framework supports interpolation) or add a comment pointing to the env var |
-
-If the file doesn't already import the env-reading module (e.g., `import os` in Python, `require('dotenv').config()` in Node), add the import. Check if the project uses `python-dotenv`, `dotenv` (Node), or similar — if so, use the project's existing pattern for loading env vars.
-
-### Step 4: Unstage remediated files
-
-After refactoring, make sure the `.env` file (with real secrets) is NOT staged:
-
-```bash
-git reset HEAD .env 2>/dev/null  # unstage if accidentally staged
-```
-
-Stage the refactored source files (which now reference env vars instead of hardcoded secrets):
-
-```bash
-git add <refactored-files>
-```
-
-### Step 5: Verify the fix
-
-Re-run Phase 1 scan on the refactored files to confirm the secrets are gone. If any remain, loop back and fix. Do not proceed until the scan is clean.
-
----
-
-## Phase 4: Report
-
-After remediation (or if the scan was clean from the start), produce a summary:
-
-**Clean scan:**
-```
-ftm-git: Clean scan. 0 secrets found in <N> files scanned. Safe to commit.
-```
-
-**After remediation:**
-```
-ftm-git: Found <N> hardcoded secrets. Auto-remediated:
-
-  CRITICAL: sk_live_**** in src/payments.py:42 -> STRIPE_SECRET_KEY
-  HIGH:     AIza**** in config/google.ts:18 -> GOOGLE_API_KEY
-  MEDIUM:   .env was not in .gitignore -> added
-
-Actions taken:
-  - Extracted <N> secrets to .env (gitignored)
-  - Created/updated .env.example with placeholder vars
-  - Refactored <N> source files to use env var references
-  - Updated .gitignore
-
-Verify the app still works with the new env var setup, then commit.
-```
-
-**Blocked (auto-fix not possible):**
-
-Some secrets can't be auto-fixed — for example, a private key embedded in a binary file, or a secret in a format the skill can't safely refactor. In these cases:
-
-```
-ftm-git: BLOCKED. Found secrets that require manual remediation:
-
-  CRITICAL: Private key in assets/cert.pem:1
-            -> Move this file outside the repo and reference via path env var
-
-  Action required: Fix the above manually, then run ftm-git again.
-```
-
----
-
-## Phase 5: Git History Check (Manual Invocation Only)
-
-When explicitly asked to do a deep scan (e.g., "scan the repo history for secrets"), also check past commits. This is expensive so it only runs on explicit request, not as part of the pre-commit gate.
-
-```bash
-git log --all --diff-filter=A --name-only --pretty=format:"%H" -- "*.env" "*.pem" "*.key" "*credentials*" "*secret*"
-```
-
-For each historically added sensitive file, check if it's still in the current tree. If it was added and later removed, warn that the secret is still in git history and suggest:
-
-1. Rotate the credential immediately (it's compromised)
-2. Use `git filter-repo` or BFG Repo Cleaner to purge from history if needed
-
----
-
-## Operating Principles
-
-1. **Block first, fix second.** Never let a secret through while figuring out the fix. The commit waits.
-2. **Zero false negatives over zero false positives.** It's better to flag something that turns out to be harmless than to miss a real key.
-3. **Never log full secrets.** In all output, mask secret values. Show only enough to identify which secret it is (first 8 + last 4 chars).
-4. **Env vars are the escape hatch.** The remediation pattern is always: secret goes to gitignored .env, code references the env var.
-5. **Existing patterns win.** If the project already uses dotenv, Vault, AWS Secrets Manager, or any other secret management system, match that pattern rather than introducing a new one.
-6. **Test files are not exempt.** A real `sk_live_*` key in a test file is just as dangerous as one in production code. Only `sk_test_*` with obviously fake values get a pass.
+# Remediation Protocol — Auto-Fix Steps
+
+Detailed remediation steps for secrets found during Phase 1–2 scanning. Apply in sequence for each finding.
+
+---
+
+## Phase 3: Auto-Remediate
+
+For each finding, apply the appropriate fix automatically. The goal is to make the code safe without breaking functionality.
+
+### Step 1: Ensure .env infrastructure exists
+
+Check for a `.env` file in the project root. If it doesn't exist, create one with a header comment:
+
+```
+# Environment variables — DO NOT COMMIT THIS FILE
+# Copy .env.example for the template, fill in real values locally
+```
+
+Check `.gitignore` for `.env` coverage. If missing, add:
+```
+# Environment files with secrets
+.env
+.env.local
+.env.production
+.env.staging
+.env.*.local
+```
+
+### Step 2: Extract secrets to .env
+
+For each finding:
+
+1. **Choose an env var name** — derive it from the context. If the code says `STRIPE_API_KEY = "sk_live_..."`, the env var is `STRIPE_API_KEY`. If it says `api_key: "AIza..."`, infer from the file/service context (e.g., `GOOGLE_API_KEY`). Use SCREAMING_SNAKE_CASE.
+
+2. **Add to .env** — append `VAR_NAME=<actual-secret-value>` to `.env`. If the var already exists, don't duplicate it.
+
+3. **Add to .env.example** — create or update `.env.example` with `VAR_NAME=your-value-here` so other developers know the variable exists without seeing the real value.
+
+### Step 3: Refactor source files
+
+Replace the hardcoded secret with an env var reference. Match the language/framework:
+
+| Language | Pattern |
+|---|---|
+| Python | `os.environ["VAR_NAME"]` or `os.getenv("VAR_NAME")` (match existing style in file) |
+| JavaScript/TypeScript | `process.env.VAR_NAME` |
+| Ruby | `ENV["VAR_NAME"]` or `ENV.fetch("VAR_NAME")` |
+| Go | `os.Getenv("VAR_NAME")` |
+| Java | `System.getenv("VAR_NAME")` |
+| Shell/Bash | `$VAR_NAME` or `${VAR_NAME}` |
+| YAML/JSON config | `${VAR_NAME}` (if the framework supports interpolation) or add a comment pointing to the env var |
+
+If the file doesn't already import the env-reading module (e.g., `import os` in Python, `require('dotenv').config()` in Node), add the import. Check if the project uses `python-dotenv`, `dotenv` (Node), or similar — if so, use the project's existing pattern for loading env vars.
+
+### Step 4: Unstage remediated files
+
+After refactoring, make sure the `.env` file (with real secrets) is NOT staged:
+
+```bash
+git reset HEAD .env 2>/dev/null  # unstage if accidentally staged
+```
+
+Stage the refactored source files (which now reference env vars instead of hardcoded secrets):
+
+```bash
+git add <refactored-files>
+```
+
+### Step 5: Verify the fix
+
+Re-run Phase 1 scan on the refactored files to confirm the secrets are gone. If any remain, loop back and fix. Do not proceed until the scan is clean.
+
+---
+
+## Phase 4: Report
+
+After remediation (or if the scan was clean from the start), produce a summary:
+
+**Clean scan:**
+```
+ftm-git: Clean scan. 0 secrets found in <N> files scanned. Safe to commit.
+```
+
+**After remediation:**
+```
+ftm-git: Found <N> hardcoded secrets. Auto-remediated:
+
+  CRITICAL: sk_live_**** in src/payments.py:42 -> STRIPE_SECRET_KEY
+  HIGH:     AIza**** in config/google.ts:18 -> GOOGLE_API_KEY
+  MEDIUM:   .env was not in .gitignore -> added
+
+Actions taken:
+  - Extracted <N> secrets to .env (gitignored)
+  - Created/updated .env.example with placeholder vars
+  - Refactored <N> source files to use env var references
+  - Updated .gitignore
+
+Verify the app still works with the new env var setup, then commit.
+```
+
+**Blocked (auto-fix not possible):**
+
+Some secrets can't be auto-fixed — for example, a private key embedded in a binary file, or a secret in a format the skill can't safely refactor. In these cases:
+
+```
+ftm-git: BLOCKED. Found secrets that require manual remediation:
+
+  CRITICAL: Private key in assets/cert.pem:1
+            -> Move this file outside the repo and reference via path env var
+
+  Action required: Fix the above manually, then run ftm-git again.
+```
+
+---
+
+## Phase 5: Git History Check (Manual Invocation Only)
+
+When explicitly asked to do a deep scan (e.g., "scan the repo history for secrets"), also check past commits. This is expensive so it only runs on explicit request, not as part of the pre-commit gate.
+
+```bash
+git log --all --diff-filter=A --name-only --pretty=format:"%H" -- "*.env" "*.pem" "*.key" "*credentials*" "*secret*"
+```
+
+For each historically added sensitive file, check if it's still in the current tree. If it was added and later removed, warn that the secret is still in git history and suggest:
+
+1. Rotate the credential immediately (it's compromised)
+2. Use `git filter-repo` or BFG Repo Cleaner to purge from history if needed
+
+---
+
+## Operating Principles
+
+1. **Block first, fix second.** Never let a secret through while figuring out the fix. The commit waits.
+2. **Zero false negatives over zero false positives.** It's better to flag something that turns out to be harmless than to miss a real key.
+3. **Never log full secrets.** In all output, mask secret values. Show only enough to identify which secret it is (first 8 + last 4 chars).
+4. **Env vars are the escape hatch.** The remediation pattern is always: secret goes to gitignored .env, code references the env var.
+5. **Existing patterns win.** If the project already uses dotenv, Vault, AWS Secrets Manager, or any other secret management system, match that pattern rather than introducing a new one.
+6. **Test files are not exempt.** A real `sk_live_*` key in a test file is just as dangerous as one in production code. Only `sk_test_*` with obviously fake values get a pass.

package/ftm-git/scripts/pre-commit-secrets.sh

@@ -1,110 +1,110 @@
-#!/usr/bin/env bash
-# ftm-git pre-commit hook — blocks commits containing hardcoded secrets
-# Installed by the ftm-git skill on first invocation. Safe to remove with:
-#   rm .git/hooks/pre-commit  (or edit to remove the ftm-git section)
-#
-# This hook scans staged files only (fast). The full ftm-git skill does
-# deeper scanning with context validation and auto-remediation — this is
-# the safety net that catches what slips through.
-
-set -euo pipefail
-
-RED='\033[0;31m'
-YELLOW='\033[0;33m'
-NC='\033[0m'
-
-# Get list of staged files (excluding deletions)
-STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
-if [ -z "$STAGED_FILES" ]; then
-  exit 0
-fi
-
-# Skip binary files, lock files, and vendored directories
-FILTERED_FILES=""
-for f in $STAGED_FILES; do
-  case "$f" in
-    node_modules/*|vendor/*|.git/*|__pycache__/*|dist/*|build/*) continue ;;
-    package-lock.json|yarn.lock|Gemfile.lock|poetry.lock|pnpm-lock.yaml) continue ;;
-    *.png|*.jpg|*.gif|*.ico|*.woff|*.woff2|*.ttf|*.eot|*.pdf|*.zip|*.tar*) continue ;;
-    .env.example|.env.sample|.env.template) continue ;;
-    *) FILTERED_FILES="$FILTERED_FILES $f" ;;
-  esac
-done
-
-if [ -z "$FILTERED_FILES" ]; then
-  exit 0
-fi
-
-FOUND=0
-FINDINGS=""
-
-# Tier 1: High-confidence patterns — these almost never false-positive
-# We scan staged content (not working tree) to catch exactly what would be committed
-PATTERNS=(
-  'AKIA[0-9A-Z]{16}'                                            # AWS Access Key ID
-  'ghp_[A-Za-z0-9_]{36}'                                        # GitHub PAT
-  'gho_[A-Za-z0-9_]{36}'                                        # GitHub OAuth
-  'ghu_[A-Za-z0-9_]{36}'                                        # GitHub user token
-  'ghs_[A-Za-z0-9_]{36}'                                        # GitHub server token
-  'github_pat_[A-Za-z0-9_]{82}'                                  # GitHub fine-grained PAT
-  'xoxb-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}'              # Slack bot token
-  'xoxp-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}'          # Slack user token
-  'xoxa-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}'          # Slack app token
-  'AIza[0-9A-Za-z\-_]{35}'                                      # Google API key
-  'sk_live_[0-9a-zA-Z]{24,}'                                    # Stripe live secret
-  'sk_test_[0-9a-zA-Z]{24,}'                                    # Stripe test secret
-  'rk_live_[0-9a-zA-Z]{24,}'                                    # Stripe restricted
-  'SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}'                 # SendGrid
-  'SK[0-9a-fA-F]{32}'                                            # Twilio
-  'npm_[A-Za-z0-9]{36}'                                          # npm token
-  'glpat-[A-Za-z0-9\-_]{20,}'                                   # GitLab PAT
-  '-----BEGIN (RSA|DSA|EC|OPENSSH|PGP) PRIVATE KEY-----'        # Private keys
-)
-
-for f in $FILTERED_FILES; do
-  # Get the staged version of the file (what would actually be committed)
-  CONTENT=$(git show ":$f" 2>/dev/null || true)
-  if [ -z "$CONTENT" ]; then
-    continue
-  fi
-
-  for pattern in "${PATTERNS[@]}"; do
-    MATCHES=$(echo "$CONTENT" | grep -nE "$pattern" 2>/dev/null || true)
-    if [ -n "$MATCHES" ]; then
-      while IFS= read -r match; do
-        LINE_NUM=$(echo "$match" | cut -d: -f1)
-        # Mask the secret value in output (show first 8 chars only)
-        MASKED=$(echo "$match" | cut -d: -f2- | sed -E 's/([A-Za-z0-9_\-]{8})[A-Za-z0-9_\-]{8,}/\1****/g')
-        FINDINGS="${FINDINGS}\n  ${RED}BLOCKED${NC}  $f:$LINE_NUM  $MASKED"
-        FOUND=$((FOUND + 1))
-      done <<< "$MATCHES"
-    fi
-  done
-done
-
-# Also check: is a .env file being committed?
-for f in $STAGED_FILES; do
-  case "$f" in
-    .env|.env.local|.env.production|.env.staging|.env.*.local)
-      FINDINGS="${FINDINGS}\n  ${YELLOW}WARNING${NC}  $f is staged — this file typically contains secrets and should be gitignored"
-      FOUND=$((FOUND + 1))
-      ;;
-  esac
-done
-
-if [ "$FOUND" -gt 0 ]; then
-  echo ""
-  echo -e "${RED}ftm-git: COMMIT BLOCKED — $FOUND secret(s) detected in staged files${NC}"
-  echo ""
-  echo -e "$FINDINGS"
-  echo ""
-  echo "To fix: run /ftm-git for auto-remediation, or manually:"
-  echo "  1. Move secrets to .env (gitignored)"
-  echo "  2. Replace hardcoded values with env var references"
-  echo "  3. Stage the cleaned files and commit again"
-  echo ""
-  echo "To bypass (NOT recommended): git commit --no-verify"
-  exit 1
-fi
-
-exit 0
+#!/usr/bin/env bash
+# ftm-git pre-commit hook — blocks commits containing hardcoded secrets
+# Installed by the ftm-git skill on first invocation. Safe to remove with:
+#   rm .git/hooks/pre-commit  (or edit to remove the ftm-git section)
+#
+# This hook scans staged files only (fast). The full ftm-git skill does
+# deeper scanning with context validation and auto-remediation — this is
+# the safety net that catches what slips through.
+
+set -euo pipefail
+
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+# Get list of staged files (excluding deletions)
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+# Skip binary files, lock files, and vendored directories
+FILTERED_FILES=""
+for f in $STAGED_FILES; do
+  case "$f" in
+    node_modules/*|vendor/*|.git/*|__pycache__/*|dist/*|build/*) continue ;;
+    package-lock.json|yarn.lock|Gemfile.lock|poetry.lock|pnpm-lock.yaml) continue ;;
+    *.png|*.jpg|*.gif|*.ico|*.woff|*.woff2|*.ttf|*.eot|*.pdf|*.zip|*.tar*) continue ;;
+    .env.example|.env.sample|.env.template) continue ;;
+    *) FILTERED_FILES="$FILTERED_FILES $f" ;;
+  esac
+done
+
+if [ -z "$FILTERED_FILES" ]; then
+  exit 0
+fi
+
+FOUND=0
+FINDINGS=""
+
+# Tier 1: High-confidence patterns — these almost never false-positive
+# We scan staged content (not working tree) to catch exactly what would be committed
+PATTERNS=(
+  'AKIA[0-9A-Z]{16}'                                            # AWS Access Key ID
+  'ghp_[A-Za-z0-9_]{36}'                                        # GitHub PAT
+  'gho_[A-Za-z0-9_]{36}'                                        # GitHub OAuth
+  'ghu_[A-Za-z0-9_]{36}'                                        # GitHub user token
+  'ghs_[A-Za-z0-9_]{36}'                                        # GitHub server token
+  'github_pat_[A-Za-z0-9_]{82}'                                  # GitHub fine-grained PAT
+  'xoxb-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}'              # Slack bot token
+  'xoxp-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}'          # Slack user token
+  'xoxa-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}'          # Slack app token
+  'AIza[0-9A-Za-z\-_]{35}'                                      # Google API key
+  'sk_live_[0-9a-zA-Z]{24,}'                                    # Stripe live secret
+  'sk_test_[0-9a-zA-Z]{24,}'                                    # Stripe test secret
+  'rk_live_[0-9a-zA-Z]{24,}'                                    # Stripe restricted
+  'SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}'                 # SendGrid
+  'SK[0-9a-fA-F]{32}'                                            # Twilio
+  'npm_[A-Za-z0-9]{36}'                                          # npm token
+  'glpat-[A-Za-z0-9\-_]{20,}'                                   # GitLab PAT
+  '-----BEGIN (RSA|DSA|EC|OPENSSH|PGP) PRIVATE KEY-----'        # Private keys
+)
+
+for f in $FILTERED_FILES; do
+  # Get the staged version of the file (what would actually be committed)
+  CONTENT=$(git show ":$f" 2>/dev/null || true)
+  if [ -z "$CONTENT" ]; then
+    continue
+  fi
+
+  for pattern in "${PATTERNS[@]}"; do
+    MATCHES=$(echo "$CONTENT" | grep -nE "$pattern" 2>/dev/null || true)
+    if [ -n "$MATCHES" ]; then
+      while IFS= read -r match; do
+        LINE_NUM=$(echo "$match" | cut -d: -f1)
+        # Mask the secret value in output (show first 8 chars only)
+        MASKED=$(echo "$match" | cut -d: -f2- | sed -E 's/([A-Za-z0-9_\-]{8})[A-Za-z0-9_\-]{8,}/\1****/g')
+        FINDINGS="${FINDINGS}\n  ${RED}BLOCKED${NC}  $f:$LINE_NUM  $MASKED"
+        FOUND=$((FOUND + 1))
+      done <<< "$MATCHES"
+    fi
+  done
+done
+
+# Also check: is a .env file being committed?
+for f in $STAGED_FILES; do
+  case "$f" in
+    .env|.env.local|.env.production|.env.staging|.env.*.local)
+      FINDINGS="${FINDINGS}\n  ${YELLOW}WARNING${NC}  $f is staged — this file typically contains secrets and should be gitignored"
+      FOUND=$((FOUND + 1))
+      ;;
+  esac
+done
+
+if [ "$FOUND" -gt 0 ]; then
+  echo ""
+  echo -e "${RED}ftm-git: COMMIT BLOCKED — $FOUND secret(s) detected in staged files${NC}"
+  echo ""
+  echo -e "$FINDINGS"
+  echo ""
+  echo "To fix: run /ftm-git for auto-remediation, or manually:"
+  echo "  1. Move secrets to .env (gitignored)"
+  echo "  2. Replace hardcoded values with env var references"
+  echo "  3. Stage the cleaned files and commit again"
+  echo ""
+  echo "To bypass (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+exit 0

package/ftm-git.yml

@@ -1,2 +1,2 @@
-name: ftm-git
-description: Secret scanning and credential safety gate for git operations. Prevents API keys, tokens, passwords, and other secrets from ever being committed or pushed to remote repositories. Scans staged files, working tree, and git history for hardcoded credentials using regex pattern matching, then auto-remediates by extracting secrets to gitignored .env files and replacing hardcoded values with env var references. Use when user says "scan for secrets", "check for keys", "audit credentials", "ftm-git", "secret scan", "remove api keys", "check before push", or any time git commit/push operations are about to happen. Also auto-invoked by ftm-executor and ftm-mind before any commit or push operation. Even if the user just says "commit this" or "push to remote", this skill MUST run first. Do NOT use for general git workflow operations like branching or merging — that's git-workflow territory. This skill is specifically the security gate.
+name: ftm-git
+description: Secret scanning and credential safety gate for git operations. Prevents API keys, tokens, passwords, and other secrets from ever being committed or pushed to remote repositories. Scans staged files, working tree, and git history for hardcoded credentials using regex pattern matching, then auto-remediates by extracting secrets to gitignored .env files and replacing hardcoded values with env var references. Use when user says "scan for secrets", "check for keys", "audit credentials", "ftm-git", "secret scan", "remove api keys", "check before push", or any time git commit/push operations are about to happen. Also auto-invoked by ftm-executor and ftm-mind before any commit or push operation. Even if the user just says "commit this" or "push to remote", this skill MUST run first. Do NOT use for general git workflow operations like branching or merging — that's git-workflow territory. This skill is specifically the security gate.

package/ftm-inbox/backend/adapters/_retry.py

@@ -1,64 +1,64 @@
-"""
-Exponential-backoff retry decorator for HTTP adapter calls.
-
-Usage:
-    @retry(max_attempts=3, base_delay=1.0)
-    def poll(self) -> list[dict]:
-        ...
-"""
-
-from __future__ import annotations
-
-import functools
-import logging
-import time
-from typing import Callable, TypeVar
-
-logger = logging.getLogger(__name__)
-
-F = TypeVar("F", bound=Callable)
-
-
-def retry(
-    max_attempts: int = 3,
-    base_delay: float = 1.0,
-    backoff_factor: float = 2.0,
-    exceptions: tuple[type[Exception], ...] = (Exception,),
-) -> Callable[[F], F]:
-    """
-    Decorator: retry on exception with exponential backoff.
-
-    Args:
-        max_attempts: Total number of attempts (including the first).
-        base_delay: Initial sleep duration in seconds.
-        backoff_factor: Multiplier applied to delay after each failure.
-        exceptions: Exception types that trigger a retry.
-    """
-
-    def decorator(func: F) -> F:
-        @functools.wraps(func)
-        def wrapper(*args, **kwargs):
-            delay = base_delay
-            last_exc: Exception | None = None
-            for attempt in range(1, max_attempts + 1):
-                try:
-                    return func(*args, **kwargs)
-                except exceptions as exc:
-                    last_exc = exc
-                    if attempt == max_attempts:
-                        break
-                    logger.warning(
-                        "%s failed (attempt %d/%d): %s — retrying in %.1fs",
-                        func.__qualname__,
-                        attempt,
-                        max_attempts,
-                        exc,
-                        delay,
-                    )
-                    time.sleep(delay)
-                    delay *= backoff_factor
-            raise last_exc  # type: ignore[misc]
-
-        return wrapper  # type: ignore[return-value]
-
-    return decorator
+"""
+Exponential-backoff retry decorator for HTTP adapter calls.
+
+Usage:
+    @retry(max_attempts=3, base_delay=1.0)
+    def poll(self) -> list[dict]:
+        ...
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import time
+from typing import Callable, TypeVar
+
+logger = logging.getLogger(__name__)
+
+F = TypeVar("F", bound=Callable)
+
+
+def retry(
+    max_attempts: int = 3,
+    base_delay: float = 1.0,
+    backoff_factor: float = 2.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+) -> Callable[[F], F]:
+    """
+    Decorator: retry on exception with exponential backoff.
+
+    Args:
+        max_attempts: Total number of attempts (including the first).
+        base_delay: Initial sleep duration in seconds.
+        backoff_factor: Multiplier applied to delay after each failure.
+        exceptions: Exception types that trigger a retry.
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            delay = base_delay
+            last_exc: Exception | None = None
+            for attempt in range(1, max_attempts + 1):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as exc:
+                    last_exc = exc
+                    if attempt == max_attempts:
+                        break
+                    logger.warning(
+                        "%s failed (attempt %d/%d): %s — retrying in %.1fs",
+                        func.__qualname__,
+                        attempt,
+                        max_attempts,
+                        exc,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    delay *= backoff_factor
+            raise last_exc  # type: ignore[misc]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator