# v76 Paper Lifecycle Watchdog Pattern

Use when a Hyperliquid/Crypto_Agent strategy has promising synthetic paper results but needs realistic paper evidence before live/shadow promotion.

## Durable lesson

Do not count instant expected-move paper exits as live-readiness evidence. A strategy candidate should persist `open_positions` and only create closed-PnL evidence after a lifecycle exit:

`entry -> open position -> stop_loss / take_profit / trailing_stop / time_exit -> fees/slippage/funding -> MFE/MAE -> net_pnl`

## Runtime pattern

- Keep Mainnet market data read-only and execution local/paper-only.
- On entry, journal `event=entry` and persist per-coin `open_positions` metadata:
  - `entry`, `size`, `stop_loss`, `take_profit`
  - `trailing_stop_pct`, `slippage_pct`, `funding_rate_hourly_pct`
  - `mfe_pct`, `mae_pct`
  - `high_watermark`, `low_watermark`
  - `ticks_held`, `max_hold_ticks`
  - `live_order_allowed=false`, `mainnet_signed_action=false`
- On each tick, update high/low watermarks and MFE/MAE from previous/current mids.
- Keep positions open on ordinary one-tick `time_exit`; only close on:
  - stop loss
  - take profit
  - trailing stop
  - max-hold time exit after `ticks_held >= max_hold_ticks`
- Block same-coin re-entry while `open_positions[coin]` exists.
- If a position closed this tick, block immediate same-tick re-entry for that coin.

## Reporting pattern

Daily reports and supervisor status should show lifecycle evidence separately from legacy synthetic exits:

- `entries`
- `exits`
- `open_positions`
- `open_by_coin`
- `exit_reasons`
- `closed_net_pnl_usd`
- `avg_mfe_pct`, `avg_mae_pct`
- `legacy_synthetic_exits`
- `live_flags`

If `legacy_synthetic_exits` is large and lifecycle `exits=0`, say explicitly that old paper PnL is not real lifecycle evidence yet.

## Supervisor/watchdog pattern

- Script-only watchdog may restart only after verifying mode remains paper-only.
- Supervisor status should include both process identity and lifecycle summary.
- Verify `/proc/<pid>/environ` contains exact strategy env flags such as `CTB_STRATEGY_ID`, `CTB_PAPER_TRADING=true`, and `CTB_DRY_RUN=false`.
- Restarting a paused paper supervisor is acceptable for data collection only; it is not live approval.

## Tests to add

- Strict candidate opens lifecycle entry instead of synthetic exit.
- Same coin cannot reopen while already open.
- Take-profit closes and journals `exit_reason=take_profit`.
- Stop/trailing close paths have explicit tests when present.
- Max hold closes with `exit_reason=time_exit` only after `ticks_held >= max_hold_ticks`.
- Supervisor lifecycle summary detects open coins, exit reasons, PnL, and unexpected live flags.
- Full suite must pass before reporting completion.

## User-facing report shape

For this user's trading-bot work, keep implementation updates operational and concise:

```text
✅ Gebaut:
🧪 Verifiziert:
🚫 Live:
➡️ Nächster Schritt:
```

Always state `paper_only`, `live_order_allowed=false`, and `mainnet_signed_action=false` when relevant.