refactor: collapse TxODDS demo to single buyer/seller/verifier, polish live narrative

Simplify the reference kit to its minimal viable loop so it forks cleanly:
- Remove echo-agent, user_proxy (dead/unused), and the seller-base persona
  wrapper; the buyer now launches one seller-agent directly instead of five
  personas multiplexed through a shared registration.
- Remove the sharp-movement/risk-policy seller services, the research-market
  watcher/detector/grading pipeline, and their UI wiring - all downstream of
  the persona collapse and unused without it.
- Modularize buyer-agent's src/ into award/, settlement/, verify/,
  reputation/, and feed/ submodules instead of a flat file list.
- Rewrite the seller's delivery LLM prompt for a colorful two-sentence take
  instead of a clinical one-liner; the live feed's story headline now shows
  that narrative directly instead of a stats-table paragraph, and drops the
  redundant progress-stage tracker in favor of the prose recap.
- Fix seller-agent's manifest missing the x402 procurement options
  (PROCURE_RAIL, PROCURE_X402_URL, SELLER_KEYPAIR_B58) that its own code and
  the round launcher already depended on.

Verified live end-to-end on devnet: WANT -> BID -> AWARD -> ESCROW_REQUIRED ->
DEPOSITED -> DELIVERED -> VERIFIED -> ARBITER_RELEASED, real TxLINE data,
real LLM read, real settlement tx.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: trilltino

.claude/settings.local.json

@@ -3,7 +3,10 @@
     "allow": [
       "Bash(powershell -Command ' *)",
       "Bash(grep -r \"///\" --include=\"*.rs\")",
-      "Bash(cargo check *)"
+      "Bash(cargo check *)",
+      "Bash(node -e ' *)",
+      "Bash(node --input-type=module --check)",
+      "Bash(npm run *)"
     ]
   }
 }

.env.example

@@ -24,13 +24,19 @@ SOLANA_RPC_URL=https://api.devnet.solana.com
 
 # ── LLM brain (the agent's reasoning + delivery) ──────────────────────────────
 
-# This kit's LLM is Venice AI — OpenAI-compatible, with free credits. Create a key at
-# https://venice.ai/settings/api; new accounts get $50 free with redeem code IMPERIAL50 (bottom of that
-# page). Recommended: set both of these.
+# Recommended: Groq — OpenAI-compatible, genuinely free (a renewing per-day/per-minute rate limit,
+# not a one-time credit grant that runs out). Create a key at https://console.groq.com/keys, no card
+# needed. Set both of these:
+#   LLM_PROVIDER=groq
+GROQ_API_KEY=
+
+# Alternative: Venice AI — OpenAI-compatible, free SIGNUP CREDITS (a one-time pool that can run out,
+# unlike Groq's renewing limit). Create a key at https://venice.ai/settings/api; new accounts get $50
+# free with redeem code IMPERIAL50 (bottom of that page).
 #   LLM_PROVIDER=venice
 VENICE_API_KEY=
 
-# Alternatives (no code change) — set LLM_PROVIDER + the matching key:
+# Other alternatives (no code change) — set LLM_PROVIDER + the matching key:
 #   LLM_PROVIDER=openai      → OPENAI_API_KEY=...
 #   LLM_PROVIDER=anthropic   → ANTHROPIC_API_KEY=...
 OPENAI_API_KEY=

API.md

