hood-traders 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 nirholas
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,214 @@
+# hood-traders
+
+Autonomous trading agents for **Robinhood Chain** — a live fleet that trades memecoins on NOXA
+and The Odyssey, and watches Stock Token premium/discount against Chainlink, with real signed
+swaps, hard risk caps, and a live decision-journal dashboard.
+
+> ## ⚠ Risk disclaimer
+> This software can autonomously sign and broadcast **real transactions with real funds** when
+> run in live mode. Trading is risky. Strategies here are honestly documented, not guaranteed —
+> **most new memecoin launches go to zero**, thin Stock Token pools can move against you, and
+> software has bugs. Read the [strategy failure modes](#strategies) before funding a wallet.
+> **Paper mode is the default and does not touch real funds.** Live mode requires you to set
+> `HOOD_TRADERS_LIVE=1` **and** provide a funded private key — never enabled by accident. There
+> are no guarantees, no warranty, and no recovery for funds lost to a bug, a bad market, or a
+> misconfigured risk cap. Start in paper mode. Use a wallet you can afford to lose. You are
+> responsible for every transaction this software signs on your behalf.
+
+Built on [`hoodchain`](../robinhood-chain-sdk) — the Robinhood Chain (chain ID 4663) TypeScript
+SDK for Stock Tokens, Chainlink quotes, Uniswap v3 swaps, USDG, and launchpad watchers.
+`hoodkit`/`hood-js` (the wave-2 convenience wrappers) had not shipped at the time this package
+was built, so `hood-traders` talks to `hoodchain` directly — swapping in a wrapper later is a
+drop-in change confined to `src/framework/market.ts`.
+
+## What it does
+
+- **Framework** (`src/framework/`): agent = strategy + wallet + risk budget + journal. Every tick
+  runs observe → decide → simulate (a real Uniswap v3 `eth_call`) → risk-check (fail-closed) →
+  execute → journal.
+- **Three strategies** (`src/strategies/`): `launch-sniper`, `momentum`, `premium-watch` — each
+  with an honestly documented edge hypothesis and failure modes (see [Strategies](#strategies)).
+- **Live dashboard** (`dashboard/`): fleet overview, per-agent equity curve, open positions, the
+  full decision journal (why each trade fired — or didn't), and a kill button.
+- **Risk layer** (`src/framework/risk.ts`): per-agent position cap, daily spend cap, fleet-wide
+  daily spend cap, slippage bound, and cooldown — every one enforced *before* execution, not
+  advisory.
+- **Kill switch** (`src/framework/kill.ts`): SIGINT/SIGTERM, a `KILL` file, or `POST /api/kill` —
+  any of the three halts new orders across the whole fleet immediately. It never force-sells; it
+  only stops taking on new risk.
+
+## Quickstart — paper mode in 5 minutes
+
+Paper mode simulates fills against **live** market data (real Chainlink prices, real Uniswap v3
+quotes) — it is a real simulation, not fake data. No wallet, no key, no config needed.
+
+```bash
+git clone https://github.com/nirholas/hood-traders.git
+cd hood-traders
+npm install
+npm run build
+npm run fleet
+```
+
+Open **http://localhost:4670** — the dashboard is live: fleet equity, per-agent P&L, open
+positions, and the decision journal.
+
+Or with Docker (same result, zero local Node/npm needed):
+
+```bash
+cd hood-traders
+docker compose up --build
+```
+
+### About `hoodchain`
+
+`hood-traders` depends on [`hoodchain`](https://www.npmjs.com/package/hoodchain), the Robinhood
+Chain TypeScript SDK, as a normal published npm dependency (`^0.1.1`) — `npm install` resolves it
+from the registry like any other package. If you're developing the SDK and this fleet together,
+clone [`robinhood-chain-sdk`](https://github.com/nirholas/robinhood-chain-sdk) as a sibling and
+point `package.json` at `file:../robinhood-chain-sdk` for local iteration; revert to the published
+semver before shipping.
+
+## Going live
+
+Live mode signs and broadcasts real transactions. It requires **both**:
+
+```bash
+cp .env.example .env
+# edit .env:
+HOOD_TRADERS_LIVE=1
+ROBINHOOD_CHAIN_PRIVATE_KEY=0x...   # env var only — never hardcode a key
+```
+
+Missing either one keeps the fleet in paper mode — there is no accidental-live path. Every risk
+cap in `.env.example` applies identically in live mode; they are not paper-mode-only guardrails.
+
+**Stock Token trading** additionally requires `HOOD_STOCK_TOKEN_ELIGIBLE=true` — an explicit
+affirmation that you are not a US/Canada/UK/Switzerland person, per the legal restriction on
+these tokenized debt securities (issuer: Robinhood Assets (Jersey) Ltd). Without it,
+`premium-watch` stays alerts-only and any Stock Token swap attempt throws
+`StockTokenEligibilityError`. Memecoin trading (`launch-sniper`, `momentum`) is never gated.
+
+## Architecture
+
+See [`docs/architecture.html`](docs/architecture.html) for the full observe → decide → simulate →
+risk-check → execute → journal diagram, and how the three strategies plug into it. Short version:
+
+```
+Market (hoodchain SDK, live RPC)
+   │
+   ▼
+Strategy.tick(ctx) ──► Decision { intents[], alerts[] }
+   │
+   ▼
+Agent: for each intent
+   1. simulate  — real QuoterV2 eth_call, no state change
+   2. price     — USD notional from the simulated fill
+   3. risk gate — RiskEngine.check(...) — fails CLOSED
+   4. execute   — paper: record the simulated fill
+                  live:  buildSwapTx → approve → sendTransaction → wait for receipt
+   5. journal   — every trade AND every refusal, into SQLite
+```
+
+A strategy can never bypass the risk gate — it proposes intents, the agent enforces every cap
+before anything executes, paper or live.
+
+## Strategies
+
+Full docs with live examples: [`docs/strategies.html`](docs/strategies.html). Summary:
+
+| Strategy | Edge hypothesis (short) | Primary failure mode |
+|---|---|---|
+| `launch-sniper` | Opening-minutes volatility on new launches is real; discipline (round-trip + deployer-concentration filters, mechanical exits) harvests a slice of it. | Most new launches go to zero — the stop loss fires often; this is negative-carry unless winners cover losers. |
+| `momentum` | Tokens that survive to graduation and then break out on price reflect real demand, not launch-day noise. | Breakouts on thin pools are trivially fakeable by one wallet; price-only signal has no depth check. |
+| `premium-watch` | Stock Token pools are thin and drift from the Chainlink oracle; buying the discount captures reversion. **Alerts-only by default** — trading requires explicit eligibility + opt-in. | A premium/discount can be *correct* (DEX reacting to news the ≤24h Chainlink heartbeat hasn't caught yet); fading it loses on purpose. No shorting primitive exists. |
+
+Every strategy exposes its `meta.edge` / `meta.failureModes` at runtime (`strategy.meta`) — the
+dashboard and docs pull the live values, not a stale copy.
+
+## Configuration
+
+All of `.env.example` is optional for paper mode. Key knobs:
+
+| Var | Default | Meaning |
+|---|---|---|
+| `HOOD_NETWORK` | `mainnet` | `mainnet` (4663) or `testnet` (46630) |
+| `HOOD_RPC_URL` | *(viem's public RPC)* | Optional paid RPC (Alchemy recommended for live trading) |
+| `HOOD_TRADERS_LIVE` | `0` | Must be `1` (+ a valid key) to trade real funds |
+| `HOOD_STOCK_TOKEN_ELIGIBLE` | `false` | Non-US-person affirmation gating Stock Token acquisition |
+| `FLEET_MAX_DAILY_SPEND_USDG` | `250` | Hard ceiling across the whole fleet, USD/day |
+| `AGENT_MAX_POSITION_USDG` | `50` | Per-agent, per-token position cap |
+| `AGENT_MAX_DAILY_SPEND_USDG` | `100` | Per-agent daily spend cap |
+| `AGENT_MAX_SLIPPAGE_BPS` | `100` | Per-agent slippage bound (1%) |
+| `AGENT_COOLDOWN_SECONDS` | `60` | Minimum gap between an agent's trades |
+| `KILL_FILE` | `./KILL` | Drop a file here to halt the fleet immediately |
+| `DASHBOARD_PORT` | `4670` | Dashboard + API port |
+
+## Kill switch
+
+Three independent triggers, all wired the same way — any one halts new orders across every agent:
+
+```bash
+# 1. Ctrl-C the process (SIGINT), or `docker compose stop` (SIGTERM)
+
+# 2. Drop the kill file
+touch KILL          # local
+touch data/KILL      # docker (mounted volume)
+
+# 3. HTTP
+curl -X POST http://localhost:4670/api/kill
+```
+
+The kill switch **never force-sells** — it stops new risk, it doesn't unwind existing positions.
+Deciding whether to exit into whatever caused the panic is an explicit operator call.
+
+## Development
+
+```bash
+npm run typecheck     # tsc --noEmit
+npm test               # unit tests — risk, kill switch, journal, strategies, agent (58 tests)
+npm run test:e2e       # live-network E2E — see below
+npm run snapshot        # capture a fresh live market snapshot into tests/snapshots/
+npm run dev              # tsx watch — fleet + dashboard with hot reload
+```
+
+Unit tests never hit the network: strategy logic is tested against **real recorded market
+snapshots** (`tests/snapshots/`, captured with `npm run snapshot`) fed through a scriptable fake
+market, and risk/kill/journal tests are pure logic. `npm run test:e2e` is the one suite that talks
+to live RPCs.
+
+## Deploy
+
+### Docker / Google Cloud Run (preferred)
+
+```bash
+docker build -f Dockerfile -t hood-traders ..   # context = parent dir, see Dockerfile comment
+docker run -p 4670:4670 -v hood-traders-data:/app/data hood-traders
+
+# Cloud Run
+gcloud run deploy hood-traders \
+  --source .. \
+  --dockerfile hood-traders/Dockerfile \
+  --region us-central1 \
+  --port 4670 \
+  --set-env-vars HOOD_NETWORK=mainnet,FLEET_MAX_DAILY_SPEND_USDG=250 \
+  --min-instances 1 --max-instances 1   # single instance — the journal is a local SQLite file
+```
+
+For live trading on Cloud Run, set `HOOD_TRADERS_LIVE` and `ROBINHOOD_CHAIN_PRIVATE_KEY` via
+`--set-secrets` (Secret Manager), never `--set-env-vars`, and mount a persistent volume (Cloud Run
++ a GCS FUSE mount, or migrate the journal to Cloud SQL) so the decision journal survives restarts.
+
+### Vercel
+
+Vercel's serverless functions are not a fit for a long-running tick loop + stateful SQLite
+journal — this is a **long-running process**, deploy it to Cloud Run, Fly.io, Railway, or any
+always-on container host instead.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).
+
+---
+
+Built by [nirholas](https://x.com/nichxbt) · [three.ws](https://three.ws)

package/dashboard/app.js

@@ -0,0 +1,215 @@
+// hood-traders dashboard — vanilla JS, no build step, polls the fleet API.
+
+const POLL_MS = 4000
+const openJournals = new Set()
+
+function fmtUsd(n) {
+  const sign = n < 0 ? '-' : ''
+  return `${sign}$${Math.abs(n).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`
+}
+
+function fmtTime(ts) {
+  if (!ts) return '—'
+  const d = new Date(ts)
+  return d.toLocaleTimeString('en-US', { hour12: false })
+}
+
+function fmtAgo(ts) {
+  if (!ts) return 'never'
+  const s = Math.floor((Date.now() - ts) / 1000)
+  if (s < 5) return 'just now'
+  if (s < 60) return `${s}s ago`
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`
+  return `${Math.floor(s / 3600)}h ago`
+}
+
+async function api(path, opts) {
+  const res = await fetch(path, opts)
+  if (!res.ok) throw new Error(`${path} → ${res.status}`)
+  return res.json()
+}
+
+function sparkline(points) {
+  if (!points || points.length < 2) {
+    return `<div class="no-positions">not enough equity history yet</div>`
+  }
+  const vals = points.map((p) => p.equityUsd)
+  const min = Math.min(...vals)
+  const max = Math.max(...vals)
+  const range = max - min || 1
+  const w = 300
+  const h = 44
+  const step = w / (points.length - 1)
+  const coords = vals.map((v, i) => `${(i * step).toFixed(1)},${(h - ((v - min) / range) * h).toFixed(1)}`)
+  const last = vals[vals.length - 1]
+  const first = vals[0]
+  const color = last >= first ? '#34d399' : '#f87171'
+  return `<svg viewBox="0 0 ${w} ${h}" preserveAspectRatio="none">
+    <polyline fill="none" stroke="${color}" stroke-width="2" points="${coords.join(' ')}" />
+  </svg>`
+}
+
+function renderSummary(summary) {
+  const el = document.getElementById('summary')
+  const tiles = [
+    ['Equity', fmtUsd(summary.equityUsd), summary.equityUsd >= 0 ? 'pos' : 'neg'],
+    ['Realized PnL', fmtUsd(summary.realizedUsd), summary.realizedUsd >= 0 ? 'pos' : 'neg'],
+    ['Open value', fmtUsd(summary.openValueUsd), ''],
+    ['Fleet spend today', `${fmtUsd(summary.fleetSpentTodayUsd)} / ${fmtUsd(summary.fleetMaxDailySpendUsdg)}`, ''],
+    ['Agents', String(summary.agents), ''],
+  ]
+  el.innerHTML = tiles
+    .map(
+      ([label, value, cls]) => `
+    <div class="stat-tile">
+      <div class="stat-label">${label}</div>
+      <div class="stat-value ${cls}">${value}</div>
+    </div>`,
+    )
+    .join('')
+
+  document.getElementById('mode-badge').textContent = summary.mode === 'live' ? '● LIVE' : '◆ PAPER'
+  document.getElementById('mode-badge').className = `badge ${summary.mode}`
+  document.getElementById('network-label').textContent = summary.network === 'testnet' ? 'testnet 46630' : 'mainnet 4663'
+
+  const killedBadge = document.getElementById('killed-badge')
+  killedBadge.hidden = !summary.killed
+  if (summary.killed) killedBadge.textContent = `⛔ killed: ${summary.killReason ?? 'unknown'}`
+
+  const killBtn = document.getElementById('kill-btn')
+  killBtn.disabled = summary.killed
+  killBtn.textContent = summary.killed ? '⛔ Halted' : '⏻ Kill switch'
+}
+
+function renderAgentCard(agent, journal, equity) {
+  const statusClass = agent.killed ? 'killed' : agent.running ? 'running' : ''
+  const isOpen = openJournals.has(agent.id)
+
+  const positionsHtml = agent.positions.length
+    ? agent.positions
+        .map((p) => {
+          const pnl = p.markUsd !== null && p.investedUsd > 0 ? (p.markUsd / p.investedUsd - 1) * 100 : null
+          const pnlStr = pnl === null ? '' : ` · ${pnl >= 0 ? '+' : ''}${pnl.toFixed(1)}%`
+          return `<div class="position-row"><span>${p.tokenSymbol}</span><span>${fmtUsd(p.markUsd ?? p.investedUsd)}${pnlStr}</span></div>`
+        })
+        .join('')
+    : `<div class="no-positions">no open positions</div>`
+
+  const journalHtml = journal.length
+    ? journal
+        .slice(0, 40)
+        .map(
+          (j) => `<div class="journal-row kind-${j.kind}"><span class="journal-time">${fmtTime(j.ts)}</span>${escapeHtml(j.detail)}</div>`,
+        )
+        .join('')
+    : `<div class="journal-row kind-observe">no decisions journaled yet</div>`
+
+  const errorHtml = agent.lastError
+    ? `<div class="error-banner">⚠ ${escapeHtml(agent.lastError)}</div>`
+    : ''
+
+  return `
+  <div class="agent-card">
+    <div class="agent-head">
+      <span class="agent-name">${agent.id}</span>
+      <span><span class="status-dot ${statusClass} ${agent.running && !agent.killed ? 'live-pulse' : ''}"></span></span>
+    </div>
+    <div class="agent-strategy">${agent.strategy} · tick ${agent.ticks} · last ${fmtAgo(agent.lastTickAt)}</div>
+
+    <div class="mini-chart">${sparkline(equity)}</div>
+
+    <div class="agent-metrics">
+      <div class="metric"><div class="metric-label">Equity</div><div class="metric-value">${fmtUsd(agent.equityUsd)}</div></div>
+      <div class="metric"><div class="metric-label">Realized</div><div class="metric-value">${fmtUsd(agent.realizedUsd)}</div></div>
+      <div class="metric"><div class="metric-label">Spent today</div><div class="metric-value">${fmtUsd(agent.spentTodayUsd)} / ${fmtUsd(agent.limits.maxDailySpendUsdg)}</div></div>
+      <div class="metric"><div class="metric-label">Trades / refused</div><div class="metric-value">${agent.trades} / ${agent.refusals}</div></div>
+    </div>
+
+    <div class="positions-list">${positionsHtml}</div>
+
+    <button class="journal-toggle" data-agent="${agent.id}" aria-expanded="${isOpen}">
+      ${isOpen ? '▾' : '▸'} Decision journal (why each trade fired)
+    </button>
+    <div class="journal-list ${isOpen ? 'open' : ''}">${journalHtml}</div>
+    ${errorHtml}
+  </div>`
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))
+}
+
+function renderFleetTrades(trades) {
+  const el = document.getElementById('fleet-trades')
+  if (!trades.length) {
+    el.innerHTML = `<div class="state-block">
+      <div class="state-icon">📭</div>
+      <div class="state-title">No trades yet</div>
+      <div class="state-detail">The fleet is observing live market data. Trades will appear here the moment a strategy's risk-checked intent executes.</div>
+    </div>`
+    return
+  }
+  el.innerHTML = `<div class="agent-card">${trades
+    .slice(0, 30)
+    .map(
+      (t) =>
+        `<div class="journal-row kind-trade"><span class="journal-time">${fmtTime(t.ts)}</span>${t.agentId} ${t.side} ${t.tokenSymbol} — ${escapeHtml(t.reason)}${t.txHash ? ` <a href="#" title="${t.txHash}">↗ tx</a>` : ' (paper)'}</div>`,
+    )
+    .join('')}</div>`
+}
+
+async function refresh() {
+  try {
+    const [summary, agents, trades] = await Promise.all([
+      api('/api/summary'),
+      api('/api/agents'),
+      api('/api/trades'),
+    ])
+    renderSummary(summary)
+
+    const agentsEl = document.getElementById('agents')
+    if (!agents.length) {
+      agentsEl.innerHTML = `<div class="state-block">
+        <div class="state-icon">🤖</div>
+        <div class="state-title">No agents configured</div>
+        <div class="state-detail">Add agents in src/main.ts and restart the fleet.</div>
+      </div>`
+    } else {
+      const withDetail = await Promise.all(
+        agents.map(async (a) => {
+          const [journal, equity] = await Promise.all([
+            api(`/api/agents/${encodeURIComponent(a.id)}/journal`).catch(() => []),
+            api(`/api/agents/${encodeURIComponent(a.id)}/equity`).catch(() => []),
+          ])
+          return renderAgentCard(a, journal, equity)
+        }),
+      )
+      agentsEl.innerHTML = withDetail.join('')
+      agentsEl.querySelectorAll('.journal-toggle').forEach((btn) => {
+        btn.addEventListener('click', () => {
+          const id = btn.dataset.agent
+          if (openJournals.has(id)) openJournals.delete(id)
+          else openJournals.add(id)
+          refresh()
+        })
+      })
+    }
+
+    renderFleetTrades(trades)
+  } catch (err) {
+    document.getElementById('summary').innerHTML = `<div class="state-block" style="grid-column: 1 / -1">
+      <div class="state-icon">⚠</div>
+      <div class="state-title">Can't reach the fleet API</div>
+      <div class="state-detail">${escapeHtml(err.message)} — is the hood-traders process running?</div>
+    </div>`
+  }
+}
+
+document.getElementById('kill-btn').addEventListener('click', async () => {
+  if (!confirm('Trip the global kill switch? This halts all new orders across every agent immediately and cannot be undone for this process.')) return
+  await api('/api/kill', { method: 'POST' })
+  refresh()
+})
+
+refresh()
+setInterval(refresh, POLL_MS)

package/dashboard/index.html

@@ -0,0 +1,44 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>hood-traders — live fleet</title>
+  <meta name="description" content="Autonomous trading agents on Robinhood Chain — live P&amp;L, decision journal, kill switch." />
+  <link rel="icon" href="data:image/svg+xml,%3Csvg%20xmlns%3D%27http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%27%20viewBox%3D%270%200%2032%2032%27%3E%3Cdefs%3E%3ClinearGradient%20id%3D%27g%27%20x1%3D%270%27%20y1%3D%270%27%20x2%3D%271%27%20y2%3D%271%27%3E%3Cstop%20offset%3D%270%27%20stop-color%3D%27%236d5ef8%27%2F%3E%3Cstop%20offset%3D%271%27%20stop-color%3D%27%232fd0e0%27%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Ccircle%20cx%3D%2716%27%20cy%3D%2716%27%20r%3D%2713%27%20fill%3D%27url(%23g)%27%2F%3E%3C%2Fsvg%3E" />
+  <link rel="stylesheet" href="/style.css" />
+</head>
+<body>
+  <div class="wrap">
+    <header class="topbar">
+      <div class="brand">
+        <span class="dot"></span>
+        hood-traders
+        <span id="mode-badge" class="badge">…</span>
+        <span id="killed-badge" class="badge killed" hidden>⛔ killed</span>
+      </div>
+      <div class="topbar-right">
+        <span id="network-label" class="badge">…</span>
+        <button id="kill-btn" class="kill-btn" title="Trip the global kill switch — halts all new orders immediately">
+          ⏻ Kill switch
+        </button>
+      </div>
+    </header>
+
+    <section id="summary" class="summary-grid" aria-label="Fleet summary"></section>
+
+    <h2 class="section-title">Agents</h2>
+    <section id="agents" class="agents-grid" aria-label="Agent fleet"></section>
+
+    <h2 class="section-title">Recent fleet trades</h2>
+    <section id="fleet-trades"></section>
+
+    <footer class="footer">
+      <span>hood-traders · Robinhood Chain (4663 / 46630) autonomous trading fleet</span>
+      <span>Built by <a href="https://x.com/nichxbt" target="_blank" rel="noopener">nirholas</a> · <a href="https://three.ws" target="_blank" rel="noopener">three.ws</a></span>
+    </footer>
+  </div>
+
+  <script src="/app.js" type="module"></script>
+</body>
+</html>