# Hyperliquid Copy Observation 7d Supervision Pattern

Use this when extending a successful 24h read-only copy-research observation into a longer 7-day run.

## Trigger

- A bounded 24h copy-observation run completed cleanly: collector OK, data quality OK, read-only guard OK.
- The next step is broader observation, not live copy.
- The user wants daily assurance that the observation is still running and a final report when complete.

## Pattern

1. **Keep the mode read-only**
   - Preserve the existing read-only guard: `read_only=true`, `live_orders=false`, `vault_deposits=false`, `wallet_execution=false`, `signing_enabled=false`.
   - Re-run the safety scan before every collection cycle.
   - Do not introduce cron/systemd that can trade; only schedule status/reporting or a read-only collector.

2. **Expand the runtime watchlist only, not the repo**
   - Store watchlist additions under the runtime state directory, e.g. `~/.local/state/CryptoTradingBot/copy_research/state/watchlist.json`.
   - Third-party leaderboards are discovery only, not ground truth or quality endorsement.
   - Keep notes explicit: `read-only observation only; no copy permission`.
   - Prefer 5-10 enabled wallets for the 7-day pass so the sample is broader without exploding API load.

3. **Use a bounded long runner**
   - 7 days at 2h cadence = 84 cycles.
   - The runner should write:
     - `reports/observation_runs/YYYY-MM-DD_7d.log`
     - `reports/observation_runs/YYYY-MM-DD_7d_status.json`
     - `reports/observation_runs/YYYY-MM-DD_7d_summary.md`
   - Per cycle, run only the established read-only steps:
     ```bash
     PYTHONPATH=. python3 -m src.ctb_copy.run_collector_once
     PYTHONPATH=. python3 -m src.ctb_copy.run_shadow_once
     PYTHONPATH=. python3 -m src.ctb_copy.reports.daily_copy_report
     ```

4. **Status file shape**
   - Include: run id, start time, last cycle time, `cycles_completed`, `expected_cycles_total`, progress percent, enabled wallets, snapshot counts by wallet, shadow decision totals, allowed/blocked/ignored, top reason codes, symbols/leaders observed, latest collector status, data quality, partial errors, and read-only guard.
   - Aggregate from runtime files since the run start day; do not dump raw JSON to the user.

5. **Daily user-facing monitor**
   - Add a script-only cron (`no_agent=true`) that reads the latest `*_7d_status.json` and prints a short plain-language status.
   - Check both status freshness and actual process liveness (`pgrep -af` or equivalent), not status file alone.
   - Mark off-plan when the runner is missing, the last cycle is stale (>~4.5h for a 2h cadence), collector/data quality is not OK, or partial errors exist.

6. **Final evaluation**
   - Schedule a one-shot LLM-backed cron shortly after expected completion.
   - Prompt must be self-contained and constrained to runtime files.
   - Final report should be concise: completed/aborted/running, cycles, wallet/snapshot coverage, allowed/blocked/ignored, top reasons, data quality/API issues, safety confirmation, and clear no-live/continue-read-only/watchlist-adjust recommendation.

## Interpretation rules

- A clean 7-day run proves data-pipeline viability, not copy-trading profitability.
- `allowed` shadow decisions are hypothetical and are not live authorization.
- If most decisions are ignored or blocked, recommend continued read-only research or watchlist adjustment, not live copy.
- If sample size is still small, state that directly. Do not infer edge from a handful of deltas.

## Pitfalls

- **Reporting only the background process completion**: the user asked for daily plan checks; add a separate daily monitor, not just notify-on-complete.
- **Trusting stale status files**: verify actual runner liveness and cycle freshness.
- **Repo pollution**: keep watchlist addresses, runtime reports, logs, and candidate discovery artifacts out of Git.
- **Leaderboard false confidence**: third-party ranks/grades are discovery hints only; Hyperliquid read-only snapshots are the evidence from first observation onward.
- **Raw JSON chat spam**: script-only cron output should be short bullets for the trading topic, not full status objects.