fix(#20 ): heid-bug-hunt fixups — open-world presenter degrade-not-crash (slice-4)

Panel (Gróa+Hulda+Regin, 5/5/5, no false positives) confirmed two 3/3 crash sites where open-world dict reads violate the declared "degrade, never crash the presenter" invariant — the wt adapter tests + the live smoke used full server dicts, so partial/drifted wire responses were never exercised: - FIX (tier3.py _run_define/_run_patch): the CLI hard-indexed the open-world define/patch dicts (`info["agent_id"]` / `["role"]` / `["agent_name"]`), so a partial 2xx → KeyError escaping main()'s exit matrix as a raw traceback (exit 1); and `make_description(info.get("system_prompt", ""))` fed None to .splitlines() on a present-but-null field → AttributeError. Now reads via `_str_field` (absent/ null/non-str → default), degrades role to '?', indexes only a well-formed identity, and maps a no-usable-agent_id 2xx to [api_failed] exit 20 (controlled, not a crash). - FIX (web/server.py _agents_endpoint): the upstream dedup hard-indexed each item (`{a["agent_id"] for a in upstream}` + `_as_dict`), so a malformed item (`[{}]`, `["str"]`, `{"name":…}`, non-str agent_id) or a non-list envelope → 500 before the local fallback merged. Now filters to well-formed mappings first; a non-list upstream degrades to the local-only list. - FIX (wt.py _error_field_from_body): type-check the parsed `field` is a str (the exception surface is `field: str | None`, the CLI prints it) — restores the retired hand-rolled `_extract_error_field` isinstance guard. Held (triaged, no change): the 429→Tier3QuotaExceeded / bare-404→Tier3AgentNotFound maps are ungated-by-error_code BY CONTRACT DESIGN (§ Error map route+status rows; the SDK's ApiError floor drops Retry-After, so retry_after=0 is canonical) — the arms flagged them spec-free; Heid's source-check confirmed intended. Dual-keying define's 429 for full row consistency is an available tightening (contract amendment), surfaced not applied. The persona-endpoint SessionApiFailed gap the arms also caught was already closed in the prior code-review fixup (aed9429). Suite 475 green (+5).
fix(#20 ): heid-code-review fixups — persona-endpoint SessionApiFailed parity (slice-4)
2026-07-19 10:18:36 -07:00 · 2026-07-19 10:13:11 -07:00 · 2026-07-19 09:58:01 -07:00 · 2026-07-19 09:20:18 -07:00 · 2026-07-19 09:13:47 -07:00
19 changed files with 1109 additions and 1069 deletions
@@ -142,6 +142,14 @@ _Archived 2026-07-18._

 _Archived 2026-07-18._

+`[2026-06-17]` **#296 triage sent to worldtree-dev** (`01KVBBH0…`): extraction SUBJECT-INVERSION (promotes assistant prose, drops the user's fact) + META-DESCRIPTION-not-content; verbose-persona aggravator. WAD-vs-bug resolved to BUG (extraction quality), not idle-gating.
+
+_Archived 2026-07-19._
+
+`[2026-06-18]` **Tier-3 memory PROVEN end-to-end live** — `ratatoskr:terse-probe` recalled a seeded user fact in a COLD history-free session (scope_any → 1 hit @ cosine 0.6994). Closes the opening "how far from Tier-3 memory" question for normal agents.
+
+_Archived 2026-07-19._
+
 ## Tried and abandoned (archived)

 The 2026-05-20 → 2026-05-28 cluster: original-build-era foot-guns. Archived 2026-06-18.
@@ -164,7 +164,15 @@ others, they get their own row here — the default is NOT a general "any 404
 | `ApiError(404)` on `sessions.write_history` | `AuthoredHistoryUnavailable` (hide-existence) |
 | `ApiError(422 cursor_invalid)` on `sessions.list` | `InvalidCursor` (dual-key: status 422 AND error_code; the flat cursor body surfaces the code) |
 | `ApiError(502)` on bound `sessions.create` | `BifrostHandshakeFailed` — NOT gated on error_code (unlike list's 422): INV-002, the synchronous handshake is the SOLE bound-502 cause; and the SDK's envelope parser prefers the nested `detail` (which carries `bifrost_error`, not `error_code`), so no distinguishing top-level `error_code` surfaces. The route+status IS the discriminator. |
-| **`ApiError` (any other status/route) — the default** | `SessionApiFailed(status, error_code, body)` |
+| `ApiError(429)` on `agents.define` (slice-4) | `Tier3QuotaExceeded(retry_after=0)` — the SDK's `ApiError` floor carries no response headers, so the `Retry-After` header the hand-rolled path read is unavailable; spec §2675 pins Phase-2.0 quota to `Retry-After: 0`, so the adapter defaults to 0. A non-zero forward-compat value is unrecoverable until the SDK surfaces headers (INFORM wtsdk-dev; reference-impl posture). |
+| `ApiError(403 tier3_user_id_unsupported)` on `agents.define` (slice-4) | `Tier3UserIdUnsupported` (dual-key: status 403 AND error_code) |
+| `ApiError(422 layer_deferred)` on `agents.define` (slice-4) | `Tier3LayerDeferred(field)` — `field` parsed from the body (`detail.field` / flat `field`); the SDK carries `error_code` but not `field`, so the adapter body-parses it (same posture as bound-502's `bifrost_error`) |
+| `ApiError(404)` on `agents.patch` / `agents.delete` (slice-4) | `Tier3AgentNotFound` (route-discriminated; agents CRUD is NOT a hide-existence route — a 404 there IS "no such agent") |
+| `ApiError(422 field_not_mutable)` on `agents.patch` (slice-4) | `Tier3FieldNotMutable(field)` (dual-key status+error_code; `field` body-parsed) |
+| `ApiError(404 persona_not_configured)` on `agents.persona_state` (slice-4) | `PersonaNotConfigured` (dual-key) |
+| `ApiError(404 agent_not_available)` on `agents.persona_state` (slice-4) | `AgentNotAvailable` (the persona-surface `sessions.AgentNotAvailable`, distinct from the eager-turn `sse_client.AgentNotAvailable`; dual-key) |
+| `ApiError(403 auth_scope_denied)` on `agents.persona_state` (slice-4) | `AuthScopeDenied(scope="persona.read")` (dual-key) |
+| **`ApiError` (any other status/route, incl. `agents.list` and any unmatched agent-route code) — the default** | `SessionApiFailed(status, error_code, body)` |

 The default row is load-bearing: any `ApiError` not matched above surfaces as the
 generic `SessionApiFailed` carrying the raw `status`/`error_code`/`body` — the
@@ -206,6 +214,39 @@ re-anchor its coverage-map rows.
   SSE parsing); retire contracts #2/#15; final coverage-map re-anchor; minor bump
   (DEC-6, operator approval).

+### Slice-4 notes (Agents/Tier-3 + `model`→`role` fold, decided at TDD)
+
+- **`model`→`role` cutover folds in here (scope B).** Worldtree spec 1.2 (`v1.0.0b128`,
+  live on :8080/:8081) made the `/agents/define` response echo `role`, closing the
+  old W-4 `model` echo. The adapter returns the SDK's OPEN-WORLD `DefinedAgent` /
+  `PatchedAgent` dicts verbatim (parity posture); callers read `info["role"]`. The
+  frozen `Tier3AgentInfo` dataclass (which read `body["model"]` and would KeyError
+  post-b128) is DELETED — no dataclass normalization layer survives.
+- **`ratatoskr.local_agents` schema bump.** `LocalAgentEntry.model` → `.role` (the
+  field stores what the wire now calls a role); `_SCHEMA_VERSION` 1→2 so any
+  pre-cutover on-disk index is discarded cleanly (no-backwards-compat, DEC-3).
+- **`AgentNotAvailable` name collision.** `sessions.AgentNotAvailable` (persona-state
+  404 `agent_not_available`) and `sse_client.AgentNotAvailable` (eager-turn 409) are
+  distinct types that share a name; `wt` already imports the sse_client one for the
+  stream, so it imports the persona one ALIASED (`PersonaAgentNotAvailable`) and
+  raises it from `get_persona_state`. The web endpoint keeps importing the persona
+  `AgentNotAvailable` from `sessions` (same class), so its `except` is unchanged.
+- **`ConnectFailed` at every rewired caller (slice-3 foot-gun).** The SDK normalizes
+  ANY transport failure to `ConnectFailed(status=0)` (`request.py`), not a raw httpx
+  error. The rewired tier3 CLI and both web endpoints (`_agents_endpoint`,
+  `_persona_state_endpoint`) catch `wtsdk.ConnectFailed` → their existing
+  network-error surface (CLI exit 21 / web 502). The web `test_network_error_returns_502`
+  (respx `httpx.ConnectError` side-effect) is the RED that proves this.
+- **`agents.get(agent_id)`** (SDK `GET /agents/{id}`) is NOT wrapped — ratatoskr has no
+  `get_agent` consumer; only list/persona_state/define/patch/delete are in coverage.
+- **Client-side Tier-3-id PRE on `patch_agent` / `delete_agent`.** Both assert
+  `":" in agent_id` pre-HTTP (a Tier-3 id is always `<user_id>:<agent_name>`, ADR-0019),
+  so a non-colon id fails fast with an `AssertionError` rather than reaching the SDK's
+  route-discriminated 404 → `Tier3AgentNotFound`. Intentional fail-fast on a
+  wrong-shaped id (carried over from the retired hand-rolled wrappers); documented here
+  per the heid-code-review slice-4 precision flag (the § Error map 404 rows assume a
+  well-formed Tier-3 id reaches the route).
+
 ## Out of scope

 - Bifrost PROVIDER planes (memory/affect) — hand-rolled, ADR-0009, untouched.
@@ -89,11 +89,11 @@ sub-gap).
 | `POST /sessions/{id}/history` (authored-history-write, #347) | ✅ | `wt.py` `write_authored_history` (SDK `sessions.write_history`) → `cli.py` `--seed-first-message`, `first_message.py` `seed_preset_first_message` (create-path seed) | **wt-adapter re-anchored (slice-3, #20)** — SDK owns the entry shape; v1 author=assistant; 404→AuthoredHistoryUnavailable (hide-existence, route is the discriminator, never probe); 409/422→SessionApiFailed default. **LIVE-SMOKE 2026-07-19** on personal :8081 (b128): `--seed-first-message` on a sindra session → **201** (seq=0, phase=seeded, turn_id=2294) → read-back verbatim; create-path preset seed observed via `--new`. (Prior 2026-07-06 hand-rolled proof superseded.) |
 | `GET /sessions/{id}/messages` (history) | ✅ | `wt.py` `get_session_messages` (SDK `sessions.messages`) → `cli.py` `--seed-first-message` read-back, `web/server.py` messages proxy | **wt-adapter re-anchored (slice-3, #20)** — the #347 seed read-back; open-world passthrough. **LIVE-SMOKE 2026-07-19**: read-back rendered the seeded seq-0 turn as a plain role=assistant message (model-invisible provenance confirmed) |
 | `POST /sessions/{id}/turns/{turn_id}/cancel` | ✅ | `wt.py` `cancel_turn` (SDK `sessions.cancel_turn`) → cli/web | **wt-adapter re-anchored (slice-2, #20)** — two-stage Ctrl-C; 404→CancelTurnNotFound, 409→CancelAlreadyCompleted, late-cancel 200 (`cancelled=False`) is a benign result, not an error |
-| `GET /agents` | ✅ | `sessions.py:341` → `tui.py:1472`,`web/server.py:100` | Tier-1 roster; merged with local index |
-| `GET /agents/{id}/persona_state` | ✅ | `sessions.py:384` → `tui.py:1132`,`web/server.py:386` | persona hydrate; 404/403 mapped |
-| `POST /agents/define` | ✅ | `tier3.py:175` → `_run_define` | Tier-3 create |
-| `PATCH /agents/{id}` | ✅ | `tier3.py:219` → `_run_patch` | Tier-3 mutate (system_prompt/model) |
-| `DELETE /agents/{id}` | ✅ | `tier3.py:242` → `_run_delete` | Tier-3 hard-delete |
+| `GET /agents` | ✅ | `wt.py` `list_agents` (SDK `agents.list`) → `web/server.py` `_agents_endpoint` | **wt-adapter re-anchored (slice-4, #20)** — open-world array verbatim (no AgentInfo normalization), merged with the local tier3 index (remote-wins); error→SessionApiFailed default, transport→ConnectFailed→502. **LIVE-SMOKE 2026-07-19** on personal :8081 (b128): 6 agents returned (forseti/lofn/mask/mimir/vili/…) |
+| `GET /agents/{id}/persona_state` | ✅ | `wt.py` `get_persona_state` (SDK `agents.persona_state`) → `web/server.py` `_persona_state_endpoint` | **wt-adapter re-anchored (slice-4, #20)** — open-world snapshot; dual-key (status,error_code) map: 404 persona_not_configured→PersonaNotConfigured, 404 agent_not_available→AgentNotAvailable, 403 auth_scope_denied→AuthScopeDenied, else default. **LIVE-SMOKE 2026-07-19**: a tier3 agent → correctly mapped `PersonaNotConfigured` (route+code adapter proven) |
+| `POST /agents/define` | ✅ | `wt.py` `define_agent` (SDK `agents.define`) → `tier3.py` `_run_define` | **wt-adapter re-anchored (slice-4, #20)** — sends AgentDefineInput `{agent_name,role,system_prompt}`, returns open-world `DefinedAgent` (echoes `role`, b128); slug pre-validated; 429→Tier3QuotaExceeded(retry_after=0, header-less floor), 403→Tier3UserIdUnsupported, 422 layer_deferred→Tier3LayerDeferred. **LIVE-SMOKE 2026-07-19**: `define --role thoughtful-character` → `defined ratatoskr:slice4-smoke (thoughtful-character)` |
+| `PATCH /agents/{id}` | ✅ | `wt.py` `patch_agent` (SDK `agents.patch`) → `tier3.py` `_run_patch` | **wt-adapter re-anchored (slice-4, #20)** — Tier-3 mutate (system_prompt/**role**, model→role folded in); 404→Tier3AgentNotFound, 422 field_not_mutable→Tier3FieldNotMutable. **LIVE-SMOKE 2026-07-19**: `patched ratatoskr:slice4-smoke`; a non-existent id via `python -m` → `[agent_not_found]` (exit 20, class-identity fix proven) |
+| `DELETE /agents/{id}` | ✅ | `wt.py` `delete_agent` (SDK `agents.delete`) → `tier3.py` `_run_delete` | **wt-adapter re-anchored (slice-4, #20)** — 204→None; 404→Tier3AgentNotFound (route-discriminated, NOT hide-existence). **LIVE-SMOKE 2026-07-19**: `deleted ratatoskr:slice4-smoke` + local index → `[]` |
 | `GET /me` | ✅ | `sessions.py:411` `get_me` → `cli.py` `--whoami` | identity/whoami probe; 401→SessionApiFailed |
 | `GET /capabilities` | ✅ | `sessions.py` `get_capabilities` → `cli.py` `--whoami` | Echo ephemeral-template discovery. **v0.21.2: `--whoami` renderer reads `allowed_roles`/`default_role`** (was the dead `allowed_models`/`default_model`) + tolerates malformed caps; matches conversation-api-spec **v1.1** (`b4a278c`) |
 | `GET /sessions/{id}/tools` | ✅ | `sessions.py:411` `get_session_tools` → `tui.py` `_hydrate_session_tools` | owner-scoped tool inventory in the TUI Tools pane (#183) |
@@ -0,0 +1,66 @@
+# worldtree-sdk cutover — SLICE-3 complete (2026-07-19)
+
+Slice-3 of the #20 consumer-layer cutover: **persona + authored-history +
+first-message** migrated onto the `ratatoskr.wt` adapter, and the last
+hand-rolled `sessions.py` paths retired. Two commits: `ca9a339` (feat) +
+`fc256bb` (heid-bug-hunt fixups), tags v0.21.11 / v0.21.12. Suite **469 green**.
+
+## What moved / what was deleted
+
+- **`wt.set_persona_state`** — passes 3 PAD axes; SDK owns the `{"pad": {…}}` wire
+  (#317) via `PadState`. No route-specific error row → `SessionApiFailed` default.
+  Finiteness enforced at the adapter precondition (chokepoint) AND the CLI.
+- **`wt.write_authored_history`** — SDK `write_history`; v1 fixes `author="assistant"`
+  (dropped the unused `author`/`effects`/`claimed_original_at` params — no caller
+  used them, and a 3-key literal type-checks against the SDK's private
+  `AuthoredHistoryInput` without importing a non-public symbol). 404 →
+  `AuthoredHistoryUnavailable` (hide-existence; the ROUTE is the discriminator,
+  never the body); else the default.
+- **`first_message.seed_preset_first_message`** — now takes a `WorldtreeClient`,
+  routes through `wt.write_authored_history`; best-effort invariants (INV-001..004)
+  unchanged. Tests rewritten to drive a fake `WorldtreeClient` (the wire is the
+  SDK's to prove via its parity corpus, not first_message's).
+- **CLI `--set-persona-pad` / `--seed-first-message`** + the `_amain` and web
+  create-path first-message seeds rewired onto the adapter.
+- **DELETED from `sessions.py`**: `create_session` + `SessionInfo`,
+  `set_persona_state`, `write_authored_history`, `get_session_messages`,
+  `_bifrost_error_from`. (The exceptions + `BifrostBinding` + `AgentInfo` +
+  slice-4/5/6 functions stay.)
+
+## Live-smoke (INV-CUT-5, personal :8081 b128)
+
+`--seed-first-message` → 201 (seq=0, phase=seeded) → read-back verbatim;
+`--set-persona-pad 0.4,0.1,-0.2` → 204; `--new` create-path preset seed observed
+routing through the adapter. All three route families proven end-to-end.
+
+## Both heid gates cleared
+
+- **heid-code-review (panel, cutover contract):** ZERO code-vs-contract drift, all
+  three arms. Regin's 3 secondary items all self-graded `accept` (non-slice-3
+  routes / web-not-unit-tested / slice-2 stream test) — correctly declined.
+- **heid-bug-hunt (panel):** earned its keep — caught **a real regression I shipped
+  in `ca9a339`**: when the two CLI probes moved off raw httpx onto the adapter,
+  transport failures changed class — the SDK normalizes ANY pre-response transport
+  failure to `worldtree_sdk.ConnectFailed` (`request.py:196`), a `WorldtreeError`
+  (not `ApiError`), so it escaped the adapter unmapped AND the probes' httpx-only
+  `except` tuples → uncaught traceback instead of `[network_error]` exit 21.
+  `_amain` (slice-2) already handled it; the probes lagged. **Fix:** add
+  `ConnectFailed` to both probe tuples (live-verified at a refused host → exit 21).
+  Second finding (3/3): finite-PAD enforced only at the CLI, not the adapter
+  chokepoint → **fix:** adapter precondition assert. Declined (correctly): deleted
+  `sessions.py` exports (intended no-shim cutover, zero un-migrated importers),
+  `session["session_id"]` index (accept-known-risk, matches `--new`), Regin's
+  "web hangs forever" (refuted by Heid from source — the seed is `wait_for`-bounded).
+
+## Foot-gun banked
+
+**The SDK wraps ALL transport failures into `ConnectFailed(status=0)`** (not raw
+httpx). Every ratatoskr caller that goes through the adapter must `except
+ConnectFailed` on its network path — the httpx-only catches are now dead. This bit
+the slice-3 probes; watch for it in slice-4+ call-site rewires.
+
+## Next
+
+Slice-4 (agents/Tier-3 — list/get/define/patch/delete/persona_state) which FOLDS
+the pending `model`→`role` cutover ([[project-tier3-agents-model-to-role-pending]]).
+See [[2026-07-19-worldtree-sdk-cutover-slice-1-2-complete]] for the slice-1+2 arc.
@@ -46,30 +46,28 @@ upstream API key stays server-side (INV-003).

 _As of 2026-07-19:_

-**🔨 ACTIVE MIGRATION — worldtree-sdk cutover (issue #20): SLICE-1 + SLICE-2 COMPLETE + PUSHED, slice-3 next.**
+**🔨 ACTIVE MIGRATION — worldtree-sdk cutover (issue #20): SLICE-1 + SLICE-2 + SLICE-3 COMPLETE, slice-4 next.**
 Operator ruled ADOPT (2026-07-18): ratatoskr cuts its CONSUMER client layer over to **worldtree-sdk (Python)
 1.0.0**, retiring the hand-rolled httpx wrappers behind a thin `ratatoskr.wt` adapter. Design locked (6 DECs,
-vor-cross'd, heid-panel-reviewed); contract `docs/contracts/worldtree_sdk_cutover.contract.md`. **SLICE-1
-(adapter foundation) ✅ + SLICE-2 (sessions/turn) ✅ DONE + PUSHED** — origin at `aba1730` (12-commit arc
-`b1fbadd`→`aba1730`, tags v0.21.3–.10, pushed 2026-07-19): adapter (`b907a7b`, all 6 route families
-create/list/messages/tools/stream/cancel + the § Error-map mapping) → CLI rewire (`e3a10ad`) → web rewire
-(`5c595b8`) → orphan deletion (`59602fe`, sse_client 714→224 + sessions 677→608; DEC-4 LIVE-SMOKE PASSED on
-:8081 create+stream+cancel FIRST) → heid-code-review fixup (`74d41eb`) → heid-bug-hunt fixup (`aba1730`).
-Suite **497 green**. **KEY ADAPTER FACTS (foot-guns for slices 3-7):** the SDK returns **open-world dicts**
-(not typed objects) for session reads → presenters read mappings, `info["session_id"]`; SDK events
-(`TurnEvent`) carry `sse_id: str` + a **body-derived `turn_id` that's ABSENT on text/thinking frames** → parse
-the cancel target's turn from the composite `sse_id`, NOT `event.turn_id`; the SDK **normalizes transport
-failures to `ConnectFailed(status=0)`** (not raw httpx) → presenters catch it; the adapter re-wraps SDK stream
-errors → ratatoskr caller-semantic exceptions (DEC-2, keep ratatoskr's typed exceptions); `consumer_key` is
-BOUND-create-only (adapter nulls it when unbound, else the SDK auths as the consumer); the SDK's error-envelope
-parser **prefers the nested `detail`** so a top-level `error_code` doesn't surface (why create's bound-502 is
-NOT gated on error_code, unlike list's 422). **NEXT = slice-3** (persona `set_persona_state` + authored-history
-`write_history` + first_message presets — retires the still-hand-rolled `create_session`/`get_session_messages`
-that the `--seed-first-message` probe uses); then slice-4 (agents/tier3, FOLDS the `model`→`role` cutover),
-slice-5 (characters/me/caps), slice-6 (admin — `stream_admin_events`+`get_session_bifrost` still hand-rolled),
-slice-7 (teardown: retire contracts #2/#15, drop `httpx-sse`, minor bump per DEC-6 w/ operator approval).
-Scope: consumer layer ONLY; Bifrost provider planes untouched. Full design → auto-memory
-`project_worldtree_sdk_cutover`.
+vor-cross'd, heid-panel-reviewed); contract `docs/contracts/worldtree_sdk_cutover.contract.md`. **SLICE-1+2
+(foundation + sessions/turn) ✅ PUSHED** origin `aba1730` (arc `b1fbadd`→`aba1730`, tags v0.21.3–.10). **SLICE-3
+(persona + authored-history + first-message) ✅ DONE** — `ca9a339` (feat) + `fc256bb` (heid-bug-hunt fixups),
+tags v0.21.11–.12; full House Code Discipline (TDD → heid-code-review CLEAN/zero-drift → heid-bug-hunt).
+Suite **469 green**. Slice-3 migrated `set_persona_state` (SDK `PadState`), `write_authored_history`
+(`write_history`, 404→AuthoredHistoryUnavailable hide-existence), `get_session_messages`, + routed
+`first_message` seed through the adapter; DELETED the last hand-rolled `sessions.py` paths (`create_session`+
+`SessionInfo`, `set_persona_state`, `write_authored_history`, `get_session_messages`, `_bifrost_error_from`).
+LIVE-SMOKE on :8081 (b128): seed→201(seq0)→read-back; persona→204; create-path preset seed. **KEY ADAPTER FACTS
+(foot-guns for slices 4-7):** SDK returns **open-world dicts** for reads → `info["session_id"]`; `TurnEvent`
+carries `sse_id` + a **`turn_id` ABSENT on text/thinking frames** → parse cancel-target from `sse_id`; the SDK
+**normalizes ANY transport failure to `ConnectFailed(status=0)`** (`request.py:196`, NOT raw httpx) — every
+caller through the adapter must `except ConnectFailed` (the slice-3 bug-hunt caught both probes missing it);
+`consumer_key` is BOUND-create-only; the SDK's envelope parser **prefers nested `detail`** (why bound-502 isn't
+error_code-gated). **NEXT = slice-4** (agents/tier3 — list/get/define/patch/delete/persona_state, FOLDS the
+`model`→`role` cutover); then slice-5 (characters/me/caps), slice-6 (admin — `stream_admin_events` +
+`get_session_bifrost` still hand-rolled), slice-7 (teardown: retire contracts #2/#15, drop `httpx-sse`, minor
+bump per DEC-6 w/ operator approval). Scope: consumer layer ONLY; Bifrost provider planes untouched. Full
+design → auto-memory `project_worldtree_sdk_cutover`.

 **⏸️ DEFERRED — tier3 agents `model`→`role` (scope B), folds into cutover slice-4.** WT renamed the
 agents-RESPONSE selector `model`→`role` (spec 1.2). **DEPLOY NOW LIVE** on :8080/:8081 (v1.0.0b128,
@@ -119,12 +117,13 @@ Full record → `persistent-memory.d/2026-07-18-368-silo-test-passed.md`. Siblin
 (2) R39 Phase-2 **matched-quartets rebuild** (confirmatory, "whenever"); (3) bifrost **snapshot-cursor
 adoption** (ruled normative, not blocking → `persistent-memory.d/2026-07-16-bifrost-cursor-conformance.md`).

-**Substrate / environment:** branch `main` at **v0.21.10**, **fully PUSHED to origin at `aba1730`** (slice-2
-cutover arc `b1fbadd`→`aba1730` + tags v0.21.3–.10 pushed 2026-07-19). origin
-`git@gitea.phasefinal.com:vh/ratatoskr.git`. **NEW core dep: `worldtree-sdk==1.0.0`** (gitea PyPI,
-`[tool.uv.sources]`; `httpx-sse` retires at slice-7). bifrost **`==1.1.4`** / wire v0.7; WT openapi vendored
-2.3.0, **conversation-api-spec re-synced to v1.1** (`b4a278c`); **suite 497 green** (was 534 pre-cutover; net
-delta = adapter/rewire tests added, ~80 deleted hand-rolled turn-stream tests). Personal WT on **b128**
+**Substrate / environment:** branch `main` at **v0.21.12**, **PUSHED to origin** (slice-3 arc `ca9a339`+
+`fc256bb` + this snapshot, tags v0.21.11–.12, pushed 2026-07-19; slice-1+2 arc `b1fbadd`→`aba1730` +
+v0.21.3–.10 earlier). origin `git@gitea.phasefinal.com:vh/ratatoskr.git`. **NEW core dep:
+`worldtree-sdk==1.0.0`** (gitea PyPI, `[tool.uv.sources]`; `httpx-sse` retires at slice-7). bifrost
+**`==1.1.4`** / wire v0.7; WT openapi vendored 2.3.0, **conversation-api-spec re-synced to v1.1** (`b4a278c`);
+**suite 469 green** (was 497 post-slice-2; net delta = slice-3 adapter/probe tests added, ~50 deleted
+hand-rolled sessions tests). Personal WT on **b128**
 (`http://10.250.50.152:8081`; #368 silo + #364 promotion-hygiene live both instances). The combined
 **:8392** provider (memory+affect) + **:8765** web are THE surfaces, dev-box BACKGROUND SHELLS —
 restart via `scratchpad/relaunch_by_pid.py <pid>` (pid via `ss -ltnp | grep <port>`). `env.sh` sets
@@ -147,8 +146,6 @@ relational-dynamics verify (bind `--bifrost-url :8392`); WT #356 resume-durabili
 Chronological log of decisions with `[YYYY-MM-DD]` prefix. One line per
 decision. Captures rationale that won't be obvious from code alone.

- `[2026-06-17]` **#296 triage sent to worldtree-dev** (`01KVBBH0…`): extraction SUBJECT-INVERSION (promotes assistant prose, drops the user's fact) + META-DESCRIPTION-not-content; verbose-persona aggravator. WAD-vs-bug resolved to BUG (extraction quality), not idle-gating.
- `[2026-06-18]` **Tier-3 memory PROVEN end-to-end live** — `ratatoskr:terse-probe` recalled a seeded user fact in a COLD history-free session (scope_any → 1 hit @ cosine 0.6994). Closes the opening "how far from Tier-3 memory" question for normal agents.
 - `[2026-06-19]` **#18 D2 SHIPPED (`v0.17.14`, `39eebd1`) and the full #17+#18 arc PUSHED to origin** → `persistent-memory.d/2026-06-19-18-d2-shipped-v0-17-14-39eebd1-and-the-full-1.md`

 - `[2026-06-19]` **bifrost repinned 0.8.0→0.10.0; `affect.fetch` became MANDATORY (strong-or-absent)** → `persistent-memory.d/2026-06-19-bifrost-repinned-0-8-0-0-10-0-affect-fetch-be.md`
@@ -275,8 +272,9 @@ decision. Captures rationale that won't be obvious from code alone.
 - `[2026-07-18]` **Rata = THE reference consumer of the worldtree-sdk Python spine** — parity pass (12 grounded findings) shaped its contract BEFORE build (open-world reads, caller-injected transport, per-wire role/model — adopted); coverage-map re-anchored to the SDK's 41-op ratified surface (`b1fbadd`); 4 ergonomics items parked post-v1 with wtsdk-dev.
 - `[2026-07-18]` **worldtree-sdk cutover DECIDED — adopt the Python SDK for the consumer client layer** (operator, overriding "stay hand-rolled"). Issue #20; contract `docs/contracts/worldtree_sdk_cutover.contract.md` (`e45640c`, vor-cross'd + heid-reviewed); auto-memory `project_worldtree_sdk_cutover`. Consumer layer only, Bifrost provider untouched; slice-1 foundation next. See in-flight.
 - `[2026-07-19]` **worldtree-sdk cutover SLICE-1 + SLICE-2 COMPLETE + PUSHED (origin `aba1730`, v0.21.10, 497 green).** The biggest, riskiest cutover slice done end-to-end through the full House Code Discipline (adapter→cli→web→delete→live-smoke→both heid gates); the bug-hunt caught 4 real confirmed bugs the conformance lens couldn't, and a convergent code-review finding was correctly REJECTED as category-5 (SDK envelope-parser behavior). Slice-3 next. → `persistent-memory.d/2026-07-19-worldtree-sdk-cutover-slice-1-2-complete.md`
+- `[2026-07-19]` **worldtree-sdk cutover SLICE-3 COMPLETE + pushed (`ca9a339`+`fc256bb`, v0.21.11–.12, 469 green).** Persona/authored-history/first-message onto the wt adapter; last hand-rolled `sessions.py` paths deleted; both heid gates cleared — code-review ZERO drift, bug-hunt caught + fixed a real regression I shipped (ConnectFailed escaping both rewired probes → uncaught crash; the SDK normalizes ALL transport failures to `ConnectFailed`, not raw httpx) plus a finite-PAD chokepoint gap. Slice-4 (agents/tier3 + model→role) next. → `persistent-memory.d/2026-07-19-worldtree-sdk-cutover-slice-3-complete.md`

-_65 older entries (2026-05-* debug-TUI/web era + the 2026-06-14 → 06-18 Bifrost-provider build / #17+#18 / #295-296 era) archived to archival-memory.md._
+_67 older entries (2026-05-* debug-TUI/web era + the 2026-06-14 → 06-18 Bifrost-provider build / #17+#18 / #295-296 era) archived to archival-memory.md._

 _For per-issue TDD implementation notes, Volva findings, and contract amendments, see the git log — every per-issue commit carries a structured message capturing the trail._

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "ratatoskr"
-version = "0.21.11"
+version = "0.21.15"
 description = "Worldtree Conversation API debug console (web + headless CLI) — multi-pane observability"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -901,7 +901,12 @@ async def _set_persona_probe(args: ParsedArgs) -> int:
                f"error_code={exc.error_code!r} body={exc.body!r}\n"
            )
            return 20
-        except (httpx.ConnectError, httpx.ReadTimeout, httpx.TransportError) as exc:
+        except (
+            httpx.ConnectError,
+            httpx.ReadTimeout,
+            httpx.TransportError,
+            ConnectFailed,  # SDK normalizes a pre-response transport failure here
+        ) as exc:
            sys.stderr.write(f"[network_error] {type(exc).__name__}: {exc}\n")
            return 21
        sys.stdout.write(
@@ -968,7 +973,12 @@ async def _seed_first_message_probe(args: ParsedArgs) -> int:
                f"error_code={exc.error_code!r} body={exc.body!r}\n"
            )
            return 20
-        except (httpx.ConnectError, httpx.ReadTimeout, httpx.TransportError) as exc:
+        except (
+            httpx.ConnectError,
+            httpx.ReadTimeout,
+            httpx.TransportError,
+            ConnectFailed,  # SDK normalizes a pre-response transport failure here
+        ) as exc:
            sys.stderr.write(f"[network_error] {type(exc).__name__}: {exc}\n")
            return 21
    return 0
@@ -27,7 +27,11 @@ import os
 from dataclasses import asdict, dataclass
 from pathlib import Path

-_SCHEMA_VERSION = 1
+# v2 (worldtree-sdk cutover slice-4): `model` → `role`. The field holds what the
+# Worldtree wire now calls a role (spec 1.2 / b128, the define response echoes
+# `role`); the version bump discards any pre-cutover on-disk index cleanly
+# (no-backwards-compat — old `{"model": …}` rows are dropped, re-defined fresh).
+_SCHEMA_VERSION = 2


@dataclass(frozen=True)
@@ -37,16 +41,17 @@ class LocalAgentEntry:
    Schema:
      - ``agent_id``: full "user_id:agent_name" string (Worldtree-owned).
      - ``agent_name``: slug from define (display name).
-      - ``model``: provider model ID at last define/patch.
+      - ``role``: model-role at last define/patch (e.g. "thoughtful-character";
+        the define/patch response's ``role`` field, W-4 resolved / b128).
      - ``description``: synthetic display string (typically derived from
        the system_prompt's first line + a "(tier 3)" prefix; the picker
        uses this in its ``{id} · {name} — {description}`` rendering).
-      - ``defined_at``: ISO-8601 timestamp from the Tier3AgentInfo response.
+      - ``defined_at``: ISO-8601 timestamp from the define/patch response.
    """

    agent_id: str
    agent_name: str
-    model: str
+    role: str
    description: str
    defined_at: str

@@ -11,26 +11,6 @@ from typing import Any
 import httpx


-@dataclass(frozen=True)
-class AgentInfo:
-    """Worldtree agent envelope from GET /agents (issue #8).
-
-    INV-005: required fields (`agent_id`, `name`, `description`) take the
-    response value verbatim. Optional fields default to None / [] / {} when
-    omitted by the server, mirroring SessionInfo's INV-001/INV-002
-    origin-conditional defaulting.
-    """
-
-    agent_id: str
-    name: str
-    description: str
-    version: str | None
-    capabilities: list[str]
-    supported_models: list[str]
-    persona_traits: dict[str, Any]
-    ui_hints: dict[str, Any]
-
-
@dataclass(frozen=True)
 class BifrostBinding:
    """Session-create Bifrost binding (Worldtree BifrostBindingRequest, #160).
@@ -169,6 +149,70 @@ class AuthoredHistoryUnavailable(Exception):
        self.session_id = session_id


+# ── Tier-3 (consumer-defined) agent lifecycle exceptions ─────────────────────
+# The worldtree-sdk adapter (`ratatoskr.wt`) re-raises these from the agents.define/
+# patch/delete routes. They live HERE (not in `tier3`) so both `wt` and the
+# `python -m ratatoskr.tier3` CLI reference the SAME class objects: `tier3` is run as
+# `__main__`, and if these were defined there, `wt`'s `from .tier3 import …` would bind
+# a SECOND copy under `ratatoskr.tier3` — so a raised exception would not match the
+# CLI's `except` (the exception would escape as an uncaught traceback). Homing them in
+# `sessions` (never run as `__main__`) makes the class identity single.
+
+
+class Tier3QuotaExceeded(Exception):
+    """Raised on HTTP 429 ``agent_quota_exceeded`` — 50-agent cap reached
+    on the Heimdall key. ``retry_after`` captures the Retry-After header
+    verbatim (defaults to 0 per spec §2675; forward-compat for non-zero).
+
+    Post-cutover the adapter constructs this with ``retry_after=0`` — the SDK's
+    ``ApiError`` floor carries no response headers, and §2675 pins Phase-2.0 quota
+    to ``Retry-After: 0``, so the value is spec-canonical."""
+
+    def __init__(self, *, retry_after: int) -> None:
+        super().__init__(f"Tier 3 agent quota exceeded (retry_after={retry_after})")
+        self.retry_after = retry_after
+
+
+class Tier3UserIdUnsupported(Exception):
+    """Raised on HTTP 403 ``tier3_user_id_unsupported`` — auth's user_id
+    is not slug-safe per Phase 2.0 gate (spec §2626)."""
+
+    def __init__(self) -> None:
+        super().__init__("tier3 caller user_id is not slug-safe")
+
+
+class Tier3FieldNotMutable(Exception):
+    """Raised on HTTP 422 ``field_not_mutable`` — PATCH request body
+    carried a key that's immutable post-define (``agent_name``, ``user_id``,
+    or any layer field). Server rejects BEFORE the DB lookup (spec §2644)."""
+
+    def __init__(self, *, field: str | None) -> None:
+        super().__init__(f"field not mutable on Tier 3 patch: {field!r}")
+        self.field = field
+
+
+class Tier3LayerDeferred(Exception):
+    """Raised on HTTP 422 ``layer_deferred`` — define request carried a
+    non-null layer field (``persona`` / ``motivational`` / ``valence`` /
+    ``memory``). Phase 2.0 ships baseline only; layers are schema-reserved.
+
+    Note: ``define_agent`` never sends layer fields, so this exception is
+    defense-against-server-side-changes / forward-compat."""
+
+    def __init__(self, *, field: str | None) -> None:
+        super().__init__(f"tier3 layer field deferred: {field!r}")
+        self.field = field
+
+
+class Tier3AgentNotFound(Exception):
+    """Raised on HTTP 404 — PATCH or DELETE on a non-existent agent_id
+    (spec §2634 + §2641)."""
+
+    def __init__(self, *, agent_id: str) -> None:
+        super().__init__(f"tier3 agent not found: {agent_id!r}")
+        self.agent_id = agent_id
+
+
 def endpoint_for_plane(plane: str, base_host: str) -> str:
    """Map a provider plane name to its Worldtree-VISIBLE base URL.

@@ -186,82 +230,6 @@ def endpoint_for_plane(plane: str, base_host: str) -> str:
    return f"http://{base_host}:{ports[plane]}"


-async def list_agents(client: httpx.AsyncClient) -> list[AgentInfo]:
-    """GET /agents — list available agents. See contract FN list_agents (issue #8).
-
-    No request params, no pagination. Returns server-ordered list. Optional
-    fields are defaulted to None / [] / {} per INV-005.
-    """
-    assert client is not None
-
-    resp = await client.get("/agents")
-    if resp.status_code != 200:
-        raise SessionApiFailed(status=resp.status_code, body=resp.content)
-    body = resp.json()
-    return [
-        AgentInfo(
-            agent_id=item["agent_id"],
-            name=item["name"],
-            description=item["description"],
-            version=item.get("version"),
-            capabilities=item.get("capabilities") or [],
-            supported_models=item.get("supported_models") or [],
-            persona_traits=item.get("persona_traits") or {},
-            ui_hints=item.get("ui_hints") or {},
-        )
-        for item in body
-    ]
-
-
-async def get_persona_state(client: httpx.AsyncClient, agent_id: str) -> dict[str, Any]:
-    """GET /agents/{agent_id}/persona_state — fetch current persona snapshot.
-
-    Worldtree #204 / v0.28.0. Returns the same `snapshot` dict shape as the
-    `affect_update` SSE event's `status="current"` emission: pad,
-    dominant_emotion, emotions_active, baseline_pad, mood_drift,
-    last_updated_at. Bootstrap read for clients that want to populate a
-    persona pane on session-open without waiting for turn-1's `affect_update`.
-
-    Auth: requires Heimdall `persona.read` scope (user-tier default).
-
-    Failure modes (mapped to typed exceptions per the spec error_codes):
-      - 404 `persona_not_configured` → PersonaNotConfigured (persona-disabled
-        agents: domari / muninn, and all Tier 3 in Phase 2.0)
-      - 404 `agent_not_available` → AgentNotAvailable (unknown agent_id)
-      - 403 `auth_scope_denied` → AuthScopeDenied (key lacks persona.read)
-      - any other non-2xx → SessionApiFailed (preserves the broader-error
-        precedent from list_agents / list_sessions / create_session)
-    """
-    assert client is not None
-    assert agent_id and isinstance(agent_id, str)
-
-    resp = await client.get(f"/agents/{agent_id}/persona_state")
-    if resp.status_code == 200:
-        return resp.json()
-    # Discriminate the 4xx error_code sub-codes; everything else falls
-    # through. Worldtree returns errors as either flat `{"error_code": …}`
-    # OR FastAPI-default `{"detail": {"error_code": …}}` depending on
-    # which handler raised — unwrap both shapes (real wire observed
-    # 2026-05-28 returning the detail-nested form for auth_scope_denied
-    # from /agents/{id}/persona_state).
-    try:
-        err = resp.json()
-    except ValueError:
-        err = None
-    error_code: str | None = None
-    if isinstance(err, dict):
-        error_code = err.get("error_code")
-        if error_code is None and isinstance(err.get("detail"), dict):
-            error_code = err["detail"].get("error_code")
-    if resp.status_code == 404 and error_code == "persona_not_configured":
-        raise PersonaNotConfigured(agent_id=agent_id)
-    if resp.status_code == 404 and error_code == "agent_not_available":
-        raise AgentNotAvailable(agent_id=agent_id)
-    if resp.status_code == 403 and error_code == "auth_scope_denied":
-        raise AuthScopeDenied(scope="persona.read")
-    raise SessionApiFailed(status=resp.status_code, body=resp.content)
-
-
 async def get_me(client: httpx.AsyncClient) -> dict[str, Any]:
    """GET /me — the authenticated principal's identity + key metadata (spec §GET /me).

@@ -1,259 +1,55 @@
-"""Worldtree Tier 3 (consumer-defined) agent lifecycle client.
+"""Worldtree Tier 3 (consumer-defined) agent CLI + caller-semantic exceptions.

-Implements docs/contracts/issues/15.contract.md. Caller-owned httpx.AsyncClient
-posture (same as ratatoskr.sessions). Exposes three lifecycle operations:
+The define / patch / delete wire calls route through the worldtree-sdk adapter
+(``ratatoskr.wt.define_agent`` / ``patch_agent`` / ``delete_agent``); this module owns
+the ``python -m ratatoskr.tier3`` CLI and the Tier-3 caller-semantic exception
+taxonomy the adapter re-raises (quota / user-id / field-not-mutable / layer-deferred /
+not-found). The picker already handles colon-containing agent_ids generically
+(issue #8).

- ``define_agent`` — POST /agents/define
- ``patch_agent`` — PATCH /agents/<id>
- ``delete_agent`` — DELETE /agents/<id>
-
-Plus a frozen ``Tier3AgentInfo`` dataclass for the response shape. The picker
-already handles colon-containing agent_ids generically (issue #8); session
-creation works unchanged via ``ratatoskr.wt.create_session`` (worldtree-sdk cutover).
-
-Spec reference: ``docs/conversation-api-spec.md`` §2576-2750 (Phase 2.0).
+The old hand-rolled httpx wrappers + the ``Tier3AgentInfo`` dataclass were deleted in
+the worldtree-sdk cutover (issue #20, slice-4); the adapter returns the SDK's
+open-world define/patch dicts (echoing ``role`` post-b128, spec 1.2), read here as
+mappings. ``wt`` imports this module's exceptions at module level; this module imports
+``wt`` only lazily inside the CLI handlers, so there is no import cycle.
 """

 from __future__ import annotations

 import argparse
-import re
-from dataclasses import dataclass
+import sys
+from collections.abc import Mapping
+from typing import Any

 import httpx

-from ratatoskr.sessions import SessionApiFailed
-
-# Per spec §2627: agent_name + user_id slugs are `[a-z][a-z0-9-]{2,63}`.
-_SLUG_RE = re.compile(r"^[a-z][a-z0-9-]{2,63}$")
+# The Tier-3 caller-semantic exceptions live in `sessions` (never run as `__main__`)
+# so the adapter's raise and this CLI's `except` reference the SAME class objects —
+# see the header note in `sessions.py`. `main()` catches these; `wt` raises them.
+from ratatoskr.sessions import (
+    Tier3AgentNotFound,
+    Tier3FieldNotMutable,
+    Tier3LayerDeferred,
+    Tier3QuotaExceeded,
+    Tier3UserIdUnsupported,
+)


-@dataclass(frozen=True)
-class Tier3AgentInfo:
-    """Worldtree Tier 3 agent envelope returned by define / patch.
-
-    INV-001: ``agent_id`` is always shape ``"<user_id>:<agent_name>"`` —
-    constructed server-side from the auth's user_id + the supplied agent_name.
-    """
-
-    agent_id: str
-    user_id: str
-    agent_name: str
-    system_prompt: str
-    model: str
-    created_at: str
-    updated_at: str
-
-
-class Tier3QuotaExceeded(Exception):
-    """Raised on HTTP 429 ``agent_quota_exceeded`` — 50-agent cap reached
-    on the Heimdall key. ``retry_after`` captures the Retry-After header
-    verbatim (defaults to 0 per spec §2675; forward-compat for non-zero)."""
-
-    def __init__(self, *, retry_after: int) -> None:
-        super().__init__(f"Tier 3 agent quota exceeded (retry_after={retry_after})")
-        self.retry_after = retry_after
-
-
-class Tier3UserIdUnsupported(Exception):
-    """Raised on HTTP 403 ``tier3_user_id_unsupported`` — auth's user_id
-    is not slug-safe per Phase 2.0 gate (spec §2626)."""
-
-    def __init__(self) -> None:
-        super().__init__("tier3 caller user_id is not slug-safe")
-
-
-class Tier3FieldNotMutable(Exception):
-    """Raised on HTTP 422 ``field_not_mutable`` — PATCH request body
-    carried a key that's immutable post-define (``agent_name``, ``user_id``,
-    or any layer field). Server rejects BEFORE the DB lookup (spec §2644)."""
-
-    def __init__(self, *, field: str | None) -> None:
-        super().__init__(f"field not mutable on Tier 3 patch: {field!r}")
-        self.field = field
-
-
-class Tier3LayerDeferred(Exception):
-    """Raised on HTTP 422 ``layer_deferred`` — define request carried a
-    non-null layer field (``persona`` / ``motivational`` / ``valence`` /
-    ``memory``). Phase 2.0 ships baseline only; layers are schema-reserved.
-
-    Note: ``define_agent`` never sends layer fields, so this exception is
-    defense-against-server-side-changes / forward-compat. INV-001 in the
-    request body construction is the first line of defense.
-    """
-
-    def __init__(self, *, field: str | None) -> None:
-        super().__init__(f"tier3 layer field deferred: {field!r}")
-        self.field = field
-
-
-class Tier3AgentNotFound(Exception):
-    """Raised on HTTP 404 — PATCH or DELETE on a non-existent agent_id
-    (spec §2634 + §2641)."""
-
-    def __init__(self, *, agent_id: str) -> None:
-        super().__init__(f"tier3 agent not found: {agent_id!r}")
-        self.agent_id = agent_id
-
-
-def _extract_error_code(resp: httpx.Response) -> str | None:
-    """Pluck the ``detail.error_code`` from a Worldtree error envelope.
-
-    Worldtree wraps API errors in ``{"detail": {"error_code": "...", ...}}``
-    per the spec. Returns None on shape mismatch (so callers fall through
-    to the generic ``SessionApiFailed`` branch).
-    """
-    try:
-        body = resp.json()
-    except ValueError:
-        return None
-    detail = body.get("detail") if isinstance(body, dict) else None
-    if isinstance(detail, dict):
-        code = detail.get("error_code")
-        if isinstance(code, str):
-            return code
-    return None
-
-
-def _extract_error_field(resp: httpx.Response) -> str | None:
-    """Pluck ``detail.field`` from a Worldtree error envelope (used for
-    ``field_not_mutable`` and ``layer_deferred`` to surface which field
-    triggered the rejection). Returns None on shape mismatch.
-    """
-    try:
-        body = resp.json()
-    except ValueError:
-        return None
-    detail = body.get("detail") if isinstance(body, dict) else None
-    if isinstance(detail, dict):
-        field = detail.get("field")
-        if isinstance(field, str):
-            return field
-    return None
-
-
-def _parse_tier3_agent_info(body: dict) -> Tier3AgentInfo:
-    """Parse a Worldtree Tier 3 agent JSON body into the frozen dataclass."""
-    return Tier3AgentInfo(
-        agent_id=body["agent_id"],
-        user_id=body["user_id"],
-        agent_name=body["agent_name"],
-        system_prompt=body["system_prompt"],
-        model=body["model"],
-        created_at=body["created_at"],
-        updated_at=body["updated_at"],
-    )
-
-
-async def define_agent(
-    client: httpx.AsyncClient,
-    *,
-    agent_name: str,
-    system_prompt: str,
-    role: str,
-) -> Tier3AgentInfo:
-    """POST /agents/define — create a Tier 3 agent.
-
-    See contract FN define_agent. Validates the agent_name slug client-side
-    before the network round-trip; server-side validation is the safety net.
-    Returns a fully populated Tier3AgentInfo on 201. Routes documented error
-    codes to typed exceptions; unknown non-2xx → SessionApiFailed.
-    """
-    assert client is not None
-    assert _SLUG_RE.match(agent_name), (
-        f"agent_name must match [a-z][a-z0-9-]{{2,63}}: {agent_name!r}"
-    )
-    assert system_prompt, "system_prompt must be non-empty"
-    assert role, "role must be non-empty"
-
-    # b125 drift: /agents/define takes `role` (a model-role, e.g. "thoughtful-character")
-    # in the request; the response echoes it back as `model`. See #15 follow-up.
-    body = {
-        "agent_name": agent_name,
-        "system_prompt": system_prompt,
-        "role": role,
-    }
-    resp = await client.post("/agents/define", json=body)
-
-    if resp.status_code == 201:
-        return _parse_tier3_agent_info(resp.json())
-    if resp.status_code == 429:
-        # Spec §2675: 51st define → 429 with Retry-After: 0.
-        try:
-            retry_after = int(resp.headers.get("Retry-After", "0"))
-        except (TypeError, ValueError):
-            retry_after = 0
-        raise Tier3QuotaExceeded(retry_after=retry_after)
-    if resp.status_code == 403:
-        if _extract_error_code(resp) == "tier3_user_id_unsupported":
-            raise Tier3UserIdUnsupported()
-    if resp.status_code == 422:
-        code = _extract_error_code(resp)
-        if code == "layer_deferred":
-            raise Tier3LayerDeferred(field=_extract_error_field(resp))
-    raise SessionApiFailed(status=resp.status_code, body=resp.content)
-
-
-async def patch_agent(
-    client: httpx.AsyncClient,
-    agent_id: str,
-    *,
-    system_prompt: str | None = None,
-    role: str | None = None,
-) -> Tier3AgentInfo:
-    """PATCH /agents/<id> — mutate system_prompt and/or model.
-
-    See contract FN patch_agent. Per spec §2641: only system_prompt + model
-    are mutable in Phase 2.0; any other key returns 422 field_not_mutable.
-    """
-    assert client is not None
-    assert ":" in agent_id, f"tier 3 agent_id must contain ':': {agent_id!r}"
-    assert system_prompt is not None or role is not None, (
-        "patch requires at least one of system_prompt or role"
-    )
-
-    body: dict[str, str] = {}
-    if system_prompt is not None:
-        body["system_prompt"] = system_prompt
-    if role is not None:
-        body["role"] = role
-    resp = await client.patch(f"/agents/{agent_id}", json=body)
-
-    if resp.status_code == 200:
-        return _parse_tier3_agent_info(resp.json())
-    if resp.status_code == 404:
-        raise Tier3AgentNotFound(agent_id=agent_id)
-    if resp.status_code == 422:
-        code = _extract_error_code(resp)
-        if code == "field_not_mutable":
-            raise Tier3FieldNotMutable(field=_extract_error_field(resp))
-    raise SessionApiFailed(status=resp.status_code, body=resp.content)
-
-
-async def delete_agent(client: httpx.AsyncClient, agent_id: str) -> None:
-    """DELETE /agents/<id> — owner hard-delete (cancels active sessions
-    server-side per spec §2636).
-
-    See contract FN delete_agent. 204 on success; 404 if the agent_id
-    doesn't exist; other non-2xx → SessionApiFailed.
-    """
-    assert client is not None
-    assert ":" in agent_id, f"tier 3 agent_id must contain ':': {agent_id!r}"
-
-    resp = await client.delete(f"/agents/{agent_id}")
-    if resp.status_code == 204:
-        return
-    if resp.status_code == 404:
-        raise Tier3AgentNotFound(agent_id=agent_id)
-    raise SessionApiFailed(status=resp.status_code, body=resp.content)
-
+def _str_field(info: Mapping[str, Any], key: str, *, default: str = "") -> str:
+    """A string field off an open-world response dict, or `default` when the key is
+    absent / null / non-string — so a partial or drifted 2xx define/patch response
+    degrades rather than KeyError/AttributeError-crashing the CLI presenter (the
+    "open-world reads degrade, never crash the presenter" invariant; heid-bug-hunt)."""
+    value = info.get(key)
+    return value if isinstance(value, str) else default

 # ---- CLI (`python -m ratatoskr.tier3 <subcommand>`) ------------------------
 #
 # Auth + server URL resolution mirrors ratatoskr.cli verbatim. Exit codes
 # mirror ratatoskr.cli: 0 happy / 10 usage / 11 auth / 20 api-failure /
-# 21 network. Outbound requests carry the same User-Agent string.
+# 21 network. Outbound requests carry the same User-Agent string. The wire calls
+# route through the worldtree-sdk adapter (ratatoskr.wt) over a ratatoskr-owned
+# injected transport (INV-CUT-1: the SDK never closes it).


 class _Tier3UsageError(Exception):
@@ -284,7 +80,7 @@ def _build_parser() -> argparse.ArgumentParser:
        help="Model role, e.g. thoughtful-character (see GET /models/available-for-characters).",
    )

-    p_patch = sub.add_parser("patch", help="Mutate system_prompt and/or model.")
+    p_patch = sub.add_parser("patch", help="Mutate system_prompt and/or role.")
    p_patch.add_argument("agent_id", help='Full "<user_id>:<agent_name>" form.')
    p_patch.add_argument("--system-prompt", dest="system_prompt", default=None)
    p_patch.add_argument("--role", default=None)
@@ -308,46 +104,63 @@ def _resolve_auth(ns: argparse.Namespace) -> tuple[str, str]:
    return api_key, server_url


+def _transport(server_url: str, api_key: str) -> httpx.AsyncClient:
+    """The ratatoskr-owned httpx transport the adapter's WorldtreeClient is built
+    over. Carries the User-Agent + a generous read timeout for agent CRUD; the SDK
+    re-applies auth per request (the default bearer here just mirrors it)."""
+    from ratatoskr.cli import USER_AGENT
+
+    return httpx.AsyncClient(
+        base_url=server_url,
+        headers={"Authorization": f"Bearer {api_key}", "User-Agent": USER_AGENT},
+        timeout=httpx.Timeout(connect=10.0, read=30.0, write=10.0, pool=10.0),
+    )
+
+
 async def _run_define(ns: argparse.Namespace) -> int:
    api_key, server_url = _resolve_auth(ns)
-    from ratatoskr.cli import USER_AGENT
+    from ratatoskr import wt
    from ratatoskr.local_agents import (
        LocalAgentEntry,
        add_local_agent,
        make_description,
    )

-    async with httpx.AsyncClient(
-        base_url=server_url,
-        headers={
-            "Authorization": f"Bearer {api_key}",
-            "User-Agent": USER_AGENT,
-        },
-        timeout=httpx.Timeout(connect=10.0, read=30.0, write=10.0, pool=10.0),
-    ) as client:
-        info = await define_agent(
+    async with _transport(server_url, api_key) as transport:
+        client = wt.build_client(server_url, api_key=api_key, transport=transport)
+        info = await wt.define_agent(
            client,
            agent_name=ns.name,
            system_prompt=ns.system_prompt,
            role=ns.role,
        )
-        # v0.8.0: persist to local index so the picker can show it.
-        add_local_agent(
-            LocalAgentEntry(
-                agent_id=info.agent_id,
-                agent_name=info.agent_name,
-                model=info.model,
-                description=make_description(info.system_prompt),
-                defined_at=info.created_at,
+        # Open-world define dict — read defensively (echoes `role` post-b128, not
+        # `model`). A partial/drifted 2xx must not crash the presenter.
+        agent_id = _str_field(info, "agent_id")
+        if not agent_id:  # a 2xx with no usable agent_id is a malformed success
+            sys.stderr.write(f"[api_failed] define returned no usable agent_id: {info!r}\n")
+            return 20
+        role = _str_field(info, "role", default="?")
+        agent_name = _str_field(info, "agent_name")
+        # v0.8.0: persist to local index so the picker can show it — only for a
+        # well-formed identity (agent_id + agent_name); else skip the write, still print.
+        if agent_name:
+            add_local_agent(
+                LocalAgentEntry(
+                    agent_id=agent_id,
+                    agent_name=agent_name,
+                    role=role,
+                    description=make_description(_str_field(info, "system_prompt")),
+                    defined_at=_str_field(info, "created_at"),
+                )
            )
-        )
-        print(f"defined {info.agent_id} ({info.model})")
+        print(f"defined {agent_id} ({role})")
        return 0


 async def _run_patch(ns: argparse.Namespace) -> int:
    api_key, server_url = _resolve_auth(ns)
-    from ratatoskr.cli import USER_AGENT
+    from ratatoskr import wt
    from ratatoskr.local_agents import (
        LocalAgentEntry,
        make_description,
@@ -358,48 +171,43 @@ async def _run_patch(ns: argparse.Namespace) -> int:
        raise _Tier3UsageError(
            "patch requires at least one of --system-prompt or --role"
        )
-    async with httpx.AsyncClient(
-        base_url=server_url,
-        headers={
-            "Authorization": f"Bearer {api_key}",
-            "User-Agent": USER_AGENT,
-        },
-        timeout=httpx.Timeout(connect=10.0, read=30.0, write=10.0, pool=10.0),
-    ) as client:
-        info = await patch_agent(
+    async with _transport(server_url, api_key) as transport:
+        client = wt.build_client(server_url, api_key=api_key, transport=transport)
+        info = await wt.patch_agent(
            client,
            ns.agent_id,
            system_prompt=ns.system_prompt,
            role=ns.role,
        )
-        # v0.8.0: refresh local index with the post-patch state.
-        update_local_agent(
-            LocalAgentEntry(
-                agent_id=info.agent_id,
-                agent_name=info.agent_name,
-                model=info.model,
-                description=make_description(info.system_prompt),
-                defined_at=info.updated_at,
+        # Open-world patch dict — read defensively (same degrade-not-crash posture).
+        agent_id = _str_field(info, "agent_id")
+        if not agent_id:  # a 2xx with no usable agent_id is a malformed success
+            sys.stderr.write(f"[api_failed] patch returned no usable agent_id: {info!r}\n")
+            return 20
+        agent_name = _str_field(info, "agent_name")
+        # v0.8.0: refresh local index with the post-patch state (well-formed identity only).
+        if agent_name:
+            update_local_agent(
+                LocalAgentEntry(
+                    agent_id=agent_id,
+                    agent_name=agent_name,
+                    role=_str_field(info, "role", default="?"),
+                    description=make_description(_str_field(info, "system_prompt")),
+                    defined_at=_str_field(info, "updated_at"),
+                )
            )
-        )
-        print(f"patched {info.agent_id}")
+        print(f"patched {agent_id}")
        return 0


 async def _run_delete(ns: argparse.Namespace) -> int:
    api_key, server_url = _resolve_auth(ns)
-    from ratatoskr.cli import USER_AGENT
+    from ratatoskr import wt
    from ratatoskr.local_agents import remove_local_agent

-    async with httpx.AsyncClient(
-        base_url=server_url,
-        headers={
-            "Authorization": f"Bearer {api_key}",
-            "User-Agent": USER_AGENT,
-        },
-        timeout=httpx.Timeout(connect=10.0, read=30.0, write=10.0, pool=10.0),
-    ) as client:
-        await delete_agent(client, ns.agent_id)
+    async with _transport(server_url, api_key) as transport:
+        client = wt.build_client(server_url, api_key=api_key, transport=transport)
+        await wt.delete_agent(client, ns.agent_id)
        # v0.8.0: drop from local index so the picker stops listing it.
        remove_local_agent(ns.agent_id)
        print(f"deleted {ns.agent_id}")
@@ -419,6 +227,10 @@ def main(argv: list[str] | None = None) -> int:
    import asyncio
    import sys

+    import worldtree_sdk as wtsdk
+
+    from ratatoskr.wt import SessionApiFailed
+
    parser = _build_parser()
    try:
        ns = parser.parse_args(argv)
@@ -459,10 +271,16 @@ def main(argv: list[str] | None = None) -> int:
        return 20
    except SessionApiFailed as exc:
        sys.stderr.write(
-            f"[api_failed] status={exc.status} body={exc.body!r}\n"
+            f"[api_failed] status={exc.status} "
+            f"error_code={exc.error_code!r} body={exc.body!r}\n"
        )
        return 20
-    except (httpx.ConnectError, httpx.ReadTimeout, httpx.TransportError) as exc:
+    except (
+        httpx.ConnectError,
+        httpx.ReadTimeout,
+        httpx.TransportError,
+        wtsdk.ConnectFailed,  # SDK normalizes any pre-response transport failure here
+    ) as exc:
        sys.stderr.write(f"[network_error] {type(exc).__name__}: {exc}\n")
        return 21

@@ -26,7 +26,13 @@ from starlette.responses import (
 )
 from starlette.routing import Mount, Route
 from starlette.staticfiles import StaticFiles
-from worldtree_sdk import CancelledEvent, DoneEvent, ErrorEvent, WorldtreeClient
+from worldtree_sdk import (
+    CancelledEvent,
+    ConnectFailed,
+    DoneEvent,
+    ErrorEvent,
+    WorldtreeClient,
+)

 from ratatoskr import local_agents as _local_agents
 from ratatoskr import wt
@@ -41,15 +47,13 @@ from ratatoskr.sessions import (
    PersonaNotConfigured,
    SessionApiFailed,
    endpoint_for_plane,
-    get_persona_state,
    get_session_bifrost,
-    list_agents,
 )

-# The turn path (create / stream / cancel / tools / messages) is served by the
-# worldtree-sdk adapter (`wt.*`), which raises ratatoskr's caller-semantic
-# exceptions (DEC-2). The hand-rolled endpoints (persona / agents / admin /
-# bifrost) stay on the `sessions` / `sse_client` wrappers until their own slices.
+# The turn path (create / stream / cancel / tools / messages) AND the agents /
+# persona-state reads are served by the worldtree-sdk adapter (`wt.*`), which raises
+# ratatoskr's caller-semantic exceptions (DEC-2). The remaining hand-rolled endpoint
+# (admin bifrost) stays on the `sessions` / `sse_client` wrappers until slice 6.
 from ratatoskr.sse_client import (
    AdminEvent,
    CancelAlreadyCompleted,
@@ -124,20 +128,31 @@ async def _agents_endpoint(request: Request) -> JSONResponse:
    client_factory = request.app.state.client_factory
    try:
        async with client_factory() as client:
-            upstream = await list_agents(client)
-    except SessionApiFailed as exc:
+            upstream = await wt.list_agents(_wt_client(client))
+    except wt.SessionApiFailed as exc:
        return JSONResponse(
            {"error_code": "session_api_failed", "status": exc.status},
            status_code=exc.status,
        )
-    except httpx.RequestError as exc:
+    except (httpx.RequestError, ConnectFailed) as exc:
+        # The SDK normalizes a transport failure to ConnectFailed(status=0), not a
+        # raw httpx error; both surface the same network envelope (slice-3 foot-gun).
        return JSONResponse(
            {"error_code": "network_error", "message": str(exc)},
            status_code=502,
        )
-    upstream_ids = {a.agent_id for a in upstream}
+    # Open-world upstream (parity: no AgentInfo normalization). Degrade, never crash:
+    # a non-list envelope OR a malformed item (missing/non-str agent_id, non-mapping)
+    # is dropped rather than KeyError/TypeError'ing the endpoint into a 500 before the
+    # local fallback merges (heid-bug-hunt: the "open-world reads degrade" invariant).
+    upstream_items = upstream if isinstance(upstream, list) else []
+    well_formed = [
+        a for a in upstream_items
+        if isinstance(a, Mapping) and isinstance(a.get("agent_id"), str)
+    ]
+    upstream_ids = {a["agent_id"] for a in well_formed}
    local = _local_agents.load_local_agents()
-    merged = [_as_dict(a) for a in upstream] + [
+    merged = [_as_dict(a) for a in well_formed] + [
        _as_dict(le) for le in local if le.agent_id not in upstream_ids
    ]
    return JSONResponse(merged, status_code=200)
@@ -433,13 +448,28 @@ async def _persona_state_endpoint(request: Request) -> JSONResponse:
    client_factory = request.app.state.client_factory
    try:
        async with client_factory() as client:
-            snap = await get_persona_state(client, agent_id)
+            snap = await wt.get_persona_state(_wt_client(client), agent_id)
    except PersonaNotConfigured:
        return JSONResponse({"error_code": "persona_not_configured"}, status_code=404)
    except AgentNotAvailable:
        return JSONResponse({"error_code": "agent_not_available"}, status_code=404)
    except AuthScopeDenied:
        return JSONResponse({"error_code": "auth_scope_denied"}, status_code=403)
+    except wt.SessionApiFailed as exc:
+        # An unmatched upstream ApiError (a 500, or a coded-but-unmapped 4xx) →
+        # controlled envelope, for parity with _agents_endpoint / create / admin
+        # (heid-code-review slice-4: the persona endpoint was the lone sibling that
+        # let it escape as a raw 500 — a latent pre-cutover gap, closed here).
+        return JSONResponse(
+            {"error_code": "session_api_failed", "status": exc.status},
+            status_code=exc.status,
+        )
+    except (httpx.RequestError, ConnectFailed) as exc:
+        # SDK normalizes a transport failure to ConnectFailed(status=0) (slice-3
+        # foot-gun); surface the network envelope rather than a 500 crash.
+        return JSONResponse(
+            {"error_code": "network_error", "message": str(exc)}, status_code=502
+        )
    return JSONResponse(snap, status_code=200)


@@ -28,7 +28,9 @@ carries the SDK's parsed `error_code`).
 from __future__ import annotations

 import json
-from collections.abc import AsyncGenerator, Mapping
+import math
+import re
+from collections.abc import AsyncGenerator, Mapping, Sequence
 from typing import Any

 import httpx
@@ -39,13 +41,23 @@ from worldtree_sdk import ApiError, AuthProvider, CancelResult, PadState, Worldt
 # type still live in the retiring `sessions` / `sse_client` modules; they relocate
 # into this adapter as their call-sites are rewired in later slices. wt →
 # sessions / sse_client is one-way (neither imports wt), so there is no cycle.
+from .sessions import (
+    AgentNotAvailable as PersonaAgentNotAvailable,
+)
 from .sessions import (
    AgentNotFound,
    AuthoredHistoryUnavailable,
+    AuthScopeDenied,
    BifrostBinding,
    BifrostConsumerKeyMissing,
    BifrostHandshakeFailed,
    InvalidCursor,
+    PersonaNotConfigured,
+    Tier3AgentNotFound,
+    Tier3FieldNotMutable,
+    Tier3LayerDeferred,
+    Tier3QuotaExceeded,
+    Tier3UserIdUnsupported,
 )
 from .sse_client import (
    AgentNotAvailable,
@@ -367,11 +379,16 @@ async def set_persona_state(
    The adapter builds the canonical `PadState`; the SDK owns the wire wrapper
    (`{"pad": {pleasure, arousal, dominance}}`, prose-pinned #317) — ratatoskr no
    longer hand-assembles it. Resolves on 204 (→ None). Error map (INV-CUT-2): no
-    route-specific row → the `SessionApiFailed` default. (A non-finite axis is the
-    caller's to reject; the SDK raises `ConfigurationError` pre-HTTP and the CLI
-    surface pre-validates finiteness before calling.)
+    route-specific row → the `SessionApiFailed` default.
+
+    Finiteness is enforced HERE at the chokepoint (not only at the CLI): a
+    non-finite axis would serialize to `null` and corrupt the injection, and the SDK
+    raises `ConfigurationError` pre-HTTP — the precondition asserts it so any caller
+    gets a clean ratatoskr-side rejection, never a leaked SDK error. (The CLI surface
+    additionally pre-validates for a friendly usage error.)
    """
    assert session_id and isinstance(session_id, str)
+    assert all(math.isfinite(v) for v in (pleasure, arousal, dominance))
    try:
        await client.sessions.set_persona_state(
            session_id, PadState(pleasure=pleasure, arousal=arousal, dominance=dominance)
@@ -411,3 +428,151 @@ async def write_authored_history(
        if exc.status == 404:
            raise AuthoredHistoryUnavailable(session_id=session_id) from exc
        raise translate_error(exc) from exc
+
+
+# ── slice-4: agents (Tier-3) adapter routes ──────────────────────────────────
+# Ratatoskr-semantic surfaces over `WorldtreeClient.agents.*` (list/persona_state/
+# define/patch/delete). The SDK returns open-world dicts (parity posture — read as
+# mappings, never normalized into a frozen dataclass) and surfaces the tier3/persona
+# failure modes on its undiscriminated `ApiError` floor; the adapter maps them by the
+# ROUTE + (status, error_code) per the § Error map (INV-CUT-2). The `model`→`role`
+# cutover folds in here: the define/patch responses echo `role` (spec 1.2 / b128), so
+# callers read `info["role"]` off the open-world dict — no `Tier3AgentInfo` survives.
+
+# Consumer-agent slug (spec §2627): agent_name is `[a-z][a-z0-9-]{2,63}`.
+_AGENT_SLUG_RE = re.compile(r"^[a-z][a-z0-9-]{2,63}$")
+
+
+def _error_field_from_body(body: str | None) -> str | None:
+    """Pull the envelope's `field` from an SDK `ApiError` body string.
+
+    The SDK's `ApiError` carries the parsed `error_code` but NOT the envelope's
+    `field`, so the field-bearing tier3 rejections (`layer_deferred`,
+    `field_not_mutable`) body-parse it here — same both-shape unwrap as
+    `_bifrost_error_from_body`, tolerant of `{"detail": {"field": …}}` and a flat
+    top-level `field`. Returns None on any parse failure (the exception still carries
+    a None field, exactly as the hand-rolled path did on shape mismatch).
+    """
+    if not body:
+        return None
+    try:
+        err = json.loads(body)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(err, dict):
+        return None
+    field = err.get("field")
+    if field is None and isinstance(err.get("detail"), dict):
+        field = err["detail"].get("field")
+    # The exception surface declares `field: str | None` (and the CLI prints it), so a
+    # non-string envelope value (`{"field": {…}}` / `{"field": 1}`) collapses to None —
+    # same guard the retired hand-rolled `_extract_error_field` applied (heid-bug-hunt).
+    return field if isinstance(field, str) else None
+
+
+async def list_agents(client: WorldtreeClient) -> Sequence[Mapping[str, Any]]:
+    """List the caller's agents (GET /agents) as the SDK's open-world array, verbatim
+    (parity: each item read as a mapping, tolerant of wire drift — no `AgentInfo`
+    normalization). Any error → the `SessionApiFailed` default."""
+    try:
+        return await client.agents.list()
+    except ApiError as exc:
+        raise translate_error(exc) from exc
+
+
+async def get_persona_state(client: WorldtreeClient, agent_id: str) -> Mapping[str, Any]:
+    """Fetch an agent's persona snapshot (GET /agents/{id}/persona_state, WT #204),
+    open-world dict verbatim. Error map (INV-CUT-2 — dual-key status+error_code): 404
+    `persona_not_configured` → `PersonaNotConfigured`; 404 `agent_not_available` →
+    `AgentNotAvailable` (the persona-surface variant); 403 `auth_scope_denied` →
+    `AuthScopeDenied`; every other error → the `SessionApiFailed` default. A 404 with
+    an unrecognized code stays generic — the error_code is the discriminator, never a
+    bare 404→hidden (this route is NOT hide-existence)."""
+    assert agent_id and isinstance(agent_id, str)
+    try:
+        return await client.agents.persona_state(agent_id)
+    except ApiError as exc:
+        if exc.status == 404 and exc.error_code == "persona_not_configured":
+            raise PersonaNotConfigured(agent_id=agent_id) from exc
+        if exc.status == 404 and exc.error_code == "agent_not_available":
+            raise PersonaAgentNotAvailable(agent_id=agent_id) from exc
+        if exc.status == 403 and exc.error_code == "auth_scope_denied":
+            raise AuthScopeDenied(scope="persona.read") from exc
+        raise translate_error(exc) from exc
+
+
+async def define_agent(
+    client: WorldtreeClient, *, agent_name: str, system_prompt: str, role: str
+) -> Mapping[str, Any]:
+    """Define a Tier-3 consumer agent (POST /agents/define). Sends the
+    `AgentDefineInput` body `{agent_name, role, system_prompt}` and returns the SDK's
+    open-world `DefinedAgent` dict verbatim (echoes `role` post-b128 — read
+    `info["role"]`, no `Tier3AgentInfo`). The slug is validated client-side pre-HTTP
+    (server-side is the safety net). Error map (INV-CUT-2): 429 →
+    `Tier3QuotaExceeded(retry_after=0)` — the SDK's `ApiError` floor drops the
+    `Retry-After` header, and §2675 pins Phase-2.0 quota to 0; 403
+    `tier3_user_id_unsupported` → `Tier3UserIdUnsupported`; 422 `layer_deferred` →
+    `Tier3LayerDeferred(field)`; else the `SessionApiFailed` default."""
+    assert _AGENT_SLUG_RE.match(agent_name), (
+        f"agent_name must match [a-z][a-z0-9-]{{2,63}}: {agent_name!r}"
+    )
+    assert system_prompt and isinstance(system_prompt, str)
+    assert role and isinstance(role, str)
+    try:
+        # Inline literal so it type-checks structurally against the SDK's
+        # AgentDefineInput TypedDict (no import of the SDK's private `_types`).
+        return await client.agents.define(
+            {"agent_name": agent_name, "role": role, "system_prompt": system_prompt}
+        )
+    except ApiError as exc:
+        if exc.status == 429:
+            raise Tier3QuotaExceeded(retry_after=0) from exc
+        if exc.status == 403 and exc.error_code == "tier3_user_id_unsupported":
+            raise Tier3UserIdUnsupported() from exc
+        if exc.status == 422 and exc.error_code == "layer_deferred":
+            raise Tier3LayerDeferred(field=_error_field_from_body(exc.body)) from exc
+        raise translate_error(exc) from exc
+
+
+async def patch_agent(
+    client: WorldtreeClient,
+    agent_id: str,
+    *,
+    system_prompt: str | None = None,
+    role: str | None = None,
+) -> Mapping[str, Any]:
+    """Mutate a Tier-3 agent (PATCH /agents/{id}). At least one of `system_prompt` /
+    `role` is required; the None-valued field is omitted from the body. Returns the
+    open-world `PatchedAgent` dict verbatim. Error map (INV-CUT-2): 404 →
+    `Tier3AgentNotFound` (agents CRUD is NOT hide-existence); 422 `field_not_mutable`
+    → `Tier3FieldNotMutable(field)`; else the `SessionApiFailed` default."""
+    assert ":" in agent_id, f"tier 3 agent_id must contain ':': {agent_id!r}"
+    assert system_prompt is not None or role is not None, (
+        "patch requires at least one of system_prompt or role"
+    )
+    changes: dict[str, Any] = {}
+    if system_prompt is not None:
+        changes["system_prompt"] = system_prompt
+    if role is not None:
+        changes["role"] = role
+    try:
+        return await client.agents.patch(agent_id, changes)
+    except ApiError as exc:
+        if exc.status == 404:
+            raise Tier3AgentNotFound(agent_id=agent_id) from exc
+        if exc.status == 422 and exc.error_code == "field_not_mutable":
+            raise Tier3FieldNotMutable(field=_error_field_from_body(exc.body)) from exc
+        raise translate_error(exc) from exc
+
+
+async def delete_agent(client: WorldtreeClient, agent_id: str) -> None:
+    """Hard-delete a Tier-3 agent (DELETE /agents/{id}); resolves on 204 → None. Error
+    map (INV-CUT-2): 404 → `Tier3AgentNotFound` (route-discriminated; NOT
+    hide-existence); else the `SessionApiFailed` default."""
+    assert ":" in agent_id, f"tier 3 agent_id must contain ':': {agent_id!r}"
+    try:
+        await client.agents.delete(agent_id)
+    except ApiError as exc:
+        if exc.status == 404:
+            raise Tier3AgentNotFound(agent_id=agent_id) from exc
+        raise translate_error(exc) from exc
@@ -1950,6 +1950,20 @@ class TestTier2Probes:
        )
        assert rc == 10

+    @respx.mock
+    def test_set_persona_probe_connect_failed(self, capsys: pytest.CaptureFixture[str]) -> None:
+        """connect_failed [error-path]: a transport failure the SDK normalizes to
+        ConnectFailed → graceful [network_error], exit 21 (not an uncaught crash)."""
+        respx.post("https://w.example/sessions/s1/persona_state").mock(
+            side_effect=httpx.ConnectError("refused")
+        )
+        rc = main(
+            ["--set-persona-pad", "0.4,0.1,-0.2", "--session", "s1",
+             "--api-key", "k", "--server", "https://w.example"]
+        )
+        assert rc == 21
+        assert "[network_error]" in capsys.readouterr().err
+

 class TestSeedFirstMessageProbe:
    """--seed-first-message one-shot (#347 authored-history-write reference-consumer probe)."""
@@ -2066,3 +2080,17 @@ class TestSeedFirstMessageProbe:
        assert rc == 0
        assert "feature-absent" in capsys.readouterr().out
        assert msgs_route.call_count == 0  # never capability-probes past the 404
+
+    @respx.mock
+    def test_seed_probe_connect_failed(self, capsys: pytest.CaptureFixture[str]) -> None:
+        """connect_failed [error-path]: a transport failure on create that the SDK
+        normalizes to ConnectFailed → graceful [network_error], exit 21."""
+        respx.post("https://w.example/sessions").mock(
+            side_effect=httpx.ConnectError("refused")
+        )
+        rc = main(
+            ["--seed-first-message", "hello", "--agent", "mimir",
+             "--api-key", "k", "--server", "https://w.example"]
+        )
+        assert rc == 21
+        assert "[network_error]" in capsys.readouterr().err
@@ -33,14 +33,14 @@ def local_path(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
 def _entry(
    agent_id: str = "ratatoskr:wizard",
    agent_name: str = "wizard",
-    model: str = "qwen3.6-35-a3b",
+    role: str = "qwen3.6-35-a3b",
    description: str = "(tier 3) test agent",
    defined_at: str = "2026-05-25T00:00:00+00:00",
 ) -> LocalAgentEntry:
    return LocalAgentEntry(
        agent_id=agent_id,
        agent_name=agent_name,
-        model=model,
+        role=role,
        description=description,
        defined_at=defined_at,
    )
@@ -91,13 +91,13 @@ class TestLoadEmpty:
        local_path.write_text(
            json.dumps(
                {
-                    "version": 1,
+                    "version": 2,
                    "agents": [
                        {"agent_id": "incomplete"},  # missing required fields
                        {
                            "agent_id": "ratatoskr:good",
                            "agent_name": "good",
-                            "model": "m",
+                            "role": "m",
                            "description": "d",
                            "defined_at": "t",
                        },
@@ -124,11 +124,11 @@ class TestAdd:
        assert ids == {"ratatoskr:a", "ratatoskr:b"}

    def test_add_replaces_same_id(self, local_path: Path) -> None:
-        add_local_agent(_entry(model="old-model"))
-        add_local_agent(_entry(model="new-model"))
+        add_local_agent(_entry(role="old-role"))
+        add_local_agent(_entry(role="new-role"))
        entries = load_local_agents()
        assert len(entries) == 1
-        assert entries[0].model == "new-model"
+        assert entries[0].role == "new-role"

    def test_creates_parent_dirs(
        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
@@ -141,11 +141,11 @@ class TestAdd:

 class TestUpdate:
    def test_update_changes_existing(self, local_path: Path) -> None:
-        add_local_agent(_entry(model="v1"))
-        update_local_agent(_entry(model="v2"))
+        add_local_agent(_entry(role="v1"))
+        update_local_agent(_entry(role="v2"))
        entries = load_local_agents()
        assert len(entries) == 1
-        assert entries[0].model == "v2"
+        assert entries[0].role == "v2"


 class TestRemove:
@@ -5,10 +5,6 @@ import pytest
 import respx

 from ratatoskr.sessions import (
-    AgentInfo,
-    AgentNotAvailable,
-    AuthScopeDenied,
-    PersonaNotConfigured,
    SessionApiFailed,
    create_character,
    delete_character,
@@ -16,9 +12,7 @@ from ratatoskr.sessions import (
    get_capabilities,
    get_character_state,
    get_me,
-    get_persona_state,
    get_session_bifrost,
-    list_agents,
    list_character_models,
 )

@@ -44,288 +38,6 @@ class TestEndpointForPlane:
            endpoint_for_plane("persona", "10.100.10.50")


-class TestListAgents:
-    @respx.mock
-    async def test_happy_full_shape(self) -> None:
-        """happy_full_shape [happy,tracer]: spec full-shape mimir example → all fields."""
-        respx.get("https://w.example/agents").mock(
-            return_value=httpx.Response(
-                200,
-                json=[
-                    {
-                        "agent_id": "mimir",
-                        "name": "Mimir",
-                        "description": "Keeper of the Well of Knowledge.",
-                        "version": "0.2.0",
-                        "capabilities": ["knowledge_base", "semantic_search"],
-                        "supported_models": ["default", "heavy"],
-                        "persona_traits": {
-                            "ocean": {
-                                "openness": 0.7,
-                                "conscientiousness": 0.9,
-                                "extraversion": 0.1,
-                                "agreeableness": 0.5,
-                                "neuroticism": 0.3,
-                            },
-                            "vibe": "contemplative",
-                        },
-                        "ui_hints": {"icon": "well", "color_hint": "#5b8aa3"},
-                    }
-                ],
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            agents = await list_agents(client)
-        assert len(agents) == 1
-        a = agents[0]
-        assert isinstance(a, AgentInfo)
-        assert a.agent_id == "mimir"
-        assert a.name == "Mimir"
-        assert a.description == "Keeper of the Well of Knowledge."
-        assert a.version == "0.2.0"
-        assert a.capabilities == ["knowledge_base", "semantic_search"]
-        assert a.supported_models == ["default", "heavy"]
-        assert a.persona_traits["vibe"] == "contemplative"
-        assert a.ui_hints["icon"] == "well"
-
-    @respx.mock
-    async def test_happy_minimum_shape(self) -> None:
-        """happy_minimum_shape: required-only agent → optional fields default."""
-        respx.get("https://w.example/agents").mock(
-            return_value=httpx.Response(
-                200,
-                json=[
-                    {
-                        "agent_id": "minimal",
-                        "name": "Minimal Agent",
-                        "description": "Just a sketch.",
-                    }
-                ],
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            agents = await list_agents(client)
-        a = agents[0]
-        assert a.agent_id == "minimal"
-        assert a.version is None
-        assert a.capabilities == []
-        assert a.supported_models == []
-        assert a.persona_traits == {}
-        assert a.ui_hints == {}
-
-    @respx.mock
-    async def test_happy_multi_agent(self) -> None:
-        """happy_multi_agent: 3 agents preserve order."""
-        respx.get("https://w.example/agents").mock(
-            return_value=httpx.Response(
-                200,
-                json=[
-                    {"agent_id": "a", "name": "A", "description": "x"},
-                    {"agent_id": "b", "name": "B", "description": "y"},
-                    {"agent_id": "c", "name": "C", "description": "z"},
-                ],
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            agents = await list_agents(client)
-        assert [a.agent_id for a in agents] == ["a", "b", "c"]
-
-    @respx.mock
-    async def test_happy_empty(self) -> None:
-        """happy_empty: 200 with [] returns empty list (no error)."""
-        respx.get("https://w.example/agents").mock(return_value=httpx.Response(200, json=[]))
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            agents = await list_agents(client)
-        assert agents == []
-
-    @respx.mock
-    async def test_omit_capabilities_empty_list(self) -> None:
-        """omit_capabilities_empty: explicit [] from server still defaults to []."""
-        respx.get("https://w.example/agents").mock(
-            return_value=httpx.Response(
-                200,
-                json=[
-                    {
-                        "agent_id": "a",
-                        "name": "A",
-                        "description": "x",
-                        "capabilities": [],
-                    }
-                ],
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            agents = await list_agents(client)
-        assert agents[0].capabilities == []
-
-    @respx.mock
-    async def test_500_raises_session_api_failed(self) -> None:
-        """500 → SessionApiFailed with status=500."""
-        respx.get("https://w.example/agents").mock(
-            return_value=httpx.Response(500, content=b"oops")
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(SessionApiFailed) as excinfo:
-                await list_agents(client)
-        assert excinfo.value.status == 500
-
-    @respx.mock
-    async def test_401_raises_session_api_failed(self) -> None:
-        """401 → SessionApiFailed with status=401."""
-        respx.get("https://w.example/agents").mock(
-            return_value=httpx.Response(401, content=b'{"error":"unauthorized"}')
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(SessionApiFailed) as excinfo:
-                await list_agents(client)
-        assert excinfo.value.status == 401
-
-
-class TestGetPersonaState:
-    """Worldtree #204 / v0.28.0 — GET /agents/{agent_id}/persona_state.
-
-    Bootstrap read for the persona snapshot — same shape as `affect_update`'s
-    `current` snapshot. Auth via `persona.read` scope (user-tier default).
-    """
-
-    @respx.mock
-    async def test_happy_full_snapshot(self) -> None:
-        """happy_full_snapshot [happy,tracer]: 200 → snapshot dict with pad +
-        dominant_emotion + emotions_active + baseline_pad + mood_drift.
-        """
-        snapshot = {
-            "agent_id": "mimir",
-            "pad": {"pleasure": 0.52, "arousal": 0.47, "dominance": 0.50},
-            "dominant_emotion": "curiosity",
-            "emotions_active": [
-                {"type": "curiosity", "intensity": 0.6, "decay_remaining_s": 202.7}
-            ],
-            "baseline_pad": {"pleasure": 0.50, "arousal": 0.40, "dominance": 0.50},
-            "mood_drift": {"valence_delta": 0.02, "arousal_delta": 0.07},
-            "last_updated_at": "2026-05-25T22:30:18+00:00",
-        }
-        respx.get("https://w.example/agents/mimir/persona_state").mock(
-            return_value=httpx.Response(200, json=snapshot)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            result = await get_persona_state(client, "mimir")
-        assert result == snapshot
-
-    @respx.mock
-    async def test_persona_not_configured_404(self) -> None:
-        """persona_not_configured_404 [error]: 404 with error_code
-        persona_not_configured → PersonaNotConfigured. Agent exists but has
-        no persona surface (e.g. domari, muninn, Tier 3).
-        """
-        respx.get("https://w.example/agents/domari/persona_state").mock(
-            return_value=httpx.Response(
-                404, json={"error_code": "persona_not_configured", "message": "no persona"}
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(PersonaNotConfigured) as exc_info:
-                await get_persona_state(client, "domari")
-        assert exc_info.value.agent_id == "domari"
-
-    @respx.mock
-    async def test_agent_not_available_404(self) -> None:
-        """agent_not_available_404 [error]: 404 with error_code
-        agent_not_available → AgentNotAvailable. Distinct from
-        persona_not_configured — the agent_id itself is unknown.
-        """
-        respx.get("https://w.example/agents/bogus/persona_state").mock(
-            return_value=httpx.Response(
-                404, json={"error_code": "agent_not_available", "message": "unknown agent"}
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(AgentNotAvailable) as exc_info:
-                await get_persona_state(client, "bogus")
-        assert exc_info.value.agent_id == "bogus"
-
-    @respx.mock
-    async def test_auth_scope_denied_403(self) -> None:
-        """auth_scope_denied_403 [error]: 403 with error_code auth_scope_denied
-        → AuthScopeDenied. Key lacks `persona.read` scope.
-        """
-        respx.get("https://w.example/agents/mimir/persona_state").mock(
-            return_value=httpx.Response(
-                403,
-                json={"error_code": "auth_scope_denied", "message": "missing persona.read"},
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(AuthScopeDenied) as exc_info:
-                await get_persona_state(client, "mimir")
-        assert exc_info.value.scope == "persona.read"
-
-    @respx.mock
-    async def test_404_unknown_error_code_falls_through(self) -> None:
-        """404_unknown_error_code_falls_through [adversarial]: 404 without the
-        two known error codes → SessionApiFailed (don't swallow novel failure
-        modes as something more specific than they are).
-        """
-        respx.get("https://w.example/agents/mimir/persona_state").mock(
-            return_value=httpx.Response(404, json={"error_code": "novel_404"})
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(SessionApiFailed) as exc_info:
-                await get_persona_state(client, "mimir")
-        assert exc_info.value.status == 404
-
-    @respx.mock
-    async def test_500_unexpected_status(self) -> None:
-        """500_unexpected_status [error]: 5xx → SessionApiFailed (matches the
-        list_agents / list_sessions / create_session precedent)."""
-        respx.get("https://w.example/agents/mimir/persona_state").mock(
-            return_value=httpx.Response(500, content=b"boom")
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(SessionApiFailed) as exc_info:
-                await get_persona_state(client, "mimir")
-        assert exc_info.value.status == 500
-
-    @respx.mock
-    async def test_auth_scope_denied_detail_envelope(self) -> None:
-        """auth_scope_denied_detail_envelope [regression]: real Worldtree
-        returns `{"detail": {"error_code": "auth_scope_denied", …}}`
-        (FastAPI default), not flat `{"error_code": …}`. Smoke against
-        personal:8081 2026-05-28 surfaced this — pre-fix the response
-        fell through to SessionApiFailed(403) instead of AuthScopeDenied.
-        """
-        respx.get("https://w.example/agents/mimir/persona_state").mock(
-            return_value=httpx.Response(
-                403,
-                json={
-                    "detail": {
-                        "error_code": "auth_scope_denied",
-                        "message": "Missing required scope: persona.read",
-                    }
-                },
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(AuthScopeDenied) as exc_info:
-                await get_persona_state(client, "mimir")
-        assert exc_info.value.scope == "persona.read"
-
-    @respx.mock
-    async def test_persona_not_configured_detail_envelope(self) -> None:
-        """persona_not_configured_detail_envelope [regression]: same
-        envelope-shape unwrap on 404 + persona_not_configured.
-        """
-        respx.get("https://w.example/agents/domari/persona_state").mock(
-            return_value=httpx.Response(
-                404,
-                json={"detail": {"error_code": "persona_not_configured"}},
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(PersonaNotConfigured) as exc_info:
-                await get_persona_state(client, "domari")
-        assert exc_info.value.agent_id == "domari"
-
-
 class TestGetMe:
    """docs/contracts/issues/2.contract.md FN get_me (slice: capabilities+me)."""

@@ -1,4 +1,14 @@
-"""Tests for ratatoskr.tier3 per docs/contracts/issues/15.contract.md."""
+"""CLI integration tests for `python -m ratatoskr.tier3`.
+
+The define/patch/delete wire calls route through the worldtree-sdk adapter
+(`ratatoskr.wt`); the adapter's body-building + error-mapping are unit-tested in
+`test_wt.py` (against a fake `client.agents`). These tests exercise the CLI
+end-to-end — argv → the real SDK over a respx-mocked HTTP layer → exit code +
+stdout + the local tier3 index side effects.
+
+The define/patch response echoes `role` (Worldtree spec 1.2 / b128), read off the
+SDK's open-world dict; `LocalAgentEntry.role` is the v2-schema field.
+"""

 from pathlib import Path

@@ -6,317 +16,20 @@ import httpx
 import pytest
 import respx

-from ratatoskr.sessions import SessionApiFailed
-from ratatoskr.tier3 import (
-    Tier3AgentInfo,
-    Tier3AgentNotFound,
-    Tier3FieldNotMutable,
-    Tier3LayerDeferred,
-    Tier3QuotaExceeded,
-    Tier3UserIdUnsupported,
-    define_agent,
-    delete_agent,
-    main,
-    patch_agent,
-)
+from ratatoskr.tier3 import main

+# The consumer-agent response echoes `role` (b128), not the former `model`.
 _FULL_AGENT_RESP = {
    "agent_id": "ratatoskr:wizard",
    "user_id": "ratatoskr",
    "agent_name": "wizard",
    "system_prompt": "You are a wizard.",
-    "model": "qwen3.6-35-a3b",
+    "role": "qwen3.6-35-a3b",
    "created_at": "2026-05-25T03:20:09.703601+00:00",
    "updated_at": "2026-05-25T03:20:09.703601+00:00",
 }


-class TestDefineAgent:
-    @respx.mock
-    async def test_happy_define(self) -> None:
-        """happy_define [happy,tracer]: 201 → fully populated Tier3AgentInfo."""
-        respx.post("https://w.example/agents/define").mock(
-            return_value=httpx.Response(201, json=_FULL_AGENT_RESP)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            info = await define_agent(
-                client,
-                agent_name="wizard",
-                system_prompt="You are a wizard.",
-                role="qwen3.6-35-a3b",
-            )
-        assert isinstance(info, Tier3AgentInfo)
-        assert info.agent_id == "ratatoskr:wizard"
-        assert info.user_id == "ratatoskr"
-        assert info.agent_name == "wizard"
-        assert info.model == "qwen3.6-35-a3b"
-
-    @respx.mock
-    async def test_request_body_shape(self) -> None:
-        """request_body_shape [trace]: outbound JSON is exactly the three keys."""
-        import json as _json
-
-        route = respx.post("https://w.example/agents/define").mock(
-            return_value=httpx.Response(201, json=_FULL_AGENT_RESP)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            await define_agent(
-                client,
-                agent_name="wizard",
-                system_prompt="You are a wizard.",
-                role="qwen3.6-35-a3b",
-            )
-        body = _json.loads(route.calls[0].request.content)
-        # INV-001: exactly these three keys — no layer fields, no metadata.
-        assert body == {
-            "agent_name": "wizard",
-            "system_prompt": "You are a wizard.",
-            "role": "qwen3.6-35-a3b",
-        }
-
-    @respx.mock
-    async def test_quota_exceeded(self) -> None:
-        """quota_exceeded [error]: 429 + Retry-After → Tier3QuotaExceeded."""
-        respx.post("https://w.example/agents/define").mock(
-            return_value=httpx.Response(
-                429,
-                headers={"Retry-After": "0"},
-                json={"detail": {"error_code": "agent_quota_exceeded"}},
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(Tier3QuotaExceeded) as exc:
-                await define_agent(
-                    client,
-                    agent_name="overflow",
-                    system_prompt="x",
-                    role="m",
-                )
-        assert exc.value.retry_after == 0
-
-    @respx.mock
-    async def test_user_id_unsupported(self) -> None:
-        """user_id_unsupported [error]: 403 + error_code → Tier3UserIdUnsupported."""
-        respx.post("https://w.example/agents/define").mock(
-            return_value=httpx.Response(
-                403, json={"detail": {"error_code": "tier3_user_id_unsupported"}}
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(Tier3UserIdUnsupported):
-                await define_agent(
-                    client, agent_name="wizard", system_prompt="x", role="m"
-                )
-
-    @respx.mock
-    async def test_layer_deferred(self) -> None:
-        """layer_deferred [error]: 422 + layer_deferred → Tier3LayerDeferred(field)."""
-        respx.post("https://w.example/agents/define").mock(
-            return_value=httpx.Response(
-                422,
-                json={"detail": {"error_code": "layer_deferred", "field": "persona"}},
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(Tier3LayerDeferred) as exc:
-                await define_agent(
-                    client, agent_name="wizard", system_prompt="x", role="m"
-                )
-        assert exc.value.field == "persona"
-
-    @respx.mock
-    async def test_bad_slug_assert(self) -> None:
-        """bad_slug_assert [adversarial]: agent_name with uppercase → AssertionError, no HTTP."""
-        route = respx.post("https://w.example/agents/define").mock(
-            return_value=httpx.Response(201, json=_FULL_AGENT_RESP)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(AssertionError):
-                await define_agent(
-                    client, agent_name="Wizard", system_prompt="x", role="m"
-                )
-        assert route.call_count == 0
-
-    @respx.mock
-    async def test_short_slug_assert(self) -> None:
-        """short_slug_assert [adversarial]: agent_name len < 3 → AssertionError."""
-        route = respx.post("https://w.example/agents/define").mock(
-            return_value=httpx.Response(201, json=_FULL_AGENT_RESP)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(AssertionError):
-                await define_agent(
-                    client, agent_name="ab", system_prompt="x", role="m"
-                )
-        assert route.call_count == 0
-
-    @respx.mock
-    async def test_empty_prompt_assert(self) -> None:
-        """empty_prompt_assert [adversarial]: empty system_prompt → AssertionError."""
-        route = respx.post("https://w.example/agents/define").mock(
-            return_value=httpx.Response(201, json=_FULL_AGENT_RESP)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(AssertionError):
-                await define_agent(
-                    client, agent_name="wizard", system_prompt="", role="m"
-                )
-        assert route.call_count == 0
-
-    @respx.mock
-    async def test_other_5xx(self) -> None:
-        """other_5xx [error]: 503 → SessionApiFailed(status=503)."""
-        respx.post("https://w.example/agents/define").mock(
-            return_value=httpx.Response(503, content=b"upstream out")
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(SessionApiFailed) as exc:
-                await define_agent(
-                    client, agent_name="wizard", system_prompt="x", role="m"
-                )
-        assert exc.value.status == 503
-
-
-class TestPatchAgent:
-    @respx.mock
-    async def test_happy_patch_both_fields(self) -> None:
-        """happy_patch_both_fields: both fields set → request body has both."""
-        import json as _json
-
-        updated = {
-            **_FULL_AGENT_RESP,
-            "system_prompt": "new prompt",
-            "model": "different-model",
-        }
-        route = respx.patch("https://w.example/agents/ratatoskr:wizard").mock(
-            return_value=httpx.Response(200, json=updated)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            info = await patch_agent(
-                client,
-                "ratatoskr:wizard",
-                system_prompt="new prompt",
-                role="different-model",
-            )
-        body = _json.loads(route.calls[0].request.content)
-        assert body == {"system_prompt": "new prompt", "role": "different-model"}
-        assert info.system_prompt == "new prompt"
-        assert info.model == "different-model"
-
-    @respx.mock
-    async def test_happy_patch_single_field(self) -> None:
-        """happy_patch_single_field: omit role → body has system_prompt only."""
-        import json as _json
-
-        updated = {**_FULL_AGENT_RESP, "system_prompt": "only this"}
-        route = respx.patch("https://w.example/agents/ratatoskr:wizard").mock(
-            return_value=httpx.Response(200, json=updated)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            await patch_agent(client, "ratatoskr:wizard", system_prompt="only this")
-        body = _json.loads(route.calls[0].request.content)
-        # INV-002: body omits the None-valued field entirely
-        assert body == {"system_prompt": "only this"}
-
-    @respx.mock
-    async def test_field_not_mutable(self) -> None:
-        """field_not_mutable [error]: 422 + error_code → Tier3FieldNotMutable(field)."""
-        respx.patch("https://w.example/agents/ratatoskr:wizard").mock(
-            return_value=httpx.Response(
-                422,
-                json={
-                    "detail": {"error_code": "field_not_mutable", "field": "agent_name"}
-                },
-            )
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(Tier3FieldNotMutable) as exc:
-                await patch_agent(
-                    client, "ratatoskr:wizard", system_prompt="x"
-                )
-        assert exc.value.field == "agent_name"
-
-    @respx.mock
-    async def test_404(self) -> None:
-        """404 [error]: PATCH on non-existent agent → Tier3AgentNotFound."""
-        respx.patch("https://w.example/agents/ratatoskr:ghost").mock(
-            return_value=httpx.Response(404, content=b"")
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(Tier3AgentNotFound) as exc:
-                await patch_agent(
-                    client, "ratatoskr:ghost", system_prompt="x"
-                )
-        assert exc.value.agent_id == "ratatoskr:ghost"
-
-    @respx.mock
-    async def test_no_fields_assert(self) -> None:
-        """no_fields_assert [adversarial]: both None → AssertionError, no HTTP."""
-        route = respx.patch("https://w.example/agents/ratatoskr:wizard").mock(
-            return_value=httpx.Response(200, json=_FULL_AGENT_RESP)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(AssertionError):
-                await patch_agent(client, "ratatoskr:wizard")
-        assert route.call_count == 0
-
-    @respx.mock
-    async def test_non_tier3_id_assert(self) -> None:
-        """non_tier3_id_assert [adversarial]: agent_id without `:` → AssertionError."""
-        route = respx.patch("https://w.example/agents/mimir").mock(
-            return_value=httpx.Response(200, json=_FULL_AGENT_RESP)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(AssertionError):
-                await patch_agent(client, "mimir", system_prompt="x")
-        assert route.call_count == 0
-
-
-class TestDeleteAgent:
-    @respx.mock
-    async def test_happy_delete(self) -> None:
-        """happy_delete [happy,tracer]: 204 → returns None."""
-        respx.delete("https://w.example/agents/ratatoskr:wizard").mock(
-            return_value=httpx.Response(204)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            result = await delete_agent(client, "ratatoskr:wizard")
-        assert result is None
-
-    @respx.mock
-    async def test_404(self) -> None:
-        """404 [error]: DELETE on non-existent agent → Tier3AgentNotFound."""
-        respx.delete("https://w.example/agents/ratatoskr:ghost").mock(
-            return_value=httpx.Response(404)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(Tier3AgentNotFound) as exc:
-                await delete_agent(client, "ratatoskr:ghost")
-        assert exc.value.agent_id == "ratatoskr:ghost"
-
-    @respx.mock
-    async def test_non_tier3_id_assert(self) -> None:
-        """non_tier3_id_assert [adversarial]: agent_id without `:` → AssertionError."""
-        route = respx.delete("https://w.example/agents/mimir").mock(
-            return_value=httpx.Response(204)
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(AssertionError):
-                await delete_agent(client, "mimir")
-        assert route.call_count == 0
-
-    @respx.mock
-    async def test_other_5xx(self) -> None:
-        """other_5xx [error]: 500 → SessionApiFailed."""
-        respx.delete("https://w.example/agents/ratatoskr:wizard").mock(
-            return_value=httpx.Response(500, content=b"oops")
-        )
-        async with httpx.AsyncClient(base_url="https://w.example") as client:
-            with pytest.raises(SessionApiFailed) as exc:
-                await delete_agent(client, "ratatoskr:wizard")
-        assert exc.value.status == 500
-
-
@pytest.fixture
 def _isolated_local_agents(
    tmp_path: "Path", monkeypatch: pytest.MonkeyPatch
@@ -335,8 +48,8 @@ class TestCli:
        monkeypatch: pytest.MonkeyPatch,
        _isolated_local_agents: "Path",
    ) -> None:
-        """cli_define_happy [happy]: argv → 201 mock → stdout confirmation;
-        local index updated with the new entry (v0.8.0 hook).
+        """cli_define_happy [happy,tracer]: argv → 201 mock → stdout confirmation;
+        local index updated with the new entry (role echoed).
        """
        from ratatoskr.local_agents import load_local_agents

@@ -354,11 +67,34 @@ class TestCli:
        out = capsys.readouterr()
        assert rc == 0
        assert out.out.strip() == "defined ratatoskr:wizard (qwen3.6-35-a3b)"
-        # v0.8.0: local index now has the new entry.
        entries = load_local_agents()
        assert len(entries) == 1
        assert entries[0].agent_id == "ratatoskr:wizard"
-        assert entries[0].model == "qwen3.6-35-a3b"
+        assert entries[0].role == "qwen3.6-35-a3b"
+
+    @respx.mock
+    def test_cli_define_body_shape(
+        self, monkeypatch: pytest.MonkeyPatch, _isolated_local_agents: "Path"
+    ) -> None:
+        """cli_define_body_shape [trace]: outbound JSON is exactly the three keys
+        (the adapter sends AgentDefineInput, no layer fields)."""
+        import json as _json
+
+        monkeypatch.setenv("WORLDTREE_API_URL", "https://w.example")
+        monkeypatch.setenv("WORLDTREE_API_KEY", "k")
+        route = respx.post("https://w.example/agents/define").mock(
+            return_value=httpx.Response(201, json=_FULL_AGENT_RESP)
+        )
+        main([
+            "define", "--name", "wizard",
+            "--system-prompt", "You are a wizard.", "--role", "qwen3.6-35-a3b",
+        ])
+        body = _json.loads(route.calls[0].request.content)
+        assert body == {
+            "agent_name": "wizard",
+            "role": "qwen3.6-35-a3b",
+            "system_prompt": "You are a wizard.",
+        }

    @respx.mock
    def test_cli_patch_happy(
@@ -384,6 +120,7 @@ class TestCli:
        entries = load_local_agents()
        assert len(entries) == 1
        assert entries[0].agent_id == "ratatoskr:wizard"
+        assert entries[0].role == "qwen3.6-35-a3b"

    @respx.mock
    def test_cli_delete_happy(
@@ -401,11 +138,11 @@ class TestCli:
            load_local_agents,
        )

-        # Pre-populate so we can verify removal.
+        # Pre-populate so we can verify removal (v2 schema: role, not model).
        add_local_agent(LocalAgentEntry(
            agent_id="ratatoskr:wizard",
            agent_name="wizard",
-            model="m",
+            role="m",
            description="d",
            defined_at="t",
        ))
@@ -426,10 +163,7 @@ class TestCli:
        """cli_missing_auth [error]: no api-key → stderr [auth_error] + exit 11."""
        monkeypatch.delenv("WORLDTREE_API_KEY", raising=False)
        rc = main([
-            "define",
-            "--name", "wizard",
-            "--system-prompt", "x",
-            "--role", "m",
+            "define", "--name", "wizard", "--system-prompt", "x", "--role", "m",
        ])
        err = capsys.readouterr().err
        assert rc == 11
@@ -446,10 +180,7 @@ class TestCli:
            return_value=httpx.Response(500, content=b"upstream out")
        )
        rc = main([
-            "define",
-            "--name", "wizard",
-            "--system-prompt", "x",
-            "--role", "m",
+            "define", "--name", "wizard", "--system-prompt", "x", "--role", "m",
        ])
        err = capsys.readouterr().err
        assert rc == 20
@@ -470,15 +201,30 @@ class TestCli:
            )
        )
        rc = main([
-            "define",
-            "--name", "wizard",
-            "--system-prompt", "x",
-            "--role", "m",
+            "define", "--name", "wizard", "--system-prompt", "x", "--role", "m",
        ])
        err = capsys.readouterr().err
        assert rc == 20
        assert "[quota_exceeded]" in err

+    @respx.mock
+    def test_cli_network_error(
+        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """cli_network_error [error]: a transport failure surfaces as the SDK's
+        ConnectFailed (not a raw httpx error) → stderr [network_error] + exit 21."""
+        monkeypatch.setenv("WORLDTREE_API_URL", "https://w.example")
+        monkeypatch.setenv("WORLDTREE_API_KEY", "k")
+        respx.post("https://w.example/agents/define").mock(
+            side_effect=httpx.ConnectError("refused")
+        )
+        rc = main([
+            "define", "--name", "wizard", "--system-prompt", "x", "--role", "m",
+        ])
+        err = capsys.readouterr().err
+        assert rc == 21
+        assert "[network_error]" in err
+
    def test_cli_patch_no_fields(
        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
    ) -> None:
@@ -489,3 +235,52 @@ class TestCli:
        err = capsys.readouterr().err
        assert rc == 10
        assert "[usage_error]" in err
+
+    @respx.mock
+    def test_cli_define_partial_response_degrades(
+        self,
+        capsys: pytest.CaptureFixture[str],
+        monkeypatch: pytest.MonkeyPatch,
+        _isolated_local_agents: "Path",
+    ) -> None:
+        """cli_define_partial [error]: a 201 missing `role` + a NULL system_prompt
+        degrades (role '?', description-safe) and exits 0 — never a KeyError/
+        AttributeError traceback (heid-bug-hunt open-world invariant)."""
+        from ratatoskr.local_agents import load_local_agents
+
+        monkeypatch.setenv("WORLDTREE_API_URL", "https://w.example")
+        monkeypatch.setenv("WORLDTREE_API_KEY", "k")
+        respx.post("https://w.example/agents/define").mock(
+            return_value=httpx.Response(201, json={
+                "agent_id": "ratatoskr:wizard", "agent_name": "wizard",
+                "system_prompt": None,  # present-but-null: .get(...,'') would NOT default
+            })
+        )
+        rc = main([
+            "define", "--name", "wizard", "--system-prompt", "x", "--role", "m",
+        ])
+        out = capsys.readouterr()
+        assert rc == 0
+        assert out.out.strip() == "defined ratatoskr:wizard (?)"
+        # Well-formed identity → still indexed (role degraded to '?').
+        entries = load_local_agents()
+        assert len(entries) == 1
+        assert entries[0].role == "?"
+
+    @respx.mock
+    def test_cli_define_no_agent_id_is_api_failure(
+        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """cli_define_no_agent_id [error]: a 2xx with no usable agent_id → [api_failed]
+        + exit 20 (controlled), not an uncaught traceback."""
+        monkeypatch.setenv("WORLDTREE_API_URL", "https://w.example")
+        monkeypatch.setenv("WORLDTREE_API_KEY", "k")
+        respx.post("https://w.example/agents/define").mock(
+            return_value=httpx.Response(201, json={"role": "m"})  # no agent_id
+        )
+        rc = main([
+            "define", "--name", "wizard", "--system-prompt", "x", "--role", "m",
+        ])
+        err = capsys.readouterr().err
+        assert rc == 20
+        assert "[api_failed]" in err
@@ -66,7 +66,7 @@ class TestAgentsEndpoint:
            LocalAgentEntry(
                agent_id="ratatoskr:sindra",
                agent_name="sindra",
-                model="artemis-31b-v1i",
+                role="artemis-31b-v1i",
                description="(tier 3) IDENTITY",
                defined_at="2026-05-28T00:00:00+00:00",
            )
@@ -118,7 +118,7 @@ class TestAgentsEndpoint:
        from ratatoskr.local_agents import LocalAgentEntry, add_local_agent
        add_local_agent(
            LocalAgentEntry(
-                agent_id="ratatoskr:sindra", agent_name="sindra", model="m",
+                agent_id="ratatoskr:sindra", agent_name="sindra", role="m",
                description="local-tier3", defined_at="2026-05-28T00:00:00+00:00",
            )
        )
@@ -132,6 +132,57 @@ class TestAgentsEndpoint:
        # Upstream entry wins (it's first in the merge); local is deduped
        assert body[0]["name"] == "Sindra-from-server"

+    @respx.mock
+    def test_malformed_upstream_items_degrade_not_500(self, monkeypatch, tmp_path) -> None:
+        """malformed_upstream [error]: a non-mapping / agent_id-less upstream item is
+        dropped, not crashed on — the endpoint degrades to the well-formed + local
+        merge (heid-bug-hunt: open-world reads degrade, never crash)."""
+        monkeypatch.setenv("RATATOSKR_LOCAL_AGENTS", str(tmp_path / "local_agents.json"))
+        respx.get("https://w.example/agents").mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {"agent_id": "mimir", "name": "Mimir", "description": "k"},
+                    {},                       # no agent_id — dropped
+                    {"name": "Ghost"},        # no agent_id — dropped
+                    "not-a-mapping",          # non-mapping — dropped
+                    {"agent_id": 123},        # non-str agent_id — dropped
+                ],
+            )
+        )
+        from ratatoskr.local_agents import LocalAgentEntry, add_local_agent
+        add_local_agent(LocalAgentEntry(
+            agent_id="ratatoskr:local", agent_name="local", role="m",
+            description="d", defined_at="t",
+        ))
+        from ratatoskr.web.server import create_app
+        app = create_app(_mock_client_factory())
+        resp = TestClient(app).get("/api/agents")
+        assert resp.status_code == 200
+        ids = {a["agent_id"] for a in resp.json()}
+        # Only the one well-formed upstream item + the local entry survive.
+        assert ids == {"mimir", "ratatoskr:local"}
+
+    @respx.mock
+    def test_non_list_upstream_falls_back_to_local(self, monkeypatch, tmp_path) -> None:
+        """non_list_upstream [error]: an envelope (non-list) upstream body degrades to
+        the local-only list rather than iterating dict keys into a crash."""
+        monkeypatch.setenv("RATATOSKR_LOCAL_AGENTS", str(tmp_path / "local_agents.json"))
+        respx.get("https://w.example/agents").mock(
+            return_value=httpx.Response(200, json={"items": [{"agent_id": "mimir"}]})
+        )
+        from ratatoskr.local_agents import LocalAgentEntry, add_local_agent
+        add_local_agent(LocalAgentEntry(
+            agent_id="ratatoskr:local", agent_name="local", role="m",
+            description="d", defined_at="t",
+        ))
+        from ratatoskr.web.server import create_app
+        app = create_app(_mock_client_factory())
+        resp = TestClient(app).get("/api/agents")
+        assert resp.status_code == 200
+        ids = {a["agent_id"] for a in resp.json()}
+        assert ids == {"ratatoskr:local"}
+

 _CREATE_OK = {
    "session_id": "s-1",
@@ -290,6 +341,20 @@ class TestPersonaStateEndpoint:
        assert resp.status_code == 403
        assert resp.json()["error_code"] == "auth_scope_denied"

+    @respx.mock
+    def test_unmatched_error_maps_to_session_api_failed(self) -> None:
+        """unmatched_error [error]: an upstream 500 (unmapped ApiError) → the
+        session_api_failed envelope carrying the upstream status, for parity with
+        _agents_endpoint (heid-code-review slice-4 fixup — was a raw 500 escape)."""
+        respx.get("https://w.example/agents/mimir/persona_state").mock(
+            return_value=httpx.Response(500, content=b"upstream out")
+        )
+        from ratatoskr.web.server import create_app
+        app = create_app(_mock_client_factory())
+        resp = TestClient(app).get("/api/agents/mimir/persona_state")
+        assert resp.status_code == 500
+        assert resp.json()["error_code"] == "session_api_failed"
+

 class TestSubmitTurnEndpoint:
    """submit_turn_endpoint FN — allocate turn_id, register in turn_registry."""
@@ -19,13 +19,23 @@ import pytest
 import worldtree_sdk as wtsdk
 from worldtree_sdk import ApiError, CancelResult, PadState, WorldtreeClient

+from ratatoskr.sessions import (
+    AgentNotAvailable as PersonaAgentNotAvailable,
+)
 from ratatoskr.sessions import (
    AgentNotFound,
    AuthoredHistoryUnavailable,
+    AuthScopeDenied,
    BifrostBinding,
    BifrostConsumerKeyMissing,
    BifrostHandshakeFailed,
    InvalidCursor,
+    PersonaNotConfigured,
+    Tier3AgentNotFound,
+    Tier3FieldNotMutable,
+    Tier3LayerDeferred,
+    Tier3QuotaExceeded,
+    Tier3UserIdUnsupported,
 )
 from ratatoskr.sse_client import (
    AgentNotAvailable,
@@ -44,9 +54,14 @@ from ratatoskr.wt import (
    build_client,
    cancel_turn,
    create_session,
+    define_agent,
+    delete_agent,
+    get_persona_state,
    get_session_messages,
    get_session_tools,
+    list_agents,
    list_sessions,
+    patch_agent,
    set_persona_state,
    stream_turn,
    translate_error,
@@ -482,6 +497,16 @@ class TestSetPersonaState:
            await set_persona_state(_wt(fake), "s", pleasure=0.0, arousal=0.0, dominance=0.0)
        assert ei.value.status == 500

+    async def test_non_finite_pad_rejected_at_the_chokepoint(self) -> None:
+        # The finite-PAD invariant is enforced at the adapter (not only the CLI): a
+        # non-finite axis would serialize to null and corrupt the injection, so a
+        # direct caller is rejected pre-SDK — never a leaked SDK ConfigurationError.
+        fake = _FakeSessions(result=None)
+        for bad in (float("nan"), float("inf"), float("-inf")):
+            with pytest.raises(AssertionError):
+                await set_persona_state(_wt(fake), "s", pleasure=bad, arousal=0.0, dominance=0.0)
+        assert fake.calls == []  # never reached the SDK
+

 class TestWriteAuthoredHistory:
    """slice-3: write_authored_history → SDK sessions.write_history. Builds the
@@ -518,3 +543,309 @@ class TestWriteAuthoredHistory:
        with pytest.raises(SessionApiFailed) as ei:
            await write_authored_history(_wt(fake), "s", content="hi", idempotency_key="k")
        assert ei.value.status == 409
+
+
+# ── slice-4: agents (Tier-3) adapter routes ──────────────────────────────────
+
+
+class _FakeAgents:
+    """Stand-in for `WorldtreeClient.agents` — records the last call and returns a
+    canned result or raises a canned error. Same shape as `_FakeSessions`."""
+
+    def __init__(self, *, result: Any = None, error: BaseException | None = None) -> None:
+        self._result = result
+        self._error = error
+        self.calls: list[tuple[str, tuple[Any, ...], dict[str, Any]]] = []
+
+    async def _dispatch(self, name: str, *args: Any, **kwargs: Any) -> Any:
+        self.calls.append((name, args, kwargs))
+        if self._error is not None:
+            raise self._error
+        return self._result
+
+    async def list(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("list", *args, **kwargs)
+
+    async def persona_state(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("persona_state", *args, **kwargs)
+
+    async def define(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("define", *args, **kwargs)
+
+    async def patch(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("patch", *args, **kwargs)
+
+    async def delete(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("delete", *args, **kwargs)
+
+
+class _FakeAgentsClient:
+    def __init__(self, agents: _FakeAgents) -> None:
+        self.agents = agents
+
+
+def _wta(agents: _FakeAgents) -> WorldtreeClient:
+    """Cast the structural agents-fake to the nominal client type (the agent route
+    functions only touch `client.agents.*`)."""
+    return cast(WorldtreeClient, _FakeAgentsClient(agents))
+
+
+class TestListAgents:
+    """slice-4: list_agents → SDK agents.list(); open-world array verbatim."""
+
+    async def test_happy_returns_array_verbatim(self) -> None:
+        data = [{"agent_id": "mimir", "name": "Mimir", "description": "k"}]
+        fake = _FakeAgents(result=data)
+        out = await list_agents(_wta(fake))
+        assert out is data  # open-world passthrough, no AgentInfo normalization
+        assert fake.calls[-1][0] == "list"
+
+    async def test_error_maps_to_session_api_failed(self) -> None:
+        fake = _FakeAgents(error=ApiError("upstream", "boom", status=500))
+        with pytest.raises(SessionApiFailed) as ei:
+            await list_agents(_wta(fake))
+        assert ei.value.status == 500
+
+
+class TestGetPersonaState:
+    """slice-4: get_persona_state → SDK agents.persona_state(id); dict verbatim.
+    404 sub-codes + 403 auth_scope_denied map by (status, error_code)."""
+
+    async def test_happy_returns_dict_verbatim(self) -> None:
+        snap = {"pad": {}, "dominant_emotion": "curiosity"}
+        fake = _FakeAgents(result=snap)
+        out = await get_persona_state(_wta(fake), "mimir")
+        assert out is snap
+        assert fake.calls[-1] == ("persona_state", ("mimir",), {})
+
+    async def test_persona_not_configured(self) -> None:
+        fake = _FakeAgents(error=ApiError("persona_not_configured", "no", status=404))
+        with pytest.raises(PersonaNotConfigured) as ei:
+            await get_persona_state(_wta(fake), "domari")
+        assert ei.value.agent_id == "domari"
+
+    async def test_agent_not_available(self) -> None:
+        fake = _FakeAgents(error=ApiError("agent_not_available", "no", status=404))
+        with pytest.raises(PersonaAgentNotAvailable) as ei:
+            await get_persona_state(_wta(fake), "bogus")
+        assert ei.value.agent_id == "bogus"
+
+    async def test_auth_scope_denied(self) -> None:
+        fake = _FakeAgents(error=ApiError("auth_scope_denied", "no", status=403))
+        with pytest.raises(AuthScopeDenied) as ei:
+            await get_persona_state(_wta(fake), "mimir")
+        assert ei.value.scope == "persona.read"
+
+    async def test_other_404_without_code_maps_to_default(self) -> None:
+        # A 404 whose error_code is neither persona sub-code → generic default,
+        # NOT a spurious PersonaNotConfigured (the code is the discriminator).
+        fake = _FakeAgents(error=ApiError("weird", "no", status=404))
+        with pytest.raises(SessionApiFailed) as ei:
+            await get_persona_state(_wta(fake), "mimir")
+        assert ei.value.status == 404
+
+    async def test_empty_agent_id_asserts(self) -> None:
+        fake = _FakeAgents(result={})
+        with pytest.raises(AssertionError):
+            await get_persona_state(_wta(fake), "")
+        assert fake.calls == []
+
+
+class TestDefineAgent:
+    """slice-4: define_agent → SDK agents.define(); open-world DefinedAgent dict
+    (echoes `role` post-b128). Slug validated client-side; tier3 error rows."""
+
+    async def test_happy_builds_body_and_returns_dict(self) -> None:
+        resp = {"agent_id": "ratatoskr:wizard", "role": "thoughtful-character"}
+        fake = _FakeAgents(result=resp)
+        out = await define_agent(
+            _wta(fake), agent_name="wizard", system_prompt="You are a wizard.",
+            role="thoughtful-character",
+        )
+        assert out is resp  # open-world passthrough (no Tier3AgentInfo)
+        name, args, _kwargs = fake.calls[-1]
+        assert name == "define"
+        # AgentDefineInput body: exactly the three keys, no layer fields.
+        assert args[0] == {
+            "agent_name": "wizard",
+            "role": "thoughtful-character",
+            "system_prompt": "You are a wizard.",
+        }
+
+    async def test_quota_exceeded_defaults_retry_after_zero(self) -> None:
+        # The SDK's ApiError floor drops the Retry-After header; spec §2675 pins it
+        # to 0, so the adapter defaults retry_after=0.
+        fake = _FakeAgents(error=ApiError("agent_quota_exceeded", "full", status=429))
+        with pytest.raises(Tier3QuotaExceeded) as ei:
+            await define_agent(_wta(fake), agent_name="overflow", system_prompt="x", role="m")
+        assert ei.value.retry_after == 0
+
+    async def test_user_id_unsupported(self) -> None:
+        fake = _FakeAgents(error=ApiError("tier3_user_id_unsupported", "no", status=403))
+        with pytest.raises(Tier3UserIdUnsupported):
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+
+    async def test_layer_deferred_field_parsed_from_body(self) -> None:
+        # `field` is not on ApiError — the adapter body-parses detail.field.
+        fake = _FakeAgents(error=ApiError(
+            "layer_deferred", "no", status=422,
+            body='{"detail": {"error_code": "layer_deferred", "field": "persona"}}',
+        ))
+        with pytest.raises(Tier3LayerDeferred) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.field == "persona"
+
+    async def test_layer_deferred_flat_field_body(self) -> None:
+        # _error_field_from_body also handles a flat top-level `field` (both-shape
+        # unwrap) — locks the contract's "detail.field / flat field" claim.
+        fake = _FakeAgents(error=ApiError(
+            "layer_deferred", "no", status=422, body='{"field": "valence"}',
+        ))
+        with pytest.raises(Tier3LayerDeferred) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.field == "valence"
+
+    async def test_layer_deferred_non_string_field_is_none(self) -> None:
+        # A non-string `field` value collapses to None — the exception surface is
+        # `field: str | None` and the CLI prints it (heid-bug-hunt hardening).
+        fake = _FakeAgents(error=ApiError(
+            "layer_deferred", "no", status=422, body='{"detail": {"field": {"x": 1}}}',
+        ))
+        with pytest.raises(Tier3LayerDeferred) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.field is None
+
+    async def test_403_wrong_code_maps_to_default(self) -> None:
+        # Dual-key negative: a 403 whose code is NOT tier3_user_id_unsupported →
+        # generic default, not a spurious Tier3UserIdUnsupported (INV-CUT-2).
+        fake = _FakeAgents(error=ApiError("auth_revoked", "no", status=403))
+        with pytest.raises(SessionApiFailed) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.status == 403
+
+    async def test_422_wrong_code_maps_to_default(self) -> None:
+        # Dual-key negative: a 422 whose code is NOT layer_deferred → default.
+        fake = _FakeAgents(error=ApiError("validation_failed", "no", status=422))
+        with pytest.raises(SessionApiFailed) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.status == 422
+
+    async def test_bad_slug_asserts_no_call(self) -> None:
+        fake = _FakeAgents(result={})
+        with pytest.raises(AssertionError):
+            await define_agent(_wta(fake), agent_name="Wizard", system_prompt="x", role="m")
+        assert fake.calls == []
+
+    async def test_short_slug_asserts_no_call(self) -> None:
+        fake = _FakeAgents(result={})
+        with pytest.raises(AssertionError):
+            await define_agent(_wta(fake), agent_name="ab", system_prompt="x", role="m")
+        assert fake.calls == []
+
+    async def test_empty_prompt_asserts(self) -> None:
+        fake = _FakeAgents(result={})
+        with pytest.raises(AssertionError):
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="", role="m")
+        assert fake.calls == []
+
+    async def test_empty_role_asserts(self) -> None:
+        fake = _FakeAgents(result={})
+        with pytest.raises(AssertionError):
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="")
+        assert fake.calls == []
+
+    async def test_other_5xx_maps_to_default(self) -> None:
+        fake = _FakeAgents(error=ApiError("upstream", "out", status=503))
+        with pytest.raises(SessionApiFailed) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.status == 503
+
+
+class TestPatchAgent:
+    """slice-4: patch_agent → SDK agents.patch(id, changes); open PatchedAgent dict."""
+
+    async def test_happy_both_fields(self) -> None:
+        resp = {"agent_id": "ratatoskr:wizard", "role": "different"}
+        fake = _FakeAgents(result=resp)
+        out = await patch_agent(
+            _wta(fake), "ratatoskr:wizard", system_prompt="new", role="different"
+        )
+        assert out is resp
+        name, args, _kwargs = fake.calls[-1]
+        assert name == "patch"
+        assert args[0] == "ratatoskr:wizard"
+        assert args[1] == {"system_prompt": "new", "role": "different"}
+
+    async def test_happy_single_field_omits_none(self) -> None:
+        fake = _FakeAgents(result={})
+        await patch_agent(_wta(fake), "ratatoskr:wizard", system_prompt="only this")
+        assert fake.calls[-1][1][1] == {"system_prompt": "only this"}
+
+    async def test_404_maps_to_agent_not_found(self) -> None:
+        fake = _FakeAgents(error=ApiError("not_found", "no", status=404))
+        with pytest.raises(Tier3AgentNotFound) as ei:
+            await patch_agent(_wta(fake), "ratatoskr:ghost", system_prompt="x")
+        assert ei.value.agent_id == "ratatoskr:ghost"
+
+    async def test_field_not_mutable_field_parsed(self) -> None:
+        fake = _FakeAgents(error=ApiError(
+            "field_not_mutable", "no", status=422,
+            body='{"detail": {"error_code": "field_not_mutable", "field": "agent_name"}}',
+        ))
+        with pytest.raises(Tier3FieldNotMutable) as ei:
+            await patch_agent(_wta(fake), "ratatoskr:wizard", system_prompt="x")
+        assert ei.value.field == "agent_name"
+
+    async def test_422_wrong_code_maps_to_default(self) -> None:
+        # Dual-key negative: a 422 whose code is NOT field_not_mutable → default,
+        # not a spurious Tier3FieldNotMutable (INV-CUT-2).
+        fake = _FakeAgents(error=ApiError("validation_failed", "no", status=422))
+        with pytest.raises(SessionApiFailed) as ei:
+            await patch_agent(_wta(fake), "ratatoskr:wizard", system_prompt="x")
+        assert ei.value.status == 422
+
+    async def test_no_fields_asserts_no_call(self) -> None:
+        fake = _FakeAgents(result={})
+        with pytest.raises(AssertionError):
+            await patch_agent(_wta(fake), "ratatoskr:wizard")
+        assert fake.calls == []
+
+    async def test_non_tier3_id_asserts(self) -> None:
+        fake = _FakeAgents(result={})
+        with pytest.raises(AssertionError):
+            await patch_agent(_wta(fake), "mimir", system_prompt="x")
+        assert fake.calls == []
+
+    async def test_other_error_maps_to_default(self) -> None:
+        fake = _FakeAgents(error=ApiError("upstream", "boom", status=500))
+        with pytest.raises(SessionApiFailed) as ei:
+            await patch_agent(_wta(fake), "ratatoskr:wizard", system_prompt="x")
+        assert ei.value.status == 500
+
+
+class TestDeleteAgent:
+    """slice-4: delete_agent → SDK agents.delete(id); None on 204; 404 → not-found."""
+
+    async def test_happy_returns_none(self) -> None:
+        fake = _FakeAgents(result=None)
+        out = await delete_agent(_wta(fake), "ratatoskr:wizard")
+        assert out is None
+        assert fake.calls[-1] == ("delete", ("ratatoskr:wizard",), {})
+
+    async def test_404_maps_to_agent_not_found(self) -> None:
+        fake = _FakeAgents(error=ApiError("not_found", "no", status=404))
+        with pytest.raises(Tier3AgentNotFound) as ei:
+            await delete_agent(_wta(fake), "ratatoskr:ghost")
+        assert ei.value.agent_id == "ratatoskr:ghost"
+
+    async def test_non_tier3_id_asserts(self) -> None:
+        fake = _FakeAgents(result=None)
+        with pytest.raises(AssertionError):
+            await delete_agent(_wta(fake), "mimir")
+        assert fake.calls == []
+
+    async def test_other_error_maps_to_default(self) -> None:
+        fake = _FakeAgents(error=ApiError("upstream", "oops", status=500))
+        with pytest.raises(SessionApiFailed) as ei:
+            await delete_agent(_wta(fake), "ratatoskr:wizard")
+        assert ei.value.status == 500
@@ -472,7 +472,7 @@ wheels = [

 [[package]]
 name = "ratatoskr"
-version = "0.21.11"
+version = "0.21.15"
 source = { editable = "." }
 dependencies = [
    { name = "httpx" },
Author	SHA1	Message	Date
vh	477d98f52e	fix(#20 ): heid-bug-hunt fixups — open-world presenter degrade-not-crash (slice-4) Panel (Gróa+Hulda+Regin, 5/5/5, no false positives) confirmed two 3/3 crash sites where open-world dict reads violate the declared "degrade, never crash the presenter" invariant — the wt adapter tests + the live smoke used full server dicts, so partial/drifted wire responses were never exercised: - FIX (tier3.py _run_define/_run_patch): the CLI hard-indexed the open-world define/patch dicts (`info["agent_id"]` / `["role"]` / `["agent_name"]`), so a partial 2xx → KeyError escaping main()'s exit matrix as a raw traceback (exit 1); and `make_description(info.get("system_prompt", ""))` fed None to .splitlines() on a present-but-null field → AttributeError. Now reads via `_str_field` (absent/ null/non-str → default), degrades role to '?', indexes only a well-formed identity, and maps a no-usable-agent_id 2xx to [api_failed] exit 20 (controlled, not a crash). - FIX (web/server.py _agents_endpoint): the upstream dedup hard-indexed each item (`{a["agent_id"] for a in upstream}` + `_as_dict`), so a malformed item (`[{}]`, `["str"]`, `{"name":…}`, non-str agent_id) or a non-list envelope → 500 before the local fallback merged. Now filters to well-formed mappings first; a non-list upstream degrades to the local-only list. - FIX (wt.py _error_field_from_body): type-check the parsed `field` is a str (the exception surface is `field: str \| None`, the CLI prints it) — restores the retired hand-rolled `_extract_error_field` isinstance guard. Held (triaged, no change): the 429→Tier3QuotaExceeded / bare-404→Tier3AgentNotFound maps are ungated-by-error_code BY CONTRACT DESIGN (§ Error map route+status rows; the SDK's ApiError floor drops Retry-After, so retry_after=0 is canonical) — the arms flagged them spec-free; Heid's source-check confirmed intended. Dual-keying define's 429 for full row consistency is an available tightening (contract amendment), surfaced not applied. The persona-endpoint SessionApiFailed gap the arms also caught was already closed in the prior code-review fixup (`aed9429`). Suite 475 green (+5).	2026-07-19 10:18:36 -07:00
vh	aed942972f	fix(#20 ): heid-code-review fixups — persona-endpoint SessionApiFailed parity (slice-4) Panel (Gróa+Hulda+Regin) returned zero adapter / error-map / model→role drift; three actionable items triaged as genuine adds: - FIX: `_persona_state_endpoint` now catches `wt.SessionApiFailed` and returns the `session_api_failed` envelope with the upstream status, for parity with `_agents_endpoint` / session-create / admin (2/3 arms flagged it; it was the lone sibling letting an unmatched upstream ApiError escape as a raw 500). Confirmed NOT a slice-4 regression — the pre-cutover persona endpoint had the same latent gap — but closed here since the endpoint's error surface is already being hardened (it gained the ConnectFailed catch this slice). - TESTS: dual-key NEGATIVE rows — a wrong error_code at the same status defaults to SessionApiFailed for `define_agent` (403, 422) and `patch_agent` (422); plus the flat-`field` body-parse shape for `_error_field_from_body` (only the nested detail.field form was exercised). Closes the assertion-symmetry gap with the persona route's existing negative test. - AMEND: contract slice-4 notes document the intentional client-side `":" in agent_id` PRE on patch/delete (a Tier-3 id is always <user>:<name>, ADR-0019). Suite 470 green (+5).	2026-07-19 10:13:11 -07:00
vh	c62b4eecb3	feat(#20 ): agents/tier3 family onto the wt adapter + model→role fold (slice-4) Cut ratatoskr's consumer agent-lifecycle routes over to worldtree-sdk (issue #20 slice-4). Five routes now flow through `ratatoskr.wt` over the SDK's `client.agents.*`, returning open-world dicts and mapping the SDK's undiscriminated `ApiError` floor by route+(status,error_code) per INV-CUT-2: - `list_agents` → `agents.list` - `get_persona_state`→ `agents.persona_state` (404 persona_not_configured / 404 agent_not_available / 403 auth_scope_denied) - `define_agent` → `agents.define` (429→Tier3QuotaExceeded(retry_after=0), 403→Tier3UserIdUnsupported, 422 layer_deferred→…) - `patch_agent` → `agents.patch` (404→Tier3AgentNotFound, 422 field_not_mutable) - `delete_agent` → `agents.delete` (404→Tier3AgentNotFound; NOT hide-existence) Rewired call-sites: the `python -m ratatoskr.tier3` CLI (define/patch/delete) and the web `_agents_endpoint` / `_persona_state_endpoint`, both catching the SDK's `ConnectFailed` transport-failure normalization. Deleted the hand-rolled paths: `sessions.list_agents` / `get_persona_state` / `AgentInfo`, and `tier3.define/patch/delete_agent` / `Tier3AgentInfo` / parse+extract helpers. model→role fold (scope B): the define/patch response echoes `role` (spec 1.2 / b128), read off the open-world dict; `LocalAgentEntry.model`→`.role`, local-index schema v1→2 (old index discarded, no-backwards-compat). The Tier-3 caller-semantic exceptions move to `sessions.py`: running the CLI as `__main__` while `wt` imports `ratatoskr.tier3` bound two copies of each exception class, so a raised `Tier3AgentNotFound` escaped the CLI's `except` as an uncaught traceback. Homing them in `sessions` (never `__main__`) makes the class identity single. The live smoke — not the unit tests, which call `main()` in-process — caught this. Error-map rows + slice-4 notes added to the cutover contract; coverage-map re-anchored. LIVE-SMOKE on personal :8081 (b128): define(thoughtful-character) → patch → list(6 agents) → persona_state(→PersonaNotConfigured mapped) → delete → index empty; non-existent-id patch via `-m` → [agent_not_found] exit 20. Suite 465 green.	2026-07-19 09:58:01 -07:00
vh	4f92a21cb9	memory: /snapshot — worldtree-sdk cutover slice-3 complete (ca9a339+fc256bb)	2026-07-19 09:20:18 -07:00
vh	fc256bbaa4	fix(#20 ): heid-bug-hunt fixups — probe ConnectFailed + adapter finite-PAD (slice-3) The slice-3 heid-bug-hunt panel (3/3) caught a real regression the cutover introduced, plus a chokepoint-invariant gap: - ConnectFailed escaped both rewired CLI probes. When --set-persona-pad and --seed-first-message moved off raw httpx onto the wt adapter, transport failures changed class: the SDK normalizes any pre-response transport error to worldtree_sdk.ConnectFailed (request.py), a WorldtreeError (not ApiError), so it passed the adapter unmapped AND the probes' httpx-only except tuples → an uncaught traceback instead of the graceful [network_error] exit 21. _amain (slice-2) already handled it; the probes lagged. Fix: add ConnectFailed to both probe except tuples (mirrors _amain). Live-verified at a refused host → [network_error] exit 21. - Finite-PAD enforced only at the CLI, not the adapter chokepoint. wt.set_persona_state delegated finiteness to the caller (documented), so a direct/non-CLI caller passing nan/inf got a raw SDK ConfigurationError. Fix: assert finiteness in the adapter precondition (consistent with its other precondition asserts) so the invariant holds at the chokepoint in ratatoskr's own terms; the CLI pre-check stays for the friendly usage error. Triaged-and-declined (all correct per the panel + Heid's source-check): the deleted sessions.py exports (intended no-shim cutover, zero un-migrated importers), the session["session_id"] index (accept-known-risk, matches --new), and Regin's "web indefinite block" (refuted — the seed is asyncio.wait_for-bounded). The concurrent heid-code-review panel returned zero drift, no code change. TDD: 3 RED tests (both probes' ConnectFailed → exit 21; adapter nan/inf/-inf → AssertionError, never reaches the SDK) → GREEN. Suite 469; ruff clean; mypy no new errors.	2026-07-19 09:13:47 -07:00