Finish the README audit: buyer, runtime, packages, marketplace

Second pass over the per-package READMEs the top-level sync missed:

- buyer-agent: flow diagram gains the policy gates + VERIFY/VERIFIED leg;
  files table adds wantFeed.ts/reputation.ts; env section documents
  VERIFIER_AGENT, WANT_FEED_URL, REPUTATION_URL, and the POLICY_* knobs
- agent-runtime: module table now lists all six modules (ledger/, policy/)
  and the VERIFY/VERIFIED protocol exports
- packages index: adds harness-runtime
- marketplace: run-ledger paragraph + sibling-market pointers, fixes the
  stale `bash build-agents.sh seller buyer` invocation (script takes one
  arg) and replaces dead `just feed`/`just dashboard` commands (no
  justfile exists) with the real ones

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

Author: trilltino

coral-agents/buyer-agent/README.md

@@ -1,14 +1,21 @@
 # buyer-agent
 
-The marketplace buyer broadcasts a `WANT`, collects competing seller bids, awards the best value, and
-settles the winner through the arbiter-gated escrow by default.
+The marketplace buyer broadcasts a `WANT` (or, in event mode, polls a feed for one), collects competing
+seller bids, awards the best value — weighing each seller's ledger-derived track record when
+`REPUTATION_URL` is set — and settles the winner through the arbiter-gated escrow by default.
+**Every deposit and release passes the policy choke point** (`enforce()` from `@pay/agent-runtime`):
+spend caps, service allowlist, payout binding, award-price binding (a seller can't inflate the escrow
+after winning), rate limit, verifier gate.
 
 ```text
 WANT -> BID* -> AWARD
   -> ESCROW_REQUIRED settlement=arbiter reference=<bound order>
+  -> [policy: caps, payout + award-price binding]
   -> ARBITER_OPENED / DEPOSITED vault=<vault PDA>
-  -> DELIVERED
-  -> ARBITER_RELEASED
+  -> DELIVERED (hash-bound payload)
+  -> VERIFY -> VERIFIED pass|fail        (when VERIFIER_AGENT is set)
+  -> [policy: verifier gate]
+  -> ARBITER_RELEASED   (fail/timeout -> funds stay refundable)
 ```
 
 > **CoralOS docs:** these messages ride Coral threads with `@mentions`
@@ -23,17 +30,30 @@ WANT -> BID* -> AWARD
 
 | File | Role |
 |---|---|
-| `src/index.ts` | Market loop: WANT, bid collection, award, arbiter open, delivery wait, release |
+| `src/index.ts` | Market loop: WANT, bid collection, award, policy-gated deposit, delivery wait, verify, policy-gated release |
 | `src/arbiter.ts` | Arbiter wrapper client: config, vault PDA, open, release |
 | `src/escrow.ts` | Legacy direct base escrow client |
