🐨 KOALA v1.0.0 — Set-and-Forget Trail HODL

The simplest possible Senpi agent. Pick an asset. Fire LONG once. Hold. Forever-ish.

Why this strategy exists

Tortoise is close to "buy and hold" but it has a cadence — every 24h it might buy more. Beaver/Heron/Hummingbird are trend followers — they read the market and decide. Hedgehog holds a basket — multiple decisions. None of them give the user the answer to "I just want to own BTC and have a safety net, and I don't want anything else."

Koala is that answer. One asset, one entry, one stop.

CRITICAL RULES

RULE 1: One asset, configured by the operator

Default is BTC. Operators set asset: "ETH" or asset: "SOL" if they want something else. There's no whitelist scan — Koala doesn't pick.

RULE 2: LONG only, fixed sizing

Margin 50% of equity (default). Leverage 2x (default, max 3x). No scoring, no conviction tiers — the choice to deploy Koala IS the bet.

RULE 3: Fire-once mode is the default

Koala persists a koala-state.json file that records first_entry_at. In fire-once mode (the default), Koala fires exactly one entry per lifetime — even if the DSL eventually exits, the producer stays silent forever after.

Operators who want a cycling deploy (buy / DSL-exits / buy again after a cooldown) can set fireOnceMode: false and a reEntryCooldownHours (default 7 days). Koala then re-enters once the configured cooldown has elapsed since the last detected exit.

RULE 4: Ultra-wide DSL is the entire exit logic

The widest DSL in the catalog:

Component	Setting
max_loss_pct	30% (vs let_winners_run's 20, parabolic_runner's 25)
retrace_threshold	25 (vs parabolic_runner's 18)
consecutive_breaches_required	3 (vs 1-2 elsewhere)
hard_timeout	90d (3 months)
weak_peak_cut	DISABLED
dead_weight_cut	DISABLED
Phase 2 ladder	+20/0 → +50/30 → +100/50 → +200/70 → +500/85

This is deliberately wider than parabolic_runner because Koala's job is to not cut on normal corrections. It only releases on catastrophic reversal or after 3 months.

RULE 5: Producer NEVER closes

DSL owns exits. Always. If the DSL trail trips, the position closes, and (in fire-once mode) Koala never re-enters. In re-entry mode, Koala waits for the cooldown.

How Koala works internally

1. Tick 1 (30 min after deploy): koala-state.json doesn't exist. should_enter returns True. Fires LONG. Writes first_entry_at = now. Records entry.
2. Subsequent ticks while holding: koala-state.json has first_entry_at. The asset is currently in held_assets. Producer outputs HOLDING and does nothing.
3. If the DSL eventually exits (say 60 days in): Position disappears from held_assets. The producer's next tick detects the change, records last_exit_at in state.
4. After exit, fire-once mode: should_enter returns False (because first_entry_at is set). Producer outputs WAITING — fire-once mode AND already entered once. Stays silent forever.
5. After exit, re-entry mode: should_enter returns False until reEntryCooldownHours elapses, then returns True on the next tick.

Scanner pattern

A state-trigger variant of archetype #2 (Single-asset alpha hunter) — see senpi-trading-runtime/references/producer-patterns.md. Unlike Beaver/Heron/Hummingbird/Wolverine which score price action per tick, Koala's "scanner" is a state-file check. No market_get_asset_data call. The pure functions (should_enter, record_entry, record_exit) are unit-tested in tests/test_signal.py.

Operator install

See README.md.

Changelog

v1.0.0 (2026-05-29) — initial release

First fleet agent with no price-side scoring at all. State-file-driven single-shot entry, ultra-wide custom DSL (max_loss 30%, retrace 25, 90d hard_timeout, super-late Phase 2 ladder), fire-once mode by default. Maker-preferred entry (no urgency). Disown-safe launch, 8/8 unit tests covering both fire-once and re-entry-cooldown branches.

License

MIT — Copyright 2026 Senpi (https://senpi.ai).

Skill Attribution

When creating a strategy, include skill_name and skill_version. See references/skill-attribution.md.