# Hyperliquid copy observation 24h runner pattern

Use when a read-only Hyperliquid copy-research system needs to move from a first manual observation round into a bounded 24h data-collection test.

## Core stance

- The 24h runner is manually started only: no cron, no systemd, no autostart, no restart-on-failure.
- The runner must stay read-only: collector, shadow engine, daily report only.
- No live copy, vault deposits, wallet/API-wallet execution, orders, or signing.
- Runtime logs/status/summary stay outside the repo under `/home/agent/.local/state/CryptoTradingBot/copy_research/reports/observation_runs/`.
- Success is data quality and delta recognition, not profit.

## Minimal implementation shape

Repository artifacts:

- `docs/copy_observation_runbook.md`
- `scripts/run-copy-observation-24h.sh`
- optional report-path helpers in the runtime paths module
- daily report section `24h Observation Run Status`
- focused tests that assert the report renders run status and no-delta language

Runtime artifacts:

- `YYYY-MM-DD_24h.log`
- `YYYY-MM-DD_24h_status.json`
- `YYYY-MM-DD_24h_summary.md`

## Runner requirements

The script should print this banner before doing anything:

```text
READ ONLY OBSERVATION RUN
NO ORDERS
NO VAULT DEPOSITS
NO WALLET EXECUTION
NO SIGNING
DURATION MAX 24H
INTERVAL 2H
```

Loop shape:

1. run read-only safety guard
2. run a code safety grep against copy code and the runner script
3. run collector once
4. run shadow engine once
5. run daily report once
6. write/update status JSON
7. sleep for 2h
8. repeat for 12 cycles or until max duration/tolerance is reached

Use `set -euo pipefail`; on failure, write an aborted status and summary before exiting. Prefer `notify_on_complete` background execution when starting from Hermes so completion is visible without a cron job.

## Daily report run-status fields

Add/update a report section with:

- `run_started_at`
- `last_cycle_at`
- `cycles_completed`
- `expected_cycles_total: 12`
- `wallet_snapshot_count_total`
- `snapshot_count_by_wallet`
- `position_delta_count`
- `shadow_decisions_count`
- `allowed_count`
- `blocked_count`
- `ignored_count`
- `top_block_reasons`
- `data_quality`
- `safety_status`

If there are no deltas yet, explicitly state: "Noch keine Position-Deltas erkannt. Das ist im frühen Beobachtungslauf kein Fehler." Do not frame no deltas as a failure.

## 24h summary report

At completion or abort, write `YYYY-MM-DD_24h_summary.md` with:

- number of cycles completed
- snapshots per wallet
- position deltas
- shadow decisions
- allowed/blocked/ignored counts
- top block reasons
- API problems and data quality
- whether the wallets were active enough
- recommendation: continue observing / replace wallets / expand research

Do not make live trading recommendations. The post-24h decision is about data quality and whether a longer observation with more wallets is justified.

## Verification before starting

Before commit and before starting the 24h run:

```bash
PYTHONPATH=. pytest -q
PYTHONPATH=. python3 -m compileall -q src tests
git diff --check
grep -RInE "create_order|market_open|set_leverage|vaultDeposit|exchange\.order|Account\.from_key|HL_AGENT_PRIVATE_KEY|HL_API_PRIVATE_KEY" src/ctb_copy scripts/run-copy-observation-24h.sh || true
```

Then commit/push code/docs only, verify local and remote SHAs, print safety status, and start the script manually in a tracked background process.