refactor: settle on x402-only + deterministic decisions, close CoralOS threads on shutdown

Drops the escrow-gated/LLM-tool-loop settlement path in favor of direct x402 payment
and deterministic bid/award/verify logic (agent/{capability,loop,safety,tools}.ts,
llm/*, bid-review.ts, bid-tools.ts, award-tools.ts, verify-tools.ts, and the
per-agent escrow/arbiter clients are removed; escrow/arbiter Anchor programs remain
deployed as an opt-in building block, not the default flow).

Refreshes docs and code comments across the repo to match: README/CORAL.md/PAY.md/
API.md, the solana-agent-commerce skill references, package.json's description, and
stale in-code comments that still described escrow-gated release or LLM-shaped
output. Deletes LLM.md (described a fully-removed provider-config subsystem).

Adds CoralMcpAgent.closeThread(), wired into startCoralAgent's shutdown handler so a
buyer-agent's market thread is marked closed on SIGINT/SIGTERM instead of just going
quiet - verified live (SIGTERM -> closeThread -> disconnect -> clean exit, no hang).

Verified end-to-end against live TxLINE World Cup data: a full CoralOS round
(WANT -> BID -> AWARD -> PAYMENT_PROOF -> PAYMENT_CONFIRMED -> DELIVERED -> VERIFIED
-> SETTLED) settling a real devnet x402 transfer, rendered correctly in the web UI.

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

Author: trilltino

.env.example

@@ -2,49 +2,22 @@
 
 # ── Wallets (node scripts/setup.js generates these) ───────────────────────────
 
-# Buyer keypair (base58 secret) — signs the escrow deposit/release and the TxLINE subscribe.
+# Buyer keypair (base58 secret) — signs x402 payments and the TxLINE subscribe.
 # Fund it at https://faucet.solana.com (GitHub sign-in; CLI/RPC airdrops are gated).
 BUYER_KEYPAIR_B58=
 
 # Seller keypair (base58 secret) — a distinct party so settlement is a real two-party transfer.
-# It only RECEIVES on release, so it needs no funding. (setup.js generates this.)
+# It only RECEIVES payment, so it needs no funding, UNLESS PROCURE_RAIL=x402 is set (then it also
+# spends on the seller's own upstream procurement leg — see PAY.md). (setup.js generates this.)
 SELLER_KEYPAIR_B58=
 
-# Seller public key — the escrow's payout destination. setup.js sets this to SELLER_KEYPAIR_B58's
-# pubkey. If unset, settle() self-pays the buyer (one-wallet demo; not a real two-party transfer).
+# Seller public key — the x402 payment's payout destination. setup.js sets this to
+# SELLER_KEYPAIR_B58's pubkey. If unset, settle() self-pays the buyer (one-wallet demo; not a real
+# two-party transfer).
 WALLET=
 
-# Arbiter keypair (base58 secret) — the neutral 3rd signer that gates release/refund (the trustless
-# wrapper, examples/txodds/escrow/programs/arbiter). When set, settle() routes through the arbiter so
-# the buyer can't take delivery and refund. Needs only tx-fee funds — the proxy tops it up from the
-# buyer automatically. If unset, settle() falls back to the direct buyer-released escrow. (setup.js generates this.)
-ARBITER_KEYPAIR_B58=
-
 SOLANA_RPC_URL=https://api.devnet.solana.com
 
-# ── LLM brain (the agent's reasoning + delivery) ──────────────────────────────
-
-# 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=
-
-# 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=
-ANTHROPIC_API_KEY=
-
-LLM_PROVIDER=
-LLM_MODEL=
-
 # ── TxLINE (optional) ─────────────────────────────────────────────────────────
 # The proxy subscribes the buyer wallet to the free World Cup tier on its own, so you don't need to
 # set these. `npm run mint` (examples/txodds) writes TXLINE_API_KEY here for the standalone TxLineClient.

API.md

@@ -42,15 +42,13 @@ if (msg.verb === 'BID') {
 | `WANT` | Buyer → thread | Request for a service at a budget. |
 | `BID` | Seller → thread | Price offer for the want. |
 | `AWARD` | Buyer → thread | Selects a seller and confirms price. |
-| `ESCROW_REQUIRED` | Buyer → thread | Requires escrow deposit before delivery. |
-| `DEPOSITED` | Buyer → thread | Confirms escrow deposit with tx signature. |
+| `PAYMENT_REQUIRED` | Seller → buyer | Payment terms for the award — the primary settlement leg, `rail=x402` by default. |
+| `PAYMENT_PROOF` | Buyer → seller | Buyer's signed-but-unsubmitted transfer, bound to the reference. |
+| `PAYMENT_CONFIRMED` | Seller → buyer | Seller submitted + verified the payment on-chain. |
 | `DELIVERED` | Seller → thread | Delivery payload with content hash. |
-| `VERIFY` | Buyer → verifier | Request delivery verification. |
+| `VERIFY` | Buyer → verifier | Request delivery verification (informational — payment already settled). |
 | `VERIFIED` | Verifier → thread | `pass` or `fail` with reason. |
-| `PAYMENT_REQUIRED` | Seller → buyer | Rail-based payment request. |
-| `PAYMENT_PROOF` | Buyer → seller | Payment proof (tx signature, reference). |
-| `PAYMENT_CONFIRMED` | Seller → thread | Payment verified on-chain. |
-| `SETTLED` | System → thread | Round complete. |
+| `SETTLED` | Buyer → thread | Round complete. |
 
 ## Payment Rails
 
@@ -139,50 +137,6 @@ const receipt = toProofReceipt({
 // Write to run ledger
 ```
 
-## LLM Integration
-
-### Basic Completion
-
-```ts
-import { complete } from '@pay/agent-runtime'
-
-const analysis = await complete({
-  system: 'You are a concise analyst. Return structured JSON.',
-  user: JSON.stringify(apiResponse),
-  maxTokens: 512,
-})
-```
-
-### With Model Override
-
-```ts
-const result = await complete({
-  system: 'Summarize this data in one sentence.',
-  user: rawPayload,
-  model: 'gpt-4o-mini',   // overrides LLM_MODEL env var
-  maxTokens: 128,
-})
-```
-
-### Bounded Tool Loop
-
-```ts
-import { runToolLoop, BudgetGuard, StepCounter } from '@pay/agent-runtime'
-
-const outcome = await runToolLoop({
-  system: 'You are a pricing agent. Use the tools to decide on a bid.',
-  tools: [clampPriceTool, submitBidTool],
-  finalTool: 'submit_bid_decision',
-  budget: new BudgetGuard({ maxToolCalls: 8, maxSpendLamports: 0, maxDurationSecs: 30 }),
-  steps: new StepCounter(4),
-  llm: complete,
-})
-
-if (outcome.finalInput) {
-  console.log(outcome.finalInput.bid, outcome.finalInput.priceSol)
-}
-```
-
 ## Policy Enforcement
 
 ```ts
@@ -268,8 +222,8 @@ await coral.postMessage(mention.threadId, formatBid({
 ```ts
 import { createHarness } from '@pay/harness-runtime'
 
-// node-llm adapter: runs deliverService() in-process
-const harness = createHarness('node-llm', {
+// in-process adapter: runs deliverService() in this process
+const harness = createHarness('in-process', {
   deliverService: async (want, cfg) => {
     const data = await fetch('https://api.example.com/data')
     return { payload: await data.json(), contentHash: hash(data) }
@@ -328,7 +282,7 @@ AGENT_NAME = "seller-myservice"
 PERSONA = "myservice"
 SERVICES = "my-api-service"
 FLOOR_SOL = "0.01"
-HARNESS = "node-llm"
+HARNESS = "in-process"
 MY_API_KEY = "${MY_API_KEY}"
 ```
 
@@ -365,19 +319,11 @@ app.get('/api/premium-data', async (req, res) => {
 | `SOLANA_RPC_URL` | agent-runtime | Solana RPC endpoint. Devnet enforced unless `ALLOW_MAINNET=1`. |
 | `BUYER_KEYPAIR_B58` | agent-runtime | Buyer wallet (base58 secret key). |
 | `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 | `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. |
-| `LLM_MODEL` | agent-runtime | Model override. |
+| `SELLER_KEYPAIR_B58` | payment-runtime | Seller's spend key (for x402 upstream procurement). |
 | `CORAL_CONNECTION_URL` | agent-runtime | CoralOS server URL (set by CoralOS at container launch). |
 | `PROCURE_RAIL` | payment-runtime | Set to `x402` to enable upstream procurement. |
 | `PROCURE_X402_URL` | payment-runtime | x402 endpoint URL. |
 | `ALLOW_MAINNET` | agent-runtime | Set to `1` to allow mainnet RPC URLs. |
-| `BID_REVIEW_ENABLED` | harness-runtime | Set to `1` to enable adversarial bid review. |
 
 ## Integration Patterns
 
@@ -403,7 +349,7 @@ const proof = await rail.verifyPayment(request)
 Wire CoralOS agents to any backend:
 
 ```ts
-import { CoralClient, complete, PolicyEngine } from '@pay/agent-runtime'
+import { CoralClient, PolicyEngine } from '@pay/agent-runtime'
 import { createRailRouter } from '@pay/payment-runtime'
 
 const coral = new CoralClient({ url: process.env.CORAL_CONNECTION_URL, agentName: 'seller-api' })

CLAUDE.md

@@ -9,17 +9,21 @@ The repository implements a devnet agent-commerce reference system. Agents coord
 Primary lifecycle:
 
 ```text
-WANT -> BID -> AWARD -> ESCROW_REQUIRED -> DEPOSITED -> DELIVERED -> VERIFIED -> RELEASED | ARBITER_RELEASED
+WANT -> BID -> AWARD -> PAYMENT_REQUIRED -> PAYMENT_PROOF -> PAYMENT_CONFIRMED -> DELIVERED -> VERIFIED -> SETTLED
 ```
 
-The Rust surface is limited to `examples/txodds/escrow`, which contains the escrow and arbiter programs. Most repository code is TypeScript.
+Settlement is x402: the buyer pays the seller directly and finally, before delivery. There is no
+escrow in the default flow — the escrow/arbiter Anchor programs still exist and are deployed
+(`examples/txodds/escrow`), available as an alternative building block, but unused by
+`coral-agents/buyer-agent`/`seller-agent`. The Rust surface is limited to that directory; most
+repository code is TypeScript.
 
 ## Layout
 
 | Path | Purpose |
 |---|---|
-| `packages/agent-runtime/` | LLM shim, Coral MCP client, Solana guard/helpers, market protocol, run ledger, reputation, and policy. |
-| `packages/harness-runtime/` | Seller execution adapter SDK for `node-llm`, `claude-code`, and arbitrary CLI harnesses. |
+| `packages/agent-runtime/` | Coral MCP client, Solana guard/helpers, market protocol, run ledger, reputation, and policy. |
+| `packages/harness-runtime/` | Seller execution adapter SDK for `in-process`, `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, and escrow workspace. |
@@ -77,18 +81,17 @@ The market protocol is owned by `packages/agent-runtime/src/market/protocol.ts`;
 
 ## Agent Orchestration Framework
 
-`packages/agent-runtime/src/agent/` holds capability grants, process-level safety gates
-(`BudgetGuard`/`StepCounter`), a `Tool` contract with an audit-log shape, an evaluation/ranking
-helper, and a bounded provider-agnostic LLM tool-calling loop (`runToolLoop`), available for
-building new Coral-native agents.
+`packages/agent-runtime/src/agent/` holds small scoring/ranking helpers (`rank`/`best`/
+`evaluateDirectionalCall`) for picking the best of several options and grading past calls,
+available for building new Coral-native agents.
 
 ## Payment and Policy
 
 Solana value movement is devnet by default. Runtime helpers reject mainnet RPC URLs unless `ALLOW_MAINNET=1` is set.
 
-Policy checks are centralized in `packages/agent-runtime/src/policy` and cover spend caps, service allowlists, payout binding, award-price binding, rate limiting, and verifier gating.
+Policy checks are centralized in `packages/agent-runtime/src/policy` and cover spend caps, service allowlists, payout binding, award-price binding, and rate limiting — all checked before the buyer signs a payment, since x402 settlement is direct and final and there is no later release step to gate.
 
-Harness processes should not receive signing keys. Agent processes hold wallet authority and call policy before deposits/releases. See `PAY.md` for how the three payment rails (Solana Pay, escrow, x402) are actually used, `CORAL.md` for how the coordination layer works, and `LLM.md` for how LLM-backed decisions are proposed and enforced.
+Harness processes should not receive signing keys. Agent processes hold wallet authority and call policy before every payment. See `PAY.md` for how the three payment rails (x402, Solana Pay, escrow) are actually used and `CORAL.md` for how the coordination layer works.
 
 ## Environment
 
@@ -97,11 +100,8 @@ Common variables:
 | Variable | Purpose |
 |---|---|
 | `BUYER_KEYPAIR_B58` | Buyer funding keypair for devnet transactions. |
-| `ARBITER_KEYPAIR_B58` | Arbiter release/refund keypair. |
 | `WALLET` / `SELLER_WALLET` | Seller payout addresses. |
 | `SOLANA_RPC_URL` | Defaults to devnet if unset. |
-| `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.

CONTRIBUTING.md

@@ -6,16 +6,16 @@ Contributions are welcome. The `main` branch is the integration branch — targe
 
 | Directory | Language | Typical changes |
 |-----------|----------|-----------------|
-| `packages/agent-runtime/` | TypeScript | The runtime: LLM shim, Solana Pay + devnet guard, CoralOS MCP client, the market protocol (incl. VERIFY/VERIFIED), the run ledger + reputation, the policy choke point |
-| `packages/harness-runtime/` | TypeScript | The harness adapter SDK (`node-llm` / `claude-code` / any CLI as sellers) |
+| `packages/agent-runtime/` | TypeScript | The runtime: Solana Pay + devnet guard, CoralOS MCP client, the market protocol (incl. VERIFY/VERIFIED), the run ledger + reputation, the policy choke point |
+| `packages/harness-runtime/` | TypeScript | The harness adapter SDK (`in-process` / `claude-code` / any CLI as sellers) |
 | `examples/txodds/` | TypeScript | The World Cup Oracle — the edge transform, the proxy (+ run grading), the web app, the CoralOS round launcher, the feed server, the research watcher |
 | `examples/txodds/escrow/` | Rust (Anchor) | The escrow + arbiter settlement contracts |
 | `coral-agents/` | TypeScript | The per-session agents: buyer, seller (+ personas), verifier, echo |
 
 ## Prerequisites
 
 - Node.js 20+
-- An LLM key + a funded devnet wallet to run the live demo (see the root README). **The default demo
+- A funded devnet wallet to run the live demo (see the root README). **The default demo
   needs no Docker**; the multi-agent CoralOS round needs Docker (coral-server).
 
 ## Development Commands

CORAL.md

@@ -45,8 +45,8 @@ await startCoralAgent({ agentName: 'my-agent' }, async (ctx) => {
 
 | Agent | Role |
 |---|---|
-| `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. |
+| `buyer-agent` | Creates market thread, sends `WANT`, collects bids, awards, pays directly via x402, and verifies. |
+| `seller-agent` | Bids on supported services, submits + verifies the buyer's x402 payment, runs a harness adapter, and delivers payloads. |
 | `verifier-agent` | Checks delivery hash/structure and replies `VERIFIED pass` or `fail`. |
 
 ### Adding Another Seller
@@ -128,17 +128,20 @@ buyer-agent  -> createThread("market", sellers, verifier)
 buyer-agent  -> WANT round=<n> service=<service> arg=<arg> budget=<sol>
 seller-*     -> BID round=<n> price=<sol> by=<seller>
 buyer-agent  -> AWARD round=<n> to=<seller>
-seller       -> ESCROW_REQUIRED round=<n> reference=<hash> settlement=arbiter
-buyer-agent  -> policy check, then escrow/arbiter deposit
-buyer-agent  -> DEPOSITED round=<n> vault=<vault PDA>
-seller       -> funded escrow check, harness run
+seller       -> PAYMENT_REQUIRED round=<n> rail=x402 amount=<sol> reference=<ref> seller=<addr>
+buyer-agent  -> policy check, then sign (not submit) a transfer
+buyer-agent  -> PAYMENT_PROOF round=<n> rail=x402 reference=<ref> proof=<signed-tx> buyer=<addr>
+seller       -> submit + verify on-chain, harness run
+seller       -> PAYMENT_CONFIRMED round=<n> rail=x402 reference=<ref> paid=true sig=<sig>
 seller       -> DELIVERED round=<n> payload=<json>
 buyer-agent  -> VERIFY round=<n> sha=<hash> ...
-verifier     -> VERIFIED round=<n> verdict=pass|fail
-buyer-agent  -> policy check, then release or leave funds refundable
+verifier     -> VERIFIED round=<n> verdict=pass|fail   (informational - payment already settled)
+buyer-agent  -> SETTLED round=<n> rail=x402 reference=<ref> sig=<sig>
 ```
 
-Solana deposit/release/refund calls happen outside CoralOS. CoralOS carries coordination messages only — see [PAY.md](PAY.md) for settlement details.
+Payment is direct and final: the buyer signs, the seller submits and verifies on-chain — there is no
+escrow, no release step, and no refund path. Solana calls happen outside CoralOS; CoralOS carries
+coordination messages only — see [PAY.md](PAY.md) for settlement details.
 
 ### Protocol Messages
 
@@ -196,17 +199,6 @@ 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
@@ -256,5 +248,4 @@ referencing it as an external plugin instead.
 ## See Also
 
 - [PAY.md](PAY.md) — payment rails and settlement.
-- [LLM.md](LLM.md) — provider config for bid/award/verify decisions.
 - [API.md](API.md) — using the market protocol with any API.