feat(dx): real-workerd DO test, README + docs/concepts, 3 examples

[drewstone]

Summary

Three days of substrate changes (#28 model-resolution, #29 durable-run supervisor + DO) shipped with no docs and no real-workerd test. This catches the surface up — without over-scoping into a substrate lift.

Test it for real

• @cloudflare/vitest-pool-workers + wrangler.workers.toml + a separate vitest.workers.config.ts — runs SessionSupervisorDO under real workerd with real DurableObjectState, real ReadableStream, real Response. The fake-state Node suite covers the supervisor logic exhaustively; this proves the same host works against the actual Cloudflare runtime.
• Pinned to @cloudflare/vitest-pool-workers ^0.8 — v0.16+ requires vitest 4; pinned to the latest vitest-3-compatible pool.
• The default pnpm test is unaffected: vitest.config.ts excludes tests/workers/**, which only pnpm test:workers runs.

Docs

• README rewrite — the entry-point table now covers every current primitive: durable turn, supervisor + DO, model resolution, defineAgent, durable chat-turn engine, analyst loop, platform clients. New sections for the durable supervisor, DO host wiring (wrangler.toml block), model resolution, defineAgent.
• docs/concepts.md — real mental-model doc: the five layers, the three durability levels (runAgentTask / runDurableTurn / runSupervisedTurn), the SandboxReconnectAdapter contract, model resolution, reading order for new consumers. Replaces the dead src/index.ts JSDoc link.

New examples (3)

All offline-runnable; each in its own dir with a short README.

• examples/model-resolution/ — resolveChatModel (precedence), validateChatModelId (fail-closed admission + allowlist short-circuit), withConfiguredModels.
• examples/durable-supervisor/ — the cross-worker resume keystone: w1 drains 2 of 5 events, lease lapses, w2 resumes from cursor → caller sees the complete sequence exactly once.
• examples/agent-into-reviewer/ — pipe one runtime's stream into a reviewer agent (the "two-runtime" pattern). Reviewer is just an AgentAdapter; no separate framework.

Out of scope (deliberate — would be its own focused PR)

• runAnalystEval lift (the ~1,200 LOC byte-identical analyst-loop.ts duplication across 4 agents). Real, but it's a substrate primitive + multi-repo refactor — should not muddy a docs/test PR.
• parseAgentStream (the 4-5 hand-rolled NDJSON decoders).
• runSimulatedConversation / retire AgentDriver. Different repo.

Test plan

• pnpm typecheck — 0 errors
• pnpm test — 251 passed (17 files)
• pnpm test:workers — 2 passed under real workerd
• pnpm exec biome check src tests examples — clean (1 pre-existing warning)
• pnpm build — green
• All 3 new examples runnable end-to-end via pnpm tsx examples/<dir>/<name>.ts

[tangletools]

Verified. Adds @cloudflare/vitest-pool-workers (pinned to v0.8 for vitest-3 compat) + wrangler.workers.toml + a separate vitest.workers.config.ts so SessionSupervisorDO is exercised under real workerd (real DurableObjectState + ReadableStream + Response). README rewrite covers every current primitive in the entry-point table; docs/concepts.md is a real mental-model doc replacing the dead JSDoc link. Three new offline examples — model-resolution, durable-supervisor (cross-worker resume keystone), agent-into-reviewer (two-runtime pipe pattern) — all runnable. typecheck 0, Node suite 251 green, workerd suite 2 green, biome clean (1 pre-existing warning), build green. Substrate lifts (runAnalystEval, parseAgentStream) deliberately deferred to their own focused PRs.