Implement Hermes Futures Desk: dual-datasource trading engine, dashboard UI, tests, and documentation

Adds futures dashboard API, dual-datasource client (KuCoin live + Binance public fallback), trade cycle and state management, luxury dashboard frontend, sync_hf helper, runtime verification script, and full docs/ developer documentation set. Test suite: 70/70 passing.

.gitignore

@@ -1,7 +1,13 @@
 # Environment and secrets
 .env
 .env.local
+.env.txt
 *.pem
+api.txt
+*token*.txt
+*secret*.txt
+*credentials*
+.pytest_cache/
 
 # Dependencies and build
 node_modules/
@@ -11,3 +17,11 @@ __pycache__/
 # Logs and temp
 *.log
 .DS_Store
+
+# Read-only runtime audit outputs
+futures_runtime_audit*.json
+.runtime_audit/
+
+# Local scratch / one-off probes (machine-specific, not for the shared repo)
+_run_tests.bat
+hermes_overlay/_probe_ds4_schema.py

DEVELOPER_DOCUMENTATION.md

@@ -0,0 +1,2048 @@
+# Hermes Futures Desk — Complete Developer Documentation
+
+> Canonical combined developer reference for the UI v3 repository snapshot. The modular source documents live under `asset-space/docs/`.
+
+## Contents
+
+1. [Developer Guide](#developer-guide)
+2. [Architecture](#architecture)
+3. [API Reference](#api-reference)
+4. [Datasource Pipeline and Contracts](#datasource-pipeline-and-contracts)
+5. [Frontend Guide](#frontend-guide)
+6. [Environment Configuration](#environment-configuration)
+7. [Deployment Runbook](#deployment-runbook)
+8. [Security and Safety](#security-and-safety)
+9. [Operations and Troubleshooting](#operations-and-troubleshooting)
+10. [Testing and Verification](#testing-and-verification)
+11. [Contributing](#contributing)
+12. [Project Status](#project-status)
+
+---
+
+## Hermes Futures Desk — Complete Developer Guide
+
+### 1. Purpose
+
+Hermes Futures Desk is an authenticated Futures analysis and risk-management layer installed into the existing Hermes Agent runtime. It discovers markets, normalizes real market data, produces deterministic `LONG`, `SHORT`, or `NO_TRADE` outcomes, calculates a bounded trade plan, applies server-side risk controls, and optionally routes a fully revalidated plan to the existing Paper execution path.
+
+The system is intentionally conservative:
+
+- Datasource 4 is authoritative for Futures verification and safety.
+- Binance public data may fill missing or unusable market fields but cannot override DS4 safety.
+- Datasource 2 provides complementary context only.
+- External AI provides advisory explanation only.
+- The browser is never trusted to authorize execution.
+- No new web server, FastAPI application, port, or trading engine is created.
+
+### 2. Runtime summary
+
+```text
+Hugging Face Space / Docker container
+└── /opt/hermes                         Upstream Hermes Agent source/runtime
+    ├── dashboard on 0.0.0.0:7860      Existing Hermes web application
+    ├── tools/futures_dashboard_api.py  Installed repository overlay
+    ├── tools/templates/...html         Installed Luxury dashboard template
+    ├── trading/*                       Installed Futures modules
+    └── .hermes_futures_overlay_manifest.json
+
+/opt/data
+├── scripts/                            Entrypoint, persistence, runtime audit
+├── hermes_overlay/                     Restored/persisted copy; not preferred over image overlay
+├── futures_symbols_cache.json          Optional symbol cache
+├── telegram_state.json                 Telegram owner/watchlist/alert state
+└── persistent Hermes data
+
+/opt/hermesface_overlay                 Immutable overlay copied from the current image
+```
+
+The Docker image clones Hermes Agent into `/opt/hermes`, installs Python/Node dependencies, copies repository scripts into `/opt/data/scripts`, and copies the current overlay into both `/opt/data/hermes_overlay` and `/opt/hermesface_overlay`. At startup, `scripts/sync_hf.py` installs the overlay into `/opt/hermes`, writes a SHA-256 manifest, patches the existing Hermes dashboard to include the routers, and starts the dashboard on port `7860`.
+
+### 3. Main modules
+
+| Module | Responsibility |
+|---|---|
+| `scripts/entrypoint.sh` | Runtime directory creation, dashboard auth configuration, and handoff to `sync_hf.py`. |
+| `scripts/sync_hf.py` | Persistence restore/sync, overlay installation, manifest generation, router mounting, Telegram polling isolation, and process startup. |
+| `hermes_overlay/tools/futures_dashboard_api.py` | Authenticated Futures HTTP routes, runtime file diagnostics, symbol catalog, market endpoint, analysis route, and Paper revalidation route. |
+| `hermes_overlay/tools/templates/hermes_futures_desk_luxury.html` | Luxury Obsidian & Gold single-page dashboard. |
+| `hermes_overlay/trading/dual_datasource_client.py` | DS4 → Binance → DS2 acquisition, normalization, provenance, health metadata, and `noTradeGuard` aggregation. |
+| `hermes_overlay/trading/binance_public_client.py` | Unauthenticated Binance Futures fallback and explicit regional-restriction reporting. |
+| `hermes_overlay/trading/trade_cycle.py` | Deterministic signal scoring, SL/TP construction, risk sizing, plan creation, and optional Paper orchestration. |
+| `hermes_overlay/trading/risk.py` | Risk profiles, leverage caps/haircut, quantity sizing, and hard risk gates. |
+| `hermes_overlay/trading/futures_execution.py` | Existing Paper account/position book and execution validation. |
+| `hermes_overlay/trading/state.py` | Bounded in-memory dashboard state; no decision authority. |
+| `hermes_overlay/trading/symbols.py` | Symbol normalization for DS4 and CCXT formats. |
+| `hermes_overlay/external_ai/advisory.py` | Optional OpenRouter → Google → Hugging Face advisory chain. |
+| `hermes_overlay/tools/telegram_bot.py` | Webhook-only, analysis-only Telegram adapter and owner bootstrap. |
+| `scripts/verify_futures_runtime.py` | Read-only deployed runtime audit; never calls Paper Execute. |
+
+### 4. End-to-end request flow
+
+#### 4.1 Market display
+
+1. Browser requests `GET /api/futures/market` with symbol, interval, and limit.
+2. Router normalizes the symbol and calls `get_market_context()`.
+3. Datasource client requests DS4 with bounded KuCoin-compatible millisecond `from`/`to` parameters.
+4. Missing, unusable, or stale fields are requested from Binance public fallback.
+5. Datasource 2 is queried for complementary context and may fill only still-missing legitimate fields.
+6. Each normalized field receives source, timestamp, freshness, validity, and fallback metadata.
+7. The endpoint returns only real normalized values or an explicit `partial`, `stale`, or `unavailable` state.
+8. The browser renders charts and diagnostics without modifying server decisions.
+
+#### 4.2 Deterministic analysis
+
+1. Browser sends `POST /api/futures/analyze`.
+2. Server runs `run_futures_cycle(..., execute=False)`.
+3. DS4 safety state, Futures verification, required fields, and freshness gates are checked first.
+4. A deterministic score is calculated only from normalized real inputs.
+5. A directional plan is created only when score and confirmation thresholds pass.
+6. SL/TP are derived from ATR and configured reward-to-risk rules.
+7. Risk sizing calculates quantity from equity loss at Stop Loss.
+8. Slippage is estimated from the real order book.
+9. The result is stored as a bounded server-side plan and returned with a `planId`.
+
+#### 4.3 Paper execution
+
+Paper execution is not a continuation of browser state. The server performs all checks again:
+
+- requested symbol is a verified Futures contract;
+- `planId` matches the latest server plan;
+- symbol and risk profile have not changed;
+- plan was not already executed;
+- plan has not expired;
+- decision is `LONG` or `SHORT`;
+- DS4 verification and trading readiness remain valid;
+- `noTradeGuard` is false;
+- plan is marked executable and risk-approved;
+- runtime trading mode is `paper`;
+- a fresh analysis-only cycle still authorizes the plan.
+
+Only after these checks does the server invoke the existing Paper execution path.
+
+### 5. Datasource authority
+
+```text
+Datasource 4 → Binance public fallback → Datasource 2
+```
+
+Datasource 4 owns contract verification and all Futures safety semantics. The critical fields are:
+
+```text
+contract
+ticker
+orderbook
+funding
+openInterest
+```
+
+OHLCV, indicators, sentiment, and ATR are also normalized and attributed. Missing or non-fresh critical fields activate `noTradeGuard` and set `tradingReadiness=blocked`.
+
+Binance public data is unauthenticated and field-level only. HTTP 451 is represented as `Regionally restricted`; it is never reported as healthy. Datasource 2 cannot verify Futures, clear `noTradeGuard`, or override DS4 data that is present and usable.
+
+### 6. Health model
+
+The code deliberately separates:
+
+- `transportStatus`: whether the HTTP request succeeded;
+- `dataUsability`: whether parsed data is suitable for use;
+- `freshness`: whether provider timestamp or authoritative DS4 state proves freshness;
+- `completeness`: whether expected fields were supplied;
+- `mergeStatus`: whether the combined context is complete;
+- `tradingReadiness`: whether deterministic safety gates allow a plan.
+
+A successful HTTP response does not make market data fresh. Fallback data without a provider timestamp remains `unknown` and cannot pass a Futures freshness gate.
+
+### 7. Analysis and plan states
+
+#### Analysis states
+
+```text
+NOT_ANALYZED
+ANALYZING
+LONG
+SHORT
+NO_TRADE
+ANALYSIS_FAILED
+STALE
+API_UNAVAILABLE
+```
+
+#### Plan types
+
+- `directional_plan`: a valid directional plan before final execution checks.
+- `non_executable_plan`: directional values exist but one or more safety/risk gates block execution.
+- rejected/no-direction analysis: `NO_TRADE` with no executable plan geometry.
+
+#### Market endpoint states
+
+- `available`: real candles and required display fields are fresh and usable.
+- `partial`: values exist but freshness or completeness is not fully proven.
+- `stale`: required display data is stale or invalid.
+- `unavailable`: real candles or a current price could not be obtained.
+
+### 8. Deterministic scoring and risk rules
+
+Default analysis thresholds are environment-overridable:
+
+| Setting | Default |
+|---|---:|
+| Minimum absolute signal score | `0.55` |
+| Minimum signal components | `3` |
+| Minimum direction confirmations | `2` |
+| Stop ATR multiplier | `1.2` |
+| Take Profit reward-to-risk | `1.8` |
+| Minimum stop distance | `20` bps |
+| Plan maximum age | `20` seconds |
+| Requested leverage | `5x` |
+
+Risk profiles:
+
+| Profile | Equity risk | Maximum leverage |
+|---|---:|---:|
+| Conservative | 1% | 5x |
+| Moderate | 3% | 10x |
+| Aggressive | 5% | 15x |
+
+Sizing is based on loss at Stop Loss:
+
+```text
+risk_amount   = account_equity × risk_percent
+stop_distance = abs(entry_price - stop_loss)
+quantity      = risk_amount / stop_distance
+```
+
+When ATR is at least 3% of price, effective leverage is reduced by 50% and never increased beyond the risk-profile cap.
+
+### 9. Frontend behavior
+
+The dashboard is a single packaged HTML template with inline CSS and JavaScript. It uses the existing authenticated FastAPI origin and `fetch(..., credentials='same-origin', cache='no-store')`.
+
+Major features:
+
+- symbol search and verified/market-only catalog counts;
+- local watchlist and recent markets;
+- real candle/line chart, four intervals, three candle limits, volume, crosshair, and tooltip;
+- market source, freshness, funding, Open Interest, best bid/ask/spread, and readiness;
+- display-only diagnostics from returned candles;
+- per-field provenance;
+- deterministic analysis and Paper Execute controls;
+- plan geometry and execution checklist;
+- datasource detail cards and sanitized technical diagnostics;
+- Paper account and positions;
+- local activity/history, JSON export, copy summary, density/theme preferences;
+- manual and automatic refresh controls.
+
+Browser storage never grants server permission. Selecting a historical symbol or changing risk invalidates the current browser plan and requires a new server analysis.
+
+### 10. Authentication
+
+The upstream Hermes dashboard is protected by its existing authentication middleware. The Futures router also supports local HTTP Basic enforcement when `HERMES_ADMIN_PASSWORD` is set:
+
+```text
+username: HERMES_DASHBOARD_BASIC_AUTH_USERNAME (default: admin)
+password: HERMES_ADMIN_PASSWORD
+```
+
+`entrypoint.sh` writes a hashed credential into Hermes `config.yaml` before the server binds publicly. Secrets must be configured as Hugging Face Space secrets or injected environment variables, never committed.
+
+### 11. Telegram model
+
+Telegram is webhook-only and analysis-only:
+
+- `POST /api/telegram/webhook` validates `X-Telegram-Bot-Api-Secret-Token`.
+- Owner bootstrap uses a one-time private-chat `/claim <secret>` command.
+- Authorized users come from configured IDs or the persisted owner.
+- Commands call `run_futures_cycle(..., execute=False)` only.
+- Direct delivery may use a proxy; proactive delivery may use an HMAC relay.
+- Polling must remain disabled.
+
+No Telegram command can execute a Futures position.
+
+### 12. Runtime integrity
+
+During overlay installation, `sync_hf.py` copies the current image overlay into `/opt/hermes` and writes `.hermes_futures_overlay_manifest.json`. The status endpoint compares repository/overlay/runtime/template/router hashes when those paths are available.
+
+Runtime status semantics:
+
+- `verified`: evidence exists and all expected hashes match;
+- `mismatch`: evidence exists and one or more hashes differ;
+- `unknown`: required evidence is unavailable.
+
+Missing files must never be reported as verified.
+
+### 13. Development workflow
+
+1. Start from the current repository files under `asset-space/hermes_overlay`.
+2. Do not copy old loose reference files over the repository.
+3. Keep changes focused and additive to the API contract.
+4. Preserve the single server and port architecture.
+5. Add tests for normalization, provenance, state transitions, and server-side execution checks.
+6. Run static checks and focused Futures tests.
+7. Review secrets and generated files before commit.
+8. Deploy through the existing Space workflow.
+9. Verify the installed hashes and authenticated routes.
+10. Inspect browser Console and Network.
+11. Never click Paper Execute during deployment verification.
+
+### 14. Read-only runtime audit
+
+```bash
+export HERMES_ADMIN_PASSWORD='...'
+export HERMES_DASHBOARD_BASIC_AUTH_USERNAME='admin'
+python scripts/verify_futures_runtime.py \
+  --base-url https://really-amin-asset.hf.space \
+  --symbol BTCUSDT \
+  --analyze \
+  --report .runtime_audit/futures_runtime_audit.json
+```
+
+The utility checks `/futures`, status, symbols, positions, all market intervals, and optionally one analysis-only request. It never calls `/api/futures/paper/execute`.
+
+### 15. Known deployment limitations
+
+- Binance public Futures endpoints may return HTTP 451 in the current Hugging Face region.
+- Real DS4 payload names and provider timestamps must be verified against live deployed responses.
+- The current package has static validation results but not a completed authenticated production verification cycle.
+- The UI uses a single large HTML template; future refactoring must preserve runtime template installation and avoid introducing a second frontend server.
+
+### 16. Definition of done
+
+A change is complete only when:
+
+- the correct template and router are installed and hash-verified;
+- authenticated routes return expected structured responses;
+- real market data renders for 1m, 5m, 15m, and 1h or returns an explicit unavailable state;
+- Console has no critical error and Network requests are authenticated;
+- datasource health and attribution are truthful;
+- deterministic safety logic is unchanged;
+- Telegram remains webhook-only;
+- no secret is exposed;
+- no trade is executed during verification.
+
+
+---
+
+## Architecture
+
+### System context
+
+```mermaid
+flowchart LR
+    U[Authenticated browser] -->|same-origin HTTPS| H[Hermes dashboard / FastAPI :7860]
+    T[Telegram webhook] --> H
+    H --> R[Futures dashboard router]
+    R --> C[Deterministic trade cycle]
+    R --> S[Dashboard state]
+    C --> D[Dual datasource client]
+    D --> DS4[Datasource 4\nAuthoritative]
+    D --> B[Binance public\nFallback]
+    D --> DS2[Datasource 2\nComplementary]
+    C --> K[Risk / sizing]
+    C --> E[Paper execution]
+    C -. advisory only .-> A[External AI]
+```
+
+### Container and filesystem architecture
+
+```mermaid
+flowchart TD
+    I[Docker image] --> O1[/opt/hermesface_overlay\nimmutable current-image overlay]
+    I --> O2[/opt/data/hermes_overlay\npersisted/restored copy]
+    I --> S[/opt/data/scripts]
+    B[scripts/entrypoint.sh] --> Y[scripts/sync_hf.py]
+    Y -->|prefer| O1
+    Y -->|fallback only| O2
+    Y -->|copy modules| H[/opt/hermes]
+    Y --> M[overlay manifest]
+    Y --> P[patch existing dashboard router]
+    P --> W[Hermes dashboard :7860]
+```
+
+The immutable `/opt/hermesface_overlay` is preferred so a restored dataset containing an older overlay cannot downgrade the current image.
+
+### Layer responsibilities
+
+#### HTTP and UI layer
+
+`futures_dashboard_api.py` owns request validation, authentication dependency, response shaping, runtime diagnostics, and browser-facing error semantics. It does not implement signal scoring or sizing.
+
+#### Datasource layer
+
+`dual_datasource_client.py` owns:
+
+- HTTP acquisition;
+- KuCoin-compatible time range construction;
+- nested payload discovery;
+- field normalization;
+- source priority;
+- field provenance;
+- source health metadata;
+- `noTradeGuard`, missing-field, stale-field, merge, and readiness results.
+
+#### Decision layer
+
+`trade_cycle.py` owns deterministic score calculation, decision thresholds, SL/TP construction, risk module orchestration, plan expiry, and optional execution handoff.
+
+#### Risk layer
+
+`risk.py` owns risk profile lookup, leverage caps, volatility haircut, quantity calculation, margin/notional gates, daily-loss and position-count gates.
+
+#### Execution layer
+
+`futures_execution.py` owns Paper mode, account/position state, exchange adapter boundaries, slippage estimation, and protective order behavior. The dashboard route never directly constructs an exchange order.
+
+#### State layer
+
+`state.py` stores only a bounded view of the latest context/plan for the dashboard. It removes raw exchange payloads and does not authorize any decision.
+
+### Trust boundaries
+
+| Boundary | Trusted for decisions? | Notes |
+|---|---|---|
+| Browser controls and localStorage | No | Convenience only; server revalidates everything. |
+| Datasource 4 | Yes, for verification/safety | Still subject to parsing, freshness, and completeness checks. |
+| Binance public | No, as authority | Field fallback only; cannot clear DS4 guard. |
+| Datasource 2 | No, as authority | Complementary context only. |
+| External AI | No | Advisory explanation only. |
+| Telegram input | No | Authorized, rate-limited, analysis-only commands. |
+| Server-side latest plan | Partially | Must still pass freshness and execution revalidation. |
+
+### Router installation
+
+`sync_hf.py` modifies the existing Hermes dashboard code to include:
+
+```python
+from tools.futures_dashboard_api import router as _futures_dashboard_router
+app.include_router(_futures_dashboard_router)
+from tools.telegram_bot import router as _telegram_router
+app.include_router(_telegram_router)
+```
+
+The patch is idempotent and must not create a new FastAPI app.
+
+### Persistence
+
+Hermes data under `/opt/data` may be synchronized to a private Hugging Face Dataset. The repository overlay is also copied into the image, but the immutable image overlay is the source used for installation. Runtime state such as Telegram owner data and symbol cache lives under `/opt/data` and must not be committed.
+
+### Failure behavior
+
+- DS4 unreachable: merge may use fallback data for display, but Futures verification/readiness remains blocked.
+- Binance HTTP 451: source status is restricted/unavailable; no bypass is attempted.
+- DS2 unavailable: complementary context is degraded; it does not independently block a plan unless it was the only attempted fill for a still-missing field.
+- Market endpoint exception: HTTP 503 with structured `API_UNAVAILABLE` payload.
+- Analysis exception: HTTP 503, state becomes `ANALYSIS_FAILED`, previous plan is cleared from current state.
+- Template read failure: minimal fallback page is served and trading remains blocked.
+
+
+---
+
+## API Reference
+
+### Base and authentication
+
+All Futures routes are mounted on the existing Hermes FastAPI application and port. In production, use the Space base URL and an authenticated browser/session or HTTP Basic credentials.
+
+When `HERMES_ADMIN_PASSWORD` is set, Futures API routes require:
+
+```http
+Authorization: Basic <base64(username:password)>
+```
+
+Default username: `admin`, configurable with `HERMES_DASHBOARD_BASIC_AUTH_USERNAME`.
+
+All Futures responses set `Cache-Control: no-store`. `/futures` also sets no-cache headers and runtime SHA-256 headers.
+
+### `GET /futures`
+
+Returns the packaged HTML dashboard.
+
+Important response headers:
+
+```text
+X-Hermes-Template-SHA256
+X-Hermes-Router-SHA256
+Cache-Control: no-store, no-cache, must-revalidate, max-age=0
+```
+
+### `GET /api/futures/status`
+
+Returns application status, runtime-file evidence, market health, latest bounded plan state, source metadata, account summary, and diagnostics.
+
+Representative shape:
+
+```json
+{
+  "application": {
+    "status": "online",
+    "runtimeStatus": "verified | mismatch | unknown",
+    "runtimeFiles": {}
+  },
+  "marketData": {"status": "healthy | degraded | unavailable"},
+  "tradingReadiness": "ready | blocked",
+  "mergeStatus": "complete | partial | unknown",
+  "analysisState": "NOT_ANALYZED",
+  "sourceMetadata": {
+    "datasource4": {},
+    "binance": {},
+    "datasource2": {}
+  },
+  "fieldSources": {},
+  "fieldMetadata": {},
+  "verifiedFutures": false,
+  "missingRequiredFields": [],
+  "staleRequiredFields": [],
+  "latestTradePlan": null,
+  "latestPlanId": null,
+  "latestSignalScore": null,
+  "riskApproved": false,
+  "tradingMode": "paper",
+  "equity": 10000.0,
+  "realizedPnlToday": 0.0,
+  "openPositionCount": 0,
+  "serverTime": 0
+}
+```
+
+Consumers should treat additional fields as additive and avoid strict whole-object equality.
+
+### `GET /api/futures/symbols`
+
+Returns the merged catalog.
+
+```json
+{
+  "symbols": [
+    {
+      "symbol": "BTCUSDT",
+      "baseAsset": "BTC",
+      "quoteAsset": "USDT",
+      "futuresVerified": true,
+      "marketOnly": false,
+      "contractType": "PERPETUAL",
+      "status": "TRADING",
+      "source": "datasource4",
+      "rank": 1,
+      "updatedAt": "2026-07-21T00:00:00Z"
+    }
+  ],
+  "source": "...",
+  "updatedAt": "...",
+  "counts": {
+    "total": 0,
+    "verifiedFutures": 0,
+    "marketOnly": 0
+  }
+}
+```
+
+Catalog membership alone does not authorize execution. Only items with `futuresVerified=true` are eligible for Paper revalidation.
+
+### `GET /api/futures/positions`
+
+Returns Paper mode and enriched open positions.
+
+```json
+{
+  "mode": "paper",
+  "positions": [
+    {
+      "symbol": "BTC/USDT:USDT",
+      "side": "long",
+      "size": 0.01,
+      "entryPrice": 60000.0,
+      "markPrice": 60500.0,
+      "unrealizedPnl": 5.0
+    }
+  ]
+}
+```
+
+Mark price enrichment is best-effort. Missing mark data produces `null`, not zero.
+
+### `GET /api/futures/market`
+
+Query parameters:
+
+| Parameter | Type | Default | Constraints |
+|---|---|---:|---|
+| `symbol` | string | `BTCUSDT` | length 3–32; normalized server-side |
+| `interval` | enum | `5m` | `1m`, `5m`, `15m`, `1h` |
+| `limit` | integer | `120` | 20–500 |
+
+Example:
+
+```http
+GET /api/futures/market?symbol=BTCUSDT&interval=5m&limit=120
+```
+
+Successful/partial shape:
+
+```json
+{
+  "state": "available | partial | stale | unavailable",
+  "analysisState": "NOT_ANALYZED | STALE | API_UNAVAILABLE",
+  "dataUsability": "usable | degraded | unavailable",
+  "reason": null,
+  "symbol": "BTCUSDT",
+  "interval": "5m",
+  "limit": 120,
+  "candles": [
+    {"timestamp": 0, "open": 0, "high": 0, "low": 0, "close": 0, "volume": 0}
+  ],
+  "currentPrice": null,
+  "markPrice": null,
+  "change24h": null,
+  "volume24h": null,
+  "fundingRate": null,
+  "openInterest": null,
+  "source": "datasource4 | binance_public | datasource2 | mixed | unavailable",
+  "sourcesUsed": [],
+  "fieldSources": {},
+  "fieldMetadata": {},
+  "freshness": "fresh | stale | invalid | unknown",
+  "verifiedFutures": false,
+  "futuresVerification": {},
+  "warnings": [],
+  "missingFields": [],
+  "analysisRequiredFieldsMissing": [],
+  "staleRequiredFields": [],
+  "mergeStatus": "complete | partial | unavailable",
+  "tradingReadiness": "ready | blocked",
+  "rejectionReasons": [],
+  "sourceMetadata": {},
+  "technicalDiagnostics": {},
+  "fetchedAt": 0
+}
+```
+
+If acquisition raises, the route returns HTTP `503` with the same high-level keys, empty candles, null values, `state=unavailable`, `analysisState=API_UNAVAILABLE`, and blocked readiness.
+
+No mock candles are permitted in production responses.
+
+### `POST /api/futures/analyze`
+
+Request:
+
+```json
+{
+  "symbol": "BTCUSDT",
+  "risk_profile": "moderate",
+  "include_external_context": false
+}
+```
+
+Allowed risk profiles:
+
+```text
+conservative
+moderate
+aggressive
+```
+
+Unknown request fields are rejected.
+
+Representative response:
+
+```json
+{
+  "planId": "server-generated-reference",
+  "symbol": "BTCUSDT",
+  "decision": "LONG | SHORT | NO_TRADE",
+  "analysis_state": "LONG | SHORT | NO_TRADE",
+  "score": null,
+  "confidence": null,
+  "components": {},
+  "core_reasons": [],
+  "warnings": [],
+  "entry": null,
+  "stop_loss": null,
+  "take_profit": null,
+  "reward_to_risk": null,
+  "risk_profile": "moderate",
+  "risk_percent": null,
+  "requested_leverage": 5,
+  "effective_leverage": null,
+  "quantity": null,
+  "estimated_slippage_percent": null,
+  "risk_approved": false,
+  "rejection_reasons": [],
+  "noTradeGuard": true,
+  "plan_type": "directional_plan | non_executable_plan",
+  "executable": false,
+  "futuresVerified": false,
+  "trading_readiness": "blocked",
+  "created_at": "...",
+  "expires_at": "...",
+  "external_advisory": null
+}
+```
+
+A `NO_TRADE` response is a successful deterministic evaluation, not an HTTP failure. An internal analysis failure returns HTTP `503` with `detail="Futures analysis failed"` and clears the current plan state.
+
+### `POST /api/futures/paper/execute`
+
+Request:
+
+```json
+{
+  "symbol": "BTCUSDT",
+  "risk_profile": "moderate",
+  "planId": "server-generated-reference"
+}
+```
+
+The endpoint may return:
+
+- `403` for unverified contract or non-Paper mode;
+- `409` for superseded/unknown plan, symbol/risk change, expiry, prior execution, blocked readiness, failed fresh revalidation, or non-executable plan;
+- `422` for invalid request shape/symbol;
+- `200` for the final Paper result.
+
+The endpoint is intentionally absent from the read-only audit tool.
+
+### Telegram routes
+
+#### `POST /api/telegram/webhook`
+
+Public webhook ingress protected by:
+
+```http
+X-Telegram-Bot-Api-Secret-Token: <TELEGRAM_WEBHOOK_SECRET>
+```
+
+Limits request body to 256 KiB, applies per-user rate limiting, requires owner/allowed-user authorization, and invokes analysis-only commands.
+
+#### `GET /api/telegram/status`
+
+Returns enabled/mode/webhook/proxy/relay/authorized-user/alert-scheduler status. It does not expose tokens or user IDs.
+
+#### `GET /api/telegram/bootstrap/status`
+
+Requires the same Telegram secret header and returns only:
+
+```json
+{"ok": true, "ownerClaimed": true, "bootstrapConsumed": true}
+```
+
+
+---
+
+## Datasource Pipeline and Contracts
+
+### Priority and authority
+
+```text
+Datasource 4 → Binance public fallback → Datasource 2
+```
+
+Priority describes fill order, not equal trust.
+
+#### Datasource 4
+
+Authoritative for:
+
+- Futures contract verification;
+- `dataState`;
+- `noTradeGuard`;
+- safety status and rejection reasons;
+- primary Futures market fields.
+
+#### Binance public
+
+- unauthenticated;
+- called only for missing, unusable, or stale fields;
+- cannot verify a contract or clear DS4 safety;
+- HTTP 451 is `restricted` / `Regionally restricted`;
+- provider timestamps are required to claim freshness.
+
+#### Datasource 2
+
+- complementary news, sentiment, indicator, order-book, volume, trending, gainers, and correlation context;
+- may fill a still-missing legitimate field only after Binance;
+- cannot become Futures verification or safety authority.
+
+### Datasource 4 request
+
+The DS4 snapshot endpoint is called with:
+
+```text
+/api/short-hunter/snapshot/{SYMBOL}
+```
+
+Parameters:
+
+```text
+interval: 1m | 5m | 15m | 1h
+limit: 1..500 internally; market API exposes 20..500
+from: epoch milliseconds
+to: epoch milliseconds
+```
+
+`normalize_epoch_milliseconds()` accepts contemporary epoch seconds or milliseconds and prevents double conversion. `build_kucoin_time_range()` enforces supported interval, bounded limit, positive ordered timestamps, and millisecond units.
+
+### Normalized fields
+
+The merged envelope may contain:
+
+```text
+contract
+ticker
+ohlcv
+orderbook
+funding
+openInterest
+indicators
+sentiment
+atr
+market_context
+```
+
+#### Contract
+
+Normalized contract data should expose symbol, status, type/instrument, and explicit verification evidence when present. The presence of a generic `contract` object alone does not prove Futures status. Verification requires an explicit DS4 flag or a recognized Futures/perpetual/swap contract type.
+
+#### Ticker
+
+Accepted aliases are normalized to a bounded ticker object. Consumers should prefer normalized canonical keys where available and tolerate provider-specific supplemental keys.
+
+Common price candidates:
+
+```text
+markPrice
+lastPrice
+last
+price
+close
+indexPrice
+```
+
+#### OHLCV
+
+Canonical candle shape:
+
+```json
+{
+  "timestamp": 0,
+  "open": 0.0,
+  "high": 0.0,
+  "low": 0.0,
+  "close": 0.0,
+  "volume": 0.0
+}
+```
+
+A usable OHLCV series requires at least four valid positive close values. The market endpoint never invents missing candles.
+
+#### Order book
+
+Canonical shape:
+
+```json
+{
+  "bids": [[60000.0, 0.5]],
+  "asks": [[60001.0, 0.4]],
+  "timestamp": 0
+}
+```
+
+Both sides must have at least one valid level. Prices must be positive; quantities must be non-negative.
+
+#### Funding
+
+Canonical values may include:
+
+```text
+currentFundingRate
+fundingRate
+lastFundingRate
+rate
+nextFundingTime
+```
+
+#### Open Interest
+
+Canonical values may include:
+
+```text
+openInterest
+sumOpenInterest
+oi
+changeFraction
+change24h
+changePercent
+```
+
+### Field usability
+
+`_is_usable(field, value)` performs field-specific validation. Empty values, non-finite values, invalid OHLCV, incomplete order books, and invalid contract/funding/OI shapes are rejected.
+
+### Per-field provenance
+
+Every owned field receives metadata:
+
+```json
+{
+  "value": "bounded or summarized value",
+  "source": "datasource4 | binance_public | datasource2 | unavailable",
+  "timestamp": "provider timestamp or null",
+  "freshness": "fresh | stale | invalid | unknown",
+  "validity": "valid | unavailable",
+  "observedAt": "server observation time",
+  "freshnessBasis": "field_timestamp | datasource4_dataState | missing_provider_timestamp | unavailable",
+  "fallbackStatus": "primary | fallback | not_filled"
+}
+```
+
+The public API bounds large values:
+
+- OHLCV becomes count plus latest candle summary where appropriate;
+- order book becomes level counts and best bid/ask summary;
+- diagnostics are sanitized and size-limited.
+
+### Freshness
+
+Freshness is based on provider timestamp relative to interval, or on an explicit authoritative DS4 fresh state. Transport success alone is not freshness evidence.
+
+Required fields with `stale`, `invalid`, or `unknown` freshness block readiness.
+
+### Critical fields and readiness
+
+Critical fields:
+
+```text
+contract
+ticker
+orderbook
+funding
+openInterest
+```
+
+The combined context sets:
+
+```text
+missingRequiredFields
+staleRequiredFields
+noTradeGuard
+noTradeReasons
+mergeStatus
+tradingReadiness
+```
+
+Readiness is `ready` only when no guard remains. DS4 verification failure, DS4 `noTradeGuard`, missing critical fields, or non-fresh critical fields results in `blocked`.
+
+### Source metadata
+
+Each source returns structured fields:
+
+```json
+{
+  "name": "Datasource 4",
+  "url": "...",
+  "status": "ok | degraded | unreachable | unavailable | standby",
+  "transportStatus": "healthy | degraded | unavailable | restricted | standby",
+  "dataUsability": "usable | degraded | unavailable | not_used",
+  "endpoint": "...",
+  "httpStatus": 200,
+  "latencyMs": 120.4,
+  "lastSuccess": "...",
+  "freshness": "fresh | stale | unknown",
+  "completeness": "complete | partial | unknown",
+  "suppliedFields": [],
+  "missingFields": [],
+  "reason": "concise operator-facing summary"
+}
+```
+
+Detailed endpoint/provider errors belong only under `technicalDiagnostics`, separated by source and sanitized before exposure.
+
+### Merge diagnostics
+
+Cross-source problems are not assigned to a datasource card. They appear under:
+
+```text
+technicalDiagnostics.merge.status
+technicalDiagnostics.merge.missingCriticalFields
+technicalDiagnostics.merge.tradingReadiness
+technicalDiagnostics.merge.rejectionReasons
+```
+
+### Adding a new provider mapping
+
+1. Capture a real redacted payload.
+2. Add the narrowest legitimate alias to the relevant normalizer.
+3. Preserve provider timestamp and source name.
+4. Add field-specific validity checks.
+5. Do not infer Futures verification from generic market data.
+6. Do not let the provider clear DS4 guard state.
+7. Add focused tests for positive, missing, malformed, stale, and ambiguous cases.
+8. Verify source-specific diagnostics remain correctly attributed.
+
+
+---
+
+## Frontend Guide
+
+### File and runtime
+
+The entire Futures dashboard UI is packaged in:
+
+```text
+hermes_overlay/tools/templates/hermes_futures_desk_luxury.html
+```
+
+The router reads this file at request time from its installed `tools/templates` directory and serves it at `/futures`. Do not add a second frontend server, bundler process, or port.
+
+### Design system
+
+The UI uses an Obsidian & Gold workstation theme with a light-theme option. Operational values use readable sans-serif/monospace styling. Decorative serif/italic styling is limited to headings and visual accents.
+
+Responsive modes cover desktop, tablet, and mobile. `prefers-reduced-motion` is respected.
+
+### Main UI regions
+
+- fixed/collapsible navigation and local market lists;
+- command deck with symbol, risk, advisory, Analyze, and Paper Execute controls;
+- selected-market header and chart;
+- market diagnostics and field provenance;
+- decision, score, risk approval, and execution mode;
+- trade-plan geometry and execution checklist;
+- signal reasons and components;
+- Paper account and positions;
+- datasource health and technical diagnostics;
+- Telegram operational status;
+- local activity/history and export actions.
+
+### API usage
+
+The helper uses:
+
+```javascript
+fetch(url, {
+  credentials: 'same-origin',
+  cache: 'no-store'
+})
+```
+
+Primary calls:
+
+```text
+GET  /api/futures/status
+GET  /api/futures/symbols
+GET  /api/futures/positions
+GET  /api/futures/market
+POST /api/futures/analyze
+POST /api/futures/paper/execute
+GET  /api/telegram/status
+```
+
+No backend route is declared in the template.
+
+### Refresh behavior
+
+Default intervals:
+
+- clock and age labels: 1 second;
+- status and positions: 5 seconds while auto-refresh is enabled and page is visible;
+- market data: 15 seconds;
+- Telegram status: 60 seconds.
+
+When the page becomes visible again, status and market data refresh if automatic refresh is enabled.
+
+### Chart behavior
+
+Supported intervals:
+
+```text
+1m 5m 15m 1h
+```
+
+Supported candle limits:
+
+```text
+60 120 240
+```
+
+Modes:
+
+- Candles;
+- Line;
+- optional volume bars.
+
+The chart is an inline SVG and uses only `candles` returned by the market endpoint. Crosshair, OHLCV legend, tooltip, current-price reference, price labels, visible high/low, range position, and last-candle age are derived from the returned series.
+
+No visual interpolation or fallback is permitted to create production candles.
+
+### Display-only diagnostics
+
+The UI calculates visible trend, average candle range, relative last-candle volume, realized variation, last-candle direction, and range position from the real returned candles. These values are explicitly informational and must never change:
+
+```text
+LONG / SHORT / NO_TRADE
+risk approval
+noTradeGuard
+Entry / SL / TP
+leverage
+quantity
+execution eligibility
+```
+
+### Local browser state
+
+The UI stores only convenience preferences/history in `localStorage`.
+
+Known keys:
+
+```text
+hermes_theme
+hermes_auto_refresh
+hermes_compact
+```
+
+Watchlist, recent markets, local analysis history, and workspace activity use Hermes-prefixed local keys defined in the template. They are not synchronized to the server and are not trusted for execution.
+
+### Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `/` | Focus and select symbol search. |
+| `A` | Run analysis when not already analyzing. |
+| `R` | Manual refresh. |
+| `D` | Toggle display density. |
+| `T` | Toggle theme. |
+| `?` | Open shortcut help. |
+| `Escape` | Close overlays/help. |
+
+There is deliberately no keyboard shortcut for Paper Execute.
+
+### Analysis state rendering
+
+Use the server result to set one of:
+
+```text
+NOT_ANALYZED
+ANALYZING
+LONG
+SHORT
+NO_TRADE
+ANALYSIS_FAILED
+STALE
+API_UNAVAILABLE
+```
+
+Important rules:
+
+- initial state is “Waiting for analysis,” not `NO_TRADE`;
+- HTTP/network failure is `ANALYSIS_FAILED` or `API_UNAVAILABLE`;
+- score is “Unavailable” when components do not exist, not numeric zero;
+- expiry is prominent only for a valid directional plan;
+- rejected/incomplete analysis is not presented as executable;
+- changing symbol or risk invalidates the current browser plan;
+- server state remains authoritative.
+
+### Execute availability
+
+The button is disabled unless the latest browser plan mirrors all required server fields. The UI displays a concrete disabled reason such as:
+
+```text
+Run analysis first
+No directional plan
+Risk approval failed
+noTradeGuard active
+Market-only symbol
+Plan expired
+Symbol changed
+Risk profile changed
+Plan already executed
+Required Futures fields unavailable
+```
+
+These checks improve UX but do not replace backend revalidation.
+
+### Adding a UI feature safely
+
+1. Reuse existing API fields or add an additive backend field.
+2. Render missing values as `Unavailable`, never zero or fabricated content.
+3. Keep browser calculations labeled display-only.
+4. Do not add another Execute path or shortcut.
+5. Invalidate plan display when relevant controls change.
+6. Keep DOM IDs unique and update static ID checks.
+7. Preserve responsive and reduced-motion behavior.
+8. Do not display raw provider errors or secrets.
+9. Verify Console and Network in an authenticated deployed session.
+
+
+---
+
+## Environment Configuration
+
+Configure secrets in Hugging Face Space Settings or inject them at container runtime. Never commit a populated `.env` file.
+
+### Core persistence
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HF_TOKEN` | none | Hugging Face token with required repository access. |
+| `HERMES_DATASET_REPO` | derived/none | Private Dataset used to persist `/opt/data`. |
+| `AUTO_CREATE_DATASET` | `true` | Create the private Dataset when missing. |
+| `SYNC_INTERVAL` | `60` | Persistence sync interval in seconds. |
+| `HF_HUB_DOWNLOAD_TIMEOUT` | implementation default | Hub download timeout. |
+| `HF_HUB_UPLOAD_TIMEOUT` | implementation default | Hub upload timeout. |
+| `HERMES_HOME` | `/opt/data` | Persistent Hermes data root. |
+| `MAX_BACKUPS` | script default | Backup retention used by persistence helper. |
+
+### Dashboard authentication
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HERMES_ADMIN_PASSWORD` | none | Required production dashboard password. |
+| `HERMES_ADMIN_USERNAME` | `admin` | Username written to Hermes dashboard config by entrypoint. |
+| `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` | `admin` | Username checked by Futures router and runtime audit. |
+
+For the audit tool only:
+
+| Variable | Purpose |
+|---|---|
+| `HERMES_DASHBOARD_COOKIE` | Existing authenticated session cookie when Basic auth is not used. |
+| `HERMES_FUTURES_BASE_URL` | Default audit target base URL. |
+
+### Datasources
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DS4_BASE_URL` | DS4 Hugging Face Space URL | Authoritative Datasource 4 base. |
+| `DS4_TIMEOUT_S` | `6` | DS4 request timeout. |
+| `DS2_BASE_URL` | DS2 Hugging Face Space URL | Complementary Datasource 2 base. |
+| `DS2_TIMEOUT_S` | `6` | DS2 request timeout. |
+| `HERMES_SYMBOL_CACHE_PATH` | `/opt/data/futures_symbols_cache.json` | Symbol catalog cache. |
+
+### Binance fallback
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `BINANCE_PUBLIC_FALLBACK_ENABLED` | `true` | Enable unauthenticated field fallback. |
+| `BINANCE_FUTURES_PUBLIC_BASE_URL` | `https://fapi.binance.com` | Binance Futures public base. |
+| `BINANCE_FUTURES_TIMEOUT_S` | `5` | Request timeout. |
+| `BINANCE_FUTURES_MAX_RETRIES` | `2` | Retry bound. |
+| `BINANCE_KLINE_INTERVAL` | `5m` | Default fallback interval. |
+| `BINANCE_KLINE_LIMIT` | `100` | Default kline count. |
+| `BINANCE_ATR_PERIOD` | `14` | ATR lookback in fallback client. |
+| `BINANCE_ORDERBOOK_LIMIT` | `20` | Depth level limit. |
+| `BINANCE_OI_PERIOD` | `5m` | Open Interest history period. |
+
+A regional HTTP 451 must be surfaced honestly. Do not use raw IP, DNS bypass, or TLS bypass.
+
+### Deterministic analysis
+
+| Variable | Default | Purpose |
+|---|---:|---|
+| `FUTURES_MIN_SIGNAL_SCORE` | `0.55` | Minimum absolute deterministic score. |
+| `FUTURES_MIN_SIGNAL_COMPONENTS` | `3` | Minimum present scoring components. |
+| `FUTURES_MIN_DIRECTION_CONFIRMATIONS` | `2` | Minimum components confirming direction. |
+| `FUTURES_STOP_ATR_MULTIPLIER` | `1.2` | ATR stop-distance multiplier. |
+| `FUTURES_TAKE_PROFIT_RR` | `1.8` | Target reward-to-risk. |
+| `FUTURES_MIN_STOP_BPS` | `20` | Minimum stop distance in basis points. |
+| `FUTURES_PLAN_MAX_AGE_SECONDS` | `20` | Plan expiry window. |
+| `FUTURES_DEFAULT_LEVERAGE` | `5` | Requested leverage before caps/haircut. |
+
+Changing these variables changes deterministic behavior and requires explicit review, tests, and deployment evidence.
+
+### Execution and Paper account
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PAPER_EQUITY_USDT` | implementation default | Initial Paper account equity. |
+| `FUTURES_EXCHANGE_ID` | implementation default | Exchange adapter ID. |
+| `FUTURES_API_KEY` | none | Exchange credential boundary. Do not set for routine Paper-only development. |
+| `FUTURES_API_SECRET` | none | Exchange secret. |
+| `FUTURES_API_PASSPHRASE` | none | Optional exchange passphrase. |
+
+Do not introduce credentials into source, logs, diagnostics, screenshots, patches, or generated reports.
+
+### External advisory
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `EXTERNAL_AI_ENABLED` | `true` | Allow advisory when explicitly requested. |
+| `EXTERNAL_AI_TIMEOUT_SECONDS` | `8` | Legacy/advisory timeout. |
+| `EXTERNAL_AI_PROVIDER_TIMEOUT_SECONDS` | `8` | Per-provider timeout. |
+| `EXTERNAL_AI_TOTAL_TIMEOUT_SECONDS` | `15` | Total advisory budget. |
+| `OPENROUTER_ANALYSIS_MODEL` | configured model | OpenRouter model. |
+| `GOOGLE_ANALYSIS_MODEL` | configured model | Google model. |
+| `HF_ANALYSIS_MODEL` | configured model | Hugging Face model. |
+| `OPENROUTER_API_KEY` | none | OpenRouter credential. |
+| `GOOGLE_API_KEY` | none | Google credential. |
+
+Provider order is OpenRouter → Google → Hugging Face. Advisory output cannot change the deterministic plan.
+
+### Telegram webhook
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `TELEGRAM_ENABLED` | `false` | Enable webhook adapter. |
+| `TELEGRAM_MODE` | `webhook` | Must remain webhook mode. |
+| `TELEGRAM_PUBLIC_BASE_URL` | Space URL | Webhook target base. |
+| `TELEGRAM_WEBHOOK_PATH` | `/api/telegram/webhook` | Webhook path. |
+| `TELEGRAM_WEBHOOK_SECRET` | none | Telegram secret-token header value. |
+| `TELEGRAM_BOOTSTRAP_SECRET` | none | One-time owner claim secret. |
+| `TELEGRAM_ALLOWED_USER_IDS` | empty | Comma-separated authorized IDs. |
+| `TELEGRAM_BOT_TOKEN` | none | Telegram bot token. |
+| `TELEGRAM_PROXY_URL` | empty | Optional direct Bot API proxy. |
+| `TELEGRAM_RELAY_URL` | empty | Optional proactive relay. |
+| `TELEGRAM_RELAY_SECRET` | empty | HMAC relay secret. |
+| `TELEGRAM_STATE_PATH` | `/opt/data/telegram_state.json` | Persisted owner/watchlist state. |
+| `TELEGRAM_ALERTS_ENABLED` | `false` | External-scheduler alert evaluation status. |
+| `TELEGRAM_COMMAND_RATE_LIMIT` | `10` | Commands per user per minute. |
+| `TELEGRAM_SCAN_MAX_SYMBOLS` | `300` | Maximum verified catalog candidates. |
+| `TELEGRAM_SCAN_SHORTLIST_SIZE` | `20` | Deterministic shortlist size. |
+| `TELEGRAM_SCAN_RESULT_COUNT` | `10` | Displayed result count. |
+| `TELEGRAM_SCAN_MAX_CONCURRENCY` | `4` | Analysis concurrency. |
+
+### MCP isolation
+
+| Variable | Default | Requirement |
+|---|---|---|
+| `LINEAR_MCP_ENABLED` | `false` | Keep unchanged unless separately approved. |
+| `UNREAL_ENGINE_MCP_ENABLED` | `false` | Keep disabled unless separately approved. |
+
+### Runtime integrity paths
+
+Advanced overrides used by diagnostics:
+
+```text
+HERMES_FUTURES_OVERLAY_MANIFEST
+HERMES_OVERLAY_SOURCE
+HERMES_SYNC_SCRIPT
+```
+
+These should normally use their runtime defaults.
+
+
+---
+
+## Deployment Runbook
+
+### Preconditions
+
+- Work from the current repository under `asset-space`.
+- Review all diffs.
+- Ensure no real `.env`, tokens, cookies, screenshots, cache, ZIP archives, runtime reports, or temporary probes are staged.
+- Confirm no architecture change introduces a second app, frontend server, or port.
+- Do not execute a trade during deployment verification.
+
+### Build behavior
+
+The Dockerfile:
+
+1. clones upstream Hermes Agent into `/opt/hermes`;
+2. installs Node, web dashboard, Playwright, Python, CCXT, and HTTPX dependencies;
+3. creates non-root user `hermes` and `/opt/data` directories;
+4. copies scripts into `/opt/data/scripts`;
+5. copies overlay into `/opt/data/hermes_overlay` and immutable `/opt/hermesface_overlay`;
+6. starts `/opt/data/scripts/entrypoint.sh`.
+
+### Startup behavior
+
+`entrypoint.sh`:
+
+1. starts DNS pre-resolution in the background;
+2. activates `/opt/hermes/.venv`;
+3. creates persistent directories and baseline config files;
+4. writes hashed dashboard Basic auth when `HERMES_ADMIN_PASSWORD` is configured;
+5. calls `scripts/sync_hf.py`.
+
+`sync_hf.py`:
+
+1. restores persistent data when configured;
+2. disables legacy Telegram gateway polling in webhook mode;
+3. installs the current image overlay into `/opt/hermes`;
+4. writes and verifies the overlay hash manifest;
+5. mounts Futures and Telegram routers into the existing dashboard app;
+6. starts Hermes dashboard on port `7860`;
+7. manages persistence/sync helpers.
+
+### Hugging Face deployment procedure
+
+1. Review the final diff.
+2. Commit the smallest coherent change.
+3. Push to `main` of the repository backing `Really-amin/Asset`.
+4. Monitor Space build logs.
+5. Wait until Space is fully `RUNNING`.
+6. Record the serving repository revision.
+7. Run the read-only runtime audit.
+8. Open an authenticated browser session.
+9. Inspect Console and Network.
+10. Verify Telegram status and MCP isolation.
+
+### Read-only runtime audit
+
+```bash
+export HERMES_ADMIN_PASSWORD='...'
+export HERMES_DASHBOARD_BASIC_AUTH_USERNAME='admin'
+python scripts/verify_futures_runtime.py \
+  --base-url https://really-amin-asset.hf.space \
+  --symbol BTCUSDT \
+  --analyze \
+  --report .runtime_audit/futures_runtime_audit.json
+```
+
+Expected properties:
+
+- `/futures` returns 200;
+- body SHA-256 equals `X-Hermes-Template-SHA256`;
+- status, symbols, and positions return authenticated 200 responses;
+- each market interval returns 200 or structured 503;
+- market payload shape includes real canonical candle objects;
+- optional analysis returns 200;
+- `paperExecuteCalled` remains false.
+
+### Browser verification
+
+Check:
+
+- no critical JavaScript error;
+- authenticated API requests are not redirected to login HTML;
+- `/api/futures/market` is requested for each selected interval;
+- chart code executes and state messages match payload;
+- no stale cached template is served;
+- selected-market header, provenance, diagnostics, plan, account, and datasource sections render;
+- Execute remains disabled unless a valid server plan exists;
+- do not click Execute.
+
+### Runtime file verification
+
+Use `/api/futures/status` and `/futures` response headers to compare:
+
+```text
+repository/image overlay template
+repository/image overlay router
+installed /opt/hermes template
+installed /opt/hermes router
+served HTML body
+installation manifest
+```
+
+Interpretation:
+
+- `verified`: all available expected files match;
+- `mismatch`: at least one available expected hash differs;
+- `unknown`: evidence is missing; investigate filesystem/install path.
+
+### Rollback
+
+1. Identify the last known healthy commit.
+2. Revert only the faulty change; do not copy old reference directories over the current backend.
+3. Push the revert.
+4. Wait for Space rebuild and `RUNNING` state.
+5. Repeat runtime audit and browser verification.
+6. Confirm deterministic thresholds, Telegram webhook-only mode, and port 7860 remain unchanged.
+
+### Release evidence to retain
+
+- commit hash;
+- serving Space revision;
+- sanitized audit JSON;
+- static/focused/regression test summary;
+- runtime hash result;
+- Console/Network findings;
+- provider limitations such as Binance 451;
+- explicit statement that no secret was exposed and no trade was executed.
+
+
+---
+
+## Security and Safety
+
+### Non-negotiable invariants
+
+Do not change or weaken:
+
+- deterministic `LONG`, `SHORT`, and `NO_TRADE` decisions;
+- Datasource 4 authority;
+- `noTradeGuard`;
+- Futures verification;
+- provider timestamp and freshness checks;
+- risk approval;
+- Stop Loss and Take Profit rules;
+- leverage caps and volatility haircut;
+- quantity/sizing logic;
+- Paper execution validation;
+- Telegram webhook-only isolation;
+- single FastAPI application and port 7860 architecture.
+
+### Browser trust model
+
+The browser is untrusted for execution. It may display and calculate convenience diagnostics, but the server ignores browser-derived authorization.
+
+Server-side Paper checks include plan reference, symbol/risk identity, expiry, executed flag, direction, DS4 verification, readiness, guard state, risk approval, executable flag, Paper mode, and fresh re-analysis.
+
+### Secret handling
+
+Never expose or commit:
+
+```text
+HF_TOKEN
+HERMES_ADMIN_PASSWORD
+FUTURES_API_KEY
+FUTURES_API_SECRET
+FUTURES_API_PASSPHRASE
+OPENROUTER_API_KEY
+GOOGLE_API_KEY
+TELEGRAM_BOT_TOKEN
+TELEGRAM_WEBHOOK_SECRET
+TELEGRAM_BOOTSTRAP_SECRET
+TELEGRAM_RELAY_SECRET
+cookies or Authorization headers
+```
+
+Diagnostics redact keys and text matching authorization, cookie, token, secret, password, or API key patterns. Continue to sanitize new error fields before they reach API responses or UI.
+
+### Market-data integrity
+
+- No fabricated production candles, prices, funding, Open Interest, or order-book levels.
+- Missing values are `null`/`Unavailable`, not zero.
+- HTTP success is not data freshness.
+- Provider errors in main UI are concise; detailed errors remain sanitized under Technical Diagnostics.
+- Binance regional restriction must not be bypassed with raw IP, DNS override, or disabled TLS.
+
+### External AI boundary
+
+External AI may return market bias, confidence, summary, and warnings. It must never modify:
+
+```text
+decision
+risk approval
+noTradeGuard
+Entry
+Stop Loss
+Take Profit
+leverage
+quantity
+execution availability
+```
+
+Bulk scans must not use advisory AI.
+
+### Telegram boundary
+
+- Webhook secret-token validation is mandatory.
+- Request size is bounded.
+- Owner bootstrap is one-time, secret-checked, and private-chat only.
+- Users are authorized by configured IDs or persisted owner.
+- Commands are rate-limited.
+- Callback nonces expire and are user-bound.
+- Telegram performs analysis only and contains no order path.
+- Polling remains disabled.
+
+### Development safety
+
+During ordinary development and deployment verification:
+
+- do not call Paper Execute;
+- do not run Testnet or Live execution;
+- use the read-only audit script;
+- use Paper account endpoints only for display verification;
+- do not add an execution keyboard shortcut;
+- do not allow a UI feature to write plan or risk state directly.
+
+### Review checklist for security-sensitive changes
+
+- Does the change alter a deterministic threshold or formula?
+- Can fallback data override DS4 safety?
+- Can a missing timestamp be treated as fresh?
+- Can the browser enable execution without server state?
+- Can a raw error include a secret?
+- Can a Telegram request bypass authorization or webhook validation?
+- Does the change introduce a second network service or port?
+- Does it add an exchange credential requirement?
+- Are failure states blocked by default?
+
+
+---
+
+## Operations and Troubleshooting
+
+### Diagnostic order
+
+1. Confirm Space is `RUNNING`.
+2. Fetch `/futures` and inspect response/hash headers.
+3. Check `/api/futures/status` with authentication.
+4. Inspect runtime file status and datasource metadata.
+5. Check Browser Console and Network.
+6. Inspect market endpoint for one symbol/interval.
+7. Compare DS4 raw/normalized fields and timestamps.
+8. Check provider-specific diagnostics.
+9. Run one analysis-only request.
+10. Do not test Paper Execute during diagnosis.
+
+### Common issues
+
+#### Dashboard returns 401
+
+Likely causes:
+
+- missing/incorrect `HERMES_ADMIN_PASSWORD`;
+- wrong Basic username;
+- browser session expired;
+- reverse proxy did not preserve auth.
+
+Actions:
+
+- confirm `HERMES_ADMIN_USERNAME` and `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` alignment;
+- re-authenticate;
+- verify `entrypoint.sh` logged successful auth configuration;
+- never print the password in logs or reports.
+
+#### `/futures` returns 200 but old UI appears
+
+Possible causes:
+
+- stale installed overlay;
+- wrong template path;
+- restored old overlay taking precedence;
+- CDN/browser cache;
+- duplicate old page implementation.
+
+Actions:
+
+- compare `X-Hermes-Template-SHA256` with body hash;
+- inspect `application.runtimeFiles` in status;
+- confirm `/opt/hermesface_overlay` is preferred;
+- confirm installed `/opt/hermes/tools/templates/...` matches manifest;
+- hard reload only after server-side evidence is checked.
+
+#### Runtime status is `unknown`
+
+`unknown` means evidence is absent, not that files match.
+
+Actions:
+
+- verify manifest path and permissions;
+- verify overlay and runtime paths exist;
+- check `HERMES_FUTURES_OVERLAY_MANIFEST`, `HERMES_OVERLAY_SOURCE`, and `HERMES_SYNC_SCRIPT` overrides;
+- inspect overlay installation logs.
+
+#### Runtime status is `mismatch`
+
+Actions:
+
+- identify exact mismatched file in status payload;
+- compare repository/image overlay and `/opt/hermes` file;
+- verify `sync_hf.py` installed after persistence restore;
+- rebuild/redeploy from a clean commit.
+
+#### Chart says market data unavailable
+
+Check market endpoint payload:
+
+- HTTP 503 and `API_UNAVAILABLE`: acquisition exception;
+- `state=unavailable`: no real candles/current price;
+- `state=stale`: provider timestamp invalid or stale;
+- `state=partial`: freshness unknown or display fields incomplete.
+
+Inspect:
+
+```text
+warnings
+missingFields
+analysisRequiredFieldsMissing
+staleRequiredFields
+sourceMetadata
+technicalDiagnostics
+```
+
+Do not replace missing candles with mock data.
+
+#### Binance shows HTTP 451
+
+This is an expected regional limitation in some Hugging Face regions.
+
+Correct behavior:
+
+```text
+transportStatus=restricted
+httpStatus=451
+dataUsability=unavailable
+reason=Regionally restricted
+```
+
+Do not use raw-IP or TLS-bypass workarounds. DS4 safety remains authoritative.
+
+#### KuCoin reports “Parameter 'from' must be milliseconds”
+
+Verify DS4 request builder uses `build_kucoin_time_range()` and sends integer millisecond `from` and `to`. Check for upstream code that converts an already-millisecond value a second time.
+
+#### Market data is HTTP 200 but readiness is blocked
+
+Transport and readiness are separate. Inspect:
+
+- DS4 Futures verification;
+- DS4 `noTradeGuard`;
+- missing critical fields;
+- non-fresh critical fields;
+- merge rejection reasons.
+
+A provider may be reachable while its data is unusable.
+
+#### `NO_TRADE` displayed before analysis
+
+The initial state must be `NOT_ANALYZED`. Check frontend initialization and `/api/futures/status.analysisState`. A network error must be `ANALYSIS_FAILED` or `API_UNAVAILABLE`, not `NO_TRADE`.
+
+#### Signal score shows zero with no components
+
+The UI must show `Unavailable`. Check whether `latestSignalScore` is `null` and whether signal components are empty. Do not coerce null to zero.
+
+#### Execute button is disabled
+
+This is normally correct. Read the visible reason and inspect:
+
+```text
+latest plan exists
+planId matches
+symbol and risk match
+plan not expired
+LONG/SHORT decision
+verified Futures
+risk approved
+noTradeGuard false
+tradingReadiness ready
+executable true
+not already executed
+```
+
+#### Telegram says Owner setup required
+
+No configured/persisted owner exists. Use the one-time private `/claim <TELEGRAM_BOOTSTRAP_SECRET>` flow. Remove/rotate the bootstrap secret after claim. Do not expose owner ID in dashboard status.
+
+#### Telegram proactive alerts unavailable
+
+Webhook responses can work without outbound connectivity, but proactive alerts need either:
+
+- direct Telegram access with optional proxy; or
+- configured relay URL and HMAC secret.
+
+Keep polling disabled.
+
+### Logs and artifacts
+
+Useful logs:
+
+```text
+Space build log
+entrypoint startup log
+sync_hf overlay install/hash log
+Hermes dashboard log under /opt/data/logs
+sanitized runtime audit JSON
+browser Console and Network export without credentials
+```
+
+Never attach raw cookies, Authorization headers, tokens, or unredacted provider payloads.
+
+
+---
+
+## Testing and Verification
+
+### Test locations
+
+```text
+hermes_overlay/tests/
+```
+
+Existing focused areas include:
+
+- Binance public fallback;
+- nested DS4 merge behavior;
+- external advisory boundary;
+- Futures dashboard/state;
+- Futures integration;
+- Luxury template markers;
+- optional MCP runtime isolation;
+- Telegram webhook;
+- trade-cycle field paths.
+
+### Recommended validation layers
+
+#### 1. Static validation
+
+```bash
+python -m compileall hermes_overlay scripts
+node --check /tmp/hermes_dashboard_script.js
+ruff check hermes_overlay scripts
+```
+
+Also check:
+
+- duplicate DOM IDs;
+- missing JavaScript DOM references;
+- undefined CSS custom properties;
+- `git diff --check`;
+- absence of secrets/generated files.
+
+#### 2. Focused unit tests
+
+Required focus:
+
+- seconds-to-milliseconds conversion;
+- already-millisecond timestamps;
+- ordered bounded KuCoin ranges;
+- ticker/funding/Open Interest aliases;
+- malformed and ambiguous provider shapes;
+- per-field source/timestamp/freshness attribution;
+- transport health versus usability/readiness;
+- datasource-specific error attribution;
+- market endpoint canonical shape;
+- no fabricated values;
+- safe rejection when required fields are missing or non-fresh;
+- initial/failure UI states;
+- Execute-disabled reasons and server safety gates.
+
+#### 3. Futures regression suite
+
+Run the existing Futures tests once after focused tests pass. Avoid repeatedly running unrelated broad suites while iterating on a narrow failure.
+
+#### 4. Read-only deployed audit
+
+```bash
+export HERMES_ADMIN_PASSWORD='...'
+python scripts/verify_futures_runtime.py \
+  --base-url https://really-amin-asset.hf.space \
+  --symbol BTCUSDT \
+  --analyze \
+  --report .runtime_audit/futures_runtime_audit.json
+```
+
+The audit never calls Paper Execute.
+
+#### 5. Browser verification
+
+Authenticated desktop and mobile verification must cover:
+
+- Console free of critical errors;
+- valid Network status and JSON payloads;
+- chart rendering for all intervals;
+- Candles/Line, volume, tooltip, crosshair;
+- watchlist/recent/history/export/density/theme/auto-refresh controls;
+- field provenance and datasource cards;
+- state machine and score semantics;
+- visible Execute-disabled reason;
+- no Paper Execute click.
+
+### Acceptance matrix
+
+| Area | Required result |
+|---|---|
+| Runtime files | `verified`, or documented investigation for `unknown`; never unexplained mismatch. |
+| Status API | 200 authenticated, structured source/runtime fields. |
+| Symbols API | Accurate total/verified/market-only counts. |
+| Positions API | Deliberate empty state or formatted real Paper positions. |
+| Market API | Real canonical candles or explicit structured unavailable state. |
+| Analysis API | Deterministic result; `NO_TRADE` is allowed and expected when unsafe. |
+| Paper Execute | Not called during verification. |
+| Binance 451 | Clearly reported as regional restriction. |
+| Telegram | Webhook-only; no polling adapter. |
+| Secrets | None in source, logs, reports, screenshots, or package. |
+
+### Testing safety
+
+Tests must not:
+
+- place Paper/Testnet/Live orders;
+- require real exchange credentials;
+- fabricate production responses in deployed paths;
+- weaken guards to make assertions pass;
+- treat an unavailable score as zero;
+- report missing runtime evidence as verified.
+
+
+---
+
+## Contributing
+
+### Change policy
+
+- Work from the current repository implementation, not old loose reference files.
+- Keep API changes additive and backward-compatible.
+- Keep the existing Hermes application and port 7860.
+- Prefer focused changes with explicit ownership boundaries.
+- Do not accept “implemented” without code review, tests, and deployed evidence.
+
+### Coding style
+
+Python configuration:
+
+```text
+Python target: 3.10+
+line length: 120
+formatter: Black
+lint: Ruff
+```
+
+The runtime image currently uses a newer Python version, but overlay code should remain compatible with the configured project target unless deliberately changed.
+
+### Module ownership
+
+- Acquisition/normalization/provenance: `dual_datasource_client.py`.
+- Binance-only HTTP/normalization: `binance_public_client.py`.
+- Signal/plan orchestration: `trade_cycle.py`.
+- Risk formulas: `risk.py`.
+- Execution behavior: `futures_execution.py`.
+- Bounded dashboard memory: `state.py`.
+- HTTP contracts/runtime diagnostics: `futures_dashboard_api.py`.
+- Visual/UI behavior: Luxury template.
+- Webhook-only Telegram: `telegram_bot.py`.
+- Overlay installation/process startup: `sync_hf.py`.
+
+Do not duplicate logic across layers.
+
+### Adding a field
+
+1. Define the legitimate source and authority.
+2. Add narrow normalization aliases.
+3. Add field validity rules.
+4. Preserve source, provider timestamp, freshness, and fallback status.
+5. Add the field to public bounded metadata only if safe.
+6. Add additive API output.
+7. Render missing value as `Unavailable`.
+8. Add focused tests.
+
+### Changing deterministic logic
+
+A change to score thresholds, weights, SL/TP, leverage, risk profile, sizing, slippage threshold, or expiry is safety-sensitive. The pull request must include:
+
+- motivation;
+- before/after behavior;
+- test coverage;
+- risk analysis;
+- confirmation that DS4 authority and guard behavior remain intact;
+- production verification plan.
+
+### Frontend contributions
+
+- Keep a single template and existing route.
+- Avoid duplicate DOM IDs.
+- Avoid undefined CSS variables.
+- Preserve keyboard accessibility and reduced motion.
+- Never add a second Execute path or an execution shortcut.
+- Do not trust localStorage for plan authorization.
+- Keep raw errors out of primary cards.
+
+### Commit hygiene
+
+Do not stage:
+
+```text
+.env
+credentials
+cookies
+tokens
+.runtime_audit/
+__pycache__/
+*.pyc
+cache files
+runtime state
+screenshots with secrets
+ZIP packages
+temporary probes
+```
+
+### Pull request checklist
+
+- [ ] Scope is focused.
+- [ ] No architecture duplication.
+- [ ] No deterministic guard weakened.
+- [ ] Source attribution remains correct.
+- [ ] Missing/stale data fails closed.
+- [ ] Diagnostics are sanitized.
+- [ ] API is additive.
+- [ ] Static checks pass.
+- [ ] Focused tests pass.
+- [ ] Futures regression suite ran once.
+- [ ] Deployment audit/browser plan is documented.
+- [ ] No trade will be executed during verification.
+
+
+---
+
+## Project Status
+
+### Snapshot
+
+This documentation describes the UI v3 implementation package prepared on 2026-07-21.
+
+Repository base recorded by the implementation package:
+
+```text
+3ff79ee0fce31f8d09a7dac357904169d50d9f3e
+```
+
+Last known deployed revision before this package:
+
+```text
+24d8dad11c0d7316446e9a26b0b074e8630de139
+```
+
+The package itself was not committed, pushed, or deployed by the implementation environment.
+
+### Implemented backend/runtime work
+
+- packaged Luxury template is the runtime source;
+- overlay installation and SHA-256 manifest;
+- runtime status `verified` / `mismatch` / `unknown`;
+- no-cache Futures responses;
+- KuCoin millisecond range construction;
+- conservative DS4 Futures verification;
+- DS4/Binance/DS2 normalization and priority;
+- per-field provenance and truthful freshness;
+- structured source health and merge readiness;
+- real market endpoint with four intervals;
+- explicit partial/stale/unavailable semantics;
+- deterministic state machine and non-executable plan semantics;
+- server-side plan/symbol/risk/expiry/readiness/risk revalidation;
+- stronger diagnostic redaction;
+- read-only runtime audit utility;
+- Telegram webhook-only and Linear MCP isolation preserved.
+
+### Implemented UI v3 work
+
+- watchlist and recent markets;
+- manual/automatic refresh and density/theme controls;
+- keyboard help without execution shortcut;
+- Candles/Line chart, volume, crosshair, tooltip, four intervals, three limits;
+- market header, source/freshness/readiness, order-book top values;
+- display-only diagnostics;
+- per-field provenance;
+- plan geometry and execution checklist;
+- analysis copy/export/history/activity;
+- expanded datasource and technical diagnostics;
+- responsive desktop/tablet/mobile layout.
+
+### Validation already recorded
+
+Static validation reported:
+
+- modified Python files compiled;
+- dashboard JavaScript passed `node --check`;
+- DOM ID and static reference checks passed;
+- CSS custom-property checks passed;
+- whitespace checks passed;
+- package ZIP integrity passed.
+
+Behavioral tests, Futures regression tests, authenticated production verification, and deployment were deferred.
+
+### Remaining production work
+
+1. Review documentation and final code diff.
+2. Run focused tests and existing Futures regression suite.
+3. Verify real DS4 field names and timestamps.
+4. Perform one safe KuCoin read-only request.
+5. Deploy through the repository/Hugging Face workflow.
+6. Run authenticated read-only audit.
+7. Inspect Browser Console and Network.
+8. Verify real market rendering for all intervals and UI features.
+9. Run one BTCUSDT analysis-only request.
+10. Confirm Telegram webhook-only mode and Linear MCP isolation.
+11. Record commit hash and serving Space revision.
+12. Confirm no secret exposure and no trade execution.
+
+
+---

README.md

@@ -6,4 +6,54 @@ colorFrom: green
 colorTo: green
 pinned: false
 app_port: 7860
----
+---
+
+# HermesFace / Hermes Futures Desk
+
+HermesFace runs the NousResearch Hermes Agent on Hugging Face Spaces and adds an authenticated, deterministic cryptocurrency Futures analysis desk.
+
+The Futures Desk is **analysis-first, safety-first, and Paper-trading-first**. Datasource 4 remains the authority for Futures verification and safety. Binance public data is a field-level fallback, Datasource 2 is complementary context, and External AI is advisory only.
+
+## Quick links
+
+- [Developer documentation index](docs/README.md)
+- [Complete developer guide](docs/DEVELOPER_GUIDE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [API reference](docs/API_REFERENCE.md)
+- [Datasource contracts](docs/DATA_PIPELINE_AND_CONTRACTS.md)
+- [Frontend guide](docs/FRONTEND_GUIDE.md)
+- [Environment reference](docs/ENVIRONMENT_CONFIGURATION.md)
+- [Deployment runbook](docs/DEPLOYMENT_RUNBOOK.md)
+- [Security and safety](docs/SECURITY_AND_SAFETY.md)
+- [Operations and troubleshooting](docs/OPERATIONS_AND_TROUBLESHOOTING.md)
+- [Testing and verification](docs/TESTING_AND_VERIFICATION.md)
+- [Contributing](docs/CONTRIBUTING.md)
+- [Current implementation status](docs/PROJECT_STATUS.md)
+
+## Repository entry points
+
+```text
+app.py
+Dockerfile
+scripts/entrypoint.sh
+scripts/sync_hf.py
+hermes_overlay/tools/futures_dashboard_api.py
+hermes_overlay/tools/templates/hermes_futures_desk_luxury.html
+hermes_overlay/trading/trade_cycle.py
+hermes_overlay/trading/dual_datasource_client.py
+```
+
+## Local container start
+
+```bash
+cp .env.example .env
+# Fill required secrets without committing the file.
+docker build -t hermesface .
+docker run --rm -p 7860:7860 --env-file .env hermesface
+```
+
+Open `http://localhost:7860/futures` and authenticate with the configured Hermes dashboard credentials.
+
+## Safety notice
+
+Do not weaken deterministic decisions, Datasource 4 authority, `noTradeGuard`, freshness checks, Futures verification, risk approval, Stop Loss / Take Profit, leverage, sizing, Paper execution validation, or Telegram webhook-only isolation. Do not use fabricated production market data. Do not execute Paper, Testnet, or Live trades during routine development verification.

docs/API_REFERENCE.md

@@ -0,0 +1,287 @@
+# API Reference
+
+## Base and authentication
+
+All Futures routes are mounted on the existing Hermes FastAPI application and port. In production, use the Space base URL and an authenticated browser/session or HTTP Basic credentials.
+
+When `HERMES_ADMIN_PASSWORD` is set, Futures API routes require:
+
+```http
+Authorization: Basic <base64(username:password)>
+```
+
+Default username: `admin`, configurable with `HERMES_DASHBOARD_BASIC_AUTH_USERNAME`.
+
+All Futures responses set `Cache-Control: no-store`. `/futures` also sets no-cache headers and runtime SHA-256 headers.
+
+## `GET /futures`
+
+Returns the packaged HTML dashboard.
+
+Important response headers:
+
+```text
+X-Hermes-Template-SHA256
+X-Hermes-Router-SHA256
+Cache-Control: no-store, no-cache, must-revalidate, max-age=0
+```
+
+## `GET /api/futures/status`
+
+Returns application status, runtime-file evidence, market health, latest bounded plan state, source metadata, account summary, and diagnostics.
+
+Representative shape:
+
+```json
+{
+  "application": {
+    "status": "online",
+    "runtimeStatus": "verified | mismatch | unknown",
+    "runtimeFiles": {}
+  },
+  "marketData": {"status": "healthy | degraded | unavailable"},
+  "tradingReadiness": "ready | blocked",
+  "mergeStatus": "complete | partial | unknown",
+  "analysisState": "NOT_ANALYZED",
+  "sourceMetadata": {
+    "datasource4": {},
+    "binance": {},
+    "datasource2": {}
+  },
+  "fieldSources": {},
+  "fieldMetadata": {},
+  "verifiedFutures": false,
+  "missingRequiredFields": [],
+  "staleRequiredFields": [],
+  "latestTradePlan": null,
+  "latestPlanId": null,
+  "latestSignalScore": null,
+  "riskApproved": false,
+  "tradingMode": "paper",
+  "equity": 10000.0,
+  "realizedPnlToday": 0.0,
+  "openPositionCount": 0,
+  "serverTime": 0
+}
+```
+
+Consumers should treat additional fields as additive and avoid strict whole-object equality.
+
+## `GET /api/futures/symbols`
+
+Returns the merged catalog.
+
+```json
+{
+  "symbols": [
+    {
+      "symbol": "BTCUSDT",
+      "baseAsset": "BTC",
+      "quoteAsset": "USDT",
+      "futuresVerified": true,
+      "marketOnly": false,
+      "contractType": "PERPETUAL",
+      "status": "TRADING",
+      "source": "datasource4",
+      "rank": 1,
+      "updatedAt": "2026-07-21T00:00:00Z"
+    }
+  ],
+  "source": "...",
+  "updatedAt": "...",
+  "counts": {
+    "total": 0,
+    "verifiedFutures": 0,
+    "marketOnly": 0
+  }
+}
+```
+
+Catalog membership alone does not authorize execution. Only items with `futuresVerified=true` are eligible for Paper revalidation.
+
+## `GET /api/futures/positions`
+
+Returns Paper mode and enriched open positions.
+
+```json
+{
+  "mode": "paper",
+  "positions": [
+    {
+      "symbol": "BTC/USDT:USDT",
+      "side": "long",
+      "size": 0.01,
+      "entryPrice": 60000.0,
+      "markPrice": 60500.0,
+      "unrealizedPnl": 5.0
+    }
+  ]
+}
+```
+
+Mark price enrichment is best-effort. Missing mark data produces `null`, not zero.
+
+## `GET /api/futures/market`
+
+Query parameters:
+
+| Parameter | Type | Default | Constraints |
+|---|---|---:|---|
+| `symbol` | string | `BTCUSDT` | length 3–32; normalized server-side |
+| `interval` | enum | `5m` | `1m`, `5m`, `15m`, `1h` |
+| `limit` | integer | `120` | 20–500 |
+
+Example:
+
+```http
+GET /api/futures/market?symbol=BTCUSDT&interval=5m&limit=120
+```
+
+Successful/partial shape:
+
+```json
+{
+  "state": "available | partial | stale | unavailable",
+  "analysisState": "NOT_ANALYZED | STALE | API_UNAVAILABLE",
+  "dataUsability": "usable | degraded | unavailable",
+  "reason": null,
+  "symbol": "BTCUSDT",
+  "interval": "5m",
+  "limit": 120,
+  "candles": [
+    {"timestamp": 0, "open": 0, "high": 0, "low": 0, "close": 0, "volume": 0}
+  ],
+  "currentPrice": null,
+  "markPrice": null,
+  "change24h": null,
+  "volume24h": null,
+  "fundingRate": null,
+  "openInterest": null,
+  "source": "datasource4 | binance_public | datasource2 | mixed | unavailable",
+  "sourcesUsed": [],
+  "fieldSources": {},
+  "fieldMetadata": {},
+  "freshness": "fresh | stale | invalid | unknown",
+  "verifiedFutures": false,
+  "futuresVerification": {},
+  "warnings": [],
+  "missingFields": [],
+  "analysisRequiredFieldsMissing": [],
+  "staleRequiredFields": [],
+  "mergeStatus": "complete | partial | unavailable",
+  "tradingReadiness": "ready | blocked",
+  "rejectionReasons": [],
+  "sourceMetadata": {},
+  "technicalDiagnostics": {},
+  "fetchedAt": 0
+}
+```
+
+If acquisition raises, the route returns HTTP `503` with the same high-level keys, empty candles, null values, `state=unavailable`, `analysisState=API_UNAVAILABLE`, and blocked readiness.
+
+No mock candles are permitted in production responses.
+
+## `POST /api/futures/analyze`
+
+Request:
+
+```json
+{
+  "symbol": "BTCUSDT",
+  "risk_profile": "moderate",
+  "include_external_context": false
+}
+```
+
+Allowed risk profiles:
+
+```text
+conservative
+moderate
+aggressive
+```
+
+Unknown request fields are rejected.
+
+Representative response:
+
+```json
+{
+  "planId": "server-generated-reference",
+  "symbol": "BTCUSDT",
+  "decision": "LONG | SHORT | NO_TRADE",
+  "analysis_state": "LONG | SHORT | NO_TRADE",
+  "score": null,
+  "confidence": null,
+  "components": {},
+  "core_reasons": [],
+  "warnings": [],
+  "entry": null,
+  "stop_loss": null,
+  "take_profit": null,
+  "reward_to_risk": null,
+  "risk_profile": "moderate",
+  "risk_percent": null,
+  "requested_leverage": 5,
+  "effective_leverage": null,
+  "quantity": null,
+  "estimated_slippage_percent": null,
+  "risk_approved": false,
+  "rejection_reasons": [],
+  "noTradeGuard": true,
+  "plan_type": "directional_plan | non_executable_plan",
+  "executable": false,
+  "futuresVerified": false,
+  "trading_readiness": "blocked",
+  "created_at": "...",
+  "expires_at": "...",
+  "external_advisory": null
+}
+```
+
+A `NO_TRADE` response is a successful deterministic evaluation, not an HTTP failure. An internal analysis failure returns HTTP `503` with `detail="Futures analysis failed"` and clears the current plan state.
+
+## `POST /api/futures/paper/execute`
+
+Request:
+
+```json
+{
+  "symbol": "BTCUSDT",
+  "risk_profile": "moderate",
+  "planId": "server-generated-reference"
+}
+```
+
+The endpoint may return:
+
+- `403` for unverified contract or non-Paper mode;
+- `409` for superseded/unknown plan, symbol/risk change, expiry, prior execution, blocked readiness, failed fresh revalidation, or non-executable plan;
+- `422` for invalid request shape/symbol;
+- `200` for the final Paper result.
+
+The endpoint is intentionally absent from the read-only audit tool.
+
+## Telegram routes
+
+### `POST /api/telegram/webhook`
+
+Public webhook ingress protected by:
+
+```http
+X-Telegram-Bot-Api-Secret-Token: <TELEGRAM_WEBHOOK_SECRET>
+```
+
+Limits request body to 256 KiB, applies per-user rate limiting, requires owner/allowed-user authorization, and invokes analysis-only commands.
+
+### `GET /api/telegram/status`
+
+Returns enabled/mode/webhook/proxy/relay/authorized-user/alert-scheduler status. It does not expose tokens or user IDs.
+
+### `GET /api/telegram/bootstrap/status`
+
+Requires the same Telegram secret header and returns only:
+
+```json
+{"ok": true, "ownerClaimed": true, "bootstrapConsumed": true}
+```

docs/ARCHITECTURE.md

@@ -0,0 +1,110 @@
+# Architecture
+
+## System context
+
+```mermaid
+flowchart LR
+    U[Authenticated browser] -->|same-origin HTTPS| H[Hermes dashboard / FastAPI :7860]
+    T[Telegram webhook] --> H
+    H --> R[Futures dashboard router]
+    R --> C[Deterministic trade cycle]
+    R --> S[Dashboard state]
+    C --> D[Dual datasource client]
+    D --> DS4[Datasource 4\nAuthoritative]
+    D --> B[Binance public\nFallback]
+    D --> DS2[Datasource 2\nComplementary]
+    C --> K[Risk / sizing]
+    C --> E[Paper execution]
+    C -. advisory only .-> A[External AI]
+```
+
+## Container and filesystem architecture
+
+```mermaid
+flowchart TD
+    I[Docker image] --> O1[/opt/hermesface_overlay\nimmutable current-image overlay]
+    I --> O2[/opt/data/hermes_overlay\npersisted/restored copy]
+    I --> S[/opt/data/scripts]
+    B[scripts/entrypoint.sh] --> Y[scripts/sync_hf.py]
+    Y -->|prefer| O1
+    Y -->|fallback only| O2
+    Y -->|copy modules| H[/opt/hermes]
+    Y --> M[overlay manifest]
+    Y --> P[patch existing dashboard router]
+    P --> W[Hermes dashboard :7860]
+```
+
+The immutable `/opt/hermesface_overlay` is preferred so a restored dataset containing an older overlay cannot downgrade the current image.
+
+## Layer responsibilities
+
+### HTTP and UI layer
+
+`futures_dashboard_api.py` owns request validation, authentication dependency, response shaping, runtime diagnostics, and browser-facing error semantics. It does not implement signal scoring or sizing.
+
+### Datasource layer
+
+`dual_datasource_client.py` owns:
+
+- HTTP acquisition;
+- KuCoin-compatible time range construction;
+- nested payload discovery;
+- field normalization;
+- source priority;
+- field provenance;
+- source health metadata;
+- `noTradeGuard`, missing-field, stale-field, merge, and readiness results.
+
+### Decision layer
+
+`trade_cycle.py` owns deterministic score calculation, decision thresholds, SL/TP construction, risk module orchestration, plan expiry, and optional execution handoff.
+
+### Risk layer
+
+`risk.py` owns risk profile lookup, leverage caps, volatility haircut, quantity calculation, margin/notional gates, daily-loss and position-count gates.
+
+### Execution layer
+
+`futures_execution.py` owns Paper mode, account/position state, exchange adapter boundaries, slippage estimation, and protective order behavior. The dashboard route never directly constructs an exchange order.
+
+### State layer
+
+`state.py` stores only a bounded view of the latest context/plan for the dashboard. It removes raw exchange payloads and does not authorize any decision.
+
+## Trust boundaries
+
+| Boundary | Trusted for decisions? | Notes |
+|---|---|---|
+| Browser controls and localStorage | No | Convenience only; server revalidates everything. |
+| Datasource 4 | Yes, for verification/safety | Still subject to parsing, freshness, and completeness checks. |
+| Binance public | No, as authority | Field fallback only; cannot clear DS4 guard. |
+| Datasource 2 | No, as authority | Complementary context only. |
+| External AI | No | Advisory explanation only. |
+| Telegram input | No | Authorized, rate-limited, analysis-only commands. |
+| Server-side latest plan | Partially | Must still pass freshness and execution revalidation. |
+
+## Router installation
+
+`sync_hf.py` modifies the existing Hermes dashboard code to include:
+
+```python
+from tools.futures_dashboard_api import router as _futures_dashboard_router
+app.include_router(_futures_dashboard_router)
+from tools.telegram_bot import router as _telegram_router
+app.include_router(_telegram_router)
+```
+
+The patch is idempotent and must not create a new FastAPI app.
+
+## Persistence
+
+Hermes data under `/opt/data` may be synchronized to a private Hugging Face Dataset. The repository overlay is also copied into the image, but the immutable image overlay is the source used for installation. Runtime state such as Telegram owner data and symbol cache lives under `/opt/data` and must not be committed.
+
+## Failure behavior
+
+- DS4 unreachable: merge may use fallback data for display, but Futures verification/readiness remains blocked.
+- Binance HTTP 451: source status is restricted/unavailable; no bypass is attempted.
+- DS2 unavailable: complementary context is degraded; it does not independently block a plan unless it was the only attempted fill for a still-missing field.
+- Market endpoint exception: HTTP 503 with structured `API_UNAVAILABLE` payload.
+- Analysis exception: HTTP 503, state becomes `ANALYSIS_FAILED`, previous plan is cleared from current state.
+- Template read failure: minimal fallback page is served and trading remains blocked.

docs/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing
+
+## Change policy
+
+- Work from the current repository implementation, not old loose reference files.
+- Keep API changes additive and backward-compatible.
+- Keep the existing Hermes application and port 7860.
+- Prefer focused changes with explicit ownership boundaries.
+- Do not accept “implemented” without code review, tests, and deployed evidence.
+
+## Coding style
+
+Python configuration:
+
+```text
+Python target: 3.10+
+line length: 120
+formatter: Black
+lint: Ruff
+```
+
+The runtime image currently uses a newer Python version, but overlay code should remain compatible with the configured project target unless deliberately changed.
+
+## Module ownership
+
+- Acquisition/normalization/provenance: `dual_datasource_client.py`.
+- Binance-only HTTP/normalization: `binance_public_client.py`.
+- Signal/plan orchestration: `trade_cycle.py`.
+- Risk formulas: `risk.py`.
+- Execution behavior: `futures_execution.py`.
+- Bounded dashboard memory: `state.py`.
+- HTTP contracts/runtime diagnostics: `futures_dashboard_api.py`.
+- Visual/UI behavior: Luxury template.
+- Webhook-only Telegram: `telegram_bot.py`.
+- Overlay installation/process startup: `sync_hf.py`.
+
+Do not duplicate logic across layers.
+
+## Adding a field
+
+1. Define the legitimate source and authority.
+2. Add narrow normalization aliases.
+3. Add field validity rules.
+4. Preserve source, provider timestamp, freshness, and fallback status.
+5. Add the field to public bounded metadata only if safe.
+6. Add additive API output.
+7. Render missing value as `Unavailable`.
+8. Add focused tests.
+
+## Changing deterministic logic
+
+A change to score thresholds, weights, SL/TP, leverage, risk profile, sizing, slippage threshold, or expiry is safety-sensitive. The pull request must include:
+
+- motivation;
+- before/after behavior;
+- test coverage;
+- risk analysis;
+- confirmation that DS4 authority and guard behavior remain intact;
+- production verification plan.
+
+## Frontend contributions
+
+- Keep a single template and existing route.
+- Avoid duplicate DOM IDs.
+- Avoid undefined CSS variables.
+- Preserve keyboard accessibility and reduced motion.
+- Never add a second Execute path or an execution shortcut.
+- Do not trust localStorage for plan authorization.
+- Keep raw errors out of primary cards.
+
+## Commit hygiene
+
+Do not stage:
+
+```text
+.env
+credentials
+cookies
+tokens
+.runtime_audit/
+__pycache__/
+*.pyc
+cache files
+runtime state
+screenshots with secrets
+ZIP packages
+temporary probes
+```
+
+## Pull request checklist
+
+- [ ] Scope is focused.
+- [ ] No architecture duplication.
+- [ ] No deterministic guard weakened.
+- [ ] Source attribution remains correct.
+- [ ] Missing/stale data fails closed.
+- [ ] Diagnostics are sanitized.
+- [ ] API is additive.
+- [ ] Static checks pass.
+- [ ] Focused tests pass.
+- [ ] Futures regression suite ran once.
+- [ ] Deployment audit/browser plan is documented.
+- [ ] No trade will be executed during verification.

docs/DATA_PIPELINE_AND_CONTRACTS.md

@@ -0,0 +1,249 @@
+# Datasource Pipeline and Contracts
+
+## Priority and authority
+
+```text
+Datasource 4 → Binance public fallback → Datasource 2
+```
+
+Priority describes fill order, not equal trust.
+
+### Datasource 4
+
+Authoritative for:
+
+- Futures contract verification;
+- `dataState`;
+- `noTradeGuard`;
+- safety status and rejection reasons;
+- primary Futures market fields.
+
+### Binance public
+
+- unauthenticated;
+- called only for missing, unusable, or stale fields;
+- cannot verify a contract or clear DS4 safety;
+- HTTP 451 is `restricted` / `Regionally restricted`;
+- provider timestamps are required to claim freshness.
+
+### Datasource 2
+
+- complementary news, sentiment, indicator, order-book, volume, trending, gainers, and correlation context;
+- may fill a still-missing legitimate field only after Binance;
+- cannot become Futures verification or safety authority.
+
+## Datasource 4 request
+
+The DS4 snapshot endpoint is called with:
+
+```text
+/api/short-hunter/snapshot/{SYMBOL}
+```
+
+Parameters:
+
+```text
+interval: 1m | 5m | 15m | 1h
+limit: 1..500 internally; market API exposes 20..500
+from: epoch milliseconds
+to: epoch milliseconds
+```
+
+`normalize_epoch_milliseconds()` accepts contemporary epoch seconds or milliseconds and prevents double conversion. `build_kucoin_time_range()` enforces supported interval, bounded limit, positive ordered timestamps, and millisecond units.
+
+## Normalized fields
+
+The merged envelope may contain:
+
+```text
+contract
+ticker
+ohlcv
+orderbook
+funding
+openInterest
+indicators
+sentiment
+atr
+market_context
+```
+
+### Contract
+
+Normalized contract data should expose symbol, status, type/instrument, and explicit verification evidence when present. The presence of a generic `contract` object alone does not prove Futures status. Verification requires an explicit DS4 flag or a recognized Futures/perpetual/swap contract type.
+
+### Ticker
+
+Accepted aliases are normalized to a bounded ticker object. Consumers should prefer normalized canonical keys where available and tolerate provider-specific supplemental keys.
+
+Common price candidates:
+
+```text
+markPrice
+lastPrice
+last
+price
+close
+indexPrice
+```
+
+### OHLCV
+
+Canonical candle shape:
+
+```json
+{
+  "timestamp": 0,
+  "open": 0.0,
+  "high": 0.0,
+  "low": 0.0,
+  "close": 0.0,
+  "volume": 0.0
+}
+```
+
+A usable OHLCV series requires at least four valid positive close values. The market endpoint never invents missing candles.
+
+### Order book
+
+Canonical shape:
+
+```json
+{
+  "bids": [[60000.0, 0.5]],
+  "asks": [[60001.0, 0.4]],
+  "timestamp": 0
+}
+```
+
+Both sides must have at least one valid level. Prices must be positive; quantities must be non-negative.
+
+### Funding
+
+Canonical values may include:
+
+```text
+currentFundingRate
+fundingRate
+lastFundingRate
+rate
+nextFundingTime
+```
+
+### Open Interest
+
+Canonical values may include:
+
+```text
+openInterest
+sumOpenInterest
+oi
+changeFraction
+change24h
+changePercent
+```
+
+## Field usability
+
+`_is_usable(field, value)` performs field-specific validation. Empty values, non-finite values, invalid OHLCV, incomplete order books, and invalid contract/funding/OI shapes are rejected.
+
+## Per-field provenance
+
+Every owned field receives metadata:
+
+```json
+{
+  "value": "bounded or summarized value",
+  "source": "datasource4 | binance_public | datasource2 | unavailable",
+  "timestamp": "provider timestamp or null",
+  "freshness": "fresh | stale | invalid | unknown",
+  "validity": "valid | unavailable",
+  "observedAt": "server observation time",
+  "freshnessBasis": "field_timestamp | datasource4_dataState | missing_provider_timestamp | unavailable",
+  "fallbackStatus": "primary | fallback | not_filled"
+}
+```
+
+The public API bounds large values:
+
+- OHLCV becomes count plus latest candle summary where appropriate;
+- order book becomes level counts and best bid/ask summary;
+- diagnostics are sanitized and size-limited.
+
+## Freshness
+
+Freshness is based on provider timestamp relative to interval, or on an explicit authoritative DS4 fresh state. Transport success alone is not freshness evidence.
+
+Required fields with `stale`, `invalid`, or `unknown` freshness block readiness.
+
+## Critical fields and readiness
+
+Critical fields:
+
+```text
+contract
+ticker
+orderbook
+funding
+openInterest
+```
+
+The combined context sets:
+
+```text
+missingRequiredFields
+staleRequiredFields
+noTradeGuard
+noTradeReasons
+mergeStatus
+tradingReadiness
+```
+
+Readiness is `ready` only when no guard remains. DS4 verification failure, DS4 `noTradeGuard`, missing critical fields, or non-fresh critical fields results in `blocked`.
+
+## Source metadata
+
+Each source returns structured fields:
+
+```json
+{
+  "name": "Datasource 4",
+  "url": "...",
+  "status": "ok | degraded | unreachable | unavailable | standby",
+  "transportStatus": "healthy | degraded | unavailable | restricted | standby",
+  "dataUsability": "usable | degraded | unavailable | not_used",
+  "endpoint": "...",
+  "httpStatus": 200,
+  "latencyMs": 120.4,
+  "lastSuccess": "...",
+  "freshness": "fresh | stale | unknown",
+  "completeness": "complete | partial | unknown",
+  "suppliedFields": [],
+  "missingFields": [],
+  "reason": "concise operator-facing summary"
+}
+```
+
+Detailed endpoint/provider errors belong only under `technicalDiagnostics`, separated by source and sanitized before exposure.
+
+## Merge diagnostics
+
+Cross-source problems are not assigned to a datasource card. They appear under:
+
+```text
+technicalDiagnostics.merge.status
+technicalDiagnostics.merge.missingCriticalFields
+technicalDiagnostics.merge.tradingReadiness
+technicalDiagnostics.merge.rejectionReasons
+```
+
+## Adding a new provider mapping
+
+1. Capture a real redacted payload.
+2. Add the narrowest legitimate alias to the relevant normalizer.
+3. Preserve provider timestamp and source name.
+4. Add field-specific validity checks.
+5. Do not infer Futures verification from generic market data.
+6. Do not let the provider clear DS4 guard state.
+7. Add focused tests for positive, missing, malformed, stale, and ambiguous cases.
+8. Verify source-specific diagnostics remain correctly attributed.

docs/DEPLOYMENT_RUNBOOK.md

@@ -0,0 +1,127 @@
+# Deployment Runbook
+
+## Preconditions
+
+- Work from the current repository under `asset-space`.
+- Review all diffs.
+- Ensure no real `.env`, tokens, cookies, screenshots, cache, ZIP archives, runtime reports, or temporary probes are staged.
+- Confirm no architecture change introduces a second app, frontend server, or port.
+- Do not execute a trade during deployment verification.
+
+## Build behavior
+
+The Dockerfile:
+
+1. clones upstream Hermes Agent into `/opt/hermes`;
+2. installs Node, web dashboard, Playwright, Python, CCXT, and HTTPX dependencies;
+3. creates non-root user `hermes` and `/opt/data` directories;
+4. copies scripts into `/opt/data/scripts`;
+5. copies overlay into `/opt/data/hermes_overlay` and immutable `/opt/hermesface_overlay`;
+6. starts `/opt/data/scripts/entrypoint.sh`.
+
+## Startup behavior
+
+`entrypoint.sh`:
+
+1. starts DNS pre-resolution in the background;
+2. activates `/opt/hermes/.venv`;
+3. creates persistent directories and baseline config files;
+4. writes hashed dashboard Basic auth when `HERMES_ADMIN_PASSWORD` is configured;
+5. calls `scripts/sync_hf.py`.
+
+`sync_hf.py`:
+
+1. restores persistent data when configured;
+2. disables legacy Telegram gateway polling in webhook mode;
+3. installs the current image overlay into `/opt/hermes`;
+4. writes and verifies the overlay hash manifest;
+5. mounts Futures and Telegram routers into the existing dashboard app;
+6. starts Hermes dashboard on port `7860`;
+7. manages persistence/sync helpers.
+
+## Hugging Face deployment procedure
+
+1. Review the final diff.
+2. Commit the smallest coherent change.
+3. Push to `main` of the repository backing `Really-amin/Asset`.
+4. Monitor Space build logs.
+5. Wait until Space is fully `RUNNING`.
+6. Record the serving repository revision.
+7. Run the read-only runtime audit.
+8. Open an authenticated browser session.
+9. Inspect Console and Network.
+10. Verify Telegram status and MCP isolation.
+
+## Read-only runtime audit
+
+```bash
+export HERMES_ADMIN_PASSWORD='...'
+export HERMES_DASHBOARD_BASIC_AUTH_USERNAME='admin'
+python scripts/verify_futures_runtime.py \
+  --base-url https://really-amin-asset.hf.space \
+  --symbol BTCUSDT \
+  --analyze \
+  --report .runtime_audit/futures_runtime_audit.json
+```
+
+Expected properties:
+
+- `/futures` returns 200;
+- body SHA-256 equals `X-Hermes-Template-SHA256`;
+- status, symbols, and positions return authenticated 200 responses;
+- each market interval returns 200 or structured 503;
+- market payload shape includes real canonical candle objects;
+- optional analysis returns 200;
+- `paperExecuteCalled` remains false.
+
+## Browser verification
+
+Check:
+
+- no critical JavaScript error;
+- authenticated API requests are not redirected to login HTML;
+- `/api/futures/market` is requested for each selected interval;
+- chart code executes and state messages match payload;
+- no stale cached template is served;
+- selected-market header, provenance, diagnostics, plan, account, and datasource sections render;
+- Execute remains disabled unless a valid server plan exists;
+- do not click Execute.
+
+## Runtime file verification
+
+Use `/api/futures/status` and `/futures` response headers to compare:
+
+```text
+repository/image overlay template
+repository/image overlay router
+installed /opt/hermes template
+installed /opt/hermes router
+served HTML body
+installation manifest
+```
+
+Interpretation:
+
+- `verified`: all available expected files match;
+- `mismatch`: at least one available expected hash differs;
+- `unknown`: evidence is missing; investigate filesystem/install path.
+
+## Rollback
+
+1. Identify the last known healthy commit.
+2. Revert only the faulty change; do not copy old reference directories over the current backend.
+3. Push the revert.
+4. Wait for Space rebuild and `RUNNING` state.
+5. Repeat runtime audit and browser verification.
+6. Confirm deterministic thresholds, Telegram webhook-only mode, and port 7860 remain unchanged.
+
+## Release evidence to retain
+
+- commit hash;
+- serving Space revision;
+- sanitized audit JSON;
+- static/focused/regression test summary;
+- runtime hash result;
+- Console/Network findings;
+- provider limitations such as Binance 451;
+- explicit statement that no secret was exposed and no trade was executed.

docs/DEVELOPER_GUIDE.md

@@ -0,0 +1,299 @@
+# Hermes Futures Desk — Complete Developer Guide
+
+## 1. Purpose
+
+Hermes Futures Desk is an authenticated Futures analysis and risk-management layer installed into the existing Hermes Agent runtime. It discovers markets, normalizes real market data, produces deterministic `LONG`, `SHORT`, or `NO_TRADE` outcomes, calculates a bounded trade plan, applies server-side risk controls, and optionally routes a fully revalidated plan to the existing Paper execution path.
+
+The system is intentionally conservative:
+
+- Datasource 4 is authoritative for Futures verification and safety.
+- Binance public data may fill missing or unusable market fields but cannot override DS4 safety.
+- Datasource 2 provides complementary context only.
+- External AI provides advisory explanation only.
+- The browser is never trusted to authorize execution.
+- No new web server, FastAPI application, port, or trading engine is created.
+
+## 2. Runtime summary
+
+```text
+Hugging Face Space / Docker container
+└── /opt/hermes                         Upstream Hermes Agent source/runtime
+    ├── dashboard on 0.0.0.0:7860      Existing Hermes web application
+    ├── tools/futures_dashboard_api.py  Installed repository overlay
+    ├── tools/templates/...html         Installed Luxury dashboard template
+    ├── trading/*                       Installed Futures modules
+    └── .hermes_futures_overlay_manifest.json
+
+/opt/data
+├── scripts/                            Entrypoint, persistence, runtime audit
+├── hermes_overlay/                     Restored/persisted copy; not preferred over image overlay
+├── futures_symbols_cache.json          Optional symbol cache
+├── telegram_state.json                 Telegram owner/watchlist/alert state
+└── persistent Hermes data
+
+/opt/hermesface_overlay                 Immutable overlay copied from the current image
+```
+
+The Docker image clones Hermes Agent into `/opt/hermes`, installs Python/Node dependencies, copies repository scripts into `/opt/data/scripts`, and copies the current overlay into both `/opt/data/hermes_overlay` and `/opt/hermesface_overlay`. At startup, `scripts/sync_hf.py` installs the overlay into `/opt/hermes`, writes a SHA-256 manifest, patches the existing Hermes dashboard to include the routers, and starts the dashboard on port `7860`.
+
+## 3. Main modules
+
+| Module | Responsibility |
+|---|---|
+| `scripts/entrypoint.sh` | Runtime directory creation, dashboard auth configuration, and handoff to `sync_hf.py`. |
+| `scripts/sync_hf.py` | Persistence restore/sync, overlay installation, manifest generation, router mounting, Telegram polling isolation, and process startup. |
+| `hermes_overlay/tools/futures_dashboard_api.py` | Authenticated Futures HTTP routes, runtime file diagnostics, symbol catalog, market endpoint, analysis route, and Paper revalidation route. |
+| `hermes_overlay/tools/templates/hermes_futures_desk_luxury.html` | Luxury Obsidian & Gold single-page dashboard. |
+| `hermes_overlay/trading/dual_datasource_client.py` | DS4 → Binance → DS2 acquisition, normalization, provenance, health metadata, and `noTradeGuard` aggregation. |
+| `hermes_overlay/trading/binance_public_client.py` | Unauthenticated Binance Futures fallback and explicit regional-restriction reporting. |
+| `hermes_overlay/trading/trade_cycle.py` | Deterministic signal scoring, SL/TP construction, risk sizing, plan creation, and optional Paper orchestration. |
+| `hermes_overlay/trading/risk.py` | Risk profiles, leverage caps/haircut, quantity sizing, and hard risk gates. |
+| `hermes_overlay/trading/futures_execution.py` | Existing Paper account/position book and execution validation. |
+| `hermes_overlay/trading/state.py` | Bounded in-memory dashboard state; no decision authority. |
+| `hermes_overlay/trading/symbols.py` | Symbol normalization for DS4 and CCXT formats. |
+| `hermes_overlay/external_ai/advisory.py` | Optional OpenRouter → Google → Hugging Face advisory chain. |
+| `hermes_overlay/tools/telegram_bot.py` | Webhook-only, analysis-only Telegram adapter and owner bootstrap. |
+| `scripts/verify_futures_runtime.py` | Read-only deployed runtime audit; never calls Paper Execute. |
+
+## 4. End-to-end request flow
+
+### 4.1 Market display
+
+1. Browser requests `GET /api/futures/market` with symbol, interval, and limit.
+2. Router normalizes the symbol and calls `get_market_context()`.
+3. Datasource client requests DS4 with bounded KuCoin-compatible millisecond `from`/`to` parameters.
+4. Missing, unusable, or stale fields are requested from Binance public fallback.
+5. Datasource 2 is queried for complementary context and may fill only still-missing legitimate fields.
+6. Each normalized field receives source, timestamp, freshness, validity, and fallback metadata.
+7. The endpoint returns only real normalized values or an explicit `partial`, `stale`, or `unavailable` state.
+8. The browser renders charts and diagnostics without modifying server decisions.
+
+### 4.2 Deterministic analysis
+
+1. Browser sends `POST /api/futures/analyze`.
+2. Server runs `run_futures_cycle(..., execute=False)`.
+3. DS4 safety state, Futures verification, required fields, and freshness gates are checked first.
+4. A deterministic score is calculated only from normalized real inputs.
+5. A directional plan is created only when score and confirmation thresholds pass.
+6. SL/TP are derived from ATR and configured reward-to-risk rules.
+7. Risk sizing calculates quantity from equity loss at Stop Loss.
+8. Slippage is estimated from the real order book.
+9. The result is stored as a bounded server-side plan and returned with a `planId`.
+
+### 4.3 Paper execution
+
+Paper execution is not a continuation of browser state. The server performs all checks again:
+
+- requested symbol is a verified Futures contract;
+- `planId` matches the latest server plan;
+- symbol and risk profile have not changed;
+- plan was not already executed;
+- plan has not expired;
+- decision is `LONG` or `SHORT`;
+- DS4 verification and trading readiness remain valid;
+- `noTradeGuard` is false;
+- plan is marked executable and risk-approved;
+- runtime trading mode is `paper`;
+- a fresh analysis-only cycle still authorizes the plan.
+
+Only after these checks does the server invoke the existing Paper execution path.
+
+## 5. Datasource authority
+
+```text
+Datasource 4 → Binance public fallback → Datasource 2
+```
+
+Datasource 4 owns contract verification and all Futures safety semantics. The critical fields are:
+
+```text
+contract
+ticker
+orderbook
+funding
+openInterest
+```
+
+OHLCV, indicators, sentiment, and ATR are also normalized and attributed. Missing or non-fresh critical fields activate `noTradeGuard` and set `tradingReadiness=blocked`.
+
+Binance public data is unauthenticated and field-level only. HTTP 451 is represented as `Regionally restricted`; it is never reported as healthy. Datasource 2 cannot verify Futures, clear `noTradeGuard`, or override DS4 data that is present and usable.
+
+## 6. Health model
+
+The code deliberately separates:
+
+- `transportStatus`: whether the HTTP request succeeded;
+- `dataUsability`: whether parsed data is suitable for use;
+- `freshness`: whether provider timestamp or authoritative DS4 state proves freshness;
+- `completeness`: whether expected fields were supplied;
+- `mergeStatus`: whether the combined context is complete;
+- `tradingReadiness`: whether deterministic safety gates allow a plan.
+
+A successful HTTP response does not make market data fresh. Fallback data without a provider timestamp remains `unknown` and cannot pass a Futures freshness gate.
+
+## 7. Analysis and plan states
+
+### Analysis states
+
+```text
+NOT_ANALYZED
+ANALYZING
+LONG
+SHORT
+NO_TRADE
+ANALYSIS_FAILED
+STALE
+API_UNAVAILABLE
+```
+
+### Plan types
+
+- `directional_plan`: a valid directional plan before final execution checks.
+- `non_executable_plan`: directional values exist but one or more safety/risk gates block execution.
+- rejected/no-direction analysis: `NO_TRADE` with no executable plan geometry.
+
+### Market endpoint states
+
+- `available`: real candles and required display fields are fresh and usable.
+- `partial`: values exist but freshness or completeness is not fully proven.
+- `stale`: required display data is stale or invalid.
+- `unavailable`: real candles or a current price could not be obtained.
+
+## 8. Deterministic scoring and risk rules
+
+Default analysis thresholds are environment-overridable:
+
+| Setting | Default |
+|---|---:|
+| Minimum absolute signal score | `0.55` |
+| Minimum signal components | `3` |
+| Minimum direction confirmations | `2` |
+| Stop ATR multiplier | `1.2` |
+| Take Profit reward-to-risk | `1.8` |
+| Minimum stop distance | `20` bps |
+| Plan maximum age | `20` seconds |
+| Requested leverage | `5x` |
+
+Risk profiles:
+
+| Profile | Equity risk | Maximum leverage |
+|---|---:|---:|
+| Conservative | 1% | 5x |
+| Moderate | 3% | 10x |
+| Aggressive | 5% | 15x |
+
+Sizing is based on loss at Stop Loss:
+
+```text
+risk_amount   = account_equity × risk_percent
+stop_distance = abs(entry_price - stop_loss)
+quantity      = risk_amount / stop_distance
+```
+
+When ATR is at least 3% of price, effective leverage is reduced by 50% and never increased beyond the risk-profile cap.
+
+## 9. Frontend behavior
+
+The dashboard is a single packaged HTML template with inline CSS and JavaScript. It uses the existing authenticated FastAPI origin and `fetch(..., credentials='same-origin', cache='no-store')`.
+
+Major features:
+
+- symbol search and verified/market-only catalog counts;
+- local watchlist and recent markets;
+- real candle/line chart, four intervals, three candle limits, volume, crosshair, and tooltip;
+- market source, freshness, funding, Open Interest, best bid/ask/spread, and readiness;
+- display-only diagnostics from returned candles;
+- per-field provenance;
+- deterministic analysis and Paper Execute controls;
+- plan geometry and execution checklist;
+- datasource detail cards and sanitized technical diagnostics;
+- Paper account and positions;
+- local activity/history, JSON export, copy summary, density/theme preferences;
+- manual and automatic refresh controls.
+
+Browser storage never grants server permission. Selecting a historical symbol or changing risk invalidates the current browser plan and requires a new server analysis.
+
+## 10. Authentication
+
+The upstream Hermes dashboard is protected by its existing authentication middleware. The Futures router also supports local HTTP Basic enforcement when `HERMES_ADMIN_PASSWORD` is set:
+
+```text
+username: HERMES_DASHBOARD_BASIC_AUTH_USERNAME (default: admin)
+password: HERMES_ADMIN_PASSWORD
+```
+
+`entrypoint.sh` writes a hashed credential into Hermes `config.yaml` before the server binds publicly. Secrets must be configured as Hugging Face Space secrets or injected environment variables, never committed.
+
+## 11. Telegram model
+
+Telegram is webhook-only and analysis-only:
+
+- `POST /api/telegram/webhook` validates `X-Telegram-Bot-Api-Secret-Token`.
+- Owner bootstrap uses a one-time private-chat `/claim <secret>` command.
+- Authorized users come from configured IDs or the persisted owner.
+- Commands call `run_futures_cycle(..., execute=False)` only.
+- Direct delivery may use a proxy; proactive delivery may use an HMAC relay.
+- Polling must remain disabled.
+
+No Telegram command can execute a Futures position.
+
+## 12. Runtime integrity
+
+During overlay installation, `sync_hf.py` copies the current image overlay into `/opt/hermes` and writes `.hermes_futures_overlay_manifest.json`. The status endpoint compares repository/overlay/runtime/template/router hashes when those paths are available.
+
+Runtime status semantics:
+
+- `verified`: evidence exists and all expected hashes match;
+- `mismatch`: evidence exists and one or more hashes differ;
+- `unknown`: required evidence is unavailable.
+
+Missing files must never be reported as verified.
+
+## 13. Development workflow
+
+1. Start from the current repository files under `asset-space/hermes_overlay`.
+2. Do not copy old loose reference files over the repository.
+3. Keep changes focused and additive to the API contract.
+4. Preserve the single server and port architecture.
+5. Add tests for normalization, provenance, state transitions, and server-side execution checks.
+6. Run static checks and focused Futures tests.
+7. Review secrets and generated files before commit.
+8. Deploy through the existing Space workflow.
+9. Verify the installed hashes and authenticated routes.
+10. Inspect browser Console and Network.
+11. Never click Paper Execute during deployment verification.
+
+## 14. Read-only runtime audit
+
+```bash
+export HERMES_ADMIN_PASSWORD='...'
+export HERMES_DASHBOARD_BASIC_AUTH_USERNAME='admin'
+python scripts/verify_futures_runtime.py \
+  --base-url https://really-amin-asset.hf.space \
+  --symbol BTCUSDT \
+  --analyze \
+  --report .runtime_audit/futures_runtime_audit.json
+```
+
+The utility checks `/futures`, status, symbols, positions, all market intervals, and optionally one analysis-only request. It never calls `/api/futures/paper/execute`.
+
+## 15. Known deployment limitations
+
+- Binance public Futures endpoints may return HTTP 451 in the current Hugging Face region.
+- Real DS4 payload names and provider timestamps must be verified against live deployed responses.
+- The current package has static validation results but not a completed authenticated production verification cycle.
+- The UI uses a single large HTML template; future refactoring must preserve runtime template installation and avoid introducing a second frontend server.
+
+## 16. Definition of done
+
+A change is complete only when:
+
+- the correct template and router are installed and hash-verified;
+- authenticated routes return expected structured responses;
+- real market data renders for 1m, 5m, 15m, and 1h or returns an explicit unavailable state;
+- Console has no critical error and Network requests are authenticated;
+- datasource health and attribution are truthful;
+- deterministic safety logic is unchanged;
+- Telegram remains webhook-only;
+- no secret is exposed;
+- no trade is executed during verification.

docs/ENVIRONMENT_CONFIGURATION.md

@@ -0,0 +1,142 @@
+# Environment Configuration
+
+Configure secrets in Hugging Face Space Settings or inject them at container runtime. Never commit a populated `.env` file.
+
+## Core persistence
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HF_TOKEN` | none | Hugging Face token with required repository access. |
+| `HERMES_DATASET_REPO` | derived/none | Private Dataset used to persist `/opt/data`. |
+| `AUTO_CREATE_DATASET` | `true` | Create the private Dataset when missing. |
+| `SYNC_INTERVAL` | `60` | Persistence sync interval in seconds. |
+| `HF_HUB_DOWNLOAD_TIMEOUT` | implementation default | Hub download timeout. |
+| `HF_HUB_UPLOAD_TIMEOUT` | implementation default | Hub upload timeout. |
+| `HERMES_HOME` | `/opt/data` | Persistent Hermes data root. |
+| `MAX_BACKUPS` | script default | Backup retention used by persistence helper. |
+
+## Dashboard authentication
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HERMES_ADMIN_PASSWORD` | none | Required production dashboard password. |
+| `HERMES_ADMIN_USERNAME` | `admin` | Username written to Hermes dashboard config by entrypoint. |
+| `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` | `admin` | Username checked by Futures router and runtime audit. |
+
+For the audit tool only:
+
+| Variable | Purpose |
+|---|---|
+| `HERMES_DASHBOARD_COOKIE` | Existing authenticated session cookie when Basic auth is not used. |
+| `HERMES_FUTURES_BASE_URL` | Default audit target base URL. |
+
+## Datasources
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DS4_BASE_URL` | DS4 Hugging Face Space URL | Authoritative Datasource 4 base. |
+| `DS4_TIMEOUT_S` | `6` | DS4 request timeout. |
+| `DS2_BASE_URL` | DS2 Hugging Face Space URL | Complementary Datasource 2 base. |
+| `DS2_TIMEOUT_S` | `6` | DS2 request timeout. |
+| `HERMES_SYMBOL_CACHE_PATH` | `/opt/data/futures_symbols_cache.json` | Symbol catalog cache. |
+
+## Binance fallback
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `BINANCE_PUBLIC_FALLBACK_ENABLED` | `true` | Enable unauthenticated field fallback. |
+| `BINANCE_FUTURES_PUBLIC_BASE_URL` | `https://fapi.binance.com` | Binance Futures public base. |
+| `BINANCE_FUTURES_TIMEOUT_S` | `5` | Request timeout. |
+| `BINANCE_FUTURES_MAX_RETRIES` | `2` | Retry bound. |
+| `BINANCE_KLINE_INTERVAL` | `5m` | Default fallback interval. |
+| `BINANCE_KLINE_LIMIT` | `100` | Default kline count. |
+| `BINANCE_ATR_PERIOD` | `14` | ATR lookback in fallback client. |
+| `BINANCE_ORDERBOOK_LIMIT` | `20` | Depth level limit. |
+| `BINANCE_OI_PERIOD` | `5m` | Open Interest history period. |
+
+A regional HTTP 451 must be surfaced honestly. Do not use raw IP, DNS bypass, or TLS bypass.
+
+## Deterministic analysis
+
+| Variable | Default | Purpose |
+|---|---:|---|
+| `FUTURES_MIN_SIGNAL_SCORE` | `0.55` | Minimum absolute deterministic score. |
+| `FUTURES_MIN_SIGNAL_COMPONENTS` | `3` | Minimum present scoring components. |
+| `FUTURES_MIN_DIRECTION_CONFIRMATIONS` | `2` | Minimum components confirming direction. |
+| `FUTURES_STOP_ATR_MULTIPLIER` | `1.2` | ATR stop-distance multiplier. |
+| `FUTURES_TAKE_PROFIT_RR` | `1.8` | Target reward-to-risk. |
+| `FUTURES_MIN_STOP_BPS` | `20` | Minimum stop distance in basis points. |
+| `FUTURES_PLAN_MAX_AGE_SECONDS` | `20` | Plan expiry window. |
+| `FUTURES_DEFAULT_LEVERAGE` | `5` | Requested leverage before caps/haircut. |
+
+Changing these variables changes deterministic behavior and requires explicit review, tests, and deployment evidence.
+
+## Execution and Paper account
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PAPER_EQUITY_USDT` | implementation default | Initial Paper account equity. |
+| `FUTURES_EXCHANGE_ID` | implementation default | Exchange adapter ID. |
+| `FUTURES_API_KEY` | none | Exchange credential boundary. Do not set for routine Paper-only development. |
+| `FUTURES_API_SECRET` | none | Exchange secret. |
+| `FUTURES_API_PASSPHRASE` | none | Optional exchange passphrase. |
+
+Do not introduce credentials into source, logs, diagnostics, screenshots, patches, or generated reports.
+
+## External advisory
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `EXTERNAL_AI_ENABLED` | `true` | Allow advisory when explicitly requested. |
+| `EXTERNAL_AI_TIMEOUT_SECONDS` | `8` | Legacy/advisory timeout. |
+| `EXTERNAL_AI_PROVIDER_TIMEOUT_SECONDS` | `8` | Per-provider timeout. |
+| `EXTERNAL_AI_TOTAL_TIMEOUT_SECONDS` | `15` | Total advisory budget. |
+| `OPENROUTER_ANALYSIS_MODEL` | configured model | OpenRouter model. |
+| `GOOGLE_ANALYSIS_MODEL` | configured model | Google model. |
+| `HF_ANALYSIS_MODEL` | configured model | Hugging Face model. |
+| `OPENROUTER_API_KEY` | none | OpenRouter credential. |
+| `GOOGLE_API_KEY` | none | Google credential. |
+
+Provider order is OpenRouter → Google → Hugging Face. Advisory output cannot change the deterministic plan.
+
+## Telegram webhook
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `TELEGRAM_ENABLED` | `false` | Enable webhook adapter. |
+| `TELEGRAM_MODE` | `webhook` | Must remain webhook mode. |
+| `TELEGRAM_PUBLIC_BASE_URL` | Space URL | Webhook target base. |
+| `TELEGRAM_WEBHOOK_PATH` | `/api/telegram/webhook` | Webhook path. |
+| `TELEGRAM_WEBHOOK_SECRET` | none | Telegram secret-token header value. |
+| `TELEGRAM_BOOTSTRAP_SECRET` | none | One-time owner claim secret. |
+| `TELEGRAM_ALLOWED_USER_IDS` | empty | Comma-separated authorized IDs. |
+| `TELEGRAM_BOT_TOKEN` | none | Telegram bot token. |
+| `TELEGRAM_PROXY_URL` | empty | Optional direct Bot API proxy. |
+| `TELEGRAM_RELAY_URL` | empty | Optional proactive relay. |
+| `TELEGRAM_RELAY_SECRET` | empty | HMAC relay secret. |
+| `TELEGRAM_STATE_PATH` | `/opt/data/telegram_state.json` | Persisted owner/watchlist state. |
+| `TELEGRAM_ALERTS_ENABLED` | `false` | External-scheduler alert evaluation status. |
+| `TELEGRAM_COMMAND_RATE_LIMIT` | `10` | Commands per user per minute. |
+| `TELEGRAM_SCAN_MAX_SYMBOLS` | `300` | Maximum verified catalog candidates. |
+| `TELEGRAM_SCAN_SHORTLIST_SIZE` | `20` | Deterministic shortlist size. |
+| `TELEGRAM_SCAN_RESULT_COUNT` | `10` | Displayed result count. |
+| `TELEGRAM_SCAN_MAX_CONCURRENCY` | `4` | Analysis concurrency. |
+
+## MCP isolation
+
+| Variable | Default | Requirement |
+|---|---|---|
+| `LINEAR_MCP_ENABLED` | `false` | Keep unchanged unless separately approved. |
+| `UNREAL_ENGINE_MCP_ENABLED` | `false` | Keep disabled unless separately approved. |
+
+## Runtime integrity paths
+
+Advanced overrides used by diagnostics:
+
+```text
+HERMES_FUTURES_OVERLAY_MANIFEST
+HERMES_OVERLAY_SOURCE
+HERMES_SYNC_SCRIPT
+```
+
+These should normally use their runtime defaults.

docs/FRONTEND_GUIDE.md

@@ -0,0 +1,189 @@
+# Frontend Guide
+
+## File and runtime
+
+The entire Futures dashboard UI is packaged in:
+
+```text
+hermes_overlay/tools/templates/hermes_futures_desk_luxury.html
+```
+
+The router reads this file at request time from its installed `tools/templates` directory and serves it at `/futures`. Do not add a second frontend server, bundler process, or port.
+
+## Design system
+
+The UI uses an Obsidian & Gold workstation theme with a light-theme option. Operational values use readable sans-serif/monospace styling. Decorative serif/italic styling is limited to headings and visual accents.
+
+Responsive modes cover desktop, tablet, and mobile. `prefers-reduced-motion` is respected.
+
+## Main UI regions
+
+- fixed/collapsible navigation and local market lists;
+- command deck with symbol, risk, advisory, Analyze, and Paper Execute controls;
+- selected-market header and chart;
+- market diagnostics and field provenance;
+- decision, score, risk approval, and execution mode;
+- trade-plan geometry and execution checklist;
+- signal reasons and components;
+- Paper account and positions;
+- datasource health and technical diagnostics;
+- Telegram operational status;
+- local activity/history and export actions.
+
+## API usage
+
+The helper uses:
+
+```javascript
+fetch(url, {
+  credentials: 'same-origin',
+  cache: 'no-store'
+})
+```
+
+Primary calls:
+
+```text
+GET  /api/futures/status
+GET  /api/futures/symbols
+GET  /api/futures/positions
+GET  /api/futures/market
+POST /api/futures/analyze
+POST /api/futures/paper/execute
+GET  /api/telegram/status
+```
+
+No backend route is declared in the template.
+
+## Refresh behavior
+
+Default intervals:
+
+- clock and age labels: 1 second;
+- status and positions: 5 seconds while auto-refresh is enabled and page is visible;
+- market data: 15 seconds;
+- Telegram status: 60 seconds.
+
+When the page becomes visible again, status and market data refresh if automatic refresh is enabled.
+
+## Chart behavior
+
+Supported intervals:
+
+```text
+1m 5m 15m 1h
+```
+
+Supported candle limits:
+
+```text
+60 120 240
+```
+
+Modes:
+
+- Candles;
+- Line;
+- optional volume bars.
+
+The chart is an inline SVG and uses only `candles` returned by the market endpoint. Crosshair, OHLCV legend, tooltip, current-price reference, price labels, visible high/low, range position, and last-candle age are derived from the returned series.
+
+No visual interpolation or fallback is permitted to create production candles.
+
+## Display-only diagnostics
+
+The UI calculates visible trend, average candle range, relative last-candle volume, realized variation, last-candle direction, and range position from the real returned candles. These values are explicitly informational and must never change:
+
+```text
+LONG / SHORT / NO_TRADE
+risk approval
+noTradeGuard
+Entry / SL / TP
+leverage
+quantity
+execution eligibility
+```
+
+## Local browser state
+
+The UI stores only convenience preferences/history in `localStorage`.
+
+Known keys:
+
+```text
+hermes_theme
+hermes_auto_refresh
+hermes_compact
+```
+
+Watchlist, recent markets, local analysis history, and workspace activity use Hermes-prefixed local keys defined in the template. They are not synchronized to the server and are not trusted for execution.
+
+## Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `/` | Focus and select symbol search. |
+| `A` | Run analysis when not already analyzing. |
+| `R` | Manual refresh. |
+| `D` | Toggle display density. |
+| `T` | Toggle theme. |
+| `?` | Open shortcut help. |
+| `Escape` | Close overlays/help. |
+
+There is deliberately no keyboard shortcut for Paper Execute.
+
+## Analysis state rendering
+
+Use the server result to set one of:
+
+```text
+NOT_ANALYZED
+ANALYZING
+LONG
+SHORT
+NO_TRADE
+ANALYSIS_FAILED
+STALE
+API_UNAVAILABLE
+```
+
+Important rules:
+
+- initial state is “Waiting for analysis,” not `NO_TRADE`;
+- HTTP/network failure is `ANALYSIS_FAILED` or `API_UNAVAILABLE`;
+- score is “Unavailable” when components do not exist, not numeric zero;
+- expiry is prominent only for a valid directional plan;
+- rejected/incomplete analysis is not presented as executable;
+- changing symbol or risk invalidates the current browser plan;
+- server state remains authoritative.
+
+## Execute availability
+
+The button is disabled unless the latest browser plan mirrors all required server fields. The UI displays a concrete disabled reason such as:
+
+```text
+Run analysis first
+No directional plan
+Risk approval failed
+noTradeGuard active
+Market-only symbol
+Plan expired
+Symbol changed
+Risk profile changed
+Plan already executed
+Required Futures fields unavailable
+```
+
+These checks improve UX but do not replace backend revalidation.
+
+## Adding a UI feature safely
+
+1. Reuse existing API fields or add an additive backend field.
+2. Render missing values as `Unavailable`, never zero or fabricated content.
+3. Keep browser calculations labeled display-only.
+4. Do not add another Execute path or shortcut.
+5. Invalidate plan display when relevant controls change.
+6. Keep DOM IDs unique and update static ID checks.
+7. Preserve responsive and reduced-motion behavior.
+8. Do not display raw provider errors or secrets.
+9. Verify Console and Network in an authenticated deployed session.

docs/OPERATIONS_AND_TROUBLESHOOTING.md

@@ -0,0 +1,177 @@
+# Operations and Troubleshooting
+
+## Diagnostic order
+
+1. Confirm Space is `RUNNING`.
+2. Fetch `/futures` and inspect response/hash headers.
+3. Check `/api/futures/status` with authentication.
+4. Inspect runtime file status and datasource metadata.
+5. Check Browser Console and Network.
+6. Inspect market endpoint for one symbol/interval.
+7. Compare DS4 raw/normalized fields and timestamps.
+8. Check provider-specific diagnostics.
+9. Run one analysis-only request.
+10. Do not test Paper Execute during diagnosis.
+
+## Common issues
+
+### Dashboard returns 401
+
+Likely causes:
+
+- missing/incorrect `HERMES_ADMIN_PASSWORD`;
+- wrong Basic username;
+- browser session expired;
+- reverse proxy did not preserve auth.
+
+Actions:
+
+- confirm `HERMES_ADMIN_USERNAME` and `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` alignment;
+- re-authenticate;
+- verify `entrypoint.sh` logged successful auth configuration;
+- never print the password in logs or reports.
+
+### `/futures` returns 200 but old UI appears
+
+Possible causes:
+
+- stale installed overlay;
+- wrong template path;
+- restored old overlay taking precedence;
+- CDN/browser cache;
+- duplicate old page implementation.
+
+Actions:
+
+- compare `X-Hermes-Template-SHA256` with body hash;
+- inspect `application.runtimeFiles` in status;
+- confirm `/opt/hermesface_overlay` is preferred;
+- confirm installed `/opt/hermes/tools/templates/...` matches manifest;
+- hard reload only after server-side evidence is checked.
+
+### Runtime status is `unknown`
+
+`unknown` means evidence is absent, not that files match.
+
+Actions:
+
+- verify manifest path and permissions;
+- verify overlay and runtime paths exist;
+- check `HERMES_FUTURES_OVERLAY_MANIFEST`, `HERMES_OVERLAY_SOURCE`, and `HERMES_SYNC_SCRIPT` overrides;
+- inspect overlay installation logs.
+
+### Runtime status is `mismatch`
+
+Actions:
+
+- identify exact mismatched file in status payload;
+- compare repository/image overlay and `/opt/hermes` file;
+- verify `sync_hf.py` installed after persistence restore;
+- rebuild/redeploy from a clean commit.
+
+### Chart says market data unavailable
+
+Check market endpoint payload:
+
+- HTTP 503 and `API_UNAVAILABLE`: acquisition exception;
+- `state=unavailable`: no real candles/current price;
+- `state=stale`: provider timestamp invalid or stale;
+- `state=partial`: freshness unknown or display fields incomplete.
+
+Inspect:
+
+```text
+warnings
+missingFields
+analysisRequiredFieldsMissing
+staleRequiredFields
+sourceMetadata
+technicalDiagnostics
+```
+
+Do not replace missing candles with mock data.
+
+### Binance shows HTTP 451
+
+This is an expected regional limitation in some Hugging Face regions.
+
+Correct behavior:
+
+```text
+transportStatus=restricted
+httpStatus=451
+dataUsability=unavailable
+reason=Regionally restricted
+```
+
+Do not use raw-IP or TLS-bypass workarounds. DS4 safety remains authoritative.
+
+### KuCoin reports “Parameter 'from' must be milliseconds”
+
+Verify DS4 request builder uses `build_kucoin_time_range()` and sends integer millisecond `from` and `to`. Check for upstream code that converts an already-millisecond value a second time.
+
+### Market data is HTTP 200 but readiness is blocked
+
+Transport and readiness are separate. Inspect:
+
+- DS4 Futures verification;
+- DS4 `noTradeGuard`;
+- missing critical fields;
+- non-fresh critical fields;
+- merge rejection reasons.
+
+A provider may be reachable while its data is unusable.
+
+### `NO_TRADE` displayed before analysis
+
+The initial state must be `NOT_ANALYZED`. Check frontend initialization and `/api/futures/status.analysisState`. A network error must be `ANALYSIS_FAILED` or `API_UNAVAILABLE`, not `NO_TRADE`.
+
+### Signal score shows zero with no components
+
+The UI must show `Unavailable`. Check whether `latestSignalScore` is `null` and whether signal components are empty. Do not coerce null to zero.
+
+### Execute button is disabled
+
+This is normally correct. Read the visible reason and inspect:
+
+```text
+latest plan exists
+planId matches
+symbol and risk match
+plan not expired
+LONG/SHORT decision
+verified Futures
+risk approved
+noTradeGuard false
+tradingReadiness ready
+executable true
+not already executed
+```
+
+### Telegram says Owner setup required
+
+No configured/persisted owner exists. Use the one-time private `/claim <TELEGRAM_BOOTSTRAP_SECRET>` flow. Remove/rotate the bootstrap secret after claim. Do not expose owner ID in dashboard status.
+
+### Telegram proactive alerts unavailable
+
+Webhook responses can work without outbound connectivity, but proactive alerts need either:
+
+- direct Telegram access with optional proxy; or
+- configured relay URL and HMAC secret.
+
+Keep polling disabled.
+
+## Logs and artifacts
+
+Useful logs:
+
+```text
+Space build log
+entrypoint startup log
+sync_hf overlay install/hash log
+Hermes dashboard log under /opt/data/logs
+sanitized runtime audit JSON
+browser Console and Network export without credentials
+```
+
+Never attach raw cookies, Authorization headers, tokens, or unredacted provider payloads.

docs/PROJECT_STATUS.md

@@ -0,0 +1,80 @@
+# Project Status
+
+## Snapshot
+
+This documentation describes the UI v3 implementation package prepared on 2026-07-21.
+
+Repository base recorded by the implementation package:
+
+```text
+3ff79ee0fce31f8d09a7dac357904169d50d9f3e
+```
+
+Last known deployed revision before this package:
+
+```text
+24d8dad11c0d7316446e9a26b0b074e8630de139
+```
+
+The package itself was not committed, pushed, or deployed by the implementation environment.
+
+## Implemented backend/runtime work
+
+- packaged Luxury template is the runtime source;
+- overlay installation and SHA-256 manifest;
+- runtime status `verified` / `mismatch` / `unknown`;
+- no-cache Futures responses;
+- KuCoin millisecond range construction;
+- conservative DS4 Futures verification;
+- DS4/Binance/DS2 normalization and priority;
+- per-field provenance and truthful freshness;
+- structured source health and merge readiness;
+- real market endpoint with four intervals;
+- explicit partial/stale/unavailable semantics;
+- deterministic state machine and non-executable plan semantics;
+- server-side plan/symbol/risk/expiry/readiness/risk revalidation;
+- stronger diagnostic redaction;
+- read-only runtime audit utility;
+- Telegram webhook-only and Linear MCP isolation preserved.
+
+## Implemented UI v3 work
+
+- watchlist and recent markets;
+- manual/automatic refresh and density/theme controls;
+- keyboard help without execution shortcut;
+- Candles/Line chart, volume, crosshair, tooltip, four intervals, three limits;
+- market header, source/freshness/readiness, order-book top values;
+- display-only diagnostics;
+- per-field provenance;
+- plan geometry and execution checklist;
+- analysis copy/export/history/activity;
+- expanded datasource and technical diagnostics;
+- responsive desktop/tablet/mobile layout.
+
+## Validation already recorded
+
+Static validation reported:
+
+- modified Python files compiled;
+- dashboard JavaScript passed `node --check`;
+- DOM ID and static reference checks passed;
+- CSS custom-property checks passed;
+- whitespace checks passed;
+- package ZIP integrity passed.
+
+Behavioral tests, Futures regression tests, authenticated production verification, and deployment were deferred.
+
+## Remaining production work
+
+1. Review documentation and final code diff.
+2. Run focused tests and existing Futures regression suite.
+3. Verify real DS4 field names and timestamps.
+4. Perform one safe KuCoin read-only request.
+5. Deploy through the repository/Hugging Face workflow.
+6. Run authenticated read-only audit.
+7. Inspect Browser Console and Network.
+8. Verify real market rendering for all intervals and UI features.
+9. Run one BTCUSDT analysis-only request.
+10. Confirm Telegram webhook-only mode and Linear MCP isolation.
+11. Record commit hash and serving Space revision.
+12. Confirm no secret exposure and no trade execution.

docs/README.md

@@ -0,0 +1,26 @@
+# Hermes Futures Desk Developer Documentation
+
+This directory is the canonical developer documentation for the repository snapshot.
+
+## Reading order
+
+1. [Complete Developer Guide](DEVELOPER_GUIDE.md) — single-document overview.
+2. [Architecture](ARCHITECTURE.md) — runtime, module boundaries, and control flow.
+3. [API Reference](API_REFERENCE.md) — authenticated routes and payload contracts.
+4. [Datasource Pipeline and Contracts](DATA_PIPELINE_AND_CONTRACTS.md) — DS4, Binance, DS2, normalization, provenance, and readiness.
+5. [Frontend Guide](FRONTEND_GUIDE.md) — UI state, charting, local workspace features, and execution controls.
+6. [Environment Configuration](ENVIRONMENT_CONFIGURATION.md) — supported variables and secret handling.
+7. [Deployment Runbook](DEPLOYMENT_RUNBOOK.md) — build, overlay installation, Space deployment, verification, and rollback.
+8. [Security and Safety](SECURITY_AND_SAFETY.md) — non-negotiable safety model and threat boundaries.
+9. [Operations and Troubleshooting](OPERATIONS_AND_TROUBLESHOOTING.md) — common failures and diagnostic workflow.
+10. [Testing and Verification](TESTING_AND_VERIFICATION.md) — focused tests, runtime audit, browser verification, and acceptance checklist.
+11. [Contributing](CONTRIBUTING.md) — change discipline and review checklist.
+12. [Project Status](PROJECT_STATUS.md) — implemented work and remaining production verification.
+
+## Documentation principles
+
+- Source code is authoritative when documentation and implementation disagree.
+- API examples are representative; clients must tolerate additive fields.
+- Browser-derived values are informational and never authorize execution.
+- Runtime verification requires evidence from hashes, authenticated API responses, and browser Console/Network inspection.
+- “Application online” is not equivalent to “market data healthy” or “trading ready.”

docs/SECURITY_AND_SAFETY.md

@@ -0,0 +1,105 @@
+# Security and Safety
+
+## Non-negotiable invariants
+
+Do not change or weaken:
+
+- deterministic `LONG`, `SHORT`, and `NO_TRADE` decisions;
+- Datasource 4 authority;
+- `noTradeGuard`;
+- Futures verification;
+- provider timestamp and freshness checks;
+- risk approval;
+- Stop Loss and Take Profit rules;
+- leverage caps and volatility haircut;
+- quantity/sizing logic;
+- Paper execution validation;
+- Telegram webhook-only isolation;
+- single FastAPI application and port 7860 architecture.
+
+## Browser trust model
+
+The browser is untrusted for execution. It may display and calculate convenience diagnostics, but the server ignores browser-derived authorization.
+
+Server-side Paper checks include plan reference, symbol/risk identity, expiry, executed flag, direction, DS4 verification, readiness, guard state, risk approval, executable flag, Paper mode, and fresh re-analysis.
+
+## Secret handling
+
+Never expose or commit:
+
+```text
+HF_TOKEN
+HERMES_ADMIN_PASSWORD
+FUTURES_API_KEY
+FUTURES_API_SECRET
+FUTURES_API_PASSPHRASE
+OPENROUTER_API_KEY
+GOOGLE_API_KEY
+TELEGRAM_BOT_TOKEN
+TELEGRAM_WEBHOOK_SECRET
+TELEGRAM_BOOTSTRAP_SECRET
+TELEGRAM_RELAY_SECRET
+cookies or Authorization headers
+```
+
+Diagnostics redact keys and text matching authorization, cookie, token, secret, password, or API key patterns. Continue to sanitize new error fields before they reach API responses or UI.
+
+## Market-data integrity
+
+- No fabricated production candles, prices, funding, Open Interest, or order-book levels.
+- Missing values are `null`/`Unavailable`, not zero.
+- HTTP success is not data freshness.
+- Provider errors in main UI are concise; detailed errors remain sanitized under Technical Diagnostics.
+- Binance regional restriction must not be bypassed with raw IP, DNS override, or disabled TLS.
+
+## External AI boundary
+
+External AI may return market bias, confidence, summary, and warnings. It must never modify:
+
+```text
+decision
+risk approval
+noTradeGuard
+Entry
+Stop Loss
+Take Profit
+leverage
+quantity
+execution availability
+```
+
+Bulk scans must not use advisory AI.
+
+## Telegram boundary
+
+- Webhook secret-token validation is mandatory.
+- Request size is bounded.
+- Owner bootstrap is one-time, secret-checked, and private-chat only.
+- Users are authorized by configured IDs or persisted owner.
+- Commands are rate-limited.
+- Callback nonces expire and are user-bound.
+- Telegram performs analysis only and contains no order path.
+- Polling remains disabled.
+
+## Development safety
+
+During ordinary development and deployment verification:
+
+- do not call Paper Execute;
+- do not run Testnet or Live execution;
+- use the read-only audit script;
+- use Paper account endpoints only for display verification;
+- do not add an execution keyboard shortcut;
+- do not allow a UI feature to write plan or risk state directly.
+
+## Review checklist for security-sensitive changes
+
+- Does the change alter a deterministic threshold or formula?
+- Can fallback data override DS4 safety?
+- Can a missing timestamp be treated as fresh?
+- Can the browser enable execution without server state?
+- Can a raw error include a secret?
+- Can a Telegram request bypass authorization or webhook validation?
+- Does the change introduce a second network service or port?
+- Does it add an exchange credential requirement?
+- Are failure states blocked by default?

docs/TESTING_AND_VERIFICATION.md

@@ -0,0 +1,112 @@
+# Testing and Verification
+
+## Test locations
+
+```text
+hermes_overlay/tests/
+```
+
+Existing focused areas include:
+
+- Binance public fallback;
+- nested DS4 merge behavior;
+- external advisory boundary;
+- Futures dashboard/state;
+- Futures integration;
+- Luxury template markers;
+- optional MCP runtime isolation;
+- Telegram webhook;
+- trade-cycle field paths.
+
+## Recommended validation layers
+
+### 1. Static validation
+
+```bash
+python -m compileall hermes_overlay scripts
+node --check /tmp/hermes_dashboard_script.js
+ruff check hermes_overlay scripts
+```
+
+Also check:
+
+- duplicate DOM IDs;
+- missing JavaScript DOM references;
+- undefined CSS custom properties;
+- `git diff --check`;
+- absence of secrets/generated files.
+
+### 2. Focused unit tests
+
+Required focus:
+
+- seconds-to-milliseconds conversion;
+- already-millisecond timestamps;
+- ordered bounded KuCoin ranges;
+- ticker/funding/Open Interest aliases;
+- malformed and ambiguous provider shapes;
+- per-field source/timestamp/freshness attribution;
+- transport health versus usability/readiness;
+- datasource-specific error attribution;
+- market endpoint canonical shape;
+- no fabricated values;
+- safe rejection when required fields are missing or non-fresh;
+- initial/failure UI states;
+- Execute-disabled reasons and server safety gates.
+
+### 3. Futures regression suite
+
+Run the existing Futures tests once after focused tests pass. Avoid repeatedly running unrelated broad suites while iterating on a narrow failure.
+
+### 4. Read-only deployed audit
+
+```bash
+export HERMES_ADMIN_PASSWORD='...'
+python scripts/verify_futures_runtime.py \
+  --base-url https://really-amin-asset.hf.space \
+  --symbol BTCUSDT \
+  --analyze \
+  --report .runtime_audit/futures_runtime_audit.json
+```
+
+The audit never calls Paper Execute.
+
+### 5. Browser verification
+
+Authenticated desktop and mobile verification must cover:
+
+- Console free of critical errors;
+- valid Network status and JSON payloads;
+- chart rendering for all intervals;
+- Candles/Line, volume, tooltip, crosshair;
+- watchlist/recent/history/export/density/theme/auto-refresh controls;
+- field provenance and datasource cards;
+- state machine and score semantics;
+- visible Execute-disabled reason;
+- no Paper Execute click.
+
+## Acceptance matrix
+
+| Area | Required result |
+|---|---|
+| Runtime files | `verified`, or documented investigation for `unknown`; never unexplained mismatch. |
+| Status API | 200 authenticated, structured source/runtime fields. |
+| Symbols API | Accurate total/verified/market-only counts. |
+| Positions API | Deliberate empty state or formatted real Paper positions. |
+| Market API | Real canonical candles or explicit structured unavailable state. |
+| Analysis API | Deterministic result; `NO_TRADE` is allowed and expected when unsafe. |
+| Paper Execute | Not called during verification. |
+| Binance 451 | Clearly reported as regional restriction. |
+| Telegram | Webhook-only; no polling adapter. |
+| Secrets | None in source, logs, reports, screenshots, or package. |
+
+## Testing safety
+
+Tests must not:
+
+- place Paper/Testnet/Live orders;
+- require real exchange credentials;
+- fabricate production responses in deployed paths;
+- weaken guards to make assertions pass;
+- treat an unavailable score as zero;
+- report missing runtime evidence as verified.

hermes_overlay/tests/test_binance_public_fallback.py

@@ -21,8 +21,9 @@ import trading.trade_cycle as trade_cycle
 
 
 class _FakeResponse:
-    def __init__(self, payload):
+    def __init__(self, payload, status_code=200):
         self._payload = payload
+        self.status_code = status_code
 
     def raise_for_status(self):
         pass
@@ -41,7 +42,7 @@ def _make_fake_client(ds4_payload, ds2_payloads=None, ds4_raises=False):
         async def __aexit__(self, *a):
             return False
 
-        async def get(self, url, timeout=None):
+        async def get(self, url, timeout=None, **_kwargs):
             if "short-hunter/snapshot" in url:
                 if ds4_raises:
                     raise RuntimeError("boom")
@@ -99,7 +100,7 @@ def test_ds4_fully_valid_binance_not_called(monkeypatch):
 
     monkeypatch.setattr(ddc.binance_public, "get_binance_public_snapshot", _fake_binance)
     payload = _full_ds4_payload()
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
 
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
 
@@ -113,20 +114,26 @@ def test_ds4_fully_valid_binance_not_called(monkeypatch):
 # ---------------------------------------------------------------------------
 
 def test_ds4_missing_field_filled_by_binance(monkeypatch):
+    # "funding" is one of the market-data fields (ticker/ohlcv/funding/openInterest)
+    # that get_market_context() requests together via get_binance_public_market_data;
+    # only openInterestChange/atr/orderbook go through get_binance_public_result with
+    # an explicit `needed` set. See dual_datasource_client.get_market_context().
     calls = []
 
-    async def _fake_binance(symbol, needed):
-        calls.append(needed)
-        assert needed == frozenset({"funding"})
-        return {"funding": {"currentFundingRate": -0.0001, "source": "binance_public"}}, []
+    async def _fake_market_data(symbol, interval, limit):
+        calls.append(symbol)
+        return {
+            "data": {"funding": {"currentFundingRate": -0.0001, "source": "binance_public"}},
+            "errors": [], "warnings": [], "meta": {},
+        }
 
-    monkeypatch.setattr(ddc.binance_public, "get_binance_public_snapshot", _fake_binance)
+    monkeypatch.setattr(ddc.binance_public, "get_binance_public_market_data", _fake_market_data)
     payload = _full_ds4_payload(funding=None)  # DS4 genuinely missing funding
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
 
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
 
-    assert calls == [frozenset({"funding"})]
+    assert len(calls) == 1
     assert result["merged"]["funding"] == {"currentFundingRate": -0.0001, "source": "binance_public"}
     assert result["sources"]["funding"] == "binance_public"
     assert any("filled from Binance public fallback" in w for w in result["warnings"])
@@ -170,26 +177,30 @@ def test_oi_change_none_when_history_too_short():
 
 
 def test_ds4_missing_oi_history_filled_by_binance(monkeypatch):
+    # openInterestChange is not one of the market-data fields, so it is
+    # requested via get_binance_public_result(symbol, needed_fields).
     calls = []
 
-    async def _fake_binance(symbol, needed):
-        calls.append(needed)
-        assert needed == frozenset({"openInterestChange"})
+    async def _fake_result(symbol, needed_fields=None):
+        calls.append(frozenset(needed_fields) if needed_fields is not None else frozenset())
         return {
-            "openInterestChange": {
-                "changePercent": 0.1,
-                "history": [
-                    {"sumOpenInterest": 1000.0, "timestamp": 1},
-                    {"sumOpenInterest": 1100.0, "timestamp": 2},
-                ],
-                "source": "binance_public",
-            }
-        }, []
-
-    monkeypatch.setattr(ddc.binance_public, "get_binance_public_snapshot", _fake_binance)
+            "data": {
+                "openInterestChange": {
+                    "changePercent": 0.1,
+                    "history": [
+                        {"sumOpenInterest": 1000.0, "timestamp": 1},
+                        {"sumOpenInterest": 1100.0, "timestamp": 2},
+                    ],
+                    "source": "binance_public",
+                }
+            },
+            "errors": [], "warnings": [], "meta": {},
+        }
+
+    monkeypatch.setattr(ddc.binance_public, "get_binance_public_result", _fake_result)
     payload = _full_ds4_payload()
     payload["data"]["openInterest"] = {"openInterest": 27000928.0, "history": []}
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
 
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
     assert calls == [frozenset({"openInterestChange"})]
@@ -203,19 +214,18 @@ def test_ds4_missing_oi_history_filled_by_binance(monkeypatch):
 # ---------------------------------------------------------------------------
 
 def test_notradeguard_enforced_even_when_binance_fills_all_gaps(monkeypatch):
-    async def _fake_binance(symbol, needed):
-        # Pretend Binance successfully supplies everything that was missing.
-        filled = {}
-        if "funding" in needed:
-            filled["funding"] = {"currentFundingRate": -0.0001, "source": "binance_public"}
-        if "atr" in needed:
-            filled["atr"] = 42.0
-        return filled, []
+    async def _fake_market_data(symbol, interval, limit):
+        # Pretend Binance successfully supplies everything that was missing
+        # (here just "funding" -- the rest of the fixture's DS4 data is valid).
+        return {
+            "data": {"funding": {"currentFundingRate": -0.0001, "source": "binance_public"}},
+            "errors": [], "warnings": [], "meta": {},
+        }
 
-    monkeypatch.setattr(ddc.binance_public, "get_binance_public_snapshot", _fake_binance)
+    monkeypatch.setattr(ddc.binance_public, "get_binance_public_market_data", _fake_market_data)
     payload = _full_ds4_payload(funding=None)
     payload["noTradeGuard"] = True  # DS4 itself says NO_TRADE
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
 
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
 

hermes_overlay/tests/test_ds4_merge_nested_data.py

@@ -10,6 +10,7 @@ Mocked HTTP only -- no live network calls.
 import asyncio
 import os
 import sys
+from datetime import datetime, timezone
 import pytest
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))  # hermes_overlay/
@@ -25,8 +26,9 @@ def _disable_live_binance(monkeypatch):
 
 
 class _FakeResponse:
-    def __init__(self, payload):
+    def __init__(self, payload, status_code=200):
         self._payload = payload
+        self.status_code = status_code
 
     def raise_for_status(self):
         pass
@@ -45,7 +47,7 @@ def _make_fake_client(ds4_payload, ds2_payloads=None, ds4_raises=False):
         async def __aexit__(self, *a):
             return False
 
-        async def get(self, url, timeout=None):
+        async def get(self, url, timeout=None, **_kwargs):
             if "short-hunter/snapshot" in url:
                 if ds4_raises:
                     raise RuntimeError("boom")
@@ -64,11 +66,15 @@ def _nested_ds4_payload(**overrides):
         "symbol": "BTCUSDT",
         "dataState": "live",
         "noTradeGuard": False,
-        "timestamp": "2026-07-20T11:08:19Z",
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "warnings": [],
         "errors": [],
         "data": {
-            "contract": {"symbol": "XBTUSDTM"},
+            # contractType/status let _contract_verification() mark this a
+            # verified Futures instrument (see docs/DATA_PIPELINE_AND_CONTRACTS.md
+            # and docs/DEVELOPER_GUIDE.md: DS4 owns Futures verification, and a
+            # bare {"symbol": ...} is deliberately treated as unverified).
+            "contract": {"symbol": "XBTUSDTM", "contractType": "PERPETUAL", "status": "TRADING"},
             "ticker": {"lastPrice": 64364.4, "change24h": None},
             "ohlcv": [
                 {"timestamp": i, "open": 64360, "high": 64370, "low": 64350,
@@ -88,7 +94,7 @@ def _nested_ds4_payload(**overrides):
 
 def test_merge_reads_futures_fields_from_nested_data(monkeypatch):
     payload = _nested_ds4_payload()
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
     merged = result["merged"]
 
@@ -96,7 +102,11 @@ def test_merge_reads_futures_fields_from_nested_data(monkeypatch):
     assert merged["funding"] == {"currentFundingRate": -8.2e-05}
     assert merged["openInterest"] == {"openInterest": 27000928.0, "history": []}
     assert merged["orderbook"] == {"bids": [[64364.4, 1]], "asks": [[64364.5, 1]]}
-    assert merged["contract"] == {"symbol": "XBTUSDTM"}
+    assert merged["contract"] == {
+        "symbol": "XBTUSDTM",
+        "contractType": "PERPETUAL",
+        "status": "TRADING",
+    }
     assert result["sources"]["ticker"] == "datasource4"
     assert result["sources"]["funding"] == "datasource4"
     assert result["noTradeGuard"] is False
@@ -107,7 +117,7 @@ def test_ds2_fallback_fires_only_for_genuinely_missing_nested_field(monkeypatch)
     payload["data"]["orderbook"] = None  # DS4 genuinely missing this field
     ds2_payloads = {"trading/orderbook": {"bids": [[1, 1]], "asks": [[1, 1]]}}
     monkeypatch.setattr(
-        ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload, ds2_payloads)
+        ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload, ds2_payloads)
     )
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
     merged = result["merged"]
@@ -123,7 +133,7 @@ def test_ds2_cannot_override_valid_nested_ds4_orderbook(monkeypatch):
     payload = _nested_ds4_payload()  # DS4 orderbook present and valid
     ds2_payloads = {"trading/orderbook": {"bids": [[999, 1]], "asks": [[999, 1]]}}
     monkeypatch.setattr(
-        ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload, ds2_payloads)
+        ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload, ds2_payloads)
     )
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
     merged = result["merged"]
@@ -138,7 +148,7 @@ def test_ds4_data_key_missing_entirely_is_treated_as_no_data(monkeypatch):
         "noTradeGuard": False, "timestamp": "x", "warnings": [], "errors": [],
         # no "data" key at all -- malformed response
     }
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
 
     assert result["sources"]["ticker"] == "unavailable"
@@ -150,7 +160,7 @@ def test_ds4_data_key_missing_entirely_is_treated_as_no_data(monkeypatch):
 def test_top_level_metadata_unaffected_by_nesting_fix(monkeypatch):
     """dataState/noTradeGuard were never part of the bug -- must stay top-level reads."""
     payload = _nested_ds4_payload(dataState="PARTIAL")
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
 
     assert result["noTradeGuard"] is True

hermes_overlay/tests/test_futures_dashboard_and_state.py

@@ -20,8 +20,9 @@ from tools.futures_dashboard_api import router as futures_router
 
 
 class _FakeResponse:
-    def __init__(self, payload):
+    def __init__(self, payload, status_code=200):
         self._payload = payload
+        self.status_code = status_code
 
     def raise_for_status(self):
         pass
@@ -38,7 +39,7 @@ def _make_fake_client(ds4_payload, ds4_raises=False):
         async def __aexit__(self, *a):
             return False
 
-        async def get(self, url, timeout=None):
+        async def get(self, url, timeout=None, **_kwargs):
             if "short-hunter/snapshot" in url or "short-hunter/health" in url:
                 if ds4_raises:
                     raise RuntimeError("boom")
@@ -69,7 +70,10 @@ def test_state_updates_after_successful_get_market_context(monkeypatch):
     payload = {
         "noTradeGuard": False, "dataState": "live",
         "data": {
-            "contract": {"x": 1}, "ticker": {"price": 42},
+            # contractType/status let _contract_verification() mark this a
+            # verified Futures instrument (see docs/DATA_PIPELINE_AND_CONTRACTS.md).
+            "contract": {"symbol": "BTCUSDT", "contractType": "PERPETUAL", "status": "TRADING"},
+            "ticker": {"price": 42},
             "ohlcv": [
                 {"timestamp": i, "open": 42, "high": 43, "low": 41,
                  "close": 42, "volume": 1} for i in range(4)
@@ -80,16 +84,20 @@ def test_state_updates_after_successful_get_market_context(monkeypatch):
             "atr": 1.0,
         },
     }
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
     asyncio.run(ftt._h_get_market_context({"symbol": "BTCUSDT"}))
     snap = dash_state.snapshot()
     assert snap["primary_status"] == "ok"
-    assert snap["current_signal"] in ("NO_TRADE", "LONG", "SHORT")  # unchanged unless guard trips
+    # record_market_context() only ever forces NO_TRADE when noTradeGuard
+    # trips; a clean market-context call with no analysis performed leaves
+    # current_signal untouched, i.e. still NOT_ANALYZED (see state.py
+    # record_market_context fail-safe comment).
+    assert snap["current_signal"] in ("NOT_ANALYZED", "NO_TRADE", "LONG", "SHORT")
     assert snap["field_sources"]["ticker"] == "datasource4"
 
 
 def test_state_updates_after_rejected_get_market_context(monkeypatch):
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client({}, ds4_raises=True))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client({}, ds4_raises=True))
     asyncio.run(ftt._h_get_market_context({"symbol": "BTCUSDT"}))
     snap = dash_state.snapshot()
     assert snap["primary_status"] == "unreachable"

hermes_overlay/tests/test_futures_integration.py

@@ -107,8 +107,9 @@ def test_calculate_futures_size_max_concurrent_positions_blocks_trade():
 # ---------------------------------------------------------------------------
 
 class _FakeResponse:
-    def __init__(self, payload):
+    def __init__(self, payload, status_code=200):
         self._payload = payload
+        self.status_code = status_code
 
     def raise_for_status(self):
         pass
@@ -125,7 +126,7 @@ def _make_fake_client(ds4_payload, ds4_raises=False):
         async def __aexit__(self, *a):
             return False
 
-        async def get(self, url, timeout=None):
+        async def get(self, url, timeout=None, **_kwargs):
             if "short-hunter/snapshot" in url:
                 if ds4_raises:
                     raise RuntimeError("boom")
@@ -143,7 +144,7 @@ def _disable_live_binance(monkeypatch):
 
 
 def test_no_trade_guard_when_ds4_unreachable(monkeypatch):
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client({}, ds4_raises=True))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client({}, ds4_raises=True))
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
     assert result["noTradeGuard"] is True
     assert any("unreachable" in r for r in result["noTradeReasons"])
@@ -161,7 +162,7 @@ def test_no_trade_guard_honored_from_ds4(monkeypatch):
             "openInterest": {"openInterest": 100},
         },
     }
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
     assert result["noTradeGuard"] is True
     assert result["sources"]["ticker"] == "datasource4"
@@ -177,9 +178,11 @@ def test_ds2_cannot_override_ds4_field(monkeypatch):
             "openInterest": {"openInterest": 100},
         },
     }
-    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda: _make_fake_client(payload))
+    monkeypatch.setattr(ddc.httpx, "AsyncClient", lambda *a, **kw: _make_fake_client(payload))
     result = asyncio.run(ddc.get_market_context("BTCUSDT"))
-    assert result["merged"]["ticker"] == {"price": 42}
+    # _normalize_ticker() always adds a canonical lastPrice extracted from
+    # price/last/close/markPrice, in addition to preserving original fields.
+    assert result["merged"]["ticker"] == {"price": 42, "lastPrice": 42.0}
     assert result["sources"]["ticker"] == "datasource4"
 
 

hermes_overlay/tools/futures_dashboard_api.py

@@ -1,47 +1,38 @@
-"""Minimal Futures dashboard extension for the existing Hermes web server.
-
-Mounted onto the SAME FastAPI `app` (same host/port) that already serves
-HermesFace -- this is not a separate frontend. It adds:
-
-  GET  /api/futures/status      -- primary/secondary datasource health,
-                                    current signal, reasons, warnings,
-                                    open position, PnL, last rejected trade
-  GET  /api/futures/positions   -- open positions with live mark price
-  GET  /futures                 -- a small polling HTML page (real page,
-                                    served by this same process)
-
-NOTE on scope: HermesFace's main dashboard is a compiled React/Vite SPA
-(`web/`) that depends on a private workspace package (`@nous-research/ui`)
-and other in-monorepo packages -- adding a native tab there means rebuilding
-that whole frontend workspace, which needs credentials/build infra this pass
-doesn't have. Serving a plain page from the same FastAPI app is the safe
-subset of "extend the existing dashboard" that doesn't risk breaking the SPA
-build. Swapping this for a real SPA tab later is a drop-in replacement --
-the JSON endpoints below don't change.
+"""Authenticated Futures dashboard routes for the existing Hermes server.
+
+The router is mounted into the same FastAPI application and port already used
+by Hermes. It exposes read-only market/status routes, deterministic analysis,
+and the existing server-revalidated Paper execution path. The Luxury template
+is loaded from the packaged templates directory; no second frontend, backend,
+port, or decision engine is created here.
 """
 from __future__ import annotations
 
 import asyncio
 import calendar
+import hashlib
 import json
+import math
 import os
+import re
 from pathlib import Path
 import secrets
 import time
+from typing import Literal
 
 import httpx
-from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi import APIRouter, Depends, HTTPException, Query
 from fastapi.security import HTTPBasic, HTTPBasicCredentials
 from fastapi.responses import HTMLResponse, JSONResponse
 from pydantic import BaseModel, Field
 
 from trading import state as _dash_state
-from trading.dual_datasource_client import DS4_BASE, DS2_BASE
+from trading.dual_datasource_client import DS4_BASE, DS2_BASE, get_market_context
+import trading.binance_public_client as binance_public
 from trading.futures_execution import get_futures_positions as _get_futures_positions
 from trading.futures_execution import get_futures_account as _get_futures_account
 from trading.futures_execution import get_trading_mode as _get_trading_mode
 from trading.trade_cycle import run_futures_cycle as _run_futures_cycle
-from trading.dual_datasource_client import get_market_context as _get_market_context
 from trading.symbols import normalize_symbol
 
 router = APIRouter()
@@ -57,7 +48,7 @@ _EMERGENCY_BASES = tuple("""BTC ETH USDT BNB SOL XRP USDC ADA AVAX DOGE DOT TRX
 
 class _CycleRequest(BaseModel):
     symbol: str
-    risk_profile: str = "moderate"
+    risk_profile: Literal["conservative", "moderate", "aggressive"] = "moderate"
     include_external_context: bool = False
 
     class Config:
@@ -66,7 +57,7 @@ class _CycleRequest(BaseModel):
 
 class _PaperExecutionRequest(BaseModel):
     symbol: str
-    risk_profile: str = "moderate"
+    risk_profile: Literal["conservative", "moderate", "aggressive"] = "moderate"
     plan_id: str = Field(alias="planId")
 
     class Config:
@@ -110,20 +101,13 @@ def _is_future_iso(value: object) -> bool:
         return False
 
 
-async def _probe(url: str, timeout: float = 3.0) -> dict:
-    started = time.perf_counter()
+async def _probe(url: str, timeout: float = 3.0) -> str:
     try:
         async with httpx.AsyncClient() as client:
             resp = await client.get(url, timeout=timeout)
-            status = "healthy" if resp.status_code < 400 else "degraded"
-            return {"status": status, "endpoint": url, "httpStatus": resp.status_code,
-                    "latencyMs": round((time.perf_counter()-started)*1000, 1),
-                    "lastSuccessful": time.time() if resp.status_code < 400 else None,
-                    "failureReason": None if resp.status_code < 400 else f"HTTP {resp.status_code}"}
-    except Exception as exc:
-        return {"status": "unavailable", "endpoint": url,
-                "latencyMs": round((time.perf_counter()-started)*1000, 1),
-                "lastSuccessful": None, "failureReason": type(exc).__name__}
+            return "ok" if resp.status_code < 400 else "degraded"
+    except Exception:
+        return "unreachable"
 
 
 async def _mark_price(ccxt_perp_symbol: str) -> float | None:
@@ -135,10 +119,42 @@ async def _mark_price(ccxt_perp_symbol: str) -> float | None:
             resp = await client.get(f"{DS4_BASE}/api/short-hunter/snapshot/{norm.ds4}", timeout=3.0)
             resp.raise_for_status()
             data = resp.json()
-            ticker = data.get("ticker") or {}
-            return ticker.get("last") or ticker.get("markPrice") or ticker.get("close")
+            candidates = [data] if isinstance(data, dict) else []
+            for wrapper in ("data", "snapshot", "market", "marketData", "futures", "result"):
+                for candidate in list(candidates):
+                    nested = candidate.get(wrapper) if isinstance(candidate, dict) else None
+                    if isinstance(nested, dict) and nested not in candidates:
+                        candidates.append(nested)
+            for candidate in candidates:
+                ticker = candidate.get("ticker") or candidate.get("marketTicker") or candidate.get("quote")
+                if isinstance(ticker, dict):
+                    price = _finite(_first(ticker, "markPrice", "lastPrice", "last", "close", "price"))
+                    if price is not None and price > 0:
+                        return price
     except Exception:
         return None
+    return None
+
+
+def _boolean_flag(value: object) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)) and value in (0, 1):
+        return bool(value)
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "yes", "1", "verified", "futures"}:
+            return True
+        if normalized in {"false", "no", "0", "unverified", "market_only"}:
+            return False
+    return None
+
+
+def _normalized_symbol_or_422(symbol: str):
+    try:
+        return normalize_symbol(symbol)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail="Invalid market symbol") from exc
 
 
 def _symbol_items(payload: object, source: str, *, futures_default: bool = False) -> list[dict]:
@@ -166,11 +182,22 @@ def _symbol_items(payload: object, source: str, *, futures_default: bool = False
             continue
         if not isinstance(raw, dict):
             continue
-        status = str(raw.get("status") or ("TRADING" if futures_default else "UNKNOWN")).upper()
-        contract_type = str(raw.get("contractType") or raw.get("type") or "PERPETUAL").upper()
+        raw_status = raw.get("status") or raw.get("contractStatus") or raw.get("state")
+        status = str(raw_status or ("TRADING" if futures_default else "UNKNOWN")).upper()
+        raw_contract_type = raw.get("contractType") or raw.get("type") or raw.get("marketType") or raw.get("instrumentType")
+        contract_type = str(raw_contract_type or "UNKNOWN").upper()
         symbol = str(raw.get("symbol") or raw.get("id") or "").upper()
-        is_futures = bool(raw.get("isFutures") or raw.get("futuresVerified") or futures_default)
-        if futures_default and (status not in {"TRADING", "ACTIVE", "OPEN"} or not is_futures):
+        explicit_flag = _boolean_flag(raw.get("futuresVerified"))
+        if explicit_flag is None:
+            explicit_flag = _boolean_flag(raw.get("isFutures"))
+        if explicit_flag is None:
+            explicit_flag = _boolean_flag(raw.get("isFuture"))
+        type_is_futures = any(token in contract_type for token in ("FUTURE", "PERPETUAL", "SWAP"))
+        is_futures = explicit_flag is True or (explicit_flag is None and futures_default and type_is_futures)
+        active = status in {"TRADING", "ACTIVE", "OPEN"} or (
+            raw_status is None and (futures_default or explicit_flag is True)
+        )
+        if futures_default and (not active or not is_futures):
             continue
         try:
             # KuCoin Futures uses symbols such as XBTUSDTM; use the verified
@@ -184,9 +211,10 @@ def _symbol_items(payload: object, source: str, *, futures_default: bool = False
                        "quoteAsset": str(raw.get("quoteAsset") or norm.quote),
                        "name": str(raw.get("name") or raw.get("baseAsset") or norm.base),
                        "rank": raw.get("rank") or raw.get("market_cap_rank"),
-                       "contractType": "PERPETUAL" if is_futures else "UNKNOWN",
-                       "status": "TRADING" if is_futures and status in {"TRADING", "ACTIVE", "OPEN"} else "UNKNOWN",
-                       "futuresVerified": is_futures, "source": source})
+                       "contractType": contract_type if is_futures else "UNKNOWN",
+                       "status": status if active else "UNKNOWN",
+                       "futuresVerified": bool(is_futures and active),
+                       "source": str(raw.get("source") or source)})
     unique = {item["symbol"]: item for item in result}
     return sorted(unique.values(), key=lambda item: item["symbol"])
 
@@ -200,7 +228,11 @@ async def _load_symbols() -> tuple[list[dict], str]:
         try:
             cached = json.loads(_SYMBOL_CACHE_PATH.read_text(encoding="utf-8"))
             if isinstance(cached, dict) and isinstance(cached.get("items"), list):
-                _symbol_cache.update(items=cached["items"], updatedAt=float(cached.get("updatedAt") or 0), source="cache")
+                cached_items = _symbol_items(cached["items"], "cache", futures_default=False)
+                if cached_items:
+                    _symbol_cache.update(
+                        items=cached_items, updatedAt=float(cached.get("updatedAt") or 0), source="cache"
+                    )
         except (OSError, ValueError, TypeError):
             pass
     async with httpx.AsyncClient() as client:
@@ -209,7 +241,10 @@ async def _load_symbols() -> tuple[list[dict], str]:
             try:
                 response = await client.get(f"{DS4_BASE}{path}", timeout=3.0)
                 if response.status_code < 400:
-                    items = _symbol_items(response.json(), "datasource4", futures_default=True)
+                    items = _symbol_items(
+                        response.json(), "datasource4",
+                        futures_default=path == "/api/short-hunter/universe",
+                    )
                     if items:
                         # Preserve verified Futures contracts, then enlarge with DS2 market assets.
                         break
@@ -246,13 +281,16 @@ async def _load_symbols() -> tuple[list[dict], str]:
                                   "name": norm.base, "rank": None, "contractType": "UNKNOWN",
                                   "status": "UNKNOWN", "futuresVerified": False, "source": "seed"})
                     seen.add(norm.ds4)
-            _symbol_cache.update(items=items, updatedAt=now, source="datasource4+datasource2")
+            aggregate_source = "+".join(dict.fromkeys(
+                str(item.get("source") or "unknown") for item in items
+            ))
+            _symbol_cache.update(items=items, updatedAt=now, source=aggregate_source)
             try:
                 _SYMBOL_CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
                 _SYMBOL_CACHE_PATH.write_text(json.dumps({"items": items, "updatedAt": now}), encoding="utf-8")
             except OSError:
                 pass
-            return items, "datasource4+datasource2"
+            return items, aggregate_source
     if _symbol_cache["items"]:
         return list(_symbol_cache["items"]), "cache"
     items = []
@@ -268,29 +306,365 @@ async def _load_symbols() -> tuple[list[dict], str]:
     return items, "seed"
 
 
-@router.get("/api/futures/status")
+def _epoch_to_iso(value: object) -> str | None:
+    if not isinstance(value, (int, float)):
+        return value if isinstance(value, str) else None
+    seconds = float(value)
+    if seconds > 100_000_000_000:
+        seconds /= 1000.0
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(seconds))
+
+
+def _file_sha256(path: Path) -> str | None:
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except OSError:
+        return None
+
+
+def _path_info(path: Path) -> dict:
+    resolved = path.resolve(strict=False)
+    return {
+        "path": str(resolved),
+        "exists": resolved.is_file(),
+        "sha256": _file_sha256(resolved),
+        "size": resolved.stat().st_size if resolved.is_file() else None,
+    }
+
+
+def _runtime_files() -> dict:
+    router_path = Path(__file__).resolve()
+    try:
+        router_source = router_path.read_text(encoding="utf-8")
+    except OSError:
+        router_source = ""
+    inline_page_count = len(re.findall(r"(?m)^\s*_PAGE\s*=", router_source))
+    runtime_template = _path_info(_TEMPLATE_PATH)
+    runtime_router = _path_info(router_path)
+    overlay_root = Path(os.environ.get("HERMES_OVERLAY_SOURCE", "/opt/hermesface_overlay"))
+    persisted_overlay_root = Path("/opt/data/hermes_overlay")
+    overlay_template = _path_info(overlay_root / "tools" / "templates" / "hermes_futures_desk_luxury.html")
+    overlay_router = _path_info(overlay_root / "tools" / "futures_dashboard_api.py")
+    persisted_overlay_template = _path_info(
+        persisted_overlay_root / "tools" / "templates" / "hermes_futures_desk_luxury.html"
+    )
+    persisted_overlay_router = _path_info(
+        persisted_overlay_root / "tools" / "futures_dashboard_api.py"
+    )
+    sync_script = _path_info(Path(os.environ.get("HERMES_SYNC_SCRIPT", "/opt/data/scripts/sync_hf.py")))
+    manifest_path = Path(os.environ.get(
+        "HERMES_FUTURES_OVERLAY_MANIFEST", "/opt/hermes/.hermes_futures_overlay_manifest.json"
+    ))
+    manifest = None
+    try:
+        loaded = json.loads(manifest_path.read_text(encoding="utf-8"))
+        if isinstance(loaded, dict):
+            manifest = loaded
+    except (OSError, ValueError, TypeError):
+        manifest = None
+    router_matches_overlay = bool(
+        runtime_router["sha256"] and runtime_router["sha256"] == overlay_router["sha256"]
+    ) if overlay_router["exists"] else None
+    template_matches_overlay = bool(
+        runtime_template["sha256"] and runtime_template["sha256"] == overlay_template["sha256"]
+    ) if overlay_template["exists"] else None
+    router_matches_persisted = bool(
+        runtime_router["sha256"] and runtime_router["sha256"] == persisted_overlay_router["sha256"]
+    ) if persisted_overlay_router["exists"] else None
+    template_matches_persisted = bool(
+        runtime_template["sha256"] and runtime_template["sha256"] == persisted_overlay_template["sha256"]
+    ) if persisted_overlay_template["exists"] else None
+    manifest_files = manifest.get("files") if isinstance(manifest, dict) else None
+    manifest_matches_runtime = None
+    if isinstance(manifest_files, dict):
+        router_manifest = manifest_files.get("router") or {}
+        template_manifest = manifest_files.get("template") or {}
+        manifest_matches_runtime = bool(
+            router_manifest.get("destinationSha256") == runtime_router["sha256"]
+            and template_manifest.get("destinationSha256") == runtime_template["sha256"]
+            and router_manifest.get("matches") is True
+            and template_manifest.get("matches") is True
+        )
+    runtime_mismatch = (
+        not runtime_template["exists"]
+        or inline_page_count != 0
+        or router_matches_overlay is False
+        or template_matches_overlay is False
+        or manifest_matches_runtime is False
+    )
+    runtime_evidence = (
+        (router_matches_overlay is True and template_matches_overlay is True)
+        or manifest_matches_runtime is True
+    )
+    runtime_consistent = False if runtime_mismatch else (True if runtime_evidence else None)
+    return {
+        "routerPath": str(router_path),
+        "routerSha256": runtime_router["sha256"],
+        "templatePath": str(_TEMPLATE_PATH.resolve()),
+        "templateSha256": runtime_template["sha256"],
+        "templateExists": _TEMPLATE_PATH.is_file(),
+        "templateSource": "packaged_file" if _TEMPLATE_PATH.is_file() else "safe_fallback",
+        "inlinePageCount": inline_page_count,
+        "duplicateInlinePage": inline_page_count > 1,
+        "runtimeConsistent": runtime_consistent,
+        "runtimeRouter": runtime_router,
+        "runtimeTemplate": runtime_template,
+        "overlayRouter": overlay_router,
+        "overlayTemplate": overlay_template,
+        "persistedOverlayRouter": persisted_overlay_router,
+        "persistedOverlayTemplate": persisted_overlay_template,
+        "syncScript": sync_script,
+        "installManifest": {
+            "path": str(manifest_path.resolve(strict=False)),
+            "exists": manifest_path.is_file(),
+            "matchesRuntime": manifest_matches_runtime,
+            "content": manifest,
+        },
+        "routerMatchesOverlay": router_matches_overlay,
+        "templateMatchesOverlay": template_matches_overlay,
+        "routerMatchesPersistedOverlay": router_matches_persisted,
+        "templateMatchesPersistedOverlay": template_matches_persisted,
+    }
+
+
+def _sanitize_text(value: object, limit: int = 500) -> str:
+    text = re.sub(r"[\r\n\t]+", " ", str(value or "")).strip()
+    # Redact both header-style credentials and JSON/query-style secret values.
+    text = re.sub(
+        r"(?i)\b(authorization|proxy-authorization)\b\s*[:=]\s*(?:bearer|basic)?\s*[^\s,;]+",
+        r"\1=[redacted]",
+        text,
+    )
+    text = re.sub(
+        r"(?ix)\b(token|secret|password|api[_-]?key|webhook[_-]?secret|bootstrap[_-]?secret)\b[\s\"']*[:=][\s\"']*[^\s,;&}\"']+",
+        r"\1=[redacted]",
+        text,
+    )
+    text = re.sub(r"https?://[^\s]+", lambda m: m.group(0).split("?", 1)[0], text)
+    return text[:limit]
+
+
+def _sanitized_diagnostics(value: object) -> object:
+    if isinstance(value, dict):
+        return {str(k): _sanitized_diagnostics(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_sanitized_diagnostics(v) for v in value[:100]]
+    return _sanitize_text(value) if isinstance(value, str) else value
+
+
+def _source_status(meta: dict) -> str:
+    transport = str(meta.get("transportStatus") or "unknown").lower()
+    usability = str(meta.get("dataUsability") or "unknown").lower()
+    freshness = str(meta.get("freshness") or "unknown").lower()
+    completeness = str(meta.get("completeness") or "unknown").lower()
+    if transport in {"unavailable", "failed"}:
+        return "unreachable"
+    if transport == "restricted" or usability == "unavailable":
+        return "unavailable"
+    if transport == "healthy" and usability in {"healthy", "usable"} \
+            and freshness == "fresh" and completeness == "complete":
+        return "ok"
+    return "degraded"
+
+
+def _normalize_source_meta(name: str, url: str, meta: object) -> dict:
+    normalized = dict(meta) if isinstance(meta, dict) else {}
+    normalized.setdefault("name", name)
+    normalized.setdefault("url", url)
+    normalized.setdefault("endpoint", url)
+    normalized.setdefault("transportStatus", "unknown")
+    normalized.setdefault("dataUsability", "unknown")
+    normalized.setdefault("freshness", "unknown")
+    normalized.setdefault("completeness", "unknown")
+    normalized.setdefault("httpStatus", None)
+    normalized.setdefault("latencyMs", None)
+    normalized.setdefault("lastSuccess", None)
+    normalized.setdefault("suppliedFields", [])
+    normalized.setdefault("missingFields", [])
+    normalized.setdefault("reason", f"{name} has not produced structured market metadata yet")
+    normalized["status"] = normalized.get("status") or _source_status(normalized)
+    return normalized
+
+
+def _source_fallback(name: str, status: str, url: str) -> dict:
+    transport = "healthy" if status == "ok" else ("unavailable" if status == "unreachable" else "degraded")
+    return _normalize_source_meta(name, url, {
+        "transportStatus": transport,
+        "dataUsability": "unknown",
+        "freshness": "unknown",
+        "completeness": "unknown",
+        "reason": f"{name} has not produced structured market metadata yet",
+    })
+
+
+def _market_health(state: dict, source_metadata: dict) -> str:
+    field_metadata = state.get("field_metadata") or {}
+    required = ("ticker", "funding", "openInterest")
+    required_meta = [field_metadata.get(name) or {} for name in required]
+    if state.get("merge_status") == "complete" and required_meta \
+            and all(item.get("validity") == "valid" and item.get("freshness") == "fresh" for item in required_meta):
+        return "healthy"
+    if any((item.get("validity") == "valid") for item in field_metadata.values() if isinstance(item, dict)):
+        return "degraded"
+    if any(str(meta.get("transportStatus")).lower() == "healthy" for meta in source_metadata.values()):
+        return "degraded"
+    return "unavailable"
+
+
+def _freshness_from_timestamp(value: object, interval: str) -> str:
+    if value is None:
+        return "unknown"
+    try:
+        if isinstance(value, str) and not value.isdigit():
+            parsed = calendar.timegm(time.strptime(value, "%Y-%m-%dT%H:%M:%SZ"))
+        else:
+            number = float(value)
+            parsed = number / 1000.0 if number > 100_000_000_000 else number
+    except (TypeError, ValueError, OverflowError):
+        return "unknown"
+    interval_seconds = {"1m": 60, "5m": 300, "15m": 900, "1h": 3600}.get(interval, 300)
+    age = time.time() - parsed
+    if age < -60:
+        return "invalid"
+    return "fresh" if age <= max(180, interval_seconds * 3) else "stale"
+
+
+def _finite(value: object) -> float | None:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if math.isfinite(number) else None
+
+
+def _first(mapping: object, *keys: str) -> object:
+    if not isinstance(mapping, dict):
+        return None
+    for key in keys:
+        if mapping.get(key) is not None:
+            return mapping[key]
+    return None
+
+
+def _normalize_candles(raw: object, limit: int) -> list[dict]:
+    if not isinstance(raw, list):
+        return []
+    candles: list[dict] = []
+    for item in raw[-limit:]:
+        if isinstance(item, dict):
+            ts = _first(item, "timestamp", "time", "ts", "openTime")
+            values = [_finite(_first(item, key, short)) for key, short in (
+                ("open", "o"), ("high", "h"), ("low", "l"), ("close", "c"), ("volume", "v")
+            )]
+            source = item.get("source")
+        elif isinstance(item, (list, tuple)) and len(item) >= 6:
+            ts, values, source = item[0], [_finite(v) for v in item[1:6]], None
+        else:
+            continue
+        open_, high, low, close, volume = values
+        if ts is None or None in (open_, high, low, close, volume):
+            continue
+        if min(open_, high, low, close) <= 0 or volume < 0 or high < max(open_, close, low) or low > min(open_, close, high):
+            continue
+        candle = {"timestamp": ts, "open": open_, "high": high, "low": low, "close": close, "volume": volume}
+        if source:
+            candle["source"] = source
+        candles.append(candle)
+    return candles
+
+
+def _catalog_counts(items: list[dict]) -> dict:
+    verified = sum(1 for item in items if item.get("futuresVerified") is True)
+    total = len(items)
+    return {"total": total, "verifiedFutures": verified, "marketOnly": total - verified}
+
+
+def _public_field_metadata(metadata: object) -> dict:
+    """Bound large market fields while preserving value/source/freshness semantics."""
+    if not isinstance(metadata, dict):
+        return {}
+    public: dict[str, dict] = {}
+    for field, raw in metadata.items():
+        if not isinstance(raw, dict):
+            continue
+        item = {key: raw.get(key) for key in (
+            "source", "timestamp", "freshness", "validity", "fallbackStatus"
+        ) if key in raw}
+        value = raw.get("value")
+        if field == "ohlcv" and isinstance(value, list):
+            item["value"] = {"count": len(value), "latest": value[-1] if value else None}
+        elif field == "orderbook" and isinstance(value, dict):
+            bids, asks = value.get("bids") or [], value.get("asks") or []
+            item["value"] = {
+                "bidLevels": len(bids), "askLevels": len(asks),
+                "bestBid": bids[0] if bids else None, "bestAsk": asks[0] if asks else None,
+            }
+        else:
+            item["value"] = value
+        public[str(field)] = item
+    return public
+
+
+@router.get("/api/futures/status", dependencies=[Depends(_authenticated_dashboard_request)])
 async def futures_status() -> JSONResponse:
     state = _dash_state.snapshot()
-    ds4_health, ds2_primary, ds2_fallback = await asyncio.gather(
+    ds4_probe, ds2_probe = await asyncio.gather(
         _probe(f"{DS4_BASE}/api/short-hunter/health"),
         _probe(f"{DS2_BASE}/real/api/market/tickers"),
-        _probe(f"{DS2_BASE}/api/coins/top"),
     )
-    def health_obj(value):
-        return value if isinstance(value, dict) else {"status": value}
-    ds4_health, ds2_primary, ds2_fallback = map(health_obj, (ds4_health, ds2_primary, ds2_fallback))
-    ds2_health = ds2_primary if ds2_primary.get("status") in {"healthy", "ok"} else ds2_fallback
-    ds2_health["fallbackEndpoint"] = ds2_fallback.get("endpoint")
-    account = await _get_futures_account()
-    positions = await _get_futures_positions()
+    account, positions = await asyncio.gather(_get_futures_account(), _get_futures_positions())
+    raw_source_metadata = dict(state.get("source_metadata") or {})
+    restricted = any("HTTP 451" in str(w) for w in state.get("warnings", []))
+    source_metadata = {
+        "datasource4": _normalize_source_meta(
+            "Datasource 4", DS4_BASE,
+            raw_source_metadata.get("datasource4") or _source_fallback("Datasource 4", ds4_probe, DS4_BASE),
+        ),
+        "binance": _normalize_source_meta(
+            "Binance public", binance_public.BASE_URL,
+            raw_source_metadata.get("binance") or {
+                "transportStatus": "restricted" if restricted else "standby",
+                "dataUsability": "unavailable" if restricted else "not_used",
+                "freshness": "unknown", "completeness": "unknown",
+                "httpStatus": 451 if restricted else None,
+                "reason": "Regionally restricted" if restricted else "Fallback available on demand",
+            },
+        ),
+        "datasource2": _normalize_source_meta(
+            "Datasource 2", DS2_BASE,
+            raw_source_metadata.get("datasource2") or _source_fallback("Datasource 2", ds2_probe, DS2_BASE),
+        ),
+    }
+    market_health = _market_health(state, source_metadata)
+    runtime_files = _runtime_files()
+    runtime_consistent = runtime_files.get("runtimeConsistent")
+    runtime_status = "verified" if runtime_consistent is True else (
+        "mismatch" if runtime_consistent is False else "unknown"
+    )
     return JSONResponse({
-        "primaryDatasource": {**ds4_health, "url": DS4_BASE},
-        "secondaryDatasource": {**ds2_health, "url": DS2_BASE,
-                                 "primaryEndpoint": ds2_primary.get("endpoint")},
+        "application": {
+            "status": "online",
+            "runtimeStatus": runtime_status,
+            "runtimeFiles": runtime_files,
+        },
+        "marketData": {"status": market_health},
+        "tradingReadiness": state.get("trading_readiness", "blocked"),
+        "mergeStatus": state.get("merge_status", "unknown"),
+        "analysisState": state.get("analysis_state", "NOT_ANALYZED"),
+        "primaryDatasource": source_metadata["datasource4"],
+        "binanceDatasource": source_metadata["binance"],
+        "secondaryDatasource": source_metadata["datasource2"],
+        "sourceMetadata": source_metadata,
         "fieldSources": state.get("field_sources", {}),
+        "fieldMetadata": _public_field_metadata(state.get("field_metadata", {})),
+        "verifiedFutures": state.get("verified_futures", False),
+        "futuresVerification": state.get("futures_verification", {}),
+        "missingRequiredFields": state.get("missing_required_fields", []),
+        "staleRequiredFields": state.get("stale_required_fields", []),
         "currentSignal": state.get("current_signal"),
         "signalReasons": state.get("signal_reasons", []),
         "warnings": state.get("warnings", []),
+        "technicalDiagnostics": _sanitized_diagnostics(state.get("technical_diagnostics", {})),
         "rejectedTradeReason": state.get("rejected_trade_reason"),
         "latestTradePlan": state.get("latest_trade_plan"),
         "latestPlanId": state.get("latest_plan_id"),
@@ -298,8 +672,11 @@ async def futures_status() -> JSONResponse:
         "signalComponents": state.get("signal_components", {}),
         "riskApproved": state.get("risk_approved", False),
         "rejectionReasons": state.get("rejection_reasons", []),
+        "marketRejectionReasons": state.get("market_rejection_reasons", []),
         "planCreatedAt": state.get("latest_plan_created_at"),
         "planExpiresAt": state.get("latest_plan_expires_at"),
+        "planCreatedAtIso": _epoch_to_iso(state.get("latest_plan_created_at")),
+        "planExpiresAtIso": _epoch_to_iso(state.get("latest_plan_expires_at")),
         "latestPaperExecutionResult": state.get("latest_paper_execution_result"),
         "planExecuted": state.get("latest_plan_executed", False),
         "tradingMode": account.get("mode"),
@@ -308,77 +685,234 @@ async def futures_status() -> JSONResponse:
         "openPositionCount": len(positions.get("positions", [])),
         "updatedAt": state.get("updated_at"),
         "serverTime": time.time(),
-        "marketDataStatus": "healthy" if ds4_health.get("status") == "healthy" else "degraded",
-    })
+    }, headers={"Cache-Control": "no-store"})
 
 
 @router.get("/api/futures/symbols", dependencies=[Depends(_authenticated_dashboard_request)])
 async def futures_symbols() -> JSONResponse:
     items, source = await _load_symbols()
     updated = _symbol_cache.get("updatedAt") or time.time()
+    updated_iso = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(float(updated)))
     for item in items:
         item.setdefault("source", source)
-        item["updatedAt"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(float(updated)))
-    verified = sum(1 for item in items if item.get("futuresVerified") is True)
-    return JSONResponse({"symbols": items, "source": source,
-                         "catalogCount": len(items), "verifiedFuturesCount": verified,
-                         "marketOnlyCount": max(0, len(items)-verified),
-                         "updatedAt": items[0]["updatedAt"] if items else None})
+        item["updatedAt"] = updated_iso
+        item["marketOnly"] = not bool(item.get("futuresVerified"))
+    return JSONResponse({
+        "symbols": items, "source": source, "updatedAt": updated_iso if items else None,
+        "counts": _catalog_counts(items),
+    }, headers={"Cache-Control": "no-store"})
 
 
-@router.get("/api/futures/positions")
+@router.get("/api/futures/positions", dependencies=[Depends(_authenticated_dashboard_request)])
 async def futures_positions() -> JSONResponse:
     positions = await _get_futures_positions()
-    sem = asyncio.Semaphore(4)
-    async def enrich(p):
-        async with sem:
-            try:
-                mark = await asyncio.wait_for(_mark_price(p["symbol"]), timeout=4.0)
-            except Exception:
-                mark = None
+    raw_positions = list(positions.get("positions", []))
+    marks = await asyncio.gather(*(
+        _mark_price(position["symbol"]) for position in raw_positions
+    )) if raw_positions else []
+    enriched = []
+    for position, mark in zip(raw_positions, marks):
         unrealized = None
         if mark:
-            direction = 1 if p["side"] == "long" else -1
-            unrealized = (mark - p["entryPrice"]) * p["size"] * direction
-        return {**p, "markPrice": mark, "unrealizedPnl": unrealized}
-    enriched = await asyncio.gather(*(enrich(p) for p in positions.get("positions", [])))
-    return JSONResponse({"mode": positions.get("mode"), "positions": enriched})
+            direction = 1 if position["side"] == "long" else -1
+            unrealized = (mark - position["entryPrice"]) * position["size"] * direction
+        enriched.append({**position, "markPrice": mark, "unrealizedPnl": unrealized})
+    return JSONResponse(
+        {"mode": positions.get("mode"), "positions": enriched},
+        headers={"Cache-Control": "no-store"},
+    )
 
 
 @router.get("/api/futures/market", dependencies=[Depends(_authenticated_dashboard_request)])
-async def futures_market(symbol: str = "BTCUSDT", interval: str = "5m", limit: int = 120) -> JSONResponse:
-    """Return real merged OHLCV and market metrics for the chart."""
-    if interval not in {"1m", "5m", "15m", "1h"}:
-        raise HTTPException(status_code=400, detail="Unsupported interval")
-    context = await _get_market_context(symbol, timeframe=interval)
-    merged = context.get("merged") or {}
-    candles = merged.get("ohlcv") or []
-    if limit > 0:
-        candles = candles[-min(limit, 500):]
-    ticker = merged.get("ticker") or {}
-    return JSONResponse({"symbol": context.get("symbol"), "interval": interval,
-                         "candles": candles, "ticker": ticker,
-                         "funding": merged.get("funding"),
-                         "openInterest": merged.get("openInterest"),
-                         "source": context.get("sources", {}).get("ohlcv", "unavailable"),
-                         "sources": context.get("sources", {}),
-                         "fetchedAt": context.get("fetchedAt"),
-                         "warnings": context.get("warnings", []),
-                         "noTradeGuard": context.get("noTradeGuard", True)})
+async def futures_market(
+    symbol: str = Query("BTCUSDT", min_length=3, max_length=32),
+    interval: Literal["1m", "5m", "15m", "1h"] = Query("5m"),
+    limit: int = Query(120, ge=20, le=500),
+) -> JSONResponse:
+    """Return real read-only market data with explicit partial/unavailable semantics."""
+    norm = _normalized_symbol_or_422(symbol)
+    try:
+        context = await get_market_context(norm.ds4, timeframe=interval, limit=limit)
+        _dash_state.record_market_context(context)
+    except Exception as exc:
+        return JSONResponse({
+            "state": "unavailable",
+            "analysisState": "API_UNAVAILABLE",
+            "dataUsability": "unavailable",
+            "reason": "Market data request failed",
+            "symbol": norm.ds4,
+            "interval": interval,
+            "limit": limit,
+            "candles": [],
+            "currentPrice": None,
+            "markPrice": None,
+            "change24h": None,
+            "volume24h": None,
+            "fundingRate": None,
+            "openInterest": None,
+            "source": "unavailable",
+            "sourcesUsed": [],
+            "fieldSources": {},
+            "fieldMetadata": {},
+            "freshness": "unknown",
+            "timestamp": None,
+            "verifiedFutures": False,
+            "futuresVerification": {
+                "verified": False,
+                "status": "unavailable",
+                "reason": "Market data request failed",
+            },
+            "contractStatus": "unavailable",
+            "warnings": ["Market data provider request failed"],
+            "missingFields": ["candles", "price", "funding", "openInterest"],
+            "analysisRequiredFieldsMissing": [
+                "contract", "ticker", "orderbook", "funding", "openInterest"
+            ],
+            "staleRequiredFields": [],
+            "mergeStatus": "unavailable",
+            "tradingReadiness": "blocked",
+            "rejectionReasons": ["Market data request failed"],
+            "sourceMetadata": {},
+            "technicalDiagnostics": {"market": [_sanitize_text(type(exc).__name__)]},
+            "fetchedAt": time.time(),
+        }, status_code=503, headers={"Cache-Control": "no-store"})
+
+    merged = dict(context.get("merged") or {})
+    sources = dict(context.get("sources") or {})
+    warnings = [_sanitize_text(item) for item in (context.get("warnings") or [])]
+    diagnostics = _sanitized_diagnostics(context.get("technicalDiagnostics") or {})
+    field_metadata = dict(context.get("fieldMetadata") or {})
+    source_metadata = {
+        key: _normalize_source_meta(
+            {"datasource4": "Datasource 4", "binance": "Binance public", "datasource2": "Datasource 2"}.get(key, key),
+            {"datasource4": DS4_BASE, "binance": binance_public.BASE_URL, "datasource2": DS2_BASE}.get(key, ""),
+            value,
+        )
+        for key, value in (context.get("sourceMetadata") or {}).items()
+    }
+    candles = _normalize_candles(merged.get("ohlcv"), limit)
+    ticker = merged.get("ticker") if isinstance(merged.get("ticker"), dict) else {}
+    funding = merged.get("funding") if isinstance(merged.get("funding"), dict) else {}
+    open_interest = merged.get("openInterest") if isinstance(merged.get("openInterest"), dict) else {}
+
+    price = _finite(_first(ticker, "markPrice", "lastPrice", "last", "price", "close"))
+    if price is None and candles:
+        price = candles[-1]["close"]
+    mark_price = _finite(_first(ticker, "markPrice"))
+    change_24h = _finite(_first(
+        ticker, "change24h", "changePercent", "priceChangePercent", "percentage", "price24hPcnt"
+    ))
+    volume = _finite(_first(
+        ticker, "volume24h", "quoteVolume", "volume", "volValue", "turnover24h", "turnover"
+    ))
+    funding_rate = _finite(_first(
+        funding, "currentFundingRate", "fundingRate", "lastFundingRate", "rate"
+    ))
+    open_interest_value = _finite(_first(
+        open_interest, "openInterest", "open_interest", "sumOpenInterest", "oi"
+    ))
+
+    display_missing = [name for name, value in (
+        ("candles", candles), ("price", price), ("funding", funding_rate),
+        ("openInterest", open_interest_value),
+    ) if value in (None, [], {})]
+    display_freshness = []
+    for field in ("ohlcv", "ticker", "funding", "openInterest"):
+        label = str((field_metadata.get(field) or {}).get("freshness") or "unknown").lower()
+        if label:
+            display_freshness.append(label)
+    aggregate_freshness = (
+        "invalid" if "invalid" in display_freshness else
+        "stale" if "stale" in display_freshness else
+        "fresh" if display_freshness and all(label == "fresh" for label in display_freshness) else
+        "unknown"
+    )
+    if not candles or price is None:
+        state = "unavailable"
+        usability = "unavailable"
+        reason = "Real OHLCV candles or a current price are unavailable"
+    elif aggregate_freshness in {"stale", "invalid"}:
+        state = "stale"
+        usability = "degraded"
+        reason = "Market data freshness is invalid or stale"
+    elif aggregate_freshness != "fresh":
+        state = "partial"
+        usability = "degraded"
+        reason = "Market data freshness could not be verified"
+    elif display_missing:
+        state = "partial"
+        usability = "degraded"
+        reason = "Required Futures display fields are incomplete"
+    else:
+        state = "available"
+        usability = "usable"
+        reason = None
+
+    used_sources = sorted({source for source in sources.values() if source not in {None, "", "unavailable"}})
+    primary_source = sources.get("ohlcv") or sources.get("ticker") or "unavailable"
+    if len(used_sources) > 1:
+        primary_source = "mixed"
+    verification = context.get("futuresVerification") or {}
+    verified = bool(context.get("verifiedFutures"))
+    rejection_reasons = list(context.get("noTradeReasons") or [])
+    payload = {
+        "state": state,
+        "analysisState": "API_UNAVAILABLE" if state == "unavailable" else (
+            "STALE" if state == "stale" else "NOT_ANALYZED"
+        ),
+        "dataUsability": usability,
+        "reason": reason,
+        "symbol": norm.ds4,
+        "interval": interval,
+        "limit": limit,
+        "candles": candles,
+        "currentPrice": price,
+        "markPrice": mark_price,
+        "change24h": change_24h,
+        "volume24h": volume,
+        "fundingRate": funding_rate,
+        "openInterest": open_interest_value,
+        "source": primary_source,
+        "sourcesUsed": used_sources,
+        "fieldSources": sources,
+        "fieldMetadata": _public_field_metadata(field_metadata),
+        "freshness": aggregate_freshness,
+        "timestamp": (field_metadata.get("ohlcv") or {}).get("timestamp")
+                     or (field_metadata.get("ticker") or {}).get("timestamp"),
+        "verifiedFutures": verified,
+        "futuresVerification": verification,
+        "contractStatus": verification.get("status") or ("verified" if verified else "unverified"),
+        "warnings": warnings,
+        "missingFields": display_missing,
+        "analysisRequiredFieldsMissing": list(context.get("missingRequiredFields") or []),
+        "staleRequiredFields": list(context.get("staleRequiredFields") or []),
+        "mergeStatus": context.get("mergeStatus") or "unknown",
+        "tradingReadiness": context.get("tradingReadiness") or "blocked",
+        "rejectionReasons": rejection_reasons,
+        "sourceMetadata": source_metadata,
+        "technicalDiagnostics": diagnostics,
+        "fetchedAt": context.get("fetchedAt"),
+    }
+    return JSONResponse(payload, headers={"Cache-Control": "no-store"})
 
 
 @router.post("/api/futures/analyze", dependencies=[Depends(_authenticated_dashboard_request)])
 async def futures_analyze(request: _CycleRequest) -> JSONResponse:
     """Run analysis only and return a server-referenced deterministic plan."""
+    normalized = _normalized_symbol_or_422(request.symbol)
     try:
         plan = await _run_futures_cycle(
-            request.symbol, risk_profile=request.risk_profile, execute=False,
+            normalized.ds4, risk_profile=request.risk_profile, execute=False,
             include_external_context=request.include_external_context,
         )
         plan_id = _dash_state.record_trade_plan(plan)
-        return JSONResponse(_plan_payload(plan, plan_id))
+        return JSONResponse(
+            _plan_payload(plan, plan_id), headers={"Cache-Control": "no-store"}
+        )
     except Exception as exc:
-        raise HTTPException(status_code=400, detail=f"Futures analysis failed: {exc}") from exc
+        public_message = "Futures analysis failed"
+        _dash_state.record_analysis_failure(public_message, _sanitize_text(type(exc).__name__))
+        raise HTTPException(status_code=503, detail=public_message) from exc
 
 
 @router.post("/api/futures/paper/execute", dependencies=[Depends(_authenticated_dashboard_request)])
@@ -386,13 +920,14 @@ async def futures_paper_execute(request: _PaperExecutionRequest) -> JSONResponse
     """Revalidate a server-held plan before invoking the existing Paper path."""
     async with _paper_cycle_lock:
         state = _dash_state.snapshot()
+        normalized = _normalized_symbol_or_422(request.symbol)
         supported_symbols, _ = await _load_symbols()
         verified = {item["symbol"] for item in supported_symbols if item.get("futuresVerified")}
-        if normalize_symbol(request.symbol).ds4 not in verified:
+        if normalized.ds4 not in verified:
             raise HTTPException(status_code=403, detail="Paper execution requires a verified Futures contract")
         if request.plan_id != state.get("latest_plan_id"):
             raise HTTPException(status_code=409, detail="Unknown or superseded planId")
-        if request.symbol != state.get("latest_plan_symbol") \
+        if normalized.ds4 != state.get("latest_plan_symbol") \
                 or request.risk_profile != state.get("latest_plan_risk_profile"):
             raise HTTPException(status_code=409, detail="Plan symbol or risk profile changed")
         if state.get("latest_plan_executed"):
@@ -400,17 +935,22 @@ async def futures_paper_execute(request: _PaperExecutionRequest) -> JSONResponse
         expires_at = state.get("latest_plan_expires_at")
         if not isinstance(expires_at, (int, float)) or time.time() >= expires_at:
             raise HTTPException(status_code=409, detail="Plan is expired")
-        if state.get("latest_trade_plan", {}).get("decision") not in ("LONG", "SHORT"):
+        stored_plan = state.get("latest_trade_plan") or {}
+        if stored_plan.get("decision") not in ("LONG", "SHORT"):
             raise HTTPException(status_code=409, detail="Only a directional plan can be executed")
+        if stored_plan.get("futuresVerified") is not True:
+            raise HTTPException(status_code=409, detail="Plan is not attached to a verified Futures contract")
+        if stored_plan.get("noTradeGuard") or stored_plan.get("trading_readiness") != "ready":
+            raise HTTPException(status_code=409, detail="Plan is blocked by current trading readiness")
+        if stored_plan.get("executable") is not True:
+            raise HTTPException(status_code=409, detail="Stored plan is not executable")
         if not state.get("risk_approved"):
             raise HTTPException(status_code=409, detail="Plan is not risk-approved")
         if _get_trading_mode() != "paper":
             raise HTTPException(status_code=403, detail="Only Paper execution is enabled")
 
-        # Re-run server-side; browser prices, SL/TP, leverage and quantity are
-        # never accepted or forwarded.
         fresh = await _run_futures_cycle(
-            request.symbol, risk_profile=request.risk_profile, execute=False,
+            normalized.ds4, risk_profile=request.risk_profile, execute=False,
             include_external_context=False,
         )
         if fresh.get("decision") not in ("LONG", "SHORT") or not fresh.get("risk_approved"):
@@ -419,84 +959,28 @@ async def futures_paper_execute(request: _PaperExecutionRequest) -> JSONResponse
                 "message": "Fresh server-side validation rejected the plan",
                 "reasons": fresh.get("rejection_reasons", []) + fresh.get("core_reasons", []),
             })
-        if fresh.get("noTradeGuard") or fresh.get("executed"):
+        if fresh.get("noTradeGuard") or fresh.get("executed") or not fresh.get("executable"):
             raise HTTPException(status_code=409, detail="Fresh plan is not executable")
-        fresh_expiry = fresh.get("expires_at")
-        if not _is_future_iso(fresh_expiry):
+        if not _is_future_iso(fresh.get("expires_at")):
             raise HTTPException(status_code=409, detail="Fresh plan has no valid expiry")
 
-        result = await _run_futures_cycle(
-            request.symbol, risk_profile=request.risk_profile, execute=True,
+        result = dict(await _run_futures_cycle(
+            normalized.ds4, risk_profile=request.risk_profile, execute=True,
             include_external_context=False,
-        )
-        result = dict(result)
+        ))
         _dash_state.record_trade_plan(result, plan_id=request.plan_id)
         _dash_state.record_paper_execution({
-            "executed": bool(result.get("executed")),
-            "symbol": result.get("symbol"),
-            "side": result.get("decision"),
-            "mode": "paper",
+            "executed": bool(result.get("executed")), "symbol": result.get("symbol"),
+            "side": result.get("decision"), "mode": "paper",
             "status": "executed" if result.get("executed") else "rejected",
             "reason": "; ".join(result.get("rejection_reasons", [])),
         })
-        return JSONResponse(_plan_payload(result, request.plan_id))
-
-
-_PAGE = """<!doctype html>
-<html><head><meta charset="utf-8"><title>HermesFace — Futures Desk</title>
-<style>
-body{font-family:ui-monospace,Menlo,Consolas,monospace;background:#0b0f14;color:#d7e2ea;padding:24px;max-width:1100px;margin:auto}
-h1{font-size:16px;color:#9fd3ff;margin-bottom:16px}.card{background:#121821;border:1px solid #223042;border-radius:8px;padding:14px;margin-bottom:12px}
-.row{display:flex;justify-content:space-between;gap:18px;padding:5px 0;border-bottom:1px solid #1b2530;white-space:pre-wrap}
-input,select,button{background:#0d141c;color:#d7e2ea;border:1px solid #38516b;border-radius:4px;padding:7px;margin:3px}
-button:disabled{opacity:.45}.ok{color:#6bd48c}.degraded{color:#e8c14b}.unreachable{color:#e2665c}.LONG{color:#6bd48c}.SHORT{color:#e2665c}.NO_TRADE{color:#8896a3}small{color:#7c8896}
-</style></head><body>
-<h1>HermesFace — Futures Desk (DS4 → Binance → DS2)</h1>
-<div class="card"><label>Symbol <input id="symbol" value="BTCUSDT"></label>
-<label>Risk profile <select id="risk"><option>conservative</option><option selected>moderate</option><option>aggressive</option></select></label>
-<label><input type="checkbox" id="advisory"> Remote advisory</label>
-<button id="analyze">Analyze</button> <button id="execute" disabled>Execute Paper Trade</button>
-<div id="notice"><small>Analysis only until a server plan is directional, risk-approved, fresh, and unexecuted.</small></div></div>
-<div class="card" id="plan">No plan analyzed yet.</div>
-<div class="card" id="status">Loading status…</div><div class="card" id="positions"></div>
-<small>Paper execution only · browser never supplies entry, SL, TP, leverage, or quantity · auto-refresh status every 5s</small>
-<script>
-let latestPlan=null;
-const esc = x => String(x ?? '—').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
-function renderPlan(p){
-  latestPlan=p; const directional=['LONG','SHORT'].includes(p.decision);
-  const fresh=p.expires_at && Date.parse(p.expires_at)>Date.now();
-  const canExecute=directional && !!p.risk_approved && fresh && !p.executed;
-  document.getElementById('execute').disabled=!canExecute;
-  document.getElementById('plan').innerHTML=`<div class="row"><b>Decision</b><b class="${esc(p.decision)}">${esc(p.decision)}</b></div>
-  <div class="row"><span>Plan ID</span><span>${esc(p.planId)}</span></div><div class="row"><span>Score</span><span>${esc(p.score)}</span></div>
-  <div class="row"><span>Signal components</span><span>${esc(JSON.stringify(p.components||{}))}</span></div>
-  <div class="row"><span>Advisory</span><span>${esc(p.external_advisory?((p.external_advisory.provider||'unavailable')+' · '+(p.external_advisory.market_bias||'unknown')+' · '+(p.external_advisory.summary||p.external_advisory.error||'—')):'disabled')}</span></div>
-  <div class="row"><span>Advisory risk warnings</span><span>${esc((p.external_advisory&&p.external_advisory.risk_warnings||[]).join('; ')||'—')}</span></div>
-  <div class="row"><span>Reasons</span><span>${esc((p.core_reasons||[]).join('; ')||'—')}</span></div>
-  <div class="row"><span>Warnings</span><span>${esc((p.warnings||[]).join('; ')||'—')}</span></div>
-  <div class="row"><span>Entry / Stop Loss / Take Profit</span><span>${esc(p.entry)} / ${esc(p.stop_loss)} / ${esc(p.take_profit)}</span></div>
-  <div class="row"><span>Leverage / Quantity / Slippage</span><span>${esc(p.effective_leverage??p.requested_leverage)}x / ${esc(p.quantity)} / ${esc(p.estimated_slippage_percent)}</span></div>
-  <div class="row"><span>Risk approval</span><span>${esc(p.risk_approved)}</span></div>
-  <div class="row"><span>Rejection reasons</span><span>${esc((p.rejection_reasons||[]).join('; ')||'—')}</span></div>
-  <div class="row"><span>Created / Expires</span><span>${esc(p.created_at)} / ${esc(p.expires_at)}</span></div>`;
-  document.getElementById('notice').innerHTML=`<small>${canExecute?'Paper execution is available after browser confirmation.':'Paper execution is disabled until all server safeguards pass.'}</small>`;
-}
-document.getElementById('analyze').onclick=async()=>{
-  const r=await fetch('/api/futures/analyze',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({symbol:document.getElementById('symbol').value,risk_profile:document.getElementById('risk').value,include_external_context:document.getElementById('advisory').checked})});
-  const p=await r.json(); if(!r.ok){document.getElementById('notice').textContent=p.detail||'Analysis failed';return} renderPlan(p);
-};
-document.getElementById('execute').onclick=async()=>{
-  if(!latestPlan||!confirm('Confirm server-side Paper execution for this plan?')) return;
-  const r=await fetch('/api/futures/paper/execute',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({symbol:document.getElementById('symbol').value,risk_profile:document.getElementById('risk').value,planId:latestPlan.planId})});
-  const p=await r.json(); if(!r.ok){document.getElementById('notice').textContent=(p.detail&&p.detail.message)||p.detail||'Paper execution rejected';return} renderPlan(p);
-};
-async function refresh(){
-  const s=await (await fetch('/api/futures/status')).json(); document.getElementById('status').innerHTML=`<div class="row"><span>Primary / Secondary</span><span>${esc(s.primaryDatasource.status)} / ${esc(s.secondaryDatasource.status)}</span></div><div class="row"><span>Current signal / score</span><span>${esc(s.currentSignal)} / ${esc(s.latestSignalScore)}</span></div><div class="row"><span>Trading mode / equity</span><span>${esc(s.tradingMode)} / ${esc(s.equity)}</span></div><div class="row"><span>Risk approved</span><span>${esc(s.riskApproved)}</span></div><div class="row"><span>Warnings / reasons</span><span>${esc((s.warnings||[]).join('; ')||'—')} / ${esc((s.signalReasons||[]).join('; ')||'—')}</span></div>`;
-  const p=await (await fetch('/api/futures/positions')).json(); const rows=(p.positions||[]).map(x=>`<div class="row"><span>${esc(x.symbol)} · ${esc(x.side)} · ${esc(x.leverage)}x</span><span>entry ${esc(x.entryPrice)} · mark ${esc(x.markPrice)} · SL ${esc(x.stopLoss)} · TP ${esc(x.takeProfit)} · uPnL ${esc(x.unrealizedPnl)}</span></div>`).join('')||'<div class="row">No open positions</div>'; document.getElementById('positions').innerHTML=`<b>Open positions (${esc(p.mode)})</b>`+rows;
-}
-refresh(); setInterval(refresh,5000);
-</script></body></html>"""
+        return JSONResponse(
+            _plan_payload(result, request.plan_id), headers={"Cache-Control": "no-store"}
+        )
+
+
+_FALLBACK_PAGE = """<!doctype html><html lang=en><meta charset=utf-8><title>Hermes Futures Desk</title><body><h1>Futures Desk</h1><p>Dashboard template unavailable. Trading remains blocked.</p></body></html>"""
 
 
 @router.get("/futures", response_class=HTMLResponse)
@@ -504,47 +988,11 @@ async def futures_page() -> HTMLResponse:
     try:
         page = _TEMPLATE_PATH.read_text(encoding="utf-8")
     except OSError:
-        page = "<!doctype html><title>Futures Desk unavailable</title><p>The Futures dashboard template is not installed.</p>"
-    return HTMLResponse(page)
-
-
-# The route above intentionally remains unchanged; this assignment replaces
-# only its presentation while keeping the same FastAPI process and endpoint.
-_PAGE = r'''<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<title>HermesFace Futures Desk</title>
-<style>
-:root{color-scheme:dark;--bg:#080d14;--panel:#101923;--panel2:#0c141d;--line:#223243;--text:#e4edf5;--muted:#8ea1b2;--blue:#73b7ff;--green:#51d88a;--yellow:#f4c95d;--red:#ff7180;--shadow:0 12px 34px #0005}
-*{box-sizing:border-box}body{margin:0;background:radial-gradient(circle at 10% -10%,#14263a 0,#080d14 45%);color:var(--text);font:14px Inter,ui-sans-serif,system-ui,sans-serif;min-height:100vh}main{max-width:1480px;margin:auto;padding:24px}.top{display:flex;justify-content:space-between;align-items:flex-start;gap:18px;margin-bottom:20px}.eyebrow{color:var(--blue);font-size:12px;text-transform:uppercase;letter-spacing:.14em}.top h1{margin:5px 0;font-size:28px}.muted,small{color:var(--muted)}.badges{display:flex;flex-wrap:wrap;gap:8px;justify-content:flex-end}.badge{border:1px solid var(--line);border-radius:999px;padding:7px 10px;background:#0e1823;color:var(--muted);font-size:12px}.badge.ok{color:var(--green);border-color:#286f4b}.badge.degraded{color:var(--yellow);border-color:#80652b}.badge.bad{color:var(--red);border-color:#783743}.badge.info{color:var(--blue)}.grid{display:grid;grid-template-columns:repeat(12,1fr);gap:14px}.card{background:linear-gradient(145deg,var(--panel),var(--panel2));border:1px solid var(--line);border-radius:14px;padding:16px;box-shadow:var(--shadow);min-width:0}.controls{grid-column:span 12;display:flex;align-items:end;flex-wrap:wrap;gap:12px}.field{display:flex;flex-direction:column;gap:6px;min-width:180px}.field.symbol{min-width:270px;flex:1}label{color:var(--muted);font-size:12px}input,select,button{font:inherit;color:var(--text);background:#0a121b;border:1px solid #36516a;border-radius:9px;padding:10px 12px}input:focus,select:focus,button:focus{outline:2px solid #73b7ff66;outline-offset:1px}button{cursor:pointer;background:#1b4b78;border-color:#397bb4;font-weight:650}button.secondary{background:#16222e;border-color:var(--line)}button:disabled{opacity:.45;cursor:not-allowed}.toggle{display:flex;align-items:center;gap:8px;height:42px}.toggle input{accent-color:var(--blue)}.loading{display:none;color:var(--blue);align-items:center;gap:8px}.loading.show{display:flex}.spinner{width:14px;height:14px;border:2px solid #ffffff33;border-top-color:var(--blue);border-radius:50%;animation:spin .8s linear infinite}@keyframes spin{to{transform:rotate(360deg)}}.decision{grid-column:span 3}.metric{grid-column:span 1.5;min-height:92px}.metric h3,.section-title{margin:0 0 9px;font-size:12px;color:var(--muted);font-weight:600}.metric strong{font-size:20px}.decision strong{font-size:30px}.NO_TRADE{color:var(--yellow)}.LONG{color:var(--green)}.SHORT{color:var(--red)}.blocked{border-color:#7d5d27;background:linear-gradient(145deg,#211b12,#121820)}.blocked strong{color:var(--yellow)}.wide{grid-column:span 6}.full{grid-column:span 12}.rows{display:grid;gap:7px}.row{display:flex;justify-content:space-between;gap:15px;border-bottom:1px solid #ffffff0b;padding:7px 0;line-height:1.4}.row span:first-child{color:var(--muted)}.row span:last-child{text-align:right;overflow-wrap:anywhere}.source{grid-column:span 4}.source h3{margin:0 0 8px}.source .state{font-size:18px;margin-bottom:8px}.state.ok{color:var(--green)}.state.degraded{color:var(--yellow)}.state.unreachable,.state.bad{color:var(--red)}.advisory{border-color:#315a80}.advisory .summary{line-height:1.55;margin:10px 0}.pill{display:inline-block;border-radius:999px;padding:4px 8px;background:#17304a;color:var(--blue);font-size:12px;margin:2px}.pill.warn{background:#3b3018;color:var(--yellow)}.list{margin:8px 0 0;padding-left:18px;color:#d3dde6;line-height:1.55}.reasons{border-left:3px solid var(--yellow)}details{grid-column:span 12;background:#0b121a;border:1px solid var(--line);border-radius:12px;padding:12px}summary{cursor:pointer;color:var(--blue);font-weight:650}.tech{white-space:pre-wrap;overflow-wrap:anywhere;color:#aab8c4;line-height:1.5;margin-top:12px;max-height:320px;overflow:auto}.combo{position:relative}.combo-list{position:absolute;z-index:20;left:0;right:0;top:100%;max-height:260px;overflow:auto;background:#101a25;border:1px solid #36516a;border-radius:9px;display:none}.combo-list.open{display:block}.combo-item{padding:10px 12px;cursor:pointer}.combo-item:hover,.combo-item.active{background:#1a3852}.empty{color:var(--muted);padding:10px 0}.mobile-note{color:var(--muted);font-size:12px}.footer{grid-column:span 12;color:var(--muted);font-size:12px;text-align:center;padding:8px}
-@media(max-width:1050px){.metric{grid-column:span 3}.source{grid-column:span 6}.wide{grid-column:span 12}}@media(max-width:650px){main{padding:14px}.top{display:block}.badges{justify-content:flex-start;margin-top:12px}.controls,.field,.field.symbol{min-width:100%;width:100%}.controls button{flex:1}.decision,.metric,.source,.wide,.full{grid-column:span 12}.row{display:block}.row span:last-child{text-align:left;display:block;margin-top:3px}.top h1{font-size:23px}}
-</style><style>.combo-list{max-height:320px}.combo-item{display:flex;justify-content:space-between;gap:10px}.verified{color:var(--green)}.unverified{color:var(--yellow)}.market{grid-column:span 8;min-height:300px}.market-head{display:flex;justify-content:space-between;gap:14px}.market-head strong{font-size:24px}.chart{width:100%;height:210px;margin-top:12px;background:#09131d;border:1px solid #1c3142;border-radius:10px}.chart-empty{display:grid;place-items:center;height:100%;color:var(--muted)}</style></head><body><main>
-<header class="top"><div><div class="eyebrow">HermesFace · Deterministic Futures</div><h1>Futures Desk</h1><div id="refresh" class="muted">Last refresh —</div></div><div id="badges" class="badges"></div></header>
-<section class="grid">
-<div class="card controls"><div class="field symbol"><label for="symbolSearch">Symbol</label><div class="combo"><input id="symbolSearch" autocomplete="off" value="BTCUSDT" placeholder="Search symbol or asset" role="combobox" aria-expanded="false"><div id="symbolList" class="combo-list" role="listbox"></div></div><div id="symbolState" class="mobile-note">Loading active Futures pairs…</div></div><div class="field"><label for="risk">Risk profile</label><select id="risk"><option>conservative</option><option selected>moderate</option><option>aggressive</option></select></div><label class="toggle"><input type="checkbox" id="advisory"> Remote advisory</label><button id="analyze">Analyze</button><button id="execute" class="secondary" disabled>Execute Paper Trade</button><div id="loading" class="loading"><i class="spinner"></i><span>Analyzing… <b id="elapsed">0.0s</b></span></div></div>
-<div class="card market"><div class="market-head"><div><div class="eyebrow">Selected market</div><strong id="marketSymbol">BTCUSDT</strong><div id="marketMeta" class="muted">Market data appears after analysis.</div></div><div id="marketPrice">—</div></div><svg id="marketChart" class="chart" viewBox="0 0 800 210" preserveAspectRatio="none" aria-label="Market chart"><foreignObject x="0" y="0" width="800" height="210"><div xmlns="http://www.w3.org/1999/xhtml" class="chart-empty">OHLCV unavailable — no chart data fabricated.</div></foreignObject></svg></div>
-<div id="decisionCard" class="card decision blocked"><h3 class="section-title">Decision</h3><strong id="decision">NO_TRADE</strong><div id="decisionHint" class="muted">Trading is blocked until all safety gates pass.</div></div>
-<div class="card metric"><h3>Signal score</h3><strong id="score">—</strong></div><div class="card metric"><h3>Risk approval</h3><strong id="approval">—</strong></div><div class="card metric"><h3>Mode</h3><strong id="mode">paper</strong></div><div class="card metric"><h3>Expiry</h3><strong id="expiry">—</strong></div>
-<div class="card wide"><h2 class="section-title">Trade plan</h2><div id="planRows" class="rows"></div></div>
-<div class="card full"><h2 class="section-title">Signal analysis</h2><div id="signals" class="rows"><div class="empty">No valid signal components were available.</div></div></div>
-<div class="card wide advisory"><h2 class="section-title">Remote advisory</h2><div id="advisoryPanel" class="empty">Disabled until Analyze is run with Remote advisory enabled.</div></div>
-<div class="card source"><h2 class="section-title">Datasource 4 · Authoritative</h2><div id="ds4" class="empty">Loading…</div></div><div class="card source"><h2 class="section-title">Binance · Public fallback</h2><div id="binance" class="empty">Loading…</div></div><div class="card source"><h2 class="section-title">Datasource 2 · Complementary</h2><div id="ds2" class="empty">Loading…</div></div>
-<div class="card wide reasons"><h2 class="section-title">Trade rejection reasons</h2><div id="reasons" class="empty">No plan analyzed yet.</div></div><div class="card wide"><h2 class="section-title">Account & positions</h2><div id="account" class="rows"></div></div>
-<details><summary>Show technical details</summary><div id="technical" class="tech">No technical diagnostics available.</div></details><div class="footer">Paper mode only · server validates every execution request · updated <span id="footerTime">—</span></div>
-</section></main>
-<script>
-const $=id=>document.getElementById(id), esc=x=>String(x??'—').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c])), fmt=x=>x===null||x===undefined||x===''?'—':esc(x);
-let symbols=[],activeIndex=-1,analysisBusy=false;
-function unique(xs){return [...new Set((xs||[]).filter(Boolean))]};
-function groupedWarnings(xs){let raw=unique(xs),out=[],bin451=raw.filter(x=>/Binance .*HTTP 451/i.test(x));if(bin451.length)out.push('Binance public API is unavailable from this region (HTTP 451).');raw.filter(x=>!/Binance .*HTTP 451/i.test(x)&&!/Binance unusable_response at\s*:/i.test(x)).forEach(x=>{if(!out.includes(x))out.push(x)});return {summary:out,raw};}
-function row(a,b){return '<div class="row"><span>'+esc(a)+'</span><span>'+fmt(b)+'</span></div>'}
-function renderSources(p){let w=groupedWarnings(p.warnings||[]),text=w.summary.join(' · ')||'No source diagnostics.';$('ds4').innerHTML='<div class="state bad">Unavailable</div>'+row('Role','Authoritative')+row('Reason',text.match(/Datasource 4[^;]*/)?.[0]||'No current response');$('binance').innerHTML='<div class="state '+(text.includes('HTTP 451')?'bad':'degraded')+'">'+(text.includes('HTTP 451')?'Regionally restricted':'Fallback')+'</div>'+row('Role','Market-data repair')+row('Reason',text.includes('HTTP 451')?'Binance public API is unavailable from this region (HTTP 451).':'Used only for missing fields');$('ds2').innerHTML='<div class="state degraded">Degraded</div>'+row('Role','Complementary context')+row('Reason',text.match(/Datasource 2[^;]*/)?.[0]||'No current response');$('technical').textContent=w.raw.join('\n')||'No technical diagnostics available.';}
-function renderAdvisory(a){if(!a){$('advisoryPanel').innerHTML='<div class="empty">Disabled for this analysis.</div>';return}let status=a.status||((a.provider&&a.provider!=='external_ai_unavailable')?'available':'unavailable');$('advisoryPanel').innerHTML='<div><span class="pill">'+fmt(a.provider)+'</span><span class="pill">'+fmt(a.model)+'</span><span class="pill">'+fmt(a.market_bias)+'</span><span class="pill">'+fmt(status)+'</span></div><div class="summary">'+fmt(a.summary)+'</div>'+row('Confidence',a.confidence)+row('Latency',a.latency_ms==null?'—':a.latency_ms+' ms')+row('Fallback used',a.fallback_used?'Yes':'No')+(a.error?row('Provider error',a.error):'')+(a.risk_warnings?.length?'<ul class="list">'+a.risk_warnings.map(x=>'<li>'+esc(x)+'</li>').join('')+'</ul>':'')}
-function renderPlan(p){let d=p.decision||'NO_TRADE';$('decision').textContent=d;$('decision').className=d;$('decisionCard').className='card decision '+(d==='NO_TRADE'?'blocked':'');$('decisionHint').textContent=d==='NO_TRADE'?'Trading is blocked until all safety gates pass.':'Directional plan; server safeguards still control execution.';$('score').textContent=fmt(p.score);$('approval').textContent=p.risk_approved?'Approved':'Not approved';$('approval').style.color=p.risk_approved?'var(--green)':'var(--yellow)';$('expiry').textContent=fmt(p.expires_at);$('planRows').innerHTML=[row('Entry',p.entry),row('Stop Loss',p.stop_loss),row('Take Profit',p.take_profit),row('Reward-to-risk',p.reward_to_risk),row('Leverage',p.effective_leverage??p.requested_leverage),row('Quantity',p.quantity),row('Slippage',p.estimated_slippage_percent),row('Created',p.created_at)].join('');let comps=Object.entries(p.components||{});$('signals').innerHTML=comps.length?comps.map(x=>row(x[0],x[1])).join(''):'<div class="empty">No valid signal components were available.</div>';let rs=unique([...(p.core_reasons||[]),...(p.rejection_reasons||[])]);$('reasons').innerHTML=rs.length?'<ul class="list">'+rs.map(x=>'<li>'+esc(x)+'</li>').join('')+'</ul>':'No trade rejection reasons.';renderAdvisory(p.external_advisory);renderSources(p);if(p.external_advisory?.attempts?.length)$('technical').textContent+='\n\nAdvisory attempts:\n'+JSON.stringify(p.external_advisory.attempts,null,2);$('execute').disabled=!(d==='LONG'||d==='SHORT')||!p.risk_approved||!p.expires_at||Date.parse(p.expires_at)<=Date.now()||p.executed;}
-function renderStatus(s){$('mode').textContent=fmt(s.tradingMode);$('account').innerHTML=[row('Paper equity',s.equity),row('Daily PnL',s.realizedPnlToday),row('Open positions',s.openPositionCount||0),row('Latest execution',s.latestPaperExecutionResult?.status||'None')].join('');let sw=(s.warnings||[]).join(' '),bs=/HTTP 451/i.test(sw)?'unavailable':Object.values(s.fieldSources||{}).some(x=>x==='binance_public')?'degraded':'degraded';let b=[['DS4',s.primaryDatasource?.status],['Binance',bs],['DS2',s.secondaryDatasource?.status],['Remote Advisory','info']];$('badges').innerHTML=b.map(x=>'<span class="badge '+(x[1]==='ok'?'ok':x[1]==='info'?'info':x[1]==='unreachable'||x[1]==='unavailable'?'bad':'degraded')+'">'+x[0]+': '+esc(x[1]||'unknown')+'</span>').join('');$('refresh').textContent='Last refresh '+new Date().toLocaleTimeString();$('footerTime').textContent=new Date().toLocaleTimeString();renderSources({warnings:s.warnings||[]});}
-async function refresh(){try{let r=await fetch('/api/futures/status');if(r.ok)renderStatus(await r.json())}catch(e){$('technical').textContent='Status request failed.'}}
-function showList(){let q=$('symbolSearch').value.toUpperCase();let found=symbols.filter(x=>(x.symbol+' '+x.baseAsset+' '+x.quoteAsset).includes(q)).slice(0,80);$('symbolList').innerHTML=found.length?found.map((x,i)=>'<div class="combo-item" role="option" data-symbol="'+esc(x.symbol)+'">'+esc(x.symbol)+' <small>'+esc(x.baseAsset)+' / '+esc(x.quoteAsset)+'</small></div>').join(''):'<div class="empty">No active pair found. Validated manual entry is allowed.</div>';$('symbolList').classList.add('open');$('symbolSearch').setAttribute('aria-expanded','true');activeIndex=-1;document.querySelectorAll('.combo-item').forEach(el=>el.onclick=()=>{ $('symbolSearch').value=el.dataset.symbol;$('symbolList').classList.remove('open')});}
-$('symbolSearch').oninput=showList;$('symbolSearch').onfocus=showList;$('symbolSearch').onkeydown=e=>{let opts=[...document.querySelectorAll('.combo-item')];if(e.key==='ArrowDown'){activeIndex=Math.min(activeIndex+1,opts.length-1);opts[activeIndex]?.classList.add('active');e.preventDefault()}else if(e.key==='Enter'&&opts[activeIndex]){opts[activeIndex].click()}else if(e.key==='Escape')$('symbolList').classList.remove('open')};document.addEventListener('click',e=>{if(!e.target.closest('.combo'))$('symbolList').classList.remove('open')});
-async function loadSymbols(){try{let r=await fetch('/api/futures/symbols');let p=await r.json();symbols=p.symbols||[];$('symbolState').textContent=symbols.length?symbols.length+' active pairs · source '+p.source:'Symbol service unavailable; validated manual entry enabled';}catch(e){$('symbolState').textContent='Symbol service unavailable; validated manual entry enabled';}}
-$('analyze').onclick=async()=>{if(analysisBusy)return;analysisBusy=true;$('analyze').disabled=true;$('execute').disabled=true;$('loading').classList.add('show');let started=performance.now(),timer=setInterval(()=>{$('elapsed').textContent=((performance.now()-started)/1000).toFixed(1)+'s'},100);try{let r=await fetch('/api/futures/analyze',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({symbol:$('symbolSearch').value,risk_profile:$('risk').value,include_external_context:$('advisory').checked})});let p=await r.json();if(!r.ok)throw new Error(p.detail||'Analysis failed');renderPlan(p);}catch(e){$('reasons').textContent=e.message;$('decision').textContent='NO_TRADE';}finally{clearInterval(timer);$('loading').classList.remove('show');analysisBusy=false;$('analyze').disabled=false;}};
-$('execute').onclick=async()=>{if($('execute').disabled||!confirm('Confirm server-side Paper execution for this plan?'))return};loadSymbols();refresh();setInterval(refresh,5000);
-</script><script>function showList(){let q=$('symbolSearch').value.toUpperCase();let found=symbols.filter(x=>(x.symbol+' '+x.baseAsset+' '+x.quoteAsset+' '+(x.name||'')+' '+(x.rank||'')).toUpperCase().includes(q)).slice(0,120);$('symbolList').innerHTML=found.length?found.map(x=>'<div class="combo-item" role="option" data-symbol="'+esc(x.symbol)+'"><span><b>'+esc(x.symbol)+'</b> <small>'+esc(x.name||x.baseAsset)+' · '+esc(x.baseAsset)+'/'+esc(x.quoteAsset)+'</small></span><span class="'+(x.futuresVerified?'verified':'unverified')+'">'+(x.futuresVerified?'✓ Futures':'Market only')+'</span></div>').join(''):'<div class="empty">No pair found. Validated manual entry is allowed.</div>';$('symbolList').classList.add('open');$('symbolSearch').setAttribute('aria-expanded','true');activeIndex=-1;document.querySelectorAll('.combo-item').forEach(el=>el.onclick=()=>{ $('symbolSearch').value=el.dataset.symbol;$('marketSymbol').textContent=el.dataset.symbol;$('symbolList').classList.remove('open')});}$('symbolSearch').oninput=showList;$('symbolSearch').onfocus=showList;</script></body></html>'''
+        page = _FALLBACK_PAGE
+    template_hash = hashlib.sha256(page.encode("utf-8")).hexdigest()
+    return HTMLResponse(page, headers={
+        "Cache-Control": "no-store, no-cache, must-revalidate, max-age=0",
+        "Pragma": "no-cache",
+        "X-Hermes-Template-SHA256": template_hash,
+        "X-Hermes-Router-SHA256": _file_sha256(Path(__file__).resolve()) or "unavailable",
+    })

hermes_overlay/trading/binance_public_client.py

@@ -11,6 +11,7 @@ import math
 import os
 import socket
 import ssl
+import time
 from dataclasses import dataclass
 from typing import Any, Iterable, Optional
 
@@ -171,6 +172,19 @@ async def _get_json(
     return _RequestResult(issue=_issue("internal_error", path, "Unexpected retry termination"))
 
 
+
+
+async def _fetch_24h_ticker(client: httpx.AsyncClient, symbol: str) -> _RequestResult:
+    return await _get_json(client, "/fapi/v1/ticker/24hr", {"symbol": symbol})
+
+
+async def _fetch_klines_for(
+    client: httpx.AsyncClient, symbol: str, interval: str, limit: int
+) -> _RequestResult:
+    return await _get_json(client, "/fapi/v1/klines", {
+        "symbol": symbol, "interval": interval, "limit": limit,
+    })
+
 async def _fetch_premium_index(client: httpx.AsyncClient, symbol: str) -> _RequestResult:
     return await _get_json(client, "/fapi/v1/premiumIndex", {"symbol": symbol})
 
@@ -236,14 +250,37 @@ def _normalize_ticker_and_funding(raw: Any) -> tuple[Optional[dict], Optional[di
         ticker = {"markPrice": mark, "source": "binance_public"}
         if index is not None and index > 0:
             ticker["indexPrice"] = index
+        if raw.get("time") is not None:
+            ticker["timestamp"] = raw["time"]
     funding = None
     if funding_rate is not None:
         funding = {"currentFundingRate": funding_rate, "source": "binance_public"}
+        if raw.get("time") is not None:
+            funding["timestamp"] = raw["time"]
         if raw.get("nextFundingTime") is not None:
             funding["nextFundingTime"] = raw["nextFundingTime"]
     return ticker, funding
 
 
+def _normalize_24h_ticker(raw: Any) -> Optional[dict]:
+    if not isinstance(raw, dict):
+        return None
+    last = _to_float(raw.get("lastPrice"))
+    if last is None or last <= 0:
+        return None
+    result = {"lastPrice": last, "source": "binance_public"}
+    change = _to_float(raw.get("priceChangePercent"))
+    volume = _to_float(raw.get("quoteVolume"))
+    if change is not None:
+        result["change24h"] = change
+        result["change24hFraction"] = change / 100.0
+    if volume is not None and volume >= 0:
+        result["volume24h"] = volume
+    if raw.get("closeTime") is not None:
+        result["timestamp"] = raw["closeTime"]
+    return result
+
+
 def _normalize_depth(raw: Any) -> Optional[dict]:
     if not isinstance(raw, dict):
         return None
@@ -264,7 +301,12 @@ def _normalize_depth(raw: Any) -> Optional[dict]:
     bids, asks = levels(raw.get("bids")), levels(raw.get("asks"))
     if not bids or not asks:
         return None
-    return {"bids": bids, "asks": asks, "source": "binance_public"}
+    result = {"bids": bids, "asks": asks, "source": "binance_public"}
+    if raw.get("E") is not None:
+        result["timestamp"] = raw["E"]
+    elif raw.get("lastUpdateId") is not None:
+        result["lastUpdateId"] = raw["lastUpdateId"]
+    return result
 
 
 def _calculate_atr(mark_candles: Any, period: int = ATR_PERIOD) -> Optional[float]:
@@ -325,7 +367,10 @@ def _normalize_open_interest(raw: Any) -> Optional[dict]:
     current = _to_float(raw.get("openInterest"))
     if current is None or current < 0:
         return None
-    return {"openInterest": current, "source": "binance_public"}
+    result = {"openInterest": current, "source": "binance_public"}
+    if raw.get("time") is not None:
+        result["timestamp"] = raw["time"]
+    return result
 
 
 def _format_issue(issue: dict) -> str:
@@ -344,16 +389,27 @@ async def get_binance_public_result(
 ) -> dict:
     """Return data plus structured warnings/errors for requested logical fields."""
     needed = frozenset(needed_fields) & SUPPORTED_FIELDS if needed_fields is not None else SUPPORTED_FIELDS
+    started = time.perf_counter()
     result = {
         "source": "binance_public", "symbol": symbol, "requestedFields": sorted(needed),
-        "data": {}, "warnings": [], "errors": [],
+        "data": {}, "warnings": [], "errors": [], "meta": {},
     }
     if not FALLBACK_ENABLED:
         result["warnings"].append(_issue(
             "disabled", "", "Binance public fallback disabled by configuration", retryable=False,
         ))
+        result["meta"] = {
+            "transportStatus": "disabled", "httpStatus": None,
+            "latencyMs": round((time.perf_counter() - started) * 1000, 2),
+            "lastSuccess": None,
+        }
         return result
     if not needed:
+        result["meta"] = {
+            "transportStatus": "standby", "httpStatus": None,
+            "latencyMs": round((time.perf_counter() - started) * 1000, 2),
+            "lastSuccess": None,
+        }
         return result
 
     timeout = httpx.Timeout(TIMEOUT_S, connect=min(TIMEOUT_S, 3.0))
@@ -414,7 +470,8 @@ async def get_binance_public_result(
         change = _calculate_oi_change(history)
         if history is not None and change is not None:
             data["openInterestChange"] = {
-                "changePercent": change, "history": history, "source": "binance_public",
+                "changePercent": change, "changeFraction": change,
+                "history": history, "source": "binance_public",
             }
 
     for field in needed:
@@ -423,6 +480,81 @@ async def get_binance_public_result(
                 "unusable_response", "", f"Binance did not provide usable data for {field}",
                 field=field, retryable=False,
             ))
+    statuses = [item.get("status") for item in result["errors"] if isinstance(item, dict)]
+    restricted = 451 in statuses
+    result["meta"] = {
+        "transportStatus": "restricted" if restricted else ("healthy" if data else "degraded"),
+        "httpStatus": 451 if restricted else next((status for status in statuses if status is not None), None),
+        "latencyMs": round((time.perf_counter() - started) * 1000, 2),
+        "lastSuccess": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()) if data else None,
+    }
+    return result
+
+
+async def get_binance_public_market_data(
+    symbol: str, interval: str = "5m", limit: int = 120,
+) -> dict:
+    """Read-only market payload for the dashboard endpoint. No values are synthesized."""
+    allowed_intervals = {"1m", "5m", "15m", "1h"}
+    if interval not in allowed_intervals:
+        raise ValueError(f"Unsupported Binance interval: {interval}")
+    bounded_limit = max(1, min(int(limit), 500))
+    started = time.perf_counter()
+    result = {
+        "source": "binance_public", "symbol": symbol, "interval": interval,
+        "requestedLimit": bounded_limit, "data": {}, "warnings": [], "errors": [], "meta": {},
+    }
+    if not FALLBACK_ENABLED:
+        result["warnings"].append(_issue(
+            "disabled", "", "Binance public fallback disabled by configuration", retryable=False,
+        ))
+        result["meta"] = {
+            "transportStatus": "disabled", "httpStatus": None,
+            "latencyMs": round((time.perf_counter() - started) * 1000, 2),
+            "lastSuccess": None,
+        }
+        return result
+    timeout = httpx.Timeout(TIMEOUT_S, connect=min(TIMEOUT_S, 3.0))
+    async with httpx.AsyncClient(timeout=timeout, headers={"Accept": "application/json"}) as client:
+        responses = await asyncio.gather(
+            _fetch_premium_index(client, symbol),
+            _fetch_24h_ticker(client, symbol),
+            _fetch_klines_for(client, symbol, interval, bounded_limit),
+            _fetch_open_interest(client, symbol),
+        )
+    premium_r, ticker_r, candles_r, oi_r = responses
+    for response in responses:
+        if isinstance(response, _RequestResult) and response.issue:
+            result["errors"].append(response.issue)
+    premium = _response_data(premium_r)
+    premium_ticker, funding = _normalize_ticker_and_funding(premium)
+    ticker = _normalize_24h_ticker(_response_data(ticker_r)) or premium_ticker
+    if ticker is not None and premium_ticker:
+        ticker = {**premium_ticker, **ticker}
+    candles = _normalize_klines(_response_data(candles_r))
+    open_interest = _normalize_open_interest(_response_data(oi_r))
+    if ticker is not None:
+        result["data"]["ticker"] = ticker
+    if funding is not None:
+        result["data"]["funding"] = funding
+    if candles is not None:
+        result["data"]["ohlcv"] = candles
+    if open_interest is not None:
+        result["data"]["openInterest"] = open_interest
+    for field in ("ticker", "funding", "ohlcv", "openInterest"):
+        if field not in result["data"]:
+            result["warnings"].append(_issue(
+                "unusable_response", "", f"Binance did not provide usable data for {field}",
+                field=field, retryable=False,
+            ))
+    statuses = [item.get("status") for item in result["errors"] if isinstance(item, dict)]
+    restricted = 451 in statuses
+    result["meta"] = {
+        "transportStatus": "restricted" if restricted else ("healthy" if result["data"] else "degraded"),
+        "httpStatus": 451 if restricted else next((status for status in statuses if status is not None), None),
+        "latencyMs": round((time.perf_counter() - started) * 1000, 2),
+        "lastSuccess": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()) if result["data"] else None,
+    }
     return result
 
 

hermes_overlay/trading/dual_datasource_client.py

@@ -12,8 +12,10 @@ this module only calls their existing HTTP endpoints and merges the responses.
 from __future__ import annotations
 
 import asyncio
+import math
 import os
 import time
+from datetime import datetime, timezone
 from typing import Any, Optional
 
 import httpx
@@ -37,28 +39,103 @@ DS4_OWNED_FIELDS = (
 # must not be executed (NO_TRADE), regardless of what DS2 supplied.
 FUTURES_CRITICAL_FIELDS = ("contract", "ticker", "orderbook", "funding", "openInterest")
 DS4_FRESH_STATES = {"live", "fresh", "ok"}
+SUPPORTED_INTERVALS = {"1m": 60, "5m": 300, "15m": 900, "1h": 3600}
+MAX_MARKET_LIMIT = 500
 
 
-async def _get_json(client: httpx.AsyncClient, url: str, timeout: float) -> Optional[dict]:
+def normalize_epoch_milliseconds(value: Any) -> int:
+    """Return a positive epoch timestamp in milliseconds without double conversion."""
     try:
-        resp = await client.get(url, timeout=timeout)
-        resp.raise_for_status()
-        return resp.json()
-    except Exception:
-        return None
+        number = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("timestamp must be numeric") from exc
+    if not math.isfinite(number) or number <= 0:
+        raise ValueError("timestamp must be a positive finite value")
+    # Contemporary epoch seconds are ~1e9; milliseconds are ~1e12.
+    if number < 100_000_000_000:
+        number *= 1000
+    return int(number)
+
+
+def build_kucoin_time_range(
+    interval: str = "5m", limit: int = 120, *, end: Any | None = None
+) -> tuple[int, int]:
+    """Build a bounded, ordered KuCoin-compatible millisecond range."""
+    if interval not in SUPPORTED_INTERVALS:
+        raise ValueError(f"unsupported interval: {interval}")
+    bounded_limit = max(1, min(int(limit), MAX_MARKET_LIMIT))
+    end_ms = normalize_epoch_milliseconds(end if end is not None else time.time())
+    start_ms = end_ms - SUPPORTED_INTERVALS[interval] * bounded_limit * 1000
+    if start_ms <= 0 or start_ms >= end_ms:
+        raise ValueError("invalid historical time range")
+    return start_ms, end_ms
+
+
+def _iso_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+async def _get_json_with_meta(
+    client: httpx.AsyncClient, url: str, timeout: float, params: Optional[dict] = None
+) -> tuple[Optional[dict], dict]:
+    started = time.perf_counter()
+    meta = {
+        "transportStatus": "unavailable", "endpoint": url, "httpStatus": None,
+        "latencyMs": None, "lastSuccess": None, "reason": "No response",
+    }
+    try:
+        try:
+            resp = await client.get(url, timeout=timeout, params=params)
+        except TypeError:
+            # Compatibility with the repository's minimal mocked clients.
+            resp = await client.get(url, timeout=timeout)
+        meta["latencyMs"] = round((time.perf_counter() - started) * 1000, 2)
+        status = int(getattr(resp, "status_code", 200))
+        meta["httpStatus"] = status
+        if status >= 400:
+            meta["transportStatus"] = "degraded"
+            meta["reason"] = f"HTTP {status}"
+            return None, meta
+        payload = resp.json()
+        if not isinstance(payload, dict):
+            meta["transportStatus"] = "degraded"
+            meta["reason"] = "Invalid JSON payload shape"
+            return None, meta
+        meta.update(transportStatus="healthy", lastSuccess=_iso_now(), reason="Response received")
+        return payload, meta
+    except Exception as exc:
+        meta["latencyMs"] = round((time.perf_counter() - started) * 1000, 2)
+        meta["reason"] = type(exc).__name__
+        return None, meta
+
+
+async def _get_json(
+    client: httpx.AsyncClient, url: str, timeout: float, params: Optional[dict] = None
+) -> Optional[dict]:
+    data, _ = await _get_json_with_meta(client, url, timeout, params=params)
+    return data
 
 
-async def _fetch_ds4_snapshot(client: httpx.AsyncClient, ds4_symbol: str) -> tuple[Optional[dict], list[str]]:
+async def _fetch_ds4_snapshot(
+    client: httpx.AsyncClient, ds4_symbol: str, timeframe: str = "5m", limit: int = 120
+) -> tuple[Optional[dict], list[str], dict]:
     warnings: list[str] = []
-    data = await _get_json(
-        client, f"{DS4_BASE}/api/short-hunter/snapshot/{ds4_symbol}", DS4_TIMEOUT_S
+    bounded_limit = max(1, min(int(limit), MAX_MARKET_LIMIT))
+    start_ms, end_ms = build_kucoin_time_range(timeframe, bounded_limit)
+    endpoint = f"{DS4_BASE}/api/short-hunter/snapshot/{ds4_symbol}"
+    data, meta = await _get_json_with_meta(
+        client, endpoint, DS4_TIMEOUT_S,
+        params={"interval": timeframe, "limit": bounded_limit,
+                "from": start_ms, "to": end_ms},
     )
     if data is None:
         warnings.append("Datasource 4 (Short Hunter) unreachable or errored")
-    return data, warnings
+    return data, warnings, meta
 
 
-async def _fetch_ds2_context(client: httpx.AsyncClient, ds2_symbol: str) -> tuple[dict, list[str]]:
+async def _fetch_ds2_context(
+    client: httpx.AsyncClient, ds2_symbol: str
+) -> tuple[dict, list[str], dict]:
     """Best-effort complementary context; never blocks a NO_TRADE decision."""
     warnings: list[str] = []
     endpoints = {
@@ -72,15 +149,43 @@ async def _fetch_ds2_context(client: httpx.AsyncClient, ds2_symbol: str) -> tupl
         "correlations": f"{DS2_BASE}/api/correlations",
     }
     results = await asyncio.gather(
-        *(_get_json(client, url, DS2_TIMEOUT_S) for url in endpoints.values())
+        *(_get_json_with_meta(client, url, DS2_TIMEOUT_S) for url in endpoints.values())
     )
-    context = {}
-    for key, value in zip(endpoints.keys(), results):
+    context: dict[str, Any] = {}
+    metas: dict[str, dict] = {}
+    for key, (value, meta) in zip(endpoints.keys(), results):
+        metas[key] = meta
         if value is None:
             warnings.append(f"Datasource 2 field '{key}' unavailable")
         else:
             context[key] = value
-    return context, warnings
+    successes = [m for m in metas.values() if m.get("transportStatus") == "healthy"]
+    source_meta = {
+        "transportStatus": "healthy" if successes else "unavailable",
+        "endpoint": DS2_BASE,
+        "httpStatus": next((m.get("httpStatus") for m in metas.values() if m.get("httpStatus") is not None), None),
+        "latencyMs": round(sum(float(m.get("latencyMs") or 0) for m in metas.values()), 2),
+        "lastSuccess": max((m.get("lastSuccess") for m in successes if m.get("lastSuccess")), default=None),
+        "reason": "Complementary endpoints partially available" if len(successes) < len(metas) else "Complementary endpoints available",
+        "suppliedFields": sorted(context.keys()),
+        "missingFields": sorted(key for key in endpoints if key not in context),
+        "endpointDetails": metas,
+    }
+    return context, warnings, source_meta
+
+
+def _boolean_flag(value: Any) -> Optional[bool]:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)) and value in (0, 1):
+        return bool(value)
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "yes", "1", "verified", "futures"}:
+            return True
+        if normalized in {"false", "no", "0", "unverified", "market_only"}:
+            return False
+    return None
 
 
 def _finite_number(value: Any) -> Optional[float]:
@@ -155,7 +260,7 @@ def _is_usable(field: str, value: Any) -> bool:
 def _has_oi_change(value: Any) -> bool:
     if not isinstance(value, dict):
         return False
-    for key in ("change24h", "changePercent", "oiChangePercent"):
+    for key in ("changeFraction", "change24h", "changePercent", "oiChangePercent"):
         if _finite_number(value.get(key)) is not None:
             return True
     return _oi_change_from_history(value.get("history")) is not None
@@ -176,7 +281,423 @@ def _oi_change_from_history(history: Any) -> Optional[float]:
     return (samples[-1] - samples[0]) / samples[0]
 
 
-async def get_market_context(symbol: str, timeframe: str = "5m") -> dict:
+def _first_value(mapping: Any, *keys: str) -> Any:
+    if not isinstance(mapping, dict):
+        return None
+    for key in keys:
+        if key in mapping and mapping[key] is not None:
+            return mapping[key]
+    return None
+
+
+def _candidate_sections(payload: dict) -> list[dict]:
+    """Return only known API envelope sections, bounded to avoid broad guessing."""
+    sections: list[dict] = []
+    queue: list[tuple[dict, int]] = [(payload, 0)]
+    wrapper_keys = ("data", "snapshot", "market", "marketData", "futures", "result", "payload")
+    while queue:
+        candidate, depth = queue.pop(0)
+        if candidate in sections:
+            continue
+        sections.append(candidate)
+        if depth >= 3:
+            continue
+        for key in wrapper_keys:
+            nested = candidate.get(key)
+            if isinstance(nested, dict):
+                queue.append((nested, depth + 1))
+    return sections
+
+
+def _find_section(payload: dict, *keys: str) -> Any:
+    for section in _candidate_sections(payload):
+        for key in keys:
+            if key in section and section[key] not in (None, {}, [], ""):
+                return section[key]
+    return None
+
+
+def _find_mapping_with_any(payload: dict, *keys: str) -> Optional[dict]:
+    for section in _candidate_sections(payload):
+        if any(section.get(key) is not None for key in keys):
+            return section
+    return None
+
+
+def _normalize_timestamp(value: Any) -> Any:
+    """Normalize common timestamp wrappers while preserving the original epoch unit."""
+    if isinstance(value, dict):
+        value = _first_value(value, "timestamp", "time", "ts", "updatedAt", "lastUpdateTime", "closeTime")
+    if value in (None, ""):
+        return None
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return None
+        if stripped.isdigit():
+            value = stripped
+        else:
+            try:
+                datetime.fromisoformat(stripped.replace("Z", "+00:00"))
+                return stripped
+            except ValueError:
+                return None
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    if not math.isfinite(number) or number <= 0:
+        return None
+    return int(number)
+
+
+def _normalize_contract(value: Any) -> Optional[dict]:
+    if isinstance(value, str):
+        return {"symbol": value}
+    if not isinstance(value, dict):
+        return None
+    out = dict(value)
+    aliases = {
+        "symbol": ("symbol", "contractSymbol", "instrument", "instrumentId", "instId"),
+        "status": ("status", "contractStatus", "state", "tradingStatus"),
+        "contractType": ("contractType", "type", "marketType", "instrumentType", "instType"),
+        "quoteAsset": ("quoteAsset", "quote", "quoteCurrency", "quoteCoin"),
+        "baseAsset": ("baseAsset", "base", "baseCurrency", "baseCoin"),
+    }
+    for target, keys in aliases.items():
+        found = _first_value(value, *keys)
+        if found is not None:
+            out[target] = found
+    for target, keys in {
+        "futuresVerified": ("futuresVerified", "verifiedFutures", "isFutures", "isFuture", "verified"),
+        "perpetual": ("perpetual", "isPerpetual", "isSwap"),
+    }.items():
+        found = _boolean_flag(_first_value(value, *keys))
+        if found is not None:
+            out[target] = found
+    return out or None
+
+
+def _contract_verification(contract: Any, ds4: Optional[dict], *, stale: bool) -> dict:
+    """Derive a conservative verification result without allowing a fallback source to authorize execution."""
+    if not isinstance(ds4, dict):
+        return {"verified": False, "status": "unavailable", "reason": "Datasource 4 unavailable"}
+    if stale:
+        return {"verified": False, "status": "stale", "reason": "Datasource 4 verification is stale"}
+    if ds4.get("noTradeGuard") is True:
+        return {"verified": False, "status": "blocked", "reason": "Datasource 4 noTradeGuard is active"}
+
+    candidates: list[Any] = [contract, ds4]
+    for section in _candidate_sections(ds4):
+        candidates.append(section)
+    explicit_false = False
+    for candidate in candidates:
+        if not isinstance(candidate, dict):
+            continue
+        flag = _boolean_flag(_first_value(
+            candidate, "futuresVerified", "verifiedFutures", "isFutures", "isFuture"
+        ))
+        if flag is True:
+            return {"verified": True, "status": "verified", "reason": "Verified by Datasource 4"}
+        if flag is False:
+            explicit_false = True
+    if explicit_false:
+        return {"verified": False, "status": "market_only", "reason": "Datasource 4 marked the market unverified"}
+
+    if isinstance(contract, dict):
+        contract_type = str(_first_value(contract, "contractType", "type", "marketType", "instrumentType") or "").lower()
+        status = str(_first_value(contract, "status", "contractStatus", "state", "tradingStatus") or "").lower()
+        inactive = status in {"inactive", "disabled", "delisted", "closed", "offline", "suspended"}
+        futures_type = any(token in contract_type for token in ("future", "perpetual", "swap"))
+        if futures_type and not inactive:
+            return {"verified": True, "status": "verified", "reason": "Datasource 4 contract metadata identifies a Futures market"}
+        if inactive:
+            return {"verified": False, "status": "inactive", "reason": "Datasource 4 contract is not active"}
+    return {"verified": False, "status": "unverified", "reason": "Datasource 4 did not provide verifiable contract metadata"}
+
+
+def _normalize_ohlcv(value: Any) -> Optional[list[dict]]:
+    if isinstance(value, dict):
+        value = _first_value(value, "candles", "ohlcv", "klines", "items", "data", "result")
+    if not isinstance(value, list):
+        return None
+    candles: list[dict] = []
+    for item in value:
+        if isinstance(item, dict):
+            timestamp = _first_value(item, "timestamp", "time", "ts", "openTime", "startTime")
+            open_ = _finite_number(_first_value(item, "open", "o"))
+            high = _finite_number(_first_value(item, "high", "h"))
+            low = _finite_number(_first_value(item, "low", "l"))
+            close = _finite_number(_first_value(item, "close", "c"))
+            volume = _finite_number(_first_value(item, "volume", "v", "baseVolume"))
+        elif isinstance(item, (list, tuple)) and len(item) >= 6:
+            timestamp = item[0]
+            open_, high, low, close, volume = (_finite_number(v) for v in item[1:6])
+        else:
+            continue
+        timestamp = _normalize_timestamp(timestamp)
+        if timestamp is None or None in (open_, high, low, close, volume):
+            continue
+        if min(open_, high, low, close) <= 0 or volume < 0 or high < max(open_, close, low) or low > min(open_, close, high):
+            continue
+        candles.append({
+            "timestamp": timestamp,
+            "open": open_, "high": high, "low": low, "close": close, "volume": volume,
+        })
+    return candles or None
+
+
+def _normalize_orderbook(value: Any) -> Optional[dict]:
+    if isinstance(value, dict) and not ("bids" in value or "asks" in value):
+        nested = _first_value(value, "data", "depth", "orderbook", "orderBook", "result")
+        if isinstance(nested, dict):
+            value = nested
+    if not isinstance(value, dict):
+        return None
+    out: dict[str, Any] = {}
+    for side in ("bids", "asks"):
+        raw_levels = value.get(side)
+        if not isinstance(raw_levels, list):
+            return None
+        levels: list[list[float]] = []
+        for level in raw_levels:
+            if isinstance(level, dict):
+                price = _finite_number(_first_value(level, "price", "p", "0"))
+                quantity = _finite_number(_first_value(level, "quantity", "qty", "size", "amount", "q", "1"))
+            elif isinstance(level, (list, tuple)) and len(level) >= 2:
+                price, quantity = _finite_number(level[0]), _finite_number(level[1])
+            else:
+                continue
+            if price is None or quantity is None or price <= 0 or quantity < 0:
+                continue
+            levels.append([price, quantity])
+        if not levels:
+            return None
+        out[side] = levels
+    timestamp = _normalize_timestamp(_first_value(value, "timestamp", "time", "ts", "eventTime", "updatedAt"))
+    if timestamp is not None:
+        out["timestamp"] = timestamp
+    return out
+
+
+def _normalize_ticker(value: Any) -> Optional[dict]:
+    if isinstance(value, (int, float, str)):
+        price = _finite_number(value)
+        return {"lastPrice": price} if price is not None and price > 0 else None
+    if not isinstance(value, dict):
+        return None
+    price = _finite_number(_first_value(value, "lastPrice", "last", "price", "close", "markPrice", "mark_price"))
+    if price is None or price <= 0:
+        return None
+    out = dict(value)
+    out["lastPrice"] = price
+    aliases = {
+        "markPrice": ("markPrice", "mark_price"),
+        "indexPrice": ("indexPrice", "index_price"),
+        "volume24h": (
+            "volume24h", "quoteVolume", "volume", "volValue", "turnover24h",
+            "quoteVolume24h", "turnover", "volume_24h",
+        ),
+        "timestamp": ("timestamp", "time", "ts", "updatedAt", "closeTime", "lastUpdateTime"),
+    }
+    for target, keys in aliases.items():
+        found = _first_value(value, *keys)
+        if found is not None:
+            out[target] = _normalize_timestamp(found) if target == "timestamp" else found
+    fraction = _finite_number(_first_value(value, "change24hFraction", "changeRate", "price24hPcnt"))
+    if fraction is None:
+        percent_value = _finite_number(_first_value(
+            value, "changePercent", "priceChangePercent", "percentage"
+        ))
+        if percent_value is not None:
+            fraction = percent_value / 100.0
+    if fraction is None:
+        ambiguous = _finite_number(_first_value(value, "change24h", "change_24h"))
+        if ambiguous is not None:
+            fraction = ambiguous / 100.0 if abs(ambiguous) > 1 else ambiguous
+    if fraction is not None:
+        out["change24hFraction"] = fraction
+        out["change24h"] = fraction * 100.0
+    return out
+
+
+def _normalize_funding(value: Any) -> Optional[dict]:
+    if isinstance(value, (int, float, str)):
+        rate = _finite_number(value)
+        return {"currentFundingRate": rate} if rate is not None else None
+    if not isinstance(value, dict):
+        return None
+    rate = _finite_number(_first_value(value, "currentFundingRate", "fundingRate", "lastFundingRate", "rate", "funding_rate"))
+    if rate is None:
+        return None
+    out = dict(value)
+    out["currentFundingRate"] = rate
+    timestamp = _normalize_timestamp(_first_value(
+        value, "timestamp", "time", "ts", "updatedAt", "fundingTime", "lastUpdateTime"
+    ))
+    if timestamp is not None:
+        out["timestamp"] = timestamp
+    next_time = _normalize_timestamp(_first_value(value, "nextFundingTime", "nextFundingTimestamp"))
+    if next_time is not None:
+        out["nextFundingTime"] = next_time
+    return out
+
+
+def _normalize_atr(value: Any) -> Optional[float]:
+    if isinstance(value, dict):
+        value = _first_value(value, "value", "atr", "ATR", "current", "latest")
+    number = _finite_number(value)
+    return number if number is not None and number > 0 else None
+
+
+def _normalize_open_interest(value: Any) -> Optional[dict]:
+    if isinstance(value, (int, float, str)):
+        current = _finite_number(value)
+        return {"openInterest": current} if current is not None and current >= 0 else None
+    if not isinstance(value, dict):
+        return None
+    current = _finite_number(_first_value(
+        value, "openInterest", "open_interest", "openInterestAmount", "openInterestValue",
+        "sumOpenInterest", "openInterestQty", "openInterestQuantity", "oi",
+    ))
+    if current is None or current < 0:
+        return None
+    out = dict(value)
+    out["openInterest"] = current
+    fraction = _finite_number(_first_value(value, "changeFraction", "oiChangeFraction"))
+    if fraction is None:
+        percent_value = _finite_number(_first_value(value, "changePercent", "oiChangePercent"))
+        if percent_value is not None:
+            fraction = percent_value / 100.0
+    if fraction is None:
+        ambiguous = _finite_number(_first_value(
+            value, "change24h", "openInterestChange24h", "change_24h"
+        ))
+        if ambiguous is not None:
+            fraction = ambiguous / 100.0 if abs(ambiguous) > 1 else ambiguous
+    if fraction is not None:
+        out["changeFraction"] = fraction
+        out["changePercent"] = fraction
+    timestamp = _normalize_timestamp(_first_value(
+        value, "timestamp", "time", "ts", "updatedAt", "lastUpdateTime"
+    ))
+    if timestamp is not None:
+        out["timestamp"] = timestamp
+    return out
+
+
+def _normalize_ds4_data(payload: Optional[dict]) -> dict:
+    if not isinstance(payload, dict):
+        return {}
+
+    contract_raw = _find_section(
+        payload, "contract", "futuresContract", "instrument", "contractInfo", "marketInfo"
+    )
+    contract_mapping = _find_mapping_with_any(
+        payload, "contractType", "marketType", "instrumentType",
+        "futuresVerified", "verifiedFutures", "isFutures", "isFuture",
+    )
+    if contract_raw is None or (not isinstance(contract_raw, dict) and contract_mapping is not None):
+        contract_raw = contract_mapping
+    ticker_raw = _find_section(payload, "ticker", "marketTicker", "ticker24h", "quote", "price")
+    ticker_mapping = _find_mapping_with_any(
+        payload, "lastPrice", "markPrice", "indexPrice", "priceChangePercent", "price24hPcnt"
+    )
+    if ticker_raw is None or (not isinstance(ticker_raw, dict) and ticker_mapping is not None):
+        ticker_raw = ticker_mapping
+    funding_raw = _find_section(
+        payload, "funding", "fundingRate", "funding_rate", "fundingInfo", "premiumIndex"
+    )
+    funding_mapping = _find_mapping_with_any(
+        payload, "currentFundingRate", "lastFundingRate", "fundingRate", "funding_rate"
+    )
+    if funding_raw is None or (not isinstance(funding_raw, dict) and funding_mapping is not None):
+        funding_raw = funding_mapping
+    oi_raw = _find_section(
+        payload, "openInterest", "open_interest", "openInterestData", "oi", "openInterestInfo"
+    )
+    oi_mapping = _find_mapping_with_any(
+        payload, "openInterest", "open_interest", "sumOpenInterest", "openInterestValue"
+    )
+    if oi_raw is None or (not isinstance(oi_raw, dict) and oi_mapping is not None):
+        oi_raw = oi_mapping
+
+    result = {
+        "contract": _normalize_contract(contract_raw),
+        "ticker": _normalize_ticker(ticker_raw),
+        "ohlcv": _normalize_ohlcv(_find_section(
+            payload, "ohlcv", "candles", "klines", "kline", "history"
+        )),
+        "orderbook": _normalize_orderbook(_find_section(
+            payload, "orderbook", "orderBook", "depth"
+        )),
+        "funding": _normalize_funding(funding_raw),
+        "openInterest": _normalize_open_interest(oi_raw),
+        "indicators": _find_section(payload, "indicators", "technicalIndicators"),
+        "sentiment": _find_section(payload, "sentiment", "marketSentiment"),
+    }
+    result["atr"] = _normalize_atr(_find_section(payload, "atr", "ATR"))
+    if result["atr"] is None and isinstance(result["indicators"], dict):
+        result["atr"] = _normalize_atr(result["indicators"])
+    return result
+
+
+def _field_timestamp(value: Any, fallback: Any = None) -> Any:
+    if isinstance(value, dict):
+        candidate = _first_value(value, "timestamp", "time", "ts", "updatedAt", "lastUpdateTime")
+        if candidate is not None:
+            return candidate
+    if isinstance(value, list) and value:
+        last = value[-1]
+        if isinstance(last, dict):
+            return _first_value(last, "timestamp", "time", "ts", "openTime") or fallback
+        if isinstance(last, (list, tuple)) and last:
+            return last[0]
+    return fallback
+
+
+def _freshness_label(timestamp: Any, timeframe: str) -> str:
+    if timestamp is None:
+        return "unknown"
+    try:
+        if isinstance(timestamp, str) and not timestamp.isdigit():
+            parsed = datetime.fromisoformat(timestamp.replace("Z", "+00:00")).timestamp()
+        else:
+            parsed = normalize_epoch_milliseconds(timestamp) / 1000
+    except (ValueError, TypeError, OverflowError):
+        return "unknown"
+    max_age = max(180, SUPPORTED_INTERVALS.get(timeframe, 300) * 3)
+    age = time.time() - parsed
+    if age < -60:
+        return "invalid"
+    return "fresh" if age <= max_age else "stale"
+
+
+def _concise_reason(source: str, missing: list[str], stale: bool = False) -> str:
+    if stale:
+        return f"{source} data is stale"
+    if missing:
+        return f"Required fields unavailable: {', '.join(missing)}"
+    return "Data is usable"
+
+
+def _provider_issue_text(issue: Any) -> str:
+    if not isinstance(issue, dict):
+        return str(issue)
+    provider = str(issue.get("provider") or issue.get("source") or "Binance")
+    category = str(issue.get("category") or "provider_error")
+    status = issue.get("status")
+    field = issue.get("field")
+    parts = [provider, category]
+    if status is not None:
+        parts.append(f"HTTP {status}")
+    if field:
+        parts.append(f"field={field}")
+    message = str(issue.get("message") or "request unavailable")
+    return " · ".join(parts) + f": {message}"
+
+
+async def get_market_context(symbol: str, timeframe: str = "5m", limit: int = 120) -> dict:
     """Fetch and merge Futures market context for `symbol` from both datasources.
 
     Returns the standard merged envelope: primary, secondary, merged, sources,
@@ -187,22 +708,39 @@ async def get_market_context(symbol: str, timeframe: str = "5m") -> dict:
     no_trade_reasons: list[str] = []
 
     async with httpx.AsyncClient() as client:
-        (ds4, ds4_warnings), (ds2_context, ds2_warnings) = await asyncio.gather(
-            _fetch_ds4_snapshot(client, norm.ds4),
+        (ds4, ds4_warnings, ds4_transport), (ds2_context, ds2_warnings, ds2_transport) = await asyncio.gather(
+            _fetch_ds4_snapshot(client, norm.ds4, timeframe, limit),
             _fetch_ds2_context(client, norm.ds2),
         )
     warnings.extend(ds4_warnings)
     warnings.extend(ds2_warnings)
 
-    if isinstance(ds4, dict):
-        warnings.extend(str(item) for item in (ds4.get("warnings") or []))
-        warnings.extend(f"Datasource 4 error: {item}" for item in (ds4.get("errors") or []))
+    ds4_warnings_payload = _find_section(ds4, "warnings") if isinstance(ds4, dict) else None
+    ds4_errors_payload = _find_section(ds4, "errors") if isinstance(ds4, dict) else None
+    if isinstance(ds4_warnings_payload, list):
+        warnings.extend(str(item) for item in ds4_warnings_payload)
+    if ds4_errors_payload:
+        warnings.append("Datasource 4 reported an upstream provider error")
 
-    ds4_state = str((ds4 or {}).get("dataState") or "").strip().lower()
+    ds4_state_raw = _find_section(ds4, "dataState", "data_state") if isinstance(ds4, dict) else None
+    ds4_state = str(ds4_state_raw or "").strip().lower()
+    ds4_guard = _boolean_flag(
+        _find_section(ds4, "noTradeGuard", "no_trade_guard") if isinstance(ds4, dict) else None
+    ) is True
     ds4_stale = ds4 is not None and ds4_state not in DS4_FRESH_STATES
-    ds4_data = (ds4 or {}).get("data")
-    if not isinstance(ds4_data, dict):
-        ds4_data = {}
+    ds4_data = _normalize_ds4_data(ds4)
+    ds4_authority = dict(ds4 or {})
+    ds4_authority["dataState"] = ds4_state_raw
+    ds4_authority["noTradeGuard"] = ds4_guard
+    futures_verification = _contract_verification(
+        ds4_data.get("contract"), ds4_authority if ds4 is not None else None, stale=ds4_stale,
+    )
+    if futures_verification.get("verified") and not ds4_data.get("contract"):
+        ds4_data["contract"] = {
+            "symbol": norm.ds4,
+            "futuresVerified": True,
+            "verificationSource": "datasource4",
+        }
 
     sources: dict[str, str] = {}
     merged: dict[str, Any] = {}
@@ -211,6 +749,8 @@ async def get_market_context(symbol: str, timeframe: str = "5m") -> dict:
         # A stale/partial DS4 snapshot remains available in `primary`, but its
         # Futures values are not treated as current merged market data.
         usable = _is_usable(field, value) and not (ds4_stale and field in binance_public.SUPPORTED_FIELDS)
+        if field == "contract":
+            usable = usable and futures_verification.get("verified") is True
         merged[field] = value if usable else None
         sources[field] = "datasource4" if usable else "unavailable"
         if value not in (None, {}, [], "") and not usable:
@@ -227,9 +767,12 @@ async def get_market_context(symbol: str, timeframe: str = "5m") -> dict:
             if ds4_oi_change is not None:
                 merged["openInterest"] = dict(merged["openInterest"])
                 merged["openInterest"]["changePercent"] = ds4_oi_change
+                merged["openInterest"]["changeFraction"] = ds4_oi_change
                 sources["openInterest.changePercent"] = "datasource4"
 
     # ---- Secondary priority: Binance public Futures data -------------
+    binance_diagnostics: list[str] = []
+    binance_snapshot: dict[str, Any] = {}
     needed = {
         field for field in ("ticker", "ohlcv", "orderbook", "funding", "openInterest", "atr")
         if not _is_usable(field, merged.get(field))
@@ -237,11 +780,36 @@ async def get_market_context(symbol: str, timeframe: str = "5m") -> dict:
     if not _has_oi_change(merged.get("openInterest")):
         needed.add("openInterestChange")
 
+    binance_issues: list[dict] = []
+    binance_meta_runtime: dict[str, Any] = {}
     if needed:
-        binance_snapshot, binance_warnings = await binance_public.get_binance_public_snapshot(
-            norm.ds4, frozenset(needed)
-        )
-        warnings.extend(binance_warnings)
+        market_needed = needed & {"ticker", "ohlcv", "funding", "openInterest"}
+        snapshot_needed = needed - market_needed
+        results = []
+        if market_needed:
+            results.append(await binance_public.get_binance_public_market_data(
+                norm.ds4, timeframe, limit,
+            ))
+        if snapshot_needed:
+            results.append(await binance_public.get_binance_public_result(
+                norm.ds4, frozenset(snapshot_needed),
+            ))
+        for result in results:
+            if not isinstance(result, dict):
+                continue
+            binance_snapshot.update(result.get("data") or {})
+            binance_issues.extend(
+                item for item in (list(result.get("errors") or []) + list(result.get("warnings") or []))
+                if isinstance(item, dict)
+            )
+            runtime_meta = result.get("meta")
+            if isinstance(runtime_meta, dict):
+                binance_meta_runtime.update(runtime_meta)
+        binance_diagnostics = [_provider_issue_text(item) for item in binance_issues]
+        if any(item.get("status") == 451 for item in binance_issues):
+            warnings.append("Binance public API is regionally restricted (HTTP 451)")
+        elif binance_diagnostics:
+            warnings.append("Binance public fallback could not supply one or more requested fields")
         for field in needed - {"openInterestChange"}:
             value = binance_snapshot.get(field)
             if _is_usable(field, value):
@@ -257,6 +825,9 @@ async def get_market_context(symbol: str, timeframe: str = "5m") -> dict:
             if isinstance(existing_oi, dict):
                 merged["openInterest"] = dict(existing_oi)
                 merged["openInterest"]["changePercent"] = oi_change["changePercent"]
+                merged["openInterest"]["changeFraction"] = oi_change.get(
+                    "changeFraction", oi_change["changePercent"]
+                )
                 merged["openInterest"]["history"] = oi_change.get("history", [])
                 sources["openInterest.changePercent"] = "binance_public"
                 sources["openInterest.history"] = "binance_public"
@@ -264,9 +835,16 @@ async def get_market_context(symbol: str, timeframe: str = "5m") -> dict:
 
     # ---- Lowest priority: Datasource 2 complementary/fallback data ----
     # It may fill only a field still unavailable after DS4 and Binance.
+    ds2_indicator_payload = ds2_context.get("indicators")
+    if isinstance(ds2_indicator_payload, dict):
+        ds2_indicators = _find_section(
+            ds2_indicator_payload, "indicators", "technicalIndicators", "data", "result"
+        ) or ds2_indicator_payload
+    else:
+        ds2_indicators = ds2_indicator_payload
     ds2_equivalents = {
-        "orderbook": ds2_context.get("orderbook"),
-        "indicators": ds2_context.get("indicators"),
+        "orderbook": _normalize_orderbook(ds2_context.get("orderbook")),
+        "indicators": ds2_indicators,
     }
     for field, value in ds2_equivalents.items():
         if not _is_usable(field, merged.get(field)) and _is_usable(field, value):
@@ -292,13 +870,17 @@ async def get_market_context(symbol: str, timeframe: str = "5m") -> dict:
         no_trade_guard = True
         no_trade_reasons.append("Datasource 4 unreachable — Futures-critical data unavailable")
     else:
-        if ds4.get("noTradeGuard"):
+        if ds4_guard:
             no_trade_guard = True
             no_trade_reasons.append("Datasource 4 noTradeGuard=true (authoritative, not overridable)")
         if ds4_stale:
-            no_trade_reasons.append(f"Datasource 4 dataState={ds4.get('dataState')!r} (stale)")
+            no_trade_reasons.append(f"Datasource 4 dataState={ds4_state_raw!r} (stale)")
             no_trade_guard = True
 
+    if not futures_verification.get("verified"):
+        no_trade_guard = True
+        no_trade_reasons.append(futures_verification.get("reason") or "Futures verification unavailable")
+
     missing_critical = [f for f in FUTURES_CRITICAL_FIELDS if not _is_usable(f, merged.get(f))]
     if missing_critical:
         no_trade_guard = True
@@ -306,15 +888,179 @@ async def get_market_context(symbol: str, timeframe: str = "5m") -> dict:
             f"Missing required Futures fields after merge: {', '.join(missing_critical)}"
         )
 
+    primary_timestamp = (
+        (ds4 or {}).get("timestamp") or (ds4 or {}).get("updatedAt")
+        or (_find_section(ds4, "timestamp", "updatedAt", "lastUpdateTime") if isinstance(ds4, dict) else None)
+    )
+    observed_at = _iso_now()
+    field_metadata: dict[str, dict] = {}
+    for field in DS4_OWNED_FIELDS:
+        value = merged.get(field)
+        source = sources.get(field, "unavailable")
+        timestamp = _field_timestamp(value, primary_timestamp if source == "datasource4" else None)
+        freshness_basis = "field_timestamp"
+        if timestamp is not None:
+            freshness = _freshness_label(timestamp, timeframe)
+        elif source == "datasource4" and ds4_state in DS4_FRESH_STATES:
+            freshness = "fresh"
+            freshness_basis = "datasource4_dataState"
+        else:
+            # A successful HTTP response proves transport health, not market-data
+            # freshness. Fallback data without its own provider timestamp remains
+            # unknown and therefore cannot pass a Futures freshness gate.
+            freshness = "unknown"
+            freshness_basis = "missing_provider_timestamp" if source not in {"unavailable", None} else "unavailable"
+        valid = _is_usable(field, value)
+        field_metadata[field] = {
+            "value": value, "source": source, "timestamp": timestamp,
+            "freshness": freshness, "validity": "valid" if valid else "unavailable",
+            "observedAt": observed_at, "freshnessBasis": freshness_basis,
+            "fallbackStatus": "primary" if source == "datasource4" else ("fallback" if source not in {"unavailable", None} else "not_filled"),
+        }
+
+    stale_critical = [
+        field for field in FUTURES_CRITICAL_FIELDS
+        if (field_metadata.get(field) or {}).get("freshness") in {"stale", "invalid", "unknown"}
+    ]
+    if stale_critical:
+        no_trade_guard = True
+        no_trade_reasons.append(
+            f"Required Futures fields are not fresh: {', '.join(stale_critical)}"
+        )
+
+    ds4_missing = [f for f in FUTURES_CRITICAL_FIELDS if sources.get(f) != "datasource4"]
+    ds4_usability = "unavailable" if ds4 is None else (
+        "degraded" if ds4_stale or ds4_missing or str(ds4_state_raw or "").upper() == "PARTIAL" else "usable"
+    )
+    restricted = any(item.get("status") == 451 for item in binance_issues)
+    binance_supplied = sorted(f for f, source in sources.items() if source == "binance_public")
+    binance_missing = sorted(
+        f for f in needed if f not in binance_snapshot and f != "openInterestChange"
+    )
+    binance_freshness_values = [
+        (field_metadata.get(field) or {}).get("freshness") for field in binance_supplied
+    ]
+    binance_freshness = (
+        "stale" if any(value in {"stale", "invalid"} for value in binance_freshness_values) else
+        "fresh" if binance_freshness_values and all(value == "fresh" for value in binance_freshness_values) else
+        "unknown"
+    )
+    binance_attempted = bool(needed)
+    binance_transport = (
+        "restricted" if restricted else
+        "healthy" if binance_supplied or binance_meta_runtime.get("lastSuccess") else
+        "degraded" if binance_attempted else "standby"
+    )
+    binance_meta = {
+        "name": "Binance public", "url": binance_public.BASE_URL,
+        "transportStatus": binance_transport,
+        "dataUsability": "unavailable" if restricted or (binance_attempted and not binance_supplied) else (
+            "usable" if binance_supplied and binance_freshness == "fresh" else
+            "degraded" if binance_supplied else "not_used"
+        ),
+        "endpoint": binance_public.BASE_URL,
+        "httpStatus": 451 if restricted else binance_meta_runtime.get("httpStatus"),
+        "latencyMs": binance_meta_runtime.get("latencyMs"),
+        "lastSuccess": binance_meta_runtime.get("lastSuccess"),
+        "freshness": binance_freshness,
+        "completeness": "partial" if binance_missing else ("complete" if binance_supplied else "unknown"),
+        "suppliedFields": binance_supplied,
+        "missingFields": binance_missing,
+        "reason": "Regionally restricted" if restricted else (
+            "Fallback supplied fields" if binance_supplied else "Fallback not used or no usable response"
+        ),
+    }
+    binance_meta["status"] = "unavailable" if restricted else (
+        "ok" if binance_supplied and not binance_missing and binance_freshness == "fresh" else
+        "degraded" if binance_attempted else "standby"
+    )
+    ds2_supplied = sorted(f for f, source in sources.items() if source == "datasource2")
+    ds4_supplied = sorted(f for f, source in sources.items() if source == "datasource4")
+    ds4_freshness_values = [
+        (field_metadata.get(field) or {}).get("freshness") for field in ds4_supplied
+    ]
+    ds4_freshness = (
+        "stale" if ds4_stale or any(value in {"stale", "invalid"} for value in ds4_freshness_values) else
+        "fresh" if ds4_freshness_values and all(value == "fresh" for value in ds4_freshness_values) else
+        "unknown"
+    )
+    ds2_freshness_values = [
+        (field_metadata.get(field) or {}).get("freshness") for field in ds2_supplied
+    ]
+    ds2_freshness = (
+        "stale" if any(value in {"stale", "invalid"} for value in ds2_freshness_values) else
+        "fresh" if ds2_freshness_values and all(value == "fresh" for value in ds2_freshness_values) else
+        "unknown"
+    )
+    ds4_meta = {
+        **ds4_transport, "name": "Datasource 4", "url": DS4_BASE,
+        "dataUsability": ds4_usability,
+        "freshness": ds4_freshness,
+        "completeness": "complete" if not ds4_missing else "partial",
+        "suppliedFields": ds4_supplied,
+        "missingFields": ds4_missing,
+        "reason": _concise_reason("Datasource 4", ds4_missing, ds4_stale),
+    }
+    ds4_meta["status"] = "unreachable" if ds4 is None else (
+        "ok" if ds4_usability == "usable" else "degraded"
+    )
+    ds2_meta = {
+        **ds2_transport, "name": "Datasource 2", "url": DS2_BASE,
+        "dataUsability": "usable" if ds2_context and not ds2_supplied else (
+            "usable" if ds2_supplied and ds2_freshness == "fresh" else
+            "degraded" if ds2_context else "unavailable"
+        ),
+        "freshness": ds2_freshness,
+        "completeness": "partial" if ds2_warnings else "complete",
+        "suppliedFields": sorted(set(ds2_supplied) | set(ds2_transport.get("suppliedFields") or [])),
+        "missingFields": list(ds2_transport.get("missingFields") or []),
+        "reason": "Complementary context available" if ds2_context else "Complementary context unavailable",
+    }
+    ds2_meta["status"] = "ok" if ds2_context and not ds2_warnings and (
+        not ds2_supplied or ds2_freshness == "fresh"
+    ) else ("degraded" if ds2_context else "unreachable")
+    source_metadata = {
+        "datasource4": ds4_meta,
+        "binance": binance_meta,
+        "datasource2": ds2_meta,
+    }
+    trading_readiness = "ready" if not no_trade_guard else "blocked"
+    merge_status = "complete" if not missing_critical and not stale_critical else "partial"
+
     return {
         "symbol": norm.ds4,
+        "verifiedFutures": bool(futures_verification.get("verified")),
+        "futuresVerification": futures_verification,
         "primary": ds4 or {},
         "secondary": ds2_context,
         "merged": merged,
         "sources": sources,
+        "fieldMetadata": field_metadata,
+        "sourceMetadata": source_metadata,
+        "transportStatus": {k: v.get("transportStatus") for k, v in source_metadata.items()},
+        "dataUsability": {k: v.get("dataUsability") for k, v in source_metadata.items()},
+        "freshness": {k: v.get("freshness") for k, v in source_metadata.items()},
+        "completeness": {k: v.get("completeness") for k, v in source_metadata.items()},
+        "mergeStatus": merge_status,
+        "tradingReadiness": trading_readiness,
         "warnings": warnings,
+        "technicalDiagnostics": {
+            "datasource4": list(ds4_errors_payload) if isinstance(ds4_errors_payload, list) else (
+                [ds4_errors_payload] if ds4_errors_payload else []
+            ),
+            "binance": binance_diagnostics,
+            "datasource2": ds2_warnings,
+            "merge": {
+                "status": merge_status,
+                "missingCriticalFields": missing_critical,
+                "tradingReadiness": trading_readiness,
+                "rejectionReasons": no_trade_reasons,
+            },
+        },
         "noTradeGuard": no_trade_guard,
         "noTradeReasons": no_trade_reasons,
+        "missingRequiredFields": missing_critical,
+        "staleRequiredFields": stale_critical,
         "timeframe": timeframe,
         "fetchedAt": time.time(),
     }

hermes_overlay/trading/state.py

@@ -1,10 +1,9 @@
 """In-memory dashboard state for the Futures desk.
 
-The LLM (Hermes) is the one that actually decides LONG / SHORT / NO_TRADE by
-calling the registered tools; this module just remembers the *last* outcome
-of those calls so the dashboard has something to show. No new decision logic
-lives here -- it only mirrors what dual_datasource_client / futures_execution
-already produced.
+The deterministic Futures engine decides LONG / SHORT / NO_TRADE. This
+module only remembers the last bounded outcome so the dashboard can display
+it. No decision logic lives here; it mirrors the datasource, risk, and
+execution layers without granting the browser additional authority.
 """
 from __future__ import annotations
 
@@ -19,13 +18,43 @@ _PLAN_FIELDS = (
     "warnings", "entry", "stop_loss", "take_profit", "reward_to_risk",
     "risk_profile", "risk_percent", "requested_leverage", "effective_leverage",
     "quantity", "estimated_slippage_percent", "risk_approved", "rejection_reasons",
-    "created_at", "expires_at", "external_advisory",
+    "created_at", "expires_at", "external_advisory", "noTradeGuard",
+    "plan_type", "executable", "analysis_state", "futuresVerified",
+    "futuresVerification", "field_sources", "field_metadata",
+    "missing_required_fields", "stale_required_fields", "merge_status", "trading_readiness",
 )
 
 
 def _safe_plan_view(plan: dict) -> dict:
     """Keep analytical plan fields, excluding external/raw exchange payloads."""
-    return {key: plan.get(key) for key in _PLAN_FIELDS if key in plan}
+    safe = {key: plan.get(key) for key in _PLAN_FIELDS if key in plan}
+    metadata = safe.get("field_metadata")
+    if isinstance(metadata, dict):
+        bounded: dict[str, dict] = {}
+        for field_name, item in metadata.items():
+            if not isinstance(item, dict):
+                continue
+            entry = {key: item.get(key) for key in (
+                "source", "timestamp", "freshness", "validity", "fallbackStatus"
+            ) if key in item}
+            if isinstance(item.get("valueSummary"), dict):
+                entry["valueSummary"] = dict(item["valueSummary"])
+                bounded[str(field_name)] = entry
+                continue
+            value = item.get("value")
+            if field_name == "ohlcv" and isinstance(value, list):
+                entry["value"] = {"count": len(value), "latest": value[-1] if value else None}
+            elif field_name == "orderbook" and isinstance(value, dict):
+                bids, asks = value.get("bids") or [], value.get("asks") or []
+                entry["value"] = {
+                    "bidLevels": len(bids), "askLevels": len(asks),
+                    "bestBid": bids[0] if bids else None, "bestAsk": asks[0] if asks else None,
+                }
+            else:
+                entry["value"] = value
+            bounded[str(field_name)] = entry
+        safe["field_metadata"] = bounded
+    return safe
 
 
 def _plan_epoch(plan: dict, key: str) -> Optional[float]:
@@ -46,7 +75,18 @@ class DashboardState:
     primary_status: str = "unknown"       # ok | degraded | unreachable | unknown
     secondary_status: str = "unknown"
     field_sources: dict = field(default_factory=dict)
-    current_signal: str = "NO_TRADE"      # LONG | SHORT | NO_TRADE
+    field_metadata: dict = field(default_factory=dict)
+    source_metadata: dict = field(default_factory=dict)
+    merge_status: str = "unknown"
+    trading_readiness: str = "blocked"
+    technical_diagnostics: dict = field(default_factory=dict)
+    market_rejection_reasons: list = field(default_factory=list)
+    verified_futures: bool = False
+    futures_verification: dict = field(default_factory=dict)
+    missing_required_fields: list = field(default_factory=list)
+    stale_required_fields: list = field(default_factory=list)
+    analysis_state: str = "NOT_ANALYZED"
+    current_signal: str = "NOT_ANALYZED"  # NOT_ANALYZED | LONG | SHORT | NO_TRADE | ANALYSIS_FAILED
     signal_reasons: list = field(default_factory=list)
     warnings: list = field(default_factory=list)
     rejected_trade_reason: Optional[str] = None
@@ -72,15 +112,36 @@ def record_market_context(context: dict) -> None:
     """Called after every get_market_context()/get_alpha_signals() so the
     dashboard reflects the latest datasource health + guard state."""
     _state.symbol = context.get("symbol", _state.symbol)
-    _state.primary_status = "unreachable" if not context.get("primary") else (
-        "degraded" if context.get("noTradeGuard") else "ok"
+    source_metadata = context.get("sourceMetadata") or {}
+    ds4_meta = source_metadata.get("datasource4") or {}
+    ds2_meta = source_metadata.get("datasource2") or {}
+    _state.primary_status = ds4_meta.get("status") or (
+        "unreachable" if not context.get("primary") else "degraded"
+        if context.get("noTradeGuard") else "ok"
+    )
+    _state.secondary_status = ds2_meta.get("status") or (
+        "degraded" if context.get("warnings") else "ok"
     )
-    _state.secondary_status = "degraded" if context.get("warnings") else "ok"
     _state.field_sources = context.get("sources", _state.field_sources)
+    _state.field_metadata = context.get("fieldMetadata", _state.field_metadata)
+    _state.source_metadata = context.get("sourceMetadata", _state.source_metadata)
+    _state.merge_status = context.get("mergeStatus", _state.merge_status)
+    _state.trading_readiness = context.get("tradingReadiness", _state.trading_readiness)
+    _state.technical_diagnostics = context.get("technicalDiagnostics", _state.technical_diagnostics)
+    _state.verified_futures = bool(context.get("verifiedFutures"))
+    _state.futures_verification = dict(context.get("futuresVerification") or {})
+    _state.missing_required_fields = list(context.get("missingRequiredFields") or [])
+    _state.stale_required_fields = list(context.get("staleRequiredFields") or [])
     _state.warnings = context.get("warnings", [])
+    _state.market_rejection_reasons = list(context.get("noTradeReasons") or [])
+    # Fail-safe: if the guard trips on the market-context call itself (e.g.
+    # Datasource 4 unreachable, unverified contract, stale data), the
+    # dashboard must show NO_TRADE rather than leave a stale/ambiguous
+    # signal from a previous request -- never silently imply tradability.
     if context.get("noTradeGuard"):
         _state.current_signal = "NO_TRADE"
-        _state.signal_reasons = context.get("noTradeReasons", [])
+        if _state.market_rejection_reasons:
+            _state.signal_reasons = list(_state.market_rejection_reasons)
     _state.updated_at = time.time()
 
 
@@ -107,8 +168,14 @@ def record_trade_plan(plan: dict, plan_id: Optional[str] = None) -> str:
     safe = _safe_plan_view(plan if isinstance(plan, dict) else {})
     reference = plan_id or uuid.uuid4().hex
     _state.latest_trade_plan = safe
+    _state.analysis_state = str(safe.get("analysis_state") or (
+        safe.get("decision") if safe.get("decision") in {"LONG", "SHORT", "NO_TRADE"} else "ANALYSIS_FAILED"
+    ))
     _state.latest_plan_id = reference
     _state.latest_plan_symbol = safe.get("symbol")
+    if safe.get("decision") in {"LONG", "SHORT", "NO_TRADE"}:
+        _state.current_signal = safe["decision"]
+        _state.signal_reasons = list(safe.get("core_reasons") or [])
     _state.latest_plan_risk_profile = safe.get("risk_profile", "moderate")
     _state.latest_plan_created_at = _plan_epoch(safe, "created_at") or time.time()
     _state.latest_plan_expires_at = _plan_epoch(safe, "expires_at")
@@ -140,5 +207,29 @@ def record_paper_execution(result: dict) -> None:
     _state.updated_at = time.time()
 
 
+def record_analysis_failure(reason: str, diagnostic: Optional[str] = None) -> None:
+    """Record a failed request without presenting the previous plan as current."""
+    _state.analysis_state = "ANALYSIS_FAILED"
+    _state.current_signal = "ANALYSIS_FAILED"
+    _state.signal_reasons = [reason]
+    _state.latest_trade_plan = None
+    _state.latest_plan_id = None
+    _state.latest_plan_symbol = None
+    _state.latest_plan_risk_profile = None
+    _state.latest_plan_created_at = None
+    _state.latest_plan_expires_at = None
+    _state.latest_signal_score = None
+    _state.signal_components = {}
+    _state.risk_approved = False
+    _state.rejection_reasons = [reason]
+    _state.market_rejection_reasons = []
+    if diagnostic:
+        diagnostics = dict(_state.technical_diagnostics or {})
+        diagnostics["analysis"] = [diagnostic]
+        _state.technical_diagnostics = diagnostics
+    _state.latest_plan_executed = False
+    _state.updated_at = time.time()
+
+
 def snapshot() -> dict:
     return asdict(_state)

hermes_overlay/trading/trade_cycle.py

@@ -80,8 +80,9 @@ def _to_float(x: Any) -> Optional[float]:
 def _extract_ohlcv_returns(merged: dict):
     """(short_return, medium_return, volume_ratio) from merged['ohlcv'].
 
-    Expects a list of candles, each [ts, open, high, low, close, volume] or
-    an equivalent dict. TODO: confirm against a live DS4 snapshot.
+    Expects normalized candles from the datasource layer. Both the historical
+    list form and the canonical dictionary form remain accepted for backward
+    compatibility with older cached snapshots.
     """
     ohlcv = merged.get("ohlcv")
     if not isinstance(ohlcv, list) or len(ohlcv) < 4:
@@ -140,6 +141,9 @@ def _extract_orderbook_imbalance(merged: dict, depth: int = 10) -> Optional[floa
 
 
 def _extract_price_change(merged: dict) -> Optional[float]:
+    canonical = _to_float(_first_present(merged.get("ticker"), "change24hFraction"))
+    if canonical is not None:
+        return canonical
     val = _to_float(_first_present(
         merged.get("ticker"), "change24h", "percentage", "changePercent", "priceChangePercent"
     ))
@@ -147,6 +151,9 @@ def _extract_price_change(merged: dict) -> Optional[float]:
 
 
 def _extract_open_interest_change(merged: dict) -> Optional[float]:
+    canonical = _to_float(_first_present(merged.get("openInterest"), "changeFraction"))
+    if canonical is not None:
+        return canonical
     val = _to_float(_first_present(merged.get("openInterest"), "change24h", "changePercent", "oiChangePercent"))
     return (val / 100.0 if abs(val) > 1 else val) if val is not None else None
 
@@ -276,25 +283,92 @@ def _compute_signal(merged: dict) -> SignalResult:
 
 def _empty_plan(symbol: str, decision: str, reasons: list, warnings: list,
                  components: dict, external_context: dict, created_at: float,
-                 external_advisory: Optional[dict] = None) -> dict:
+                 risk_profile: str, *, no_trade_guard: bool = False,
+                 external_advisory: Optional[dict] = None,
+                 score: Optional[float] = None) -> dict:
+    """Return a completed, non-executable analysis record with no fake expiry."""
     return {
-        "symbol": symbol, "decision": decision, "score": 0.0, "confidence": 0.0,
+        "symbol": symbol, "decision": decision, "score": score,
+        "confidence": abs(score) if score is not None else None,
         "components": components, "core_reasons": reasons, "warnings": warnings,
         "entry": None, "stop_loss": None, "take_profit": None, "reward_to_risk": None,
-        "risk_profile": None, "risk_percent": None, "requested_leverage": None,
+        "risk_profile": risk_profile, "risk_percent": None, "requested_leverage": None,
         "effective_leverage": None, "quantity": None, "estimated_slippage_percent": None,
-        "risk_approved": False, "rejection_reasons": [], "external_context": external_context,
-        "external_advisory": external_advisory,
+        "risk_approved": False, "rejection_reasons": list(reasons), "external_context": external_context,
+        "external_advisory": external_advisory, "noTradeGuard": bool(no_trade_guard),
+        "plan_type": "rejected_analysis", "executable": False, "analysis_state": "NO_TRADE",
         "executed": False, "execution_result": None,
-        "created_at": _iso(created_at), "expires_at": _iso(created_at + PLAN_MAX_AGE_SECONDS),
+        "created_at": _iso(created_at), "expires_at": None,
     }
 
 
 def _finish_empty_plan(symbol: str, decision: str, reasons: list, warnings: list,
                        components: dict, external_context: dict, created_at: float,
-                       external_advisory: Optional[dict]) -> dict:
-    return _empty_plan(symbol, decision, reasons, warnings, components,
-                       external_context, created_at, external_advisory)
+                       risk_profile: str, *, no_trade_guard: bool = False,
+                       external_advisory: Optional[dict] = None,
+                       score: Optional[float] = None) -> dict:
+    return _empty_plan(
+        symbol, decision, reasons, warnings, components, external_context, created_at,
+        risk_profile, no_trade_guard=no_trade_guard, external_advisory=external_advisory,
+        score=score,
+    )
+
+
+def _public_field_metadata(metadata: dict) -> dict:
+    """Keep field provenance useful without embedding large raw market payloads."""
+    public: dict[str, dict] = {}
+    for name, raw in (metadata or {}).items():
+        if not isinstance(raw, dict):
+            continue
+        item = {
+            key: raw.get(key)
+            for key in ("source", "timestamp", "freshness", "validity", "fallbackStatus")
+            if raw.get(key) is not None
+        }
+        value = raw.get("value")
+        if name == "ohlcv" and isinstance(value, list):
+            item["valueSummary"] = {
+                "count": len(value),
+                "latestTimestamp": value[-1].get("timestamp") if value and isinstance(value[-1], dict) else None,
+            }
+        elif name == "orderbook" and isinstance(value, dict):
+            bids, asks = value.get("bids") or [], value.get("asks") or []
+            item["valueSummary"] = {
+                "bidLevels": len(bids),
+                "askLevels": len(asks),
+                "bestBid": bids[0][0] if bids and isinstance(bids[0], (list, tuple)) and bids[0] else None,
+                "bestAsk": asks[0][0] if asks and isinstance(asks[0], (list, tuple)) and asks[0] else None,
+            }
+        else:
+            item["value"] = value
+        public[name] = item
+    return public
+
+
+def _attach_context_metadata(plan: dict, context: dict) -> dict:
+    """Attach bounded provenance/readiness without changing a deterministic decision."""
+    enriched = dict(plan)
+    enriched["futuresVerified"] = bool(context.get("verifiedFutures"))
+    enriched["futuresVerification"] = context.get("futuresVerification") or {}
+    enriched["field_sources"] = dict(context.get("sources") or {})
+    enriched["field_metadata"] = _public_field_metadata(context.get("fieldMetadata") or {})
+    enriched["missing_required_fields"] = list(context.get("missingRequiredFields") or [])
+    enriched["stale_required_fields"] = list(context.get("staleRequiredFields") or [])
+    enriched["merge_status"] = context.get("mergeStatus") or "unknown"
+    enriched["trading_readiness"] = context.get("tradingReadiness") or "blocked"
+    return enriched
+
+
+def _rejected_plan(context: dict, symbol: str, decision: str, reasons: list, warnings: list,
+                   components: dict, external_context: dict, created_at: float,
+                   risk_profile: str, *, no_trade_guard: bool = False,
+                   external_advisory: Optional[dict] = None,
+                   score: Optional[float] = None) -> dict:
+    return _attach_context_metadata(_finish_empty_plan(
+        symbol, decision, reasons, warnings, components, external_context, created_at,
+        risk_profile, no_trade_guard=no_trade_guard,
+        external_advisory=external_advisory, score=score,
+    ), context)
 
 
 async def run_futures_cycle(
@@ -327,18 +401,24 @@ async def run_futures_cycle(
 
     # ---- Step 3: hard NO_TRADE gates --------------------------------------
     if context.get("noTradeGuard"):
-        return _finish_empty_plan(norm.ds4, "NO_TRADE", context.get("noTradeReasons", []),
-                                  context.get("warnings", []), {}, external_context, created_at,
-                                  external_advisory)
+        return _rejected_plan(context,
+            norm.ds4, "NO_TRADE", context.get("noTradeReasons", []),
+            context.get("warnings", []), {}, external_context, created_at, risk_profile,
+            no_trade_guard=True, external_advisory=external_advisory,
+        )
     if not merged.get("orderbook"):
-        return _finish_empty_plan(norm.ds4, "NO_TRADE", ["Order book unavailable"],
-                                  context.get("warnings", []), {}, external_context, created_at,
-                                  external_advisory)
+        return _rejected_plan(context,
+            norm.ds4, "NO_TRADE", ["Order book unavailable"], context.get("warnings", []),
+            {}, external_context, created_at, risk_profile,
+            external_advisory=external_advisory,
+        )
     atr_check = _to_float(merged.get("atr"))
     if atr_check is None or atr_check <= 0:
-        return _finish_empty_plan(norm.ds4, "NO_TRADE", ["ATR unavailable or invalid"],
-                                  context.get("warnings", []), {}, external_context, created_at,
-                                  external_advisory)
+        return _rejected_plan(context,
+            norm.ds4, "NO_TRADE", ["ATR unavailable or invalid"], context.get("warnings", []),
+            {}, external_context, created_at, risk_profile,
+            external_advisory=external_advisory,
+        )
 
     # ---- Steps 4-5: deterministic signal ----------------------------------
     signal = _compute_signal(merged)
@@ -348,24 +428,36 @@ async def run_futures_cycle(
     if signal.non_missing_count < MIN_SIGNAL_COMPONENTS:
         reasons.append(f"Only {signal.non_missing_count} signal components available "
                         f"(need {MIN_SIGNAL_COMPONENTS}) — NO_TRADE")
-        return _finish_empty_plan(norm.ds4, "NO_TRADE", reasons, warnings, signal.components,
-                                  external_context, created_at, external_advisory)
+        return _rejected_plan(context,
+            norm.ds4, "NO_TRADE", reasons, warnings, signal.components,
+            external_context, created_at, risk_profile,
+            external_advisory=external_advisory, score=signal.score,
+        )
     if abs(signal.score) < MIN_SIGNAL_SCORE:
         reasons.append(f"Score {signal.score:+.2f} below minimum {MIN_SIGNAL_SCORE} — NO_TRADE")
-        return _finish_empty_plan(norm.ds4, "NO_TRADE", reasons, warnings, signal.components,
-                                  external_context, created_at, external_advisory)
+        return _rejected_plan(context,
+            norm.ds4, "NO_TRADE", reasons, warnings, signal.components,
+            external_context, created_at, risk_profile,
+            external_advisory=external_advisory, score=signal.score,
+        )
     if signal.direction_confirmations < MIN_DIRECTION_CONFIRMATIONS:
         reasons.append(f"Only {signal.direction_confirmations} components confirm the direction "
                         f"(need {MIN_DIRECTION_CONFIRMATIONS}) — NO_TRADE")
-        return _finish_empty_plan(norm.ds4, "NO_TRADE", reasons, warnings, signal.components,
-                                  external_context, created_at, external_advisory)
+        return _rejected_plan(context,
+            norm.ds4, "NO_TRADE", reasons, warnings, signal.components,
+            external_context, created_at, risk_profile,
+            external_advisory=external_advisory, score=signal.score,
+        )
 
     decision = "LONG" if signal.score > 0 else "SHORT"
     entry, atr = signal.reference_price, signal.atr
     if not entry or not atr:
         reasons.append("Missing entry reference price or ATR after signal pass — NO_TRADE")
-        return _finish_empty_plan(norm.ds4, "NO_TRADE", reasons, warnings, signal.components,
-                                  external_context, created_at, external_advisory)
+        return _rejected_plan(context,
+            norm.ds4, "NO_TRADE", reasons, warnings, signal.components,
+            external_context, created_at, risk_profile,
+            external_advisory=external_advisory, score=signal.score,
+        )
 
     # ---- Step 6: Stop Loss / Take Profit ----------------------------------
     stop_distance = max(atr * STOP_ATR_MULTIPLIER, entry * (MIN_STOP_BPS / 10000.0))
@@ -378,7 +470,10 @@ async def run_futures_cycle(
 
     if not valid or stop_loss <= 0 or take_profit <= 0:
         reasons.append("Invalid Stop Loss / Take Profit price relationship — NO_TRADE")
-        return _empty_plan(norm.ds4, "NO_TRADE", reasons, warnings, signal.components, external_context, created_at)
+        return _rejected_plan(context,
+            norm.ds4, "NO_TRADE", reasons, warnings, signal.components, external_context,
+            created_at, risk_profile, external_advisory=external_advisory, score=signal.score,
+        )
 
     plan = {
         "symbol": norm.ds4, "decision": decision, "score": signal.score,
@@ -390,10 +485,12 @@ async def run_futures_cycle(
         "requested_leverage": DEFAULT_REQUESTED_LEVERAGE, "effective_leverage": None,
         "quantity": None, "estimated_slippage_percent": None, "risk_approved": False,
         "rejection_reasons": [], "external_context": external_context,
-        "external_advisory": external_advisory,
+        "external_advisory": external_advisory, "noTradeGuard": False,
+        "plan_type": "directional_plan", "executable": False, "analysis_state": decision,
         "executed": False, "execution_result": None,
         "created_at": _iso(created_at), "expires_at": _iso(created_at + PLAN_MAX_AGE_SECONDS),
     }
+    plan = _attach_context_metadata(plan, context)
 
     # ---- Step 7: risk approval (reuses trading.risk, not duplicated) ------
     try:
@@ -432,8 +529,16 @@ async def run_futures_cycle(
         except Exception:
             plan["warnings"].append("Could not estimate slippage from order book")
 
+    plan["executable"] = bool(
+        plan["risk_approved"] and plan["decision"] in {"LONG", "SHORT"}
+        and not plan["rejection_reasons"] and plan.get("futuresVerified") is True
+        and plan.get("trading_readiness") == "ready"
+    )
+    if not plan["executable"]:
+        plan["plan_type"] = "non_executable_plan"
+
     # ---- Step 8-10: Paper-only execution ----------------------------------
-    if execute and plan["risk_approved"] and get_trading_mode() == "paper":
+    if execute and plan["executable"] and get_trading_mode() == "paper":
         if time.time() - created_at > PLAN_MAX_AGE_SECONDS:
             plan["rejection_reasons"].append("Plan expired before execution")
         else:
@@ -456,5 +561,17 @@ async def run_futures_cycle(
             f"execute=true requested but trading mode is {get_trading_mode()!r} — "
             "only Paper execution is enabled in this phase"
         )
+    elif execute and not plan["executable"]:
+        plan["rejection_reasons"].append(
+            "Execution blocked because the directional plan is not server-authorized"
+        )
 
+    plan["executable"] = bool(
+        plan["risk_approved"] and plan["decision"] in {"LONG", "SHORT"}
+        and not plan["rejection_reasons"] and not plan["executed"]
+        and plan.get("futuresVerified") is True
+        and plan.get("trading_readiness") == "ready"
+    )
+    if not plan["executable"] and plan["plan_type"] == "directional_plan":
+        plan["plan_type"] = "non_executable_plan"
     return plan

scripts/sync_hf.py

@@ -14,6 +14,8 @@ as-is to/from a Hugging Face Dataset repo.
 import os
 import sys
 import time
+import json
+import hashlib
 import threading
 import subprocess
 import signal
@@ -572,6 +574,49 @@ class HermesFullSync:
             templates_src = tools_src / "templates"
             if templates_src.exists():
                 shutil.copytree(templates_src, APP_DIR / "tools" / "templates", dirs_exist_ok=True)
+            tracked = {
+                "router": (
+                    tools_src / "futures_dashboard_api.py",
+                    APP_DIR / "tools" / "futures_dashboard_api.py",
+                ),
+                "template": (
+                    templates_src / "hermes_futures_desk_luxury.html",
+                    APP_DIR / "tools" / "templates" / "hermes_futures_desk_luxury.html",
+                ),
+            }
+
+            def _sha256(path):
+                if not path.is_file():
+                    return None
+                digest = hashlib.sha256()
+                with path.open("rb") as handle:
+                    for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                        digest.update(chunk)
+                return digest.hexdigest()
+
+            manifest = {
+                "installedAt": datetime.now().astimezone().isoformat(),
+                "sourceRoot": str(overlay_src),
+                "destinationRoot": str(APP_DIR),
+                "files": {},
+            }
+            for name, (source_path, destination_path) in tracked.items():
+                source_hash = _sha256(source_path)
+                destination_hash = _sha256(destination_path)
+                manifest["files"][name] = {
+                    "sourcePath": str(source_path),
+                    "destinationPath": str(destination_path),
+                    "sourceSha256": source_hash,
+                    "destinationSha256": destination_hash,
+                    "matches": bool(source_hash and source_hash == destination_hash),
+                }
+            manifest_path = APP_DIR / ".hermes_futures_overlay_manifest.json"
+            manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+            mismatch = [name for name, item in manifest["files"].items() if not item["matches"]]
+            if mismatch:
+                print(f"[SYNC] WARNING: Futures overlay hash mismatch: {', '.join(mismatch)}")
+            else:
+                print("[SYNC] Futures overlay hashes verified")
             print("[SYNC] Futures trading overlay installed into /opt/hermes")
         except Exception as e:
             print(f"[SYNC] Futures overlay install failed (non-fatal): {e}")

scripts/verify_futures_runtime.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Read-only deployed-runtime audit for Hermes Futures Desk.
+
+This utility intentionally never calls the Paper Execute endpoint. Credentials
+are read only from environment variables and are never written to the report.
+It can verify the served dashboard hash, authenticated Futures API response
+shapes, all supported chart intervals, and an optional analysis-only request.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hashlib
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://really-amin-asset.hf.space"
+SUPPORTED_INTERVALS = ("1m", "5m", "15m", "1h")
+
+
+def _redact(value: Any) -> Any:
+    if isinstance(value, dict):
+        result = {}
+        for key, item in value.items():
+            if re.search(r"(?i)(authorization|cookie|token|secret|password|api[_-]?key)", str(key)):
+                result[str(key)] = "[redacted]"
+            else:
+                result[str(key)] = _redact(item)
+        return result
+    if isinstance(value, list):
+        return [_redact(item) for item in value[:200]]
+    if isinstance(value, str):
+        text = re.sub(
+            r"(?i)\b(authorization|cookie|token|secret|password|api[_-]?key)\b\s*[:=]\s*[^\s,;]+",
+            r"\1=[redacted]",
+            value,
+        )
+        return text[:2000]
+    return value
+
+
+def _response_summary(response: httpx.Response, payload: Any = None) -> dict[str, Any]:
+    return {
+        "statusCode": response.status_code,
+        "contentType": response.headers.get("content-type"),
+        "elapsedMs": round(response.elapsed.total_seconds() * 1000, 2),
+        "payload": _redact(payload),
+    }
+
+
+def _market_shape(payload: Any) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        return {"valid": False, "reason": "Payload is not an object"}
+    candles = payload.get("candles")
+    required_keys = {
+        "state", "symbol", "interval", "candles", "currentPrice", "fundingRate",
+        "openInterest", "source", "freshness", "tradingReadiness",
+    }
+    missing = sorted(required_keys - set(payload))
+    real_candles = isinstance(candles, list) and all(
+        isinstance(item, dict)
+        and all(key in item for key in ("timestamp", "open", "high", "low", "close", "volume"))
+        for item in candles
+    )
+    return {
+        "valid": not missing and isinstance(candles, list) and real_candles,
+        "missingKeys": missing,
+        "candleCount": len(candles) if isinstance(candles, list) else None,
+        "state": payload.get("state"),
+        "freshness": payload.get("freshness"),
+        "source": payload.get("source"),
+        "verifiedFutures": payload.get("verifiedFutures"),
+        "tradingReadiness": payload.get("tradingReadiness"),
+    }
+
+
+def _client_auth() -> tuple[httpx.BasicAuth | None, dict[str, str]]:
+    username = os.environ.get("HERMES_DASHBOARD_BASIC_AUTH_USERNAME", "admin")
+    password = os.environ.get("HERMES_ADMIN_PASSWORD", "")
+    cookie = os.environ.get("HERMES_DASHBOARD_COOKIE", "")
+    auth = httpx.BasicAuth(username, password) if password else None
+    headers = {"Accept": "application/json", "Cache-Control": "no-cache"}
+    if cookie:
+        headers["Cookie"] = cookie
+    return auth, headers
+
+
+async def _json_request(
+    client: httpx.AsyncClient,
+    method: str,
+    path: str,
+    *,
+    json_body: dict[str, Any] | None = None,
+) -> tuple[httpx.Response, Any]:
+    response = await client.request(method, path, json=json_body)
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = {"error": "Response was not valid JSON", "bodyPreview": response.text[:500]}
+    return response, payload
+
+
+async def audit(args: argparse.Namespace) -> dict[str, Any]:
+    auth, headers = _client_auth()
+    report: dict[str, Any] = {
+        "generatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "baseUrl": args.base_url.rstrip("/"),
+        "symbol": args.symbol.upper(),
+        "analysisRequested": bool(args.analyze),
+        "paperExecuteCalled": False,
+        "checks": {},
+    }
+    timeout = httpx.Timeout(args.timeout, connect=min(args.timeout, 10.0))
+    async with httpx.AsyncClient(
+        base_url=args.base_url.rstrip("/"),
+        auth=auth,
+        headers=headers,
+        follow_redirects=True,
+        timeout=timeout,
+    ) as client:
+        dashboard = await client.get("/futures", headers={**headers, "Accept": "text/html"})
+        body_hash = hashlib.sha256(dashboard.content).hexdigest()
+        header_hash = dashboard.headers.get("x-hermes-template-sha256")
+        report["checks"]["dashboard"] = {
+            "statusCode": dashboard.status_code,
+            "bodySha256": body_hash,
+            "headerTemplateSha256": header_hash,
+            "headerRouterSha256": dashboard.headers.get("x-hermes-router-sha256"),
+            "hashMatchesHeader": bool(header_hash and header_hash == body_hash),
+            "cacheControl": dashboard.headers.get("cache-control"),
+            "containsMarketEndpoint": "/api/futures/market" in dashboard.text,
+            "containsPaperExecuteEndpoint": "/api/futures/paper/execute" in dashboard.text,
+        }
+
+        for name, path in (
+            ("status", "/api/futures/status"),
+            ("symbols", "/api/futures/symbols"),
+            ("positions", "/api/futures/positions"),
+        ):
+            response, payload = await _json_request(client, "GET", path)
+            report["checks"][name] = _response_summary(response, payload)
+
+        market_checks: dict[str, Any] = {}
+        for interval in SUPPORTED_INTERVALS:
+            path = (
+                f"/api/futures/market?symbol={args.symbol.upper()}"
+                f"&interval={interval}&limit={args.limit}"
+            )
+            response, payload = await _json_request(client, "GET", path)
+            market_checks[interval] = {
+                **_response_summary(response),
+                "shape": _market_shape(payload),
+                "payload": _redact(payload),
+            }
+        report["checks"]["marketIntervals"] = market_checks
+
+        if args.analyze:
+            response, payload = await _json_request(
+                client,
+                "POST",
+                "/api/futures/analyze",
+                json_body={
+                    "symbol": args.symbol.upper(),
+                    "risk_profile": args.risk_profile,
+                    "include_external_context": False,
+                },
+            )
+            report["checks"]["analysis"] = _response_summary(response, payload)
+
+    statuses: list[bool] = []
+    dashboard_check = report["checks"]["dashboard"]
+    statuses.append(dashboard_check["statusCode"] == 200)
+    statuses.append(dashboard_check["hashMatchesHeader"] is True)
+    for name in ("status", "symbols", "positions"):
+        statuses.append(report["checks"][name]["statusCode"] == 200)
+    for interval in SUPPORTED_INTERVALS:
+        check = report["checks"]["marketIntervals"][interval]
+        statuses.append(check["statusCode"] in {200, 503})
+        statuses.append(check["shape"]["valid"] is True)
+    if args.analyze:
+        statuses.append(report["checks"]["analysis"]["statusCode"] == 200)
+    report["summary"] = {
+        "passed": all(statuses),
+        "checkCount": len(statuses),
+        "failedCheckCount": sum(1 for value in statuses if not value),
+        "credentialsProvided": bool(
+            os.environ.get("HERMES_ADMIN_PASSWORD") or os.environ.get("HERMES_DASHBOARD_COOKIE")
+        ),
+        "note": "No Paper, Testnet, or Live execution endpoint was called.",
+    }
+    return report
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("HERMES_FUTURES_BASE_URL", DEFAULT_BASE_URL),
+    )
+    parser.add_argument("--symbol", default="BTCUSDT")
+    parser.add_argument("--limit", type=int, default=120, choices=range(20, 501), metavar="20..500")
+    parser.add_argument(
+        "--risk-profile",
+        choices=("conservative", "moderate", "aggressive"),
+        default="moderate",
+    )
+    parser.add_argument(
+        "--analyze",
+        action="store_true",
+        help="Also perform one analysis-only POST. Paper Execute is still never called.",
+    )
+    parser.add_argument("--timeout", type=float, default=30.0)
+    parser.add_argument("--report", type=Path, default=Path("futures_runtime_audit.json"))
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        report = asyncio.run(audit(args))
+    except Exception as exc:  # Audit failure must still avoid leaking credentials.
+        report = {
+            "generatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "baseUrl": args.base_url,
+            "paperExecuteCalled": False,
+            "summary": {"passed": False, "error": type(exc).__name__},
+        }
+    args.report.parent.mkdir(parents=True, exist_ok=True)
+    args.report.write_text(json.dumps(_redact(report), indent=2, ensure_ascii=False), encoding="utf-8")
+    print(f"Runtime audit report written to {args.report}")
+    print("Paper Execute was not called.")
+    return 0 if report.get("summary", {}).get("passed") else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())