@@ -367,7 +367,8 @@ app.get('/api/premium-data', async (req, res) => {
 | `SELLER_WALLET` | agent-runtime | Seller's receive-only public key. |
 | `SELLER_KEYPAIR_B58` | payment-runtime | Seller's spend key (for x402 procurement). |
 | `ARBITER_KEYPAIR_B58` | payment-runtime | Arbiter authority for escrow release/refund. |
-| `LLM_PROVIDER` | agent-runtime | `venice`, `openai`, or `anthropic`. |
+| `LLM_PROVIDER` | agent-runtime | `groq`, `venice`, `openai`, or `anthropic`. Groq recommended — free, renewing rate limit. |
+| `GROQ_API_KEY` | agent-runtime | Groq API key. |
 | `VENICE_API_KEY` | agent-runtime | Venice API key. |
 | `OPENAI_API_KEY` | agent-runtime | OpenAI API key. |
 | `ANTHROPIC_API_KEY` | agent-runtime | Anthropic API key. |

CLAUDE.md

@@ -9,7 +9,7 @@ The repository implements a devnet agent-commerce reference system. Agents coord
 Primary lifecycle:
 
 ```text
-WANT -> BID -> AWARD -> ESCROW_REQUIRED -> DEPOSITED -> DELIVERED -> VERIFIED -> RELEASED
+WANT -> BID -> AWARD -> ESCROW_REQUIRED -> DEPOSITED -> DELIVERED -> VERIFIED -> RELEASED | ARBITER_RELEASED
 ```
 
 The Rust surface is limited to `examples/txodds/escrow`, which contains the escrow and arbiter programs. Most repository code is TypeScript.
@@ -22,8 +22,8 @@ The Rust surface is limited to `examples/txodds/escrow`, which contains the escr
 | `packages/harness-runtime/` | Seller execution adapter SDK for `node-llm`, `claude-code`, and arbitrary CLI harnesses. |
 | `packages/payment-runtime/` | Rail interface/router, working devnet Solana Pay and escrow rails, scaffold rails, and proof receipts. |
 | `packages/solana-agent-tools/` | Read-only Solana context tools and optional Solana Agent Kit adapter. |
-| `examples/txodds/` | TxODDS proxy, web UI, service implementation, feed server, research watcher, and escrow workspace. |
-| `coral-agents/` | Buyer, seller, verifier, and echo agent containers. |
+| `examples/txodds/` | TxODDS proxy, web UI, service implementation, feed server, and escrow workspace. |
+| `coral-agents/` | Buyer, seller, and verifier agent containers. |
 | `scripts/` | Setup, wallet provisioning, and example runner scripts. |
 
 ## Common Commands
@@ -57,8 +57,7 @@ Key files:
 | `examples/txodds/agent/txline.ts` | TxLINE client. |
 | `examples/txodds/agent/edge.ts` | Verified odds to fair-line analysis. |
 | `examples/txodds/agent/service.ts` | `deliverService()` for paid delivery. |
-| `examples/txodds/server/proxy.ts` | Proxy, settlement endpoints, run persistence, grading. |
-| `examples/txodds/research/watcher.ts` | Odds-move event queue. |
+| `examples/txodds/server/proxy.ts` | Proxy, settlement endpoints, run persistence. |
 | `examples/txodds/escrow/` | Escrow and arbiter Anchor programs. |
 
 `npm run dev` starts the proxy on `:8801` and the static UI on `:3020`.
@@ -101,8 +100,8 @@ Common variables:
 | `ARBITER_KEYPAIR_B58` | Arbiter release/refund keypair. |
 | `WALLET` / `SELLER_WALLET` | Seller payout addresses. |
 | `SOLANA_RPC_URL` | Defaults to devnet if unset. |
-| `LLM_PROVIDER` | `venice`, `openai`, or `anthropic`. |
-| `VENICE_API_KEY` / `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | Provider keys. |
+| `LLM_PROVIDER` | `groq`, `venice`, `openai`, or `anthropic`. Groq is the recommended free default — see `LLM.md`. |
+| `GROQ_API_KEY` / `VENICE_API_KEY` / `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | Provider keys. |
 | `TXLINE_API_KEY` | TxLINE token for TxODDS examples. |
 
 Never commit `.env`, private keys, provider keys, seed phrases, or generated wallet secrets.

CORAL.md

@@ -8,7 +8,7 @@ CoralOS provides multi-agent coordination. Solana payment signing and settlement
 |---|---|---|
 | Runtime | `packages/agent-runtime/src/coral/` | MCP client, tool discovery, agent entrypoint, context helpers. |
 | Protocol | `packages/agent-runtime/src/market/protocol.ts` | Market message formatters/parsers. Coral transports these as strings. |
-| Agents | `coral-agents/` | Buyer, seller, verifier, echo, and user-proxy implementations. |
+| Agents | `coral-agents/` | Buyer, seller, and verifier implementations. |
 | Orchestration | `docker-compose.yml`, `examples/txodds/coral/round.ts` | Start CoralOS and create sessions from agent graphs. |
 | UI/feed | `examples/txodds/feed` | Read extended session state and expose browser-safe APIs. |
 
@@ -48,27 +48,28 @@ await startCoralAgent({ agentName: 'my-agent' }, async (ctx) => {
 | `buyer-agent` | Creates market thread, sends `WANT`, collects bids, awards, deposits, verifies, and releases. |
 | `seller-agent` | Bids on supported services, verifies funded escrow, runs a harness adapter, and delivers payloads. |
 | `verifier-agent` | Checks delivery hash/structure and replies `VERIFIED pass` or `fail`. |
-| `echo-agent` | Minimal connectivity test agent. |
-| `user_proxy` | Idle session participant driven by the puppet API. |
 
-### Seller Personas
+### Adding Another Seller
 
-Seller personas reuse the `seller-agent` Docker image with different manifest values:
+The TxODDS round (`examples/txodds/coral/round.ts`) runs a single `seller-agent`. To add a second,
+competing seller, reuse the `seller-agent` Docker image with a new manifest under its own
+`coral-agents/` directory, overriding just the market identity and pricing:
 
 ```toml
-# coral-agents/seller-worldcup/coral-agent.toml
+# coral-agents/seller-fast/coral-agent.toml
 [agent]
-name = "seller-worldcup"
+name = "seller-fast"
 image = "seller-agent"
 
 [agent.env]
-AGENT_NAME = "seller-worldcup"
-PERSONA = "worldcup-specialist"
+AGENT_NAME = "seller-fast"
+PERSONA = "a fast generalist"
 FLOOR_SOL = "0.0001"
 SERVICES = "txline"
 ```
 
-No new code needed — just a new `coral-agent.toml` directory under `coral-agents/`.
+No new code needed — just a new `coral-agent.toml` directory under `coral-agents/`, and adding it to
+`round.ts`'s agent list so the buyer's `MARKET_SELLERS` includes it.
 
 ### Agent Discovery
 
@@ -81,6 +82,25 @@ localAgents = ["/agents/*"]
 
 Every directory under `coral-agents/` with a `coral-agent.toml` is auto-registered. Nothing needs to be hand-listed.
 
+### Agent Runtimes
+
+Every `coral-agent.toml` can declare `[runtimes.docker]`, `[runtimes.executable]`, or both — CoralOS
+either launches the agent as a container (via the mounted Docker socket) or execs it directly as its
+own child process. `examples/txodds/coral/round.ts`'s `agent()` helper picks per agent:
+
+- **`runtime: 'docker'`** — `buyer-agent` and `seller-agent`. These hold real devnet signing
+  keys, so container process isolation is worth the overhead.
+- **`runtime: 'executable'`** — `verifier-agent`. It holds no key, so there's no isolation to trade
+  away, and coral-server just execs `node dist/index.js` directly — no image, no `docker build`.
+
+The stock `ghcr.io/coral-protocol/coral-server` image has no Node.js (it's `ubuntu:noble` + a minimal
+JRE), so `runtime: 'executable'` needs `docker/coral-server.Dockerfile`'s Node layer to actually work
+— `docker-compose.yml`'s `coral` service builds from that Dockerfile, not the bare upstream image.
+
+This is deliberately not applied to `buyer-agent`/`seller-agent` — moving wallet-holding agents off
+Docker was considered and set aside; see the "Not adopted" note below for the same reasoning applied
+to Coral Cloud.
+
 ## Session Creation
 
 ```ts
@@ -89,7 +109,7 @@ const session = await createSession({
   agentGraphRequest: {
     agents: [
       { name: 'buyer-agent', ... },
-      { name: 'seller-worldcup', ... },
+      { name: 'seller-agent', ... },
       { name: 'verifier-agent', ... },
     ],
   },
@@ -98,7 +118,8 @@ const session = await createSession({
 })
 ```
 
-CoralOS starts one container per graph agent and injects `CORAL_CONNECTION_URL`.
+CoralOS starts each graph agent per its declared runtime (a container, or a direct child process —
+see "Agent Runtimes" above) and injects `CORAL_CONNECTION_URL` either way.
 
 ## Market Flow
 
@@ -130,12 +151,12 @@ import { formatWant, formatBid, parseMarketMessage } from '@pay/agent-runtime'
 const want = formatWant({ round: 1, service: 'txline', arg: 'FIFA World Cup', budgetSol: 0.001 })
 // => "WANT round=1 service=txline arg=FIFA World Cup budget=0.001"
 
-const bid = formatBid({ round: 1, priceSol: 0.0002, by: 'seller-worldcup' })
-// => "BID round=1 price=0.0002 by=seller-worldcup"
+const bid = formatBid({ round: 1, priceSol: 0.0002, by: 'seller-agent' })
+// => "BID round=1 price=0.0002 by=seller-agent"
 
 // Parse incoming messages
-const parsed = parseMarketMessage('BID round=1 price=0.0002 by=seller-worldcup')
-// => { verb: 'BID', round: 1, priceSol: 0.0002, by: 'seller-worldcup' }
+const parsed = parseMarketMessage('BID round=1 price=0.0002 by=seller-agent')
+// => { verb: 'BID', round: 1, priceSol: 0.0002, by: 'seller-agent' }
 ```
 
 ## Extended State and Feed
@@ -175,18 +196,47 @@ npm run dev                  # Probes automatically before launch
 
 Set `CORAL_CONSOLE=0` to skip the probe. Set `CORAL_CONSOLE_REQUIRED=1` to make failures fatal.
 
+## Not Adopted: Coral Cloud LLM Proxy
+
+CoralOS agents can route every model call through **Coral Cloud** (`llm.coralcloud.ai`), a hosted
+OpenAI-compatible proxy, by declaring `[[llm.proxies]]` in `coral-agent.toml` and setting a
+`CORAL_API_KEY`. This repo doesn't use it — LLM calls go straight to Groq/Anthropic/OpenAI/Venice
+(`packages/agent-runtime/src/llm/complete.ts`). That's a deliberate choice, not an oversight: Coral
+Cloud trades this kit's bring-your-own-key flexibility (in particular Groq's free renewing-rate-limit
+path, which the whole kit is built around — see `README.md`) for a dependency on a separate hosted
+account. Worth knowing it exists if you're forking this for a context where a Coral Cloud account is
+already a given.
+
 ## Running
 
 ```sh
 # Single-agent (no CoralOS needed)
 npm run dev
 
-# Multi-agent CoralOS round
+# One-command multi-agent CoralOS round (brings up coral-server + creates a round automatically)
+npm run dev:agentic
+
+# ...or the manual steps dev:agentic wraps, useful if one of them is stuck and you want to isolate which:
 docker compose up -d coral
 bash build-agents.sh
 npm run demo:coral
 ```
 
+### Cleaning Up Agent Containers
+
+Buyer/seller agent containers are **not** docker-compose services — CoralOS launches them dynamically
+per round (one per seller persona, with per-round env), through the Docker socket mounted into the
+`coral` container, so a static compose `services:` entry can't represent them. `docker compose down`
+only stops `coral-server` itself.
+
+```sh
+npm run agents:stop    # force-removes every buyer-agent/seller-agent container, any time
+```
+
+Every new round already does this automatically before it starts (`round.ts`'s `stopPreviousRound()`),
+and `npm run dev:agentic`'s Ctrl+C shutdown handler does it too — the only case you'd run this by hand
+is wanting a clean slate without immediately starting a new round.
+
 ## Claude Code Plugin: `coral-skills`
 
 `.claude/settings.json` pre-registers and enables the official

LLM.md

@@ -1,22 +1,29 @@
 # LLM Provider Configuration
 
-`packages/agent-runtime/src/llm/complete.ts` exposes one SDK-free `complete()` function over `fetch`. Supports Venice, OpenAI, and Anthropic.
+`packages/agent-runtime/src/llm/complete.ts` exposes one SDK-free `complete()` function over `fetch`. Supports Venice, OpenAI, Anthropic, and Groq.
+
+## Which Provider to Use
+
+**Groq is the recommended default for this kit.** It's genuinely free — not a one-time credit grant like Venice's signup bonus, but a renewing per-day/per-minute rate limit, so it doesn't run dry the way Venice credits do. Get a key at [console.groq.com/keys](https://console.groq.com/keys), no card required.
+
+Venice, OpenAI, and Anthropic remain fully supported for anyone with existing keys or who wants a different model — nothing about them changed.
 
 ## Environment Variables
 
 | Variable | Description |
 |---|---|
-| `LLM_PROVIDER` | `venice`, `openai`, or `anthropic`. Set explicitly when more than one key exists. |
-| `VENICE_API_KEY` | Venice API key. |
+| `LLM_PROVIDER` | `groq`, `venice`, `openai`, or `anthropic`. Set explicitly when more than one key exists. |
+| `GROQ_API_KEY` | Groq API key — free, renewing rate limit. |
+| `VENICE_API_KEY` | Venice API key — free signup credits, one-time (can run out). |
 | `OPENAI_API_KEY` | OpenAI API key. |
 | `ANTHROPIC_API_KEY` | Anthropic API key. |
 | `LLM_MODEL` | Optional model override. |
 | `TRACE` | Set to `1` to log provider/model selection and raw replies. |
 
 ```ini
 # .env (gitignored)
-LLM_PROVIDER=venice
-VENICE_API_KEY=...
+LLM_PROVIDER=groq
+GROQ_API_KEY=...
 ```
 
 ## Provider Selection
@@ -26,25 +33,29 @@ VENICE_API_KEY=...
 1. `LLM_PROVIDER` set explicitly → use it.
 2. `OPENAI_API_KEY` exists → OpenAI.
 3. `VENICE_API_KEY` exists → Venice.
-4. Fallback → Anthropic (fails if no key).
+4. `GROQ_API_KEY` exists → Groq.
+5. Fallback → Anthropic (fails if no key).
+
+Auto-detection is a convenience for having exactly one key set; if you have both `VENICE_API_KEY` and `GROQ_API_KEY` in `.env` (e.g. switching over after Venice ran out), set `LLM_PROVIDER=groq` explicitly rather than relying on priority order.
 
 ## Default Models
 
 | Provider | Default Model |
 |---|---|
+| Groq | `llama-3.3-70b-versatile` |
 | Venice | `llama-3.3-70b` |
 | OpenAI | `gpt-4o-mini` |
 | Anthropic | `claude-haiku-4-5-20251001` |
 
 Override with `LLM_MODEL`:
 
 ```ini
-LLM_PROVIDER=venice
-VENICE_API_KEY=...
-LLM_MODEL=kimi-k2-7-code
+LLM_PROVIDER=groq
+GROQ_API_KEY=...
+LLM_MODEL=llama-3.3-70b-versatile
 ```
 
-Venice Kimi models: the runtime raises `maxTokens` requests below `1024` to `1024` (Kimi may consume budget on reasoning before emitting content).
+Venice Kimi models: the runtime raises `maxTokens` requests below `1024` to `1024` (Kimi may consume budget on reasoning before emitting content). Groq has no equivalent quirk.
 
 ## Usage
 
@@ -71,10 +82,10 @@ Every decision follows **propose → enforce**: the model proposes, deterministi
 
 ### Bid Review (Optional)
 
-Set `BID_REVIEW_ENABLED=1` on a seller persona to add a second, independently-prompted loop that can veto a proposed bid. The reviewer has no visibility into the first loop's reasoning.
+Set `BID_REVIEW_ENABLED=1` on the seller to add a second, independently-prompted loop that can veto a proposed bid. The reviewer has no visibility into the first loop's reasoning.
 
 ```toml
-# coral-agents/seller-worldcup/coral-agent.toml
+# coral-agents/seller-agent/coral-agent.toml
 [agent.env]
 BID_REVIEW_ENABLED = "1"
 ```
@@ -95,7 +106,7 @@ Every LLM-backed decision emits an `LlmUse` record into the run ledger:
 ```ts
 {
   round: 1,
-  agent: 'seller-worldcup',
+  agent: 'seller-agent',
   purpose: 'bid-decision',
   status: 'ok',
   provider: 'venice',
@@ -110,9 +121,20 @@ Every LLM-backed decision emits an `LlmUse` record into the run ledger:
 
 When a provider key is absent, invalid, rate-limited, or exhausted, callers either surface the error or use a deterministic fallback. TxODDS UI labels deterministic reads separately from LLM reads.
 
+## Groq Free Tier
+
+No credit card, no expiring credit pool — a renewing rate limit instead. Limits vary by model; roughly, at time of writing:
+
+| Model | Requests/day | Tokens/minute |
+|---|---|---|
+| `llama-3.3-70b-versatile` (default) | 14,400 | 6,000 |
+| `groq/compound` | 250 | 70,000 |
+
+Check [console.groq.com](https://console.groq.com) for current limits per model — Groq adjusts these. If you're hitting the per-minute token cap in a tight bid/verify loop, either switch to a lighter-limit model via `LLM_MODEL`, or fall back to another configured provider for that run.
+
 ## Adding a Provider
 
-All wiring is in `packages/agent-runtime/src/llm/complete.ts`:
+All wiring is in `packages/agent-runtime/src/llm/complete.ts`. `completeGroq()` there is a real, working example of the pattern below — copy it.
 
 1. Add the provider to `LlmProvider`.
 2. Add a default model.

PAY.md

@@ -160,6 +160,11 @@ if (violations.length > 0) throw new PolicyError(violations)
 | `rate-limit` | Deposits closer than `POLICY_MIN_INTERVAL_MS`. |
 | `verifier-gate` | Release without `VERIFIED pass` when verifier is required. |
 
+The x402 upstream-procurement leg (`packages/payment-runtime/src/procure.ts`) is gated separately by
+an `AllowancePolicy` (`packages/payment-runtime/src/policy/spend-policy.ts`): per-call and per-day
+caps, allowed providers/services/currencies, and expiry. This is distinct from the escrow-round policy
+above — it governs what the seller is allowed to *spend upstream*, not what the buyer deposits.
+
 ## Configuration
 
 | Variable | Rail | Notes |