FIX_REPORT.md

# Hermes Futures Desk — Functional Real-UI Repair Report

Date: 2026-07-22
Package: V5 real-code audit

## Scope

The supplied V4 project was inspected again with a specific requirement: the
production Futures interface must be functional and must not display fabricated,
seeded, random, mock, or presentation-only market/account data. The deterministic
trading engine, Datasource 4 authority, `noTradeGuard`, freshness gates, risk
formulas, server-side Paper revalidation, and Telegram webhook isolation were not
weakened.

## Live-Space verification status

The requested URL was targeted for comparison, but outbound DNS/browser navigation
to `really-amin-simplechatbot.hf.space` was blocked in the available execution
environment. Therefore this report does **not** claim an authenticated live-browser
pass against that deployment. The actual source package was instead audited and
validated locally through its API contracts, complete test suite, JavaScript
parsing, HTML/DOM checks, and production-code scans. A post-deployment authenticated
read-only browser check is still required.

## Newly confirmed and repaired UI issues

### 1. Fabricated symbol catalog entries

**Found:** The server padded a failed/short provider catalog with a large hard-coded
list marked as `source=seed`. Those entries looked like real available markets even
though they had not been returned by a live provider.

**Repair:**
- Removed the entire emergency/seed symbol universe from production code.
- The catalog now contains only symbols returned by real public providers or a
  previously persisted real provider cache.
- If neither is available, `/api/futures/symbols` returns an explicit
  `state=unavailable`, an empty list, and a reason.
- Manual symbol entry remains possible for real server-side analysis, but it does
  not imply Futures verification and cannot authorize execution.

### 2. Presentation-only runtime state

**Found:** The sidebar initially declared the execution environment `Online` before
any server status request had succeeded.

**Repair:**
- The initial state is now `Checking`.
- The badge is updated only from `/api/futures/status`.
- A failed status request changes it to `Unavailable`; no optimistic online state
  remains in static HTML.

### 3. Prefilled local user activity

**Found:** New browsers were given a prefilled BTC watchlist and recent-market list,
which looked like existing user activity.

**Repair:**
- Default watchlist is empty.
- Default recent-market history is empty.
- Entries are created only after an actual user selection/action.

### 4. Fabricated account defaults

**Found:** Missing account fields could render as `0` open positions or `paper` mode,
which confused an unavailable response with a genuine zero/real mode.

**Repair:**
- Missing mode and position counts now display `Unavailable`.
- A valid empty positions array still correctly displays `No open Paper positions`.
- Invalid/unavailable position responses are distinguished from a valid empty book.

### 5. Stale chart under a new or unavailable market

**Found:** An old chart could remain visible while a different symbol/interval was
loading or after the new market request failed, making old data appear to belong to
the current market.

**Repair:**
- Candles are cleared whenever symbol, interval, or candle limit changes.
- Structured HTTP 503/unavailable payloads are rendered instead of discarded.
- Generic market errors clear price, funding, open interest, order book, chart, and
  verification fields to explicit unavailable/blocked values.

### 6. Duplicate overlapping market requests

**Found:** Automatic refresh, page visibility, symbol changes, and manual refresh
could overlap and issue duplicate market requests.

**Repair:**
- Market loading is single-flight.
- One pending refresh is coalesced and runs after the active request finishes.
- Request sequence checks prevent an older response from overwriting the currently
  selected symbol/interval.
- Real refresh cadence is displayed in the UI: status 15 seconds, market 30 seconds,
  Telegram 60 seconds.

### 7. Login/session response handling

**Found:** Redirected login HTML or a non-JSON authentication response could be
reported as a generic JSON/API failure.

**Repair:**
- `apiFetch` detects login redirects and expired sessions.
- Non-JSON login pages trigger the real sign-in redirect.
- HTTP status and structured payload are retained on errors so the UI can render
  truthful unavailable states.

### 8. Analysis history timestamps

**Found:** The browser could substitute its own current time as if it were the
server-created plan timestamp.

**Repair:**
- Server `created_at` is preserved when present.
- Browser receipt time is stored separately as `received_at`.
- The UI no longer labels a locally invented time as the server plan creation time.

## Existing V4 functional repairs retained

- DS4 fast request plus one bounded cold-start wake retry.
- External Advisory chain: OpenRouter → Google → Hugging Face.
- HTTP 402 skips the failed provider and continues the chain without retrying the
  same paid/unavailable provider.
- Sanitized provider-attempt diagnostics in the Advisory page.
- Deprecated Hermes `--insecure` startup option removed.
- Empty `max_concurrent_sessions` normalized.
- Eight hash-routed pages with synchronous navigation, Back/Forward, direct hashes,
  keyboard navigation, `hidden`, `inert`, and ARIA state synchronization.
- Paper execution remains server-revalidated and unavailable for unverified markets.

## Real production API bindings verified in source

The production template calls the matching real routes below; it does not generate
market/account responses inside the browser:

- `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`

The corresponding Futures/Telegram routes exist in the backend. Chart diagnostics
are calculated from the returned real candle array; when candles are unavailable,
the diagnostics and chart remain unavailable rather than substituting samples.

## Validation results

- Full local test suite: **108 passed**.
- Python compilation: passed.
- Inline production JavaScript syntax (`node --check`): passed.
- Shell syntax for `scripts/entrypoint.sh`: passed.
- HTML IDs: **119 unique IDs**, no duplicates.
- Static DOM-reference audit: passed.
- All ID-bearing interactive controls have production event handlers.
- Production scan found no seeded catalog, random market generator, mock market
  response, dummy position, or synthetic OHLCV path.
- Populated-secret scan: no production secret value found.
- ZIP integrity check: passed after packaging.
- No Paper, Testnet, or Live trade was executed.
- Paper Execute was not called during verification.

Tests use controlled fixtures/mocks only inside the test directory; those are not
production runtime data paths.

## Files changed in the V5 UI truthfulness pass

- `README.md`
- `hermes_overlay/tools/futures_dashboard_api.py`
- `hermes_overlay/tools/templates/hermes_futures_desk_luxury.html`
- `hermes_overlay/tests/test_futures_dashboard_and_state.py`
- `hermes_overlay/tests/test_luxury_template.py`
- `FIX_REPORT.md`

## Required post-deployment acceptance

After deploying this exact package, perform an authenticated read-only pass on the
Space and verify all eight pages, browser Console/Network, real status/symbol/market
responses, 1m/5m/15m/1h chart states, unavailable-state clearing, Back/Forward, and
mobile overflow. Do not click Paper Execute during that verification.