-| `src/guard.ts` | Seller payout binding and legacy payment guards |
+| `src/wantFeed.ts` | Event mode: `fetchNextWant()` — poll the research watcher for the next job |
+| `src/reputation.ts` | `fetchReputationLines()` — the feed's `/api/reputation` folded into the award prompt |
+| `src/guard.ts` | Legacy payout guard (subsumed by the policy choke point's `payout-binding` rule) |
 
 ## Env
 
 `BUYER_KEYPAIR_B58` funds the order. `ARBITER_KEYPAIR_B58` signs arbiter release/refund.
 `SELLER_WALLET` binds the payout wallet. `BUYER_SERVICE` defaults to `txline`, `BUYER_ARG` defaults to
 an `edge <fixtureId>` style request, and `MARKET_SELLERS` controls the competing sellers.
 
+New layers (all optional — unset means the classic loop):
+
+- `VERIFIER_AGENT` + `VERIFY_WINDOW_MS` — hand each delivery to this agent and release **only** on a
+  `VERIFIED pass` ([verifier-agent](../verifier-agent/README.md)); no verdict → funds stay refundable.
+- `WANT_FEED_URL` — event mode: poll this URL for the next job instead of rotating `BUYER_ARGS`
+  (the research market's watcher); empty queue → no WANT, no spend.
+- `REPUTATION_URL` — the feed's `/api/reputation`; sellers' run-ledger track records enter the
+  best-value prompt.
+- `POLICY_MAX_SOL_PER_ROUND`, `POLICY_MAX_SOL_PER_SESSION`, `POLICY_SERVICES`,
+  `POLICY_MIN_INTERVAL_MS` — the choke point's knobs (round cap defaults to the budget).
+
 For best-value bid selection set an LLM key — the kit's LLM is **Venice AI** (`LLM_PROVIDER=venice` +
 `VENICE_API_KEY`; new accounts get $50 free via code `IMPERIAL50` at
 [venice.ai/settings/api](https://venice.ai/settings/api)). `ANTHROPIC_API_KEY`, or `LLM_PROVIDER=openai`

examples/marketplace/README.md

@@ -28,7 +28,7 @@ The escrow program is already deployed to devnet — no `anchor deploy` needed.
 
 ```sh
 (cd examples/txodds && npm run mint)       # one-time: free devnet TxLINE token → .env
-bash build-agents.sh seller buyer          # build the two agent images (sellers reuse the seller image)
+bash build-agents.sh                       # build the agent images (sellers reuse the seller image)
 docker compose up -d coral                 # CoralOS (MCP coordinator)
 cd examples/marketplace && npm install && npm start
 ```
@@ -68,12 +68,20 @@ Watch the auction in a browser instead of the logs — a read-only visualizer (n
 each round's bids, the winner + reasoning, and the escrow settlement with Explorer links:
 
 ```sh
-just feed            # the feed server on :4000 (in another shell)
-just dashboard       # the UI on :5173 → open ?session=<the market session id>
+cd feed && SESSION=<the market session id> npm start   # the feed server on :4000 (another shell)
+npm run marketplace:web                                # from the repo root — the UI on :5173
 ```
 
 It's e2e-tested with fixtures (no devnet needed) — see [`web/`](web/README.md).
 
+The feed also writes every round to the **run ledger** (`runs/<session>/round-<n>/` — want, bids,
+award reasoning, escrow + deposit tx, sha256-bound delivery, verifier verdict, Explorer-linked txs,
+raw transcript), serves `/api/runs` + `/api/reputation`, and **replays a session from disk when
+coral-server is down**. Details: [`feed/`](feed/README.md).
+
+Sibling markets on the same rails: [`../freelancer`](../freelancer/README.md) (harness sellers +
+verifier-gated release) and [`../research`](../research/README.md) (odds events trigger the WANTs).
+
 ## Demo flourishes
 
 - **Drop in a competitor live:** add a fourth seller to `start.ts`'s graph — it bids next round with

packages/README.md

@@ -1,3 +1,9 @@
 # packages
 
-- **[agent-runtime/](agent-runtime/README.md)** — the runtime the agent imports: the LLM provider shim, Solana Pay + devnet guard, a CoralOS MCP client, and the market protocol.
+- **[agent-runtime/](agent-runtime/README.md)** — the runtime the agent imports: the LLM provider
+  shim, Solana Pay + devnet guard, a CoralOS MCP client, the market protocol (incl. VERIFY/VERIFIED),
+  the run ledger + reputation, and the policy choke point.
+- **[harness-runtime/](harness-runtime/README.md)** — the harness adapter SDK: one
+  `HarnessAdapter` interface (`quote`/`run`) so a seller can be a prompt (`node-llm`), headless
+  **Claude Code** (`claude-code`), or any CLI (`HARNESS=cli HARNESS_CMD='hermes {prompt}'`).
+  Harness processes never hold keys. Build after agent-runtime.

packages/agent-runtime/README.md

@@ -20,7 +20,9 @@ Each is a folder under `src/` with its own barrel; the root `src/index.ts` re-ex
 | **LLM** | `complete()` — SDK-free provider shim (**Venice AI** is the kit's LLM; `LLM_PROVIDER` also accepts `openai`/`anthropic`) + `parseJsonReply` | `llm/` (`complete.ts`) |
 | **Solana** | `solanaConnection`/`assertDevnet` (devnet guard), `generatePaymentUrl`/`verifyPayment`/`signTransfer`/`loadKeypairB58` (reference-bound) | `solana/` (`connection.ts`, `pay.ts`) |
 | **CoralOS** | `startCoralAgent(config, run)`, `CoralMcpAgent`, and the `ctx` verbs (`waitForMention`, `waitForAgent`, `reply`, `send`, `createThread`) | `coral/` (`mcp.ts`, `server.ts`) |
-| **Market** | `formatWant`/`parseBid`/`parseAward`/… + `selectBids`/`pickCheapest` — the WANT/BID/AWARD wire protocol (pure) | `market/` (`protocol.ts`) |
+| **Market** | `formatWant`/`parseBid`/`parseAward`/`parseVerify`/`parseVerified`/… + `selectBids`/`pickCheapest` — the WANT/BID/AWARD (+ VERIFY/VERIFIED) wire protocol (pure) | `market/` (`protocol.ts`) |
+| **Ledger** | `writeRun`/`readRun`/`listRuns` — one folder per paid round (hash-bound delivery, verdict, Explorer-linked txs, transcript) + `reputation()` derived from it | `ledger/` (`run.ts`, `store.ts`, `reputation.ts`) |
+| **Policy** | `enforce(action, policy)` + `policyFromEnv` — the choke point every deposit/release passes: spend caps, service allowlist, payout + award-price binding, rate limit, verifier gate | `policy/` (`policy.ts`) |
 
 The runtime is coordination + helpers — it never holds a keypair. Settlement is the escrow contract,
 called agent-side.