polyester-bot 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 natanim-kemal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,274 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="polyester-bot.png" alt="Polyester" width="120" height="120" style="border-radius:50%; object-fit:cover;" />
+
+# Polyester Gap Hunter
+
+**Testnet market-making bot · one position at a time · Telegram alerts · GitHub Actions deploy**
+
+![Python](https://img.shields.io/badge/Python-3.13-blue?logo=python)
+![asyncio](https://img.shields.io/badge/asyncio-trading-2b5f8a?logo=asyncio)
+![systemd](https://img.shields.io/badge/systemd-service-81dafb?logo=systemd)
+![GitHub Actions](https://img.shields.io/badge/deploy-GitHub_Actions-2088ff?logo=github-actions)
+
+</div>
+
+## How it works
+
+```
+scan pairs → find gap → BUY at the bid → ASK under the offer → CYCLE DONE
+```
+
+- **Gap mode** — buys the bid, asks one tick under the offer (maker on both legs).
+  A gap must clear the `0.20%` round-trip fee, so `GAP_MIN_PCT` defaults to `0.21%`.
+- **Volume fallback** — when nothing clears the fee bar, the deepest tightest pair is
+  cycled anyway to keep season volume up.
+- **Bail-out rule** — if more than `BETTER_ASKS_LIMIT` better asks sit under our
+  price for `PERSIST_SECONDS`, the ask is cancelled and re-placed under them
+  (maker exit, even at a loss). It then rests until the rule fires again.
+- **One position** — never stacks trades; the exception is a `>20%` 24h mover.
+- **Volume tracker** — every cycle adds to `volume_state.json`, milestone alert
+  every 10,000 USDT.
+
+## Install
+
+**npm** — the wrapper builds its own Python environment on first run:
+
+```bash
+npm install -g polyester-bot
+polyester-bot setup
+```
+
+**pip** — straight from the release tag:
+
+```bash
+pip install "polyester-bot @ git+https://github.com/natanim-kemal/polyester-bot.git@v1.1.0"
+polyester-bot setup
+```
+
+**source**:
+
+```bash
+git clone https://github.com/natanim-kemal/polyester-bot.git
+cd polyester-bot
+pip install -e .
+polyester-bot setup
+```
+
+Python 3.11 or newer.
+
+## Setup
+
+One command walks you through the credentials and leaves a working `.env` behind:
+
+```bash
+polyester-bot setup
+```
+
+It asks for:
+
+| Question | Where to get it |
+| --- | --- |
+| Polyester API key id (`ak_...`) | Polyester dashboard → API keys |
+| Ed25519 seed (64 hex chars or base64) | the same API key, shown once when you create it |
+| Telegram bot token | [@BotFather](https://t.me/BotFather) → `/newbot` |
+| Telegram chat id | send `/start` to your bot; the wizard finds it, or paste the id |
+| EOA private key | optional, only for the daily paper-asset claim |
+
+The account id is **not** asked for: the wizard signs a `GET /v1/auth/me` with
+your key and derives it. The exchange and Telegram are both checked before
+anything is written, and the wizard sends one test message so you know the
+alerts will arrive.
+
+Credentials land in `~/.polyester-bot/.env` (and in a `.env` next to the bot if
+one is already there), never in the git repository. The bot reads the working
+directory first, then the home copy, so it works from anywhere.
+
+Run the bot the same way:
+
+```bash
+polyester-bot
+```
+
+`POLYESTER_STATE_DIR` moves the working directory somewhere else. The bot trades
+**testnet** funds only.
+
+## Project Structure
+
+```
+├── bot/
+│   ├── monitor.py            # the bot: scanner, executor, bail-out rule
+│   ├── setup.py              # guided setup: ask, check, write the .env
+│   ├── polyester_farm.py     # season volume, daily paper-asset claim
+│   ├── paths.py              # where .env and the state files live
+│   ├── check_orders.py       # print open orders
+│   ├── cancel_all.py         # cancel every open order
+│   ├── status_all.py         # open orders + hot pairs
+│   ├── scan_spread.py        # spread of every pair
+│   ├── big_buy.py            # one-off market buy
+│   ├── hunter_forever.py     # run monitor.py in a loop
+│   ├── kill_bot.py           # stop the bot
+│   └── .env.example          # every setting, no secrets
+├── bin/                      # npm wrapper: polyester-bot, polyester-farm
+├── deploy/
+│   ├── polyester-bot.service    # systemd unit for the bot
+│   ├── polyester-claim.service  # daily paper-asset claim
+│   ├── polyester-claim.timer    # 00:10 UTC, persistent
+│   └── deploy.sh                # install code + units, restart
+├── tests/
+│   ├── test_sell_loop.py        # regression test for the cancel storm
+│   ├── test_freeze_detect.py    # detects a paused sandbox from clock skew
+│   ├── test_paths.py            # .env and state file resolution
+│   ├── test_stuck.py            # a filled buy survives a lagging balance
+│   └── test_setup.py            # the setup wizard and account derivation
+├── .github/workflows/
+│   ├── deploy.yml               # push to main → deploy to the sandbox
+│   └── keepalive.yml            # every 10 min: keep the sandbox awake
+├── pyproject.toml            # the Python package (pip install .)
+├── package.json              # the npm package (npm install -g polyester-bot)
+└── polyester-bot.png
+```
+
+## Configuration
+
+`bot/.env` holds the credentials and tuning; `bot/.env.example` lists every key.
+The real file stays on the machine and is gitignored — a deploy never overwrites it.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `GAP_MIN_PCT` | `0.21` | minimum spread to take in gap mode |
+| `DEPTH_MIN_USD` | `50` | minimum depth on both sides |
+| `SCAN_SECONDS` | `10` | how often to scan for a gap |
+| `POLL_SECONDS` | `2` | how often to manage the open position |
+| `PERSIST_SECONDS` | `60` | how long better asks must persist before the bail-out fires |
+| `BETTER_ASKS_LIMIT` | `2` | how many better asks trigger the bail-out |
+| `BUY_TIMEOUT_SECONDS` | `180` | cancel an unfilled buy after this long |
+| `FREEZE_SECONDS` | `300` | wall-vs-monotonic clock skew that counts as a paused sandbox |
+| `STALL_SECONDS` | `900` | how long the loop may hang before it counts as a pause |
+| `FALLBACK_*` | see example | volume fallback mode |
+| `VOLUME_BASELINE` | `57000` | season volume to start from with no state file |
+
+Alerts go to **Telegram** (every alert) and **Discord** if `DISCORD_WEBHOOK_URL`
+is set. Everything is also printed to the journal.
+
+Every Telegram alert is three lines — the action, the market with its spread,
+then the money:
+
+```
+🟢 BUY
+BTC-USDT | gap 0.85% (net +0.65%) | 0.0123 @ 41,250.00 | depth 12,450.00/12,556.00
+expected +8.20 USDT | USDT 3,094.10 | BTC 0.0123
+```
+
+```
+🔵 ASK
+ARB-USDT | gap 0.118% | 8,946.0 @ 0.167 | bought @ 0.167
+expected +1.21 USDT | USDT 2,983.94 | ARB 8,946.35
+```
+
+`🟡 VOLUME BUY`, `✅ BUY FILLED`, `✅ CYCLE DONE`, `🏆 MILESTONE`, `❄️ FREEZE
+DETECTED` and `⚠️` warnings use the same shape.
+
+## Deploy
+
+Push to `main` → GitHub Actions → SSH → `deploy/deploy.sh` → systemd restart → verify.
+
+| Name | Kind | Value |
+| --- | --- | --- |
+| `INSTABOX_SSH_KEY` | secret | private key with access to the sandbox |
+| `INSTABOX_HOST` | variable | `ssh.instabox.sh` |
+| `INSTABOX_PORT` | variable | `2222` |
+| `INSTABOX_USER` | variable | sandbox user |
+
+Secrets, `.session` and `volume_state.json` are never touched by a deploy.
+
+`keepalive.yml` runs every 10 minutes and opens an SSH session: the sandbox pauses
+itself after 30 idle minutes, and SSH traffic counts as activity, so it stays up.
+It also restarts the bot when its heartbeat file (`/var/tmp/polyester.heartbeat`)
+goes stale, which catches a bot that is alive but wedged.
+
+The bot defends itself as well. A paused sandbox stops the guest clock, so the
+wall clock jumps while the monotonic clock does not; when the bot sees that
+skew (or a loop that hung for minutes), it cancels its **own** stale orders,
+re-reads the balances and re-adopts the real position. If the exchange is
+unreachable it keeps the position it has and retries on the next poll instead
+of trading on stale state.
+
+## Daily claim
+
+`polyester-claim.timer` claims the daily paper asset at **00:10 UTC** with
+`Persistent=true`, so a run missed while the machine was down happens on next boot.
+Whatever it pays out arrives as extra balances, which the bot adopts and sells back
+into USDT before looking for the next gap.
+
+```bash
+systemctl list-timers polyester-claim.timer
+journalctl -u polyester-claim.service
+```
+
+## Tests
+
+`tests/test_sell_loop.py` replays the sell state machine against a fake exchange.
+It reproduces the bug where the bot cancelled the ask it had just placed — the
+`canceling` flag was never cleared once the order reached a terminal state, so
+every re-ask was cancelled again on the next poll.
+
+```bash
+python tests/test_sell_loop.py
+```
+
+Exits non-zero if the bot cancels more than once per bail-out.
+
+`tests/test_freeze_detect.py` pulls the real freeze-detection code out of
+`bot/monitor.py` and drives it: a normal poll does nothing, the real 1h47m
+pause triggers a re-sync, a stalled loop triggers it too, and an unreachable
+exchange keeps the position instead of forgetting it.
+
+```bash
+python tests/test_freeze_detect.py
+```
+
+`tests/test_paths.py` checks where the bot looks for its `.env` and its state
+files: the working directory wins, the script directory is the fallback, and an
+existing state file is never moved.
+
+```bash
+python tests/test_paths.py
+```
+
+`tests/test_stuck.py` replays the bug where a filled buy was invisible because
+the balance lagged behind the order, which froze the bot for hours. It fails on
+the old code and passes on the new.
+
+`tests/test_setup.py` checks the setup wizard: seed formats, the `.env` merge,
+the home copy, and that the bot asks the exchange for its account id instead of
+having one baked in.
+
+All five run in CI on every push, before anything is deployed, together with a
+build of the Python package and a smoke test of its entry point.
+
+## Ops
+
+| Script | What it does |
+| --- | --- |
+| `check_orders.py` | print all open orders with client ids |
+| `cancel_all.py` | cancel every open order |
+| `status_all.py` | open orders plus hot pairs |
+| `scan_spread.py` | print the spread of every pair |
+| `big_buy.py` | buy a fixed notional at market |
+| `hunter_forever.py` | keep `monitor.py` running |
+| `kill_bot.py` | stop the bot processes |
+
+## Remote / Links
+
+- GitHub: [@natanim-kemal](https://github.com/natanim-kemal)
+- Telegram: [@phnatanim](https://t.me/phnatanim)
+- Email: reachnatanim@gmail.com
+
+---
+
+<div align="center">
+
+Built for the <a href="https://polyester.com">Polyester</a> testnet by <a href="https://github.com/natanim-kemal">@natanim-kemal</a>
+
+</div>

package/bin/polyester-bot.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+"use strict";
+
+const args = process.argv.slice(2);
+const target = args[0] === "setup" ? "polyester_bot.setup" : "polyester_bot.monitor";
+
+require("./venv").run(target, args[0] === "setup" ? args.slice(1) : args);

package/bin/polyester-farm.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+require("./venv").run("polyester_bot.polyester_farm", process.argv.slice(2));

package/bin/setup.js

@@ -0,0 +1,75 @@
+"use strict";
+
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const root = path.join(__dirname, "..");
+const venv = path.join(root, ".venv");
+
+function python() {
+  return process.platform === "win32"
+    ? path.join(venv, "Scripts", "python.exe")
+    : path.join(venv, "bin", "python");
+}
+
+function run(cmd, args, label) {
+  const r = spawnSync(cmd, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8"
+  });
+  if (r.status !== 0) {
+    console.error("polyester-bot: " + label + " failed");
+    if (r.stderr) console.error(r.stderr.trim());
+    console.error("Install it by hand:");
+    console.error("  python3 -m venv .venv && .venv/bin/pip install .");
+    process.exit(1);
+  }
+  return r.stdout || "";
+}
+
+function findPython() {
+  const candidates = process.platform === "win32"
+    ? [["py", ["-3"]], ["python", []], ["python3", []]]
+    : [["python3", []], ["python", []]];
+  for (const [cmd, args] of candidates) {
+    const probe = spawnSync(
+      cmd,
+      args.concat(["-c", "import sys; print(sys.version_info >= (3, 11))"]),
+      { encoding: "utf8" }
+    );
+    if (probe.status === 0 && probe.stdout.trim() === "True") {
+      return [cmd, args];
+    }
+  }
+  return null;
+}
+
+function ready() {
+  if (!fs.existsSync(python())) {
+    return false;
+  }
+  return spawnSync(python(), ["-c", "import polyester_bot"], { encoding: "utf8" }).status === 0;
+}
+
+function ensurePython() {
+  if (ready()) {
+    return python();
+  }
+  const found = findPython();
+  if (!found) {
+    console.error("polyester-bot: Python 3.11 or newer is required and was not found.");
+    console.error("Install Python 3.11+, then run: npm rebuild polyester-bot");
+    process.exit(1);
+  }
+  console.log("polyester-bot: setting up the Python environment (takes a minute)...");
+  run(found[0], found[1].concat(["-m", "venv", venv]),
+      "creating the Python environment");
+  run(python(), ["-m", "pip", "install", "--upgrade", "--quiet", "pip"],
+      "upgrading pip");
+  run(python(), ["-m", "pip", "install", "--quiet", root],
+      "installing the bot");
+  return python();
+}
+
+module.exports = { root, venv, python, ensurePython };

package/bin/venv.js

@@ -0,0 +1,12 @@
+"use strict";
+
+const { spawnSync } = require("child_process");
+const { ensurePython } = require("./setup");
+
+function run(moduleName, args) {
+  const py = ensurePython();
+  const r = spawnSync(py, ["-m", moduleName].concat(args), { stdio: "inherit" });
+  process.exit(r.status === null ? 1 : r.status);
+}
+
+module.exports = { run };

package/bot/__init__.py

@@ -0,0 +1 @@
+"""Polyester testnet gap-hunter bot."""

package/bot/big_buy.py

@@ -0,0 +1,75 @@
+"""One-shot: place a full-balance BUY one tick above best bid on BTC-USDT."""
+
+import asyncio
+import os
+import uuid
+from decimal import Decimal, ROUND_FLOOR
+
+from polyester import POLYESTER_TESTNET_ENVIRONMENT, AsyncPolyester
+
+if __package__:
+    from .paths import env_files
+else:
+    from paths import env_files
+
+
+def load_env():
+    for path in env_files():
+        try:
+            with open(path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line and not line.startswith("#") and "=" in line:
+                        k, _, v = line.partition("=")
+                        os.environ.setdefault(k.strip(), v.strip())
+        except OSError:
+            pass
+
+
+load_env()
+
+SYMBOL = "BTC-USDT"
+STEP = Decimal("0.00000001")
+FEE_BUFFER = Decimal("1.0015")
+
+CID = "man1-" + uuid.uuid4().hex[:16]
+
+
+async def main():
+    c = AsyncPolyester(environment=POLYESTER_TESTNET_ENVIRONMENT,
+                       api_key_id=os.environ["POLYESTER_API_KEY_ID"],
+                       api_private_key=os.environ["POLYESTER_ED25519_SEED"],
+                       default_account_id=os.environ["POLYESTER_ACCOUNT_ID"])
+    try:
+        await c.wait_for_catalogs()
+        b = await c.balances.list()
+        usdt = next(a for a in b.balances if a.asset_id == 1)
+        avail = Decimal(usdt.available) / Decimal(10 ** 18)
+
+        book = await c.orderbook.get(symbol=SYMBOL, depth=1)
+        bid = book.bids[0].price.as_decimal()
+        price = bid + Decimal("0.01")
+
+        qty = (avail / (price * FEE_BUFFER)).quantize(STEP, rounding=ROUND_FLOOR)
+        notional = qty * price
+
+        print(f"USDT available : {avail}")
+        print(f"best bid       : {bid}")
+        print(f"order price    : {price}  (bid + 1 tick)")
+        print(f"order qty      : {qty} BTC")
+        print(f"notional       : ~{notional.quantize(Decimal('0.01'))} USDT")
+        print(f"maker fee 0.1% : ~{(notional * Decimal('0.001')).quantize(Decimal('0.01'))} USDT on fill")
+
+        res = await c.orders.batch_create(symbol=SYMBOL, items=[{
+            "symbol": SYMBOL, "side": "buy", "order_type": "limit", "tif": "gtc",
+            "qty": format(qty, "f"), "price": format(price, "f"),
+            "client_order_id": CID,
+        }], request_id="man1-" + uuid.uuid4().hex[:16])
+        for item in res.results:
+            print("RESULT:", item.status, getattr(item, "code", "") or "",
+                  getattr(item, "order_id", ""))
+    finally:
+        await c.aclose()
+
+
+asyncio.run(main())

package/bot/cancel_all.py

@@ -0,0 +1,72 @@
+"""List ALL open orders on the account, cancel everything, verify empty."""
+
+import hashlib
+import json
+import os
+import time
+import urllib.request
+import urllib.error
+
+import nacl.signing
+
+if __package__:
+    from .paths import env_files
+else:
+    from paths import env_files
+
+for path in env_files():
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                k, _, v = line.partition("=")
+                os.environ.setdefault(k.strip(), v.strip())
+
+KEY = os.environ["POLYESTER_API_KEY_ID"]
+sk = nacl.signing.SigningKey(bytes.fromhex(os.environ["POLYESTER_ED25519_SEED"]))
+UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+      "(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36")
+API = "https://api.testnet.polyester.com"
+
+
+def signed(method, path, query="", body=b""):
+    ts = str(int(time.time() * 1000))
+    canon = "\n".join([ts, method.upper(), path, query,
+                       hashlib.sha256(body).hexdigest()])
+    req = urllib.request.Request(API + path + (("?") + query if query else ""),
+                                 data=body or None, method=method)
+    req.add_header("User-Agent", UA)
+    req.add_header("Accept", "application/json")
+    req.add_header("Origin", "https://testnet.polyester.com")
+    if body:
+        req.add_header("Content-Type", "application/json")
+    req.add_header("X-API-KEY-ID", KEY)
+    req.add_header("X-API-TIMESTAMP", ts)
+    req.add_header("X-API-SIGNATURE", sk.sign(canon.encode()).signature.hex())
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            return r.status, json.loads(r.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        return e.code, {"raw": e.read().decode(errors="replace")[:200]}
+
+
+s, before = signed("GET", "/v1/orders/open")
+orders = before.get("orders", []) if isinstance(before, dict) else []
+print(f"open orders BEFORE: {len(orders)}")
+for o in orders:
+    print(" ", o.get("orderId"), o.get("symbol"), o.get("side"), o.get("origQty"),
+          "@", o.get("price"), o.get("status"), o.get("clientOrderId", "")[:14])
+
+if orders:
+    import uuid
+    body = json.dumps({"requestId": "manual-" + uuid.uuid4().hex[:12]}).encode()
+    s, res = signed("POST", "/v1/orders/cancel-all", body=body)
+    print("cancel-all:", s, str(res)[:200])
+    time.sleep(2)
+    s, after = signed("GET", "/v1/orders/open")
+    left = after.get("orders", []) if isinstance(after, dict) else []
+    print(f"open orders AFTER: {len(left)}")
+    for o in left:
+        print(" ", o.get("orderId"), o.get("symbol"), o.get("side"), o.get("status"))
+else:
+    print("nothing open — nothing to cancel")

package/bot/check_orders.py

@@ -0,0 +1,47 @@
+"""One-shot check: list the bot's open BTC-USDT quotes."""
+import hashlib
+import json
+import os
+import time
+import urllib.request
+import urllib.error
+
+import nacl.signing
+
+if __package__:
+    from .paths import env_files
+else:
+    from paths import env_files
+
+for path in env_files():
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                k, _, v = line.partition("=")
+                os.environ.setdefault(k.strip(), v.strip())
+
+KEY = os.environ["POLYESTER_API_KEY_ID"]
+sk = nacl.signing.SigningKey(bytes.fromhex(os.environ["POLYESTER_ED25519_SEED"]))
+UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+      "(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36")
+API = "https://api.testnet.polyester.com"
+
+path, query = "/v1/orders/open", "symbol=BTC-USDT"
+ts = str(int(time.time() * 1000))
+canon = "\n".join([ts, "GET", path, query, hashlib.sha256(b"").hexdigest()])
+req = urllib.request.Request(f"{API}{path}?{query}", method="GET")
+req.add_header("User-Agent", UA)
+req.add_header("Accept", "application/json")
+req.add_header("Origin", "https://testnet.polyester.com")
+req.add_header("X-API-KEY-ID", KEY)
+req.add_header("X-API-TIMESTAMP", ts)
+req.add_header("X-API-SIGNATURE", sk.sign(canon.encode()).signature.hex())
+try:
+    with urllib.request.urlopen(req, timeout=30) as r:
+        data = json.loads(r.read())
+    for o in data.get("orders", []):
+        print(o["side"], o["origQty"], "@", o["price"], o["status"], o["clientOrderId"][:12])
+    print(len(data.get("orders", [])), "open orders")
+except urllib.error.HTTPError as e:
+    print("ERR", e.code, e.read().decode(errors="replace")[:300])

package/bot/hunter_forever.py

@@ -0,0 +1,18 @@
+"""Supervisor: restart the gap hunter whenever it exits (crash, WiFi drop)."""
+
+import os
+import subprocess
+import sys
+import time
+
+if __package__:
+    from .paths import HERE
+else:
+    from paths import HERE
+
+print("[supervisor] gap hunter supervisor started", flush=True)
+
+while True:
+    p = subprocess.run([sys.executable, os.path.join(HERE, "monitor.py")], cwd=HERE)
+    print(f"[supervisor] hunter exited ({p.returncode}); restarting in 10s", flush=True)
+    time.sleep(10)

package/bot/kill_bot.py

@@ -0,0 +1,11 @@
+"""Kill the gap hunter, its supervisor, and any leftover bot processes."""
+import subprocess
+import sys
+
+ps = r"""
+Get-CimInstance Win32_Process |
+  Where-Object { $_.CommandLine -match 'monitor|hunter_forever' -and $_.ProcessId -ne $PID } |
+  ForEach-Object { Write-Output $_.ProcessId; Stop-Process -Id $_.ProcessId -Force }
+"""
+subprocess.run(["powershell", "-NoProfile", "-Command", ps])
+print("done")