fix(tui): drop post-Done Markdown body re-render (v0.8.2)

Operator: "first turn double prints agent's turn."

Root cause: v0.8.1 wrote both the streamed Text lines AND the post-
Done `Markdown(event.response)` body into the transcript. Same
content rendered twice — once as plain streaming, once as a full
markdown re-render. The v0.8.1 commit message documented this as
"some duplication is acceptable" but the live UX read as a bug.

## Fix

Drop the post-Done `Rule + Markdown(response)` writes in non-raw
mode. The streamed text IS the response; whatever the model emitted
flows into the transcript line-by-line via coalesce-on-newline.
Markdown formatting (bold, lists, code blocks) renders as plain
text — a known regression from v0.8.1's polished output but the
right tradeoff vs the duplication bug.

## What this loses temporarily

Pre-v0.8.2 (after Done):
  [done] turn_id=... ───
  ─── (Rule separator) ───
  **Bold text** rendered bold, `code` highlighted, lists as bullets, etc.

v0.8.2 (after Done):
  [done] turn_id=... ───
  **Bold text** as plain asterisks, `code` as backticks, lists as plain dashes

## v0.9.0 plan

Restore markdown rendering via LIVE rendering during the stream
(not post-Done re-render). Replace `RichLog#transcript` with a
`VerticalScroll` container that mounts a fresh `Markdown` widget
per turn; Text deltas update the widget; markdown renders as
content arrives. No duplication, no snap, full formatting.
Operator-confirmed direction (2026-05-25 AskUserQuestion).

## Tests

287/287 GREEN; ruff clean. Two tests updated for the new shape:
- test_done_renders_markdown_after_label → renamed
  test_done_flushes_tail_and_writes_label; asserts NO Markdown, NO
  Rule (post-Done) in the writes.
- test_happy_text_done_renders_markdown → renamed
  test_happy_text_done_no_double_print; asserts NO Markdown in the
  spy.

Patch bump (v0.8.1 → v0.8.2): bug fix; no public API change.

docs/contracts/issues/13.contract.md

@@ -0,0 +1,218 @@
+---
+contract_version: "2.1"
+target_module: "ratatoskr.tui"
+scope: "Design-brief §5 v1 entry point: reshape the TUI from vertical-stack single-pane to Horizontal two-column with `TabbedContent` on the right; first (and only v1) tab is `Tools`, which consumes `ToolStart` / `ToolResult` SSE events that previously rendered inline in the transcript. Pure in-place amendment to issue #4 + #12 — no new modules, no new files apart from this contract. The CLI (`ratatoskr.cli`) is unaffected: `--send` mode is non-interactive and keeps its current inline tool-event rendering. Substrate move only: persona / admin-events / bifrost-state / server-log panes stay deferred (blocked on remote-Worldtree topology + admin scope + opt-in flag). The TabbedContent shape makes them additive — when a blocker resolves the new pane plugs in as another TabPane sibling without further layout work."
+depends_on:
+  - "textual"
+used_by: []
+language: "python"
+complexity: "medium"
+estimated_loc: 180
+confidence: 0.85
+assumptions:
+  - "Textual's `TabbedContent(*titles, initial='')` + `TabPane(title, *children, id=...)` is the right primitive for the right-column tabs (verified API at textual.widgets._tabbed_content). One `TabPane(\"Tools\", tools_log, id=\"tools-tab\")` in v1; additional siblings get appended as Persona/AdminEvents/BifrostState/ServerLog land."
+  - "Textual's `Horizontal` + `Vertical` containers compose the two-column split (verified at textual.containers). Width via CSS `width: 2fr` on the left container + `width: 1fr` on the right container gives the 2:1 chat-primary split."
+  - "**The presenter contract amendment is small and tightly scoped**: `TuiPresenterState.render` gains a `tools_log: RichLog` parameter alongside the existing `log: RichLog` (main transcript) + `thinking_widget: Static`. `ToolStart` / `ToolResult` events route to `tools_log`; every other event (Text, Thinking, WorkerPhase, Done, Error, Cancelled, TextBoundary) keeps its existing routing to `log` + `thinking_widget`. The plain-label fallback path in `_plain_label` (issue #12 INV-009 render-exception recovery) keeps its current shape — only the routing target changes."
+  - "**Tool events are routed, not duplicated**. The brief's §5 wording 'side pane (inline-from-SSE for v1)' factors tool events OUT of the main transcript. A consumer who wants to debug a tool-using turn now reads the Tools pane; the main transcript stays focused on assistant text. Trade-off: a fast-skim of the transcript no longer shows tool activity inline; if that hurts the debug ergonomics empirically, a follow-up issue can add a one-line `· tool_used name=...` breadcrumb to the transcript as a compromise. v1 commits to the cleaner split."
+  - "**Demoted-prefix style stays consistent across panes**. ToolStart in the Tools pane renders as `· tool_start: name=foo args={...}` — the same `· ` ASCII prefix issue #12 INV-005 established for demoted telemetry in the main transcript. Pane separation handles the visual hierarchy; prefix style stays cross-pane consistent so the operator's mental model is portable."
+  - "**Input field retains focus across tab switches** (design-brief §5 invariant: 'Tab key (Ctrl+1..5) jumps between tabs without losing focus on the input field'). INV-016 is the load-bearing invariant; the assumption about Textual's default behavior is just an implementation hint. If Textual's default `TabbedContent.active = ...` programmatic assignment preserves Input focus (current observed behavior), no extra code is needed. If a future Textual version regresses on this, the implementation MUST add `self.query_one('#prompt', Input).focus()` immediately after the `.active = ` assignment in `action_focus_tools` to satisfy INV-016. The test `test_ctrl_1_preserves_input_focus` is the regression guard; if it fails, the fix is the explicit `.focus()` call, not relaxing the invariant. Pre-existing INV-007 (Input always-focused except during error sub-states) is preserved verbatim."
+  - "**Status footer gains a `current-pane-name` element** — design-brief §5 calls for it explicitly. v1 only has one tab so the indicator stable-renders \"Tools\". Wiring it as a separate Static (`id='pane-name'`) docked alongside identity + hint makes it trivially extend when more tabs land — the widget is in place; the value will become dynamic in the future multi-tab issue. **No tab-switch handler wiring lands in #13.** The `on_mount` flow populates `pane-name` once with the literal string \"Tools\" and never updates it. Adding event-handler plumbing in v1 (a `@on(TabbedContent.TabActivated)` handler, etc.) is out of scope — that's a deliberate deferral, not an implementer's call."
+  - "**The existing `· thinking-current` widget keeps its position** — docked to the top of the left column (was docked top of the whole App; now docked top of the left Vertical container). Pre-amendment dock-fix from v0.2.1 stays; the scope of the dock just narrows from \"App\" to \"left column\" so it doesn't bleed into the right column's TabbedContent area."
+  - "**Width split is fixed `2fr : 1fr` for v1**. User-resizable splits are textual-native (via `Splitter` or similar), but adding interactive resize is its own UX surface. v1 ships fixed; if the right pane proves cramped on narrow terminals operators will tell us. Out of scope."
+  - "**TabbedContent's CSS classes**: the right column's TabbedContent + its tabbed-content wrappers (`#tabbed-content`, `.--tabs`, etc.) come with Textual's default styling. No custom CSS for tab strip in v1; if the visual feels wrong adjust later. The contract specifies the structure; the chrome stays Textual-default."
+  - "**Test strategy**: existing TestStreamTurnWorker tests for Text/Thinking/Done/Error/Cancelled routing stay GREEN unchanged (they assert what shows in the transcript log; that still shows the same content). ToolStart/ToolResult tests get adjusted to assert routing to `tools_log` instead of `log`. New tests cover layout shape (Horizontal parent exists, TabbedContent with tools-tab on the right) + Ctrl+1 binding + tools_log writes for tool events."
+  - "**Issue #12's INV-009 render-exception fallback path** stays correct: `_plain_label(event)` is still callable; the render method's except branch writes the labeled-string to the appropriate Widget (tools_log for tool events; log for everything else). The fallback writes to the same routed widget as a successful render — failure mode preserves the routing invariant."
+open_questions:
+  - "Should the Tools tab show a count badge when new tool events arrive while the user is on a future Persona/AdminEvents tab? Draft: no for v1 — only one tab, so the question is moot. When persona/admin-events panes land, revisit: a small `[N]` badge on the tab header (`'Tools [3]'`) would help operators not miss tool activity that happens off-screen. Defer to a follow-up that touches multiple panes."
+  - "Should the Tools pane support filter-by-tool-name (e.g., show only `kb_search` results)? Draft: no for v1 — flat scroll matches the design brief's posture. The volume of tool events per turn is small enough that scrollback handles the use case. Revisit if mimir-style heavy-tool agents produce visible-cluttering volume."
+  - "Should the v1 Ctrl+1 binding be Ctrl+1 specifically, or `t` for 'tools' (no modifier)? Draft: Ctrl+1 — design brief specifies `Ctrl+1..5` as the family; matches the Ctrl-prefix discipline already used by Ctrl-C / Ctrl-D bindings. Plain-letter bindings would steal letter input from the Input field; Ctrl-prefixed is the standard escape."
+prd:
+  issue: 13
+  issue_url: "https://gitea.phasefinal.com/vh/ratatoskr/issues/13"
+  body_sha256_16: "52c8f886a9cc986a"
+  lock_in_comment_id: null
+  lock_in_sha256_16: null
+  lock_in_at: null
+  pinned_at: "2026-05-24T02:28:28+00:00"
+dependencies:
+  - issue: 4
+    path: "src/ratatoskr/tui.py"
+    reason: "In-place contract amendment: `RatatoskrApp.compose()` reshapes from vertical-stack to Horizontal 2-col + TabbedContent right; `RatatoskrApp.DEFAULT_CSS` reshapes to scope dock rules to the new left/right containers; `RatatoskrApp.__init__` is unchanged (state attributes carry over); `RatatoskrApp.on_mount` gains pane-name widget population + tools_log lookup; `RatatoskrApp.BINDINGS` gains `Ctrl+1` → `action_focus_tools`; existing `action_interrupt` / `action_quit` unchanged."
+  - issue: 12
+    path: "src/ratatoskr/tui.py"
+    reason: "In-place contract amendment: `TuiPresenterState.render` signature widens to accept `tools_log: RichLog` alongside `log` + `thinking_widget`; ToolStart/ToolResult branches write to `tools_log` instead of `log`. `_stream_turn_worker` does the new lookup (`self.query_one('#tools-log', RichLog)`) and threads it through. All other event branches stay verbatim."
+---
+
+# TUI layout reshape + Tools pane — §5 v1 entry point
+
+## Context
+
+`ratatoskr.tui` ships v0.x as a single-pane Textual app: Header / thinking-current widget / transcript RichLog / Input / identity + hint Statics / Footer, vertical-stacked via `dock: top` / `dock: bottom` CSS (v0.2.1 layout fix). Design-brief §5 commits the product to a multi-pane debug-observability dashboard. Most of §5's panes (Persona, AdminEvents, BifrostState widget, ServerLog) are blocked on substrate that isn't here — remote-Worldtree topology blocks file-tail-based panes; issue #11's `admin.events.read` scope blocks the admin surfaces.
+
+The unblocked v1 entry point is **layout reshape + Tools pane together**: reshape the TUI into the Horizontal two-column shape the design brief specifies, with `TabbedContent` on the right populated by a single `Tools` tab that consumes the existing `ToolStart` / `ToolResult` SSE events. No new endpoints; no scope grants; no cross-repo coordination. The shape is the foundation; subsequent panes plug in additively.
+
+## Data flow
+
+**Input** (unchanged from issue #4):
+- `args: ParsedArgs`, `session_id: str`, `agent_id: str | None`, `client: httpx.AsyncClient`.
+- SSE event stream from `ratatoskr.sse_client.stream_turn`.
+
+**Output** (unchanged):
+- Exit code via `App.exit(code)`.
+
+**Internal routing change**:
+- `ToolStart` / `ToolResult` events route to `tools_log: RichLog` (Tools pane) instead of the main transcript `log: RichLog`.
+- All other event types (`Text`, `Thinking`, `WorkerPhase`, `TextBoundary`, `Done`, `Error`, `Cancelled`) keep their existing routing.
+
+## Layout shape (post-amendment)
+
+```
+RatatoskrApp(App[int]):
+  compose():
+    yield Header()
+    yield Horizontal(
+      Vertical(
+        Static(id="thinking-current"),     # dock: top of left column
+        RichLog(id="transcript"),          # height: 1fr (fills middle)
+        Input(id="prompt"),                # dock: bottom of left column
+        id="left-column",
+      ),
+      Vertical(
+        TabbedContent(
+          TabPane("Tools", RichLog(id="tools-log"), id="tools-tab"),
+          # future: TabPane("Persona", …, id="persona-tab"), etc.
+          id="side-panes",
+        ),
+        id="right-column",
+      ),
+      id="main-row",
+    )
+    yield Static(id="identity")            # dock: bottom of App
+    yield Static(id="pane-name")           # dock: bottom of App (new in §5)
+    yield Static(id="hint")                # dock: bottom of App
+    yield Footer()
+```
+
+**DEFAULT_CSS reshape:**
+
+```css
+#main-row { height: 1fr; }
+#left-column { width: 2fr; }
+#right-column { width: 1fr; }
+#thinking-current { dock: top; height: auto; }
+#transcript { height: 1fr; }
+#prompt { dock: bottom; }
+#identity { dock: bottom; height: 1; }
+#pane-name { dock: bottom; height: 1; }
+#hint { dock: bottom; height: 1; }
+```
+
+Dock rules scope to the right container (left column for `thinking-current`/`prompt`; App for `identity`/`pane-name`/`hint`). The left-column `prompt` Input docks to the bottom of its column, not the App, so the right column's TabbedContent extends full height beside it.
+
+## Presenter routing (amendment to issue #12)
+
+```
+FN TuiPresenterState.render(
+    event: Event,
+    *,
+    log: RichLog,
+    thinking_widget: Static,
+    tools_log: RichLog,         # NEW (issue #13)
+    raw: bool,
+) -> None
+```
+
+Steps (only the ToolStart/ToolResult cases change; every other case keeps issue #12's behavior verbatim):
+
+- `ToolStart` → write `· tool_start: name=<name> args=<args!r>` to `tools_log` (not `log`).
+- `ToolResult` → write `· tool_result: name=<name> duration_ms=<n> result=<r!r:.200>` to `tools_log` (not `log`).
+- All other events → unchanged routing per issue #12 INV-005.
+- Render-exception fallback (`_plain_label(event)`): write to `tools_log` if the event is `ToolStart`/`ToolResult`; write to `log` otherwise. Routing preservation under failure.
+
+## Keybindings (amendment)
+
+```
+BINDINGS: ClassVar[list[Binding]] = [
+  Binding("ctrl+c", "interrupt", "Cancel / Exit", priority=True),
+  Binding("ctrl+d", "quit", "Exit immediately", priority=True),
+  Binding("ctrl+1", "focus_tools", "Tools tab", priority=False),  # NEW
+]
+
+def action_focus_tools(self) -> None:
+    self.query_one(TabbedContent).active = "tools-tab"
+    # Input focus is preserved by Textual's default behavior — TabbedContent
+    # doesn't steal focus when `.active` is set programmatically.
+```
+
+`Ctrl+1` is the v1 entry of the design-brief `Ctrl+1..5` family. `Ctrl+2..5` get added by subsequent issues as Persona/AdminEvents/BifrostState/ServerLog land. The binding does NOT steal Input focus — the test asserts `Input` keeps focus across the tab switch.
+
+## Status footer (amendment)
+
+New `Static(id="pane-name")` widget alongside the existing `identity` + `hint` widgets. v1 renders the literal string `"Tools"` set once at `on_mount`; the widget never updates after that. Dynamic updating + tab-switch handler wiring is **out of scope for #13** — it lands in the multi-tab follow-up that introduces the second TabPane. An implementer who adds a `@on(TabbedContent.TabActivated)` handler in this issue is out of spec.
+
+## Invariants
+
+- **INV-013**: Layout is `Horizontal` two-column. Left column width = 2fr; right column width = 1fr.
+- **INV-014**: `ToolStart` / `ToolResult` events route to `tools_log` (Tools pane), never to `log` (transcript).
+- **INV-015** *(amended v0.5.0)*: The transcript (`log`) is **content-only** — receives `Text`, `Done` (label + Markdown body + Rule), `Error`, `Cancelled`, and the user-prompt echo (`❯ <content>`). **All telemetry events (`Thinking` closed runs, `WorkerPhase`, `TextBoundary`) route to `debug_log` (Debug pane), NOT `log`.** Live thinking deltas continue to update `thinking_widget` per-delta. The pre-v0.5.0 shape (telemetry mixed into transcript) is retired under the project's no-backwards-compat rule.
+- **INV-016**: Input retains keyboard focus across `Ctrl+1` / `Ctrl+2` tab switches.
+- **INV-017** *(amended v0.5.0)*: `thinking-current` Static docks to the top of the **right column** (above `TabbedContent`), not the left column. Live thinking visibility persists across tab switches. v0.5.0 moves it from left → right so the left column is genuinely content-only.
+- **INV-018**: CLI mode (`ratatoskr.cli._amain`) is unaffected. CLI keeps inline `· tool_start: …` / `· tool_result: …` rendering on stderr per issue #12 INV-005.
+- **INV-019** *(amended v0.6.0)*: Three TabPanes in the right column: `Tools` (id `tools-tab`, contains `#tools-log`) + `Debug` (id `debug-tab`, contains `#debug-log`) + `Thinking` (id `thinking-tab`, contains `#thinking-log`). Ctrl+1/Ctrl+2/Ctrl+3 activate respective tabs. `pane-name` Static reflects active tab name dynamically.
+- **INV-020** *(amended v0.6.0)*: Render-exception fallback (INV-009) preserves routing per event class: `ToolStart` / `ToolResult` → `tools_log`; `Thinking` → `thinking_log`; `WorkerPhase` / `TextBoundary` → `debug_log`; everything else → `log`.
+- **INV-021** *(new v0.6.0)*: `Text` events do NOT route to `log` per-delta. They accumulate into `TuiPresenterState.text_buffer` and update a single `current_text` Static (docked above the prompt). On terminal event (`Done`/`Error`/`Cancelled`), `current_text` is cleared and (raw mode) accumulated text or (non-raw) post-Done `Markdown(response)` is written to `log`. The pre-v0.6.0 per-token RichLog spam is retired.
+- **INV-022** *(amended v0.7.1)*: Thinking deltas COALESCE on `\n` boundaries before writing to `thinking_log`. The first delta of a run writes `Rule(title=f"turn N · thinking #K start")`; subsequent deltas accumulate in `TuiPresenterState.thinking_chunk_buffer`; whenever the buffer contains `\n`, the leading line(s) flush as RichLog entries (one entry per natural paragraph). The run closes on the next non-thinking event: any tail in the buffer flushes as a final line, then `Rule(title=f"turn N · thinking #K end")`. Pre-v0.7.1 per-delta-per-line caused token-spam (Worldtree emits thinking at token granularity); coalescing produces one log line per natural paragraph, not per token.
+- **INV-023** *(new v0.6.0)*: Turn-ID header `Rule(title=f"turn N")` is written to all four log panes (`log`, `tools_log`, `debug_log`, `thinking_log`) by `_stream_turn_worker` on the first event of each turn — enables cross-pane visual correlation during multi-turn debugging.
+- **INV-024** *(amended v0.6.5)*: `thinking-current` Static REMOVED. v0.6.1 placed it inside the Thinking pane (docked bottom); operators reported the bottom-docked Static "scrolling a little section at the bottom" (its 200-char tail acting as a scroll-window) instead of letting the whole pane scroll. v0.6.5 deletes the Static entirely and streams Thinking deltas directly into `thinking_log` (the scrollable RichLog) — the whole pane scrolls naturally as content arrives. The Rule(start) at the first delta of a run is now the live "thinking is happening" indicator.
+
+## TESTS (additions / changes to test_tui.py)
+
+```
+- test_compose_has_horizontal_main_row: RatatoskrApp.compose() yields a Horizontal with id="main-row" containing left-column + right-column children.
+- test_compose_right_column_has_tabbed_content: query_one("#side-panes", TabbedContent) is non-None; one TabPane child with title="Tools" id="tools-tab".
+- test_compose_left_column_has_transcript_input: query_one("#left-column", Vertical) contains #transcript (RichLog) + #prompt (Input).
+- test_tools_log_present: query_one("#tools-log", RichLog) is non-None; lives inside the tools-tab TabPane.
+- test_pane_name_widget_renders_tools: query_one("#pane-name", Static).renderable == "Tools" (v1 static).
+- test_tool_start_routes_to_tools_log: stream_turn emits ToolStart → tools_log receives the line; transcript RichLog does NOT receive it.
+- test_tool_result_routes_to_tools_log: stream_turn emits ToolResult → tools_log receives the line; transcript does NOT receive it.
+- test_text_event_still_routes_to_transcript: stream_turn emits Text("hello") → transcript receives it; tools_log does NOT.
+- test_thinking_event_still_routes_to_thinking_widget: thinking deltas continue to update #thinking-current Static, not tools_log.
+- test_done_event_still_routes_to_transcript: Done event renders `[done] …` in transcript, not tools_log.
+- test_ctrl_1_activates_tools_tab: simulate Ctrl+1 → TabbedContent.active == "tools-tab".
+- test_ctrl_1_preserves_input_focus: simulate Ctrl+1 while Input is focused → Input is still focused afterwards.
+- test_plain_label_fallback_routes_tool_events_to_tools_log: simulate render exception on a ToolStart → tools_log gets the _plain_label fallback string; transcript doesn't.
+```
+
+Existing tests that need adjustment (NOT rewrite):
+- Any test that asserted `log.write(...)` was called with a `tool_start: …` / `tool_result: …` string changes its target widget to `tools_log` instead.
+- TestAppMount tests gain `tools_log` widget lookup assertions.
+
+## ERROR_ROUTING (unchanged)
+
+All error routing from issues #4 / #6 / #7 / #12 stays verbatim. The tools_log routing change is internal to the presenter; error paths (`SseConnectFailed`, `SseConnectionDropped`, `MalformedSseId`, `MalformedSseData`, `TurnIdFlip`) all write their labeled lines to `log` (the main transcript). Reason: errors are turn-terminal and need to be visible in the operator's primary attention surface; routing them to the Tools pane would hide them behind a tab switch.
+
+## Layout-spec snapshot (after v0.5.0)
+
+```
++────────────────────────────────+──────────────────────+
+|  ❯ user-typed line             | · thinking-current   |
+|  assistant streaming text...   |  ┌Tools─┬─Debug─────┐|
+|  [done] turn_id=… duration=…   |  │ · tool_start:..  │|
+|  …markdown render…             |  │ · tool_result..  │|
+|                                |  │                  │|
+|                                |  │                  │|
+|                                |  │                  │|
+|  [prompt: type and press Enter]|  └──────────────────┘|
++────────────────────────────────+──────────────────────+
+| agent · …sess_id  Tools  Ctrl-C twice to exit         |
++───────────────────────────────────────────────────────+
+```
+
+Left column is content-only (transcript + prompt). Right column hosts the
+live `thinking-current` Static at top + `TabbedContent` cycling between
+`Tools` (tool events) and `Debug` (thinking closed runs + worker_phase +
+text_boundary).
+
+(Width split 2fr:1fr; tab strip is Textual-default; Header/Footer
+backgrounds explicitly set to `$surface` to override the Textual default
+`$primary`-blue tinting.)

docs/contracts/issues/15.contract.md

@@ -0,0 +1,290 @@
+---
+contract_version: "2.1"
+target_module: "ratatoskr.tier3"
+scope: "New module `ratatoskr.tier3` exposing Worldtree's Tier 3 (consumer-defined) agent lifecycle: `define_agent` (POST /agents/define), `patch_agent` (PATCH /agents/<id>), `delete_agent` (DELETE /agents/<id>), plus `Tier3AgentInfo` frozen dataclass. Plus a thin CLI entry point (`python -m ratatoskr.tier3 <define|patch|delete>`) that mirrors `ratatoskr.cli`'s env-var posture (`WORLDTREE_API_URL`, `WORLDTREE_API_KEY`). Convention-aligned with `ratatoskr.sessions` (issue #2): caller-owned httpx.AsyncClient, no Worldtree imports, response parsing into frozen dataclass, exception `.body` truncated to `[:1024]`. Picker stays generic — agents with `:` in agent_id show in the list like any other per issue #8's out-of-scope clause. Goal: ratatoskr operators can define, mutate, and delete Tier 3 agents from the command line, then exercise the full session flow against them to observe how Tier 3 agent_ids (colon-containing) flow through the picker / session-create / SSE stream."
+depends_on:
+  - "httpx"
+used_by: []
+language: "python"
+complexity: "low"
+estimated_loc: 250
+confidence: 0.9
+assumptions:
+  - "Tier 3 endpoints land at the same `WORLDTREE_API_URL` as the rest of the Conversation API — no separate hostname / port. Auth via the same bearer key. The caller's user_id is derived server-side from the API key's owner; the agent's `agent_id` is constructed as `<auth_user_id>:<agent_name>`. Live probe against personal Worldtree (2026-05-25) confirmed: POST with `{agent_name: 'smoke-test', ...}` and `Authorization: Bearer <key>` returned `agent_id=ratatoskr:smoke-test`, `user_id=ratatoskr`."
+  - "Per Worldtree spec §2576-2750: `agent_name` is a strict slug `[a-z][a-z0-9-]{2,63}` and immutable after definition. `user_id` is derived from the auth, must be slug-safe (`[a-z][a-z0-9-]{2,63}` per Phase 2.0 gate). PATCH accepts ONLY `system_prompt` and/or `model`; any other key (including the immutable `agent_name`, `user_id`, or layer fields `persona`/`motivational`/`valence`/`memory` — even with `null` value) returns 422 `field_not_mutable` BEFORE the DB lookup."
+  - "**Layer fields are explicitly null** on define. Phase 2.0 ships baseline addressing + ownership + lifecycle only; `persona` / `motivational` / `valence` / `memory` are schema-reserved. Non-null on these → 422 `layer_deferred`. The module's `define_agent` does NOT expose these as parameters at all — sending them would require an amendment when a future Phase enables them."
+  - "**`model` field is a provider model ID, not a profile alias.** Live probe found: `model='default'` (an llm_profiles profile name) returns 422 `model_not_available`; `model='qwen3.6-35-a3b'` (an actual provider model ID) returns 201. The CLI / module take the string verbatim and pass through — validation is server-side. Operators discover valid IDs via the model `metadata` on existing sessions or out-of-band."
+  - "**Quota: 50 Tier 3 agents per Heimdall key.** 51st define → 429 `agent_quota_exceeded` with `Retry-After: 0`. The module raises `Tier3QuotaExceeded(retry_after=0)` — the retry_after field captures the header value verbatim for forward-compat if Worldtree later returns a non-zero throttle."
+  - "**Key-revocation cascade is server-side.** When an API key is revoked (`DELETE /admin/keys/{key_id}`), every Tier 3 agent with `owner_key_hash` equal to the revoked key's hash is soft-deleted in the same SQL transaction. Active sessions on those agents return 401 `auth_revoked` on next message. The ratatoskr module doesn't track or simulate this — operators discover it via runtime 401s and the admin-side audit log."
+  - "**Picker integration is implicit** — no changes to `ratatoskr.tui.AgentPickerApp` for this issue. Tier 3 agents appear in `GET /agents` if defined and the picker's existing format `{agent_id} · {name} — {description}` renders the colon-containing agent_id without special-casing. Per issue #8 out-of-scope clause, ratatoskr does not visually distinguish Tier 1 vs Tier 3 in the picker — same UX surface."
+  - "**Session-create with colon-containing agent_id works unchanged.** Issue #5 already routes `end_user_id` into the POST /sessions body, which Tier 3 session-create requires from Phase 2.0 (per spec §2649-2664). No `ratatoskr.sessions` change needed."
+  - "**CLI uses argparse with subparsers** (define / patch / delete). The subparsers entry point lives at `python -m ratatoskr.tier3` via `__main__.py`. Output on success: prints a one-line summary (`defined ratatoskr:wizard (qwen3.6-35-a3b)` / `patched ratatoskr:wizard` / `deleted ratatoskr:wizard`). Output on error: `[<error_code>] <message>` to stderr + non-zero exit. Exit codes mirror `ratatoskr.cli`: 0 happy / 10 usage / 11 auth / 20 api-failure / 21 network."
+  - "**No `list` subcommand in v1.** A `tier3 list` operation would have to filter `GET /agents` by prefix-matching the caller's user_id, but that prefix isn't exposed in the response — only the agent_id is, and you'd have to introspect the auth's user_id. Operators discover their own Tier 3 agents by reading the `GET /agents` list (which the picker already surfaces) and looking for `<their-user-id>:*` entries. Add `list` in a follow-up if operators report friction."
+  - "**Module is standalone**: does NOT import or interact with `ratatoskr.sessions` / `ratatoskr.sse_client` / `ratatoskr.tui` / `ratatoskr.cli` beyond reusing the `USER_AGENT` constant from `ratatoskr.cli`. Cross-module use is one-way (cli supplies the user-agent string; tier3 does not import sessions). This keeps the module surface minimal and testable in isolation."
+  - "**The CLI's `python -m ratatoskr.tier3` entry point uses sys.argv handling that mirrors `ratatoskr.cli`** — a top-level `main(argv: list[str] | None = None) -> int` function that argparse-dispatches to subcommand handlers. Each subcommand handler is an async coroutine wrapped by `asyncio.run(...)`. Auth resolution: `--api-key` flag > `$WORLDTREE_API_KEY` env > `_AuthError` (exit 11). Server URL: `--server` > `$WORLDTREE_API_URL` > default `http://localhost:8000` (same default as `ratatoskr.cli`)."
+  - "**Tests use `respx` for HTTP mocking** (same pattern as `tests/test_sessions.py`). New test file: `tests/test_tier3.py`. Cover all success + error response codes per the ERROR_ROUTING matrix below. No live network in unit tests — the live smoke is in the acceptance criteria, not the unit tests."
+open_questions:
+  - "Should `define_agent` accept an optional `bifrost` parameter for Bifrost-bound Tier 3 sessions? The spec §2658 shows `bifrost` as a session-create field (not define-time). Draft: no — Bifrost binding is per-session; if a Tier 3 agent needs Bifrost on every session, that's an orthogonal feature on POST /sessions, not POST /agents/define. Issue #5's `--end-user-id` already covers the session-create-side parameters."
+  - "Should the CLI also offer `--end-user-id` for sessions created via tier3 + ratatoskr-cli composition? Draft: no — once an agent is defined, operators use the main `ratatoskr --new --agent <id> --end-user-id <eid>` flow; tier3 CLI is define/patch/delete only."
+  - "Should `delete_agent` support a `--force` flag for 'really delete even if active sessions exist'? Per spec §2634-2639, `DELETE` already cancels active sessions and revokes the per-resource scope grant on the owner — there's no soft fail. Draft: no — the spec's hard-delete-with-cascade behavior is the right shape; ratatoskr doesn't need to wrap it."
+prd:
+  issue: 15
+  issue_url: "https://gitea.phasefinal.com/vh/ratatoskr/issues/15"
+  body_sha256_16: "03367d7b451ab17f"
+  lock_in_comment_id: null
+  lock_in_sha256_16: null
+  lock_in_at: null
+  pinned_at: "2026-05-25T03:21:38+00:00"
+dependencies:
+  - issue: 2
+    path: "src/ratatoskr/sessions.py"
+    reason: "Convention dependency, not a code dependency. Issue #2 (`ratatoskr.sessions`) is the posture template: caller-owned httpx client, async-native, no Worldtree imports, response-parsing into frozen dataclasses, exception body truncation to [:1024]. `ratatoskr.tier3` follows the same shape verbatim."
+  - issue: 3
+    path: "src/ratatoskr/cli.py"
+    reason: "Convention dependency only. `ratatoskr.tier3.__main__` mirrors `ratatoskr.cli`'s argparse + env-fallback + exit-code shape. Imports `USER_AGENT` from `ratatoskr.cli` so outbound HTTP carries the same identity string."
+---
+
+# Tier 3 — Consumer-defined agent lifecycle module
+
+## Context
+
+Worldtree's Tier 3 (Phase 2.0, spec §2576-2750) lets the consumer define their own agents at `<user_id>:<agent_name>`. The agent's `user_id` is the auth's user identity (derived from the API key's owner); the `agent_name` is supplied at define-time. The lifecycle is owner-only — only the key that defined an agent can patch / delete it (modulo the key-revocation cascade).
+
+`ratatoskr.tier3` exposes this lifecycle as a Python module + small CLI tool. Picker integration is implicit (Tier 3 agents already appear in `GET /agents` per issue #8). Session-create works unchanged through `ratatoskr.sessions.create_session` since the colon-containing agent_id is opaque to that layer.
+
+## Public surface
+
+```python
+@dataclass(frozen=True)
+class Tier3AgentInfo:
+    """Worldtree Tier 3 agent envelope returned by define / patch."""
+
+    agent_id: str       # f"{user_id}:{agent_name}"
+    user_id: str
+    agent_name: str
+    system_prompt: str
+    model: str
+    created_at: str     # ISO 8601 with offset
+    updated_at: str     # ISO 8601 with offset
+
+
+async def define_agent(
+    client: httpx.AsyncClient,
+    *,
+    agent_name: str,
+    system_prompt: str,
+    model: str,
+) -> Tier3AgentInfo:
+    """POST /agents/define → 201 with Tier3AgentInfo. See FN define_agent."""
+
+
+async def patch_agent(
+    client: httpx.AsyncClient,
+    agent_id: str,
+    *,
+    system_prompt: str | None = None,
+    model: str | None = None,
+) -> Tier3AgentInfo:
+    """PATCH /agents/<id> → 200 with updated Tier3AgentInfo. See FN patch_agent."""
+
+
+async def delete_agent(client: httpx.AsyncClient, agent_id: str) -> None:
+    """DELETE /agents/<id> → 204. See FN delete_agent."""
+```
+
+## Exception classes
+
+```python
+class Tier3QuotaExceeded(Exception):
+    """429 agent_quota_exceeded — 50-agent cap reached on the Heimdall key."""
+    def __init__(self, *, retry_after: int) -> None: ...
+    retry_after: int
+
+class Tier3UserIdUnsupported(Exception):
+    """403 tier3_user_id_unsupported — auth's user_id not slug-safe."""
+
+class Tier3FieldNotMutable(Exception):
+    """422 field_not_mutable — PATCH carrying an immutable key."""
+    def __init__(self, *, field: str | None) -> None: ...
+    field: str | None
+
+class Tier3LayerDeferred(Exception):
+    """422 layer_deferred — define carrying non-null layer field."""
+    def __init__(self, *, field: str | None) -> None: ...
+    field: str | None
+
+class Tier3AgentNotFound(Exception):
+    """404 — patch/delete on non-existent agent."""
+    def __init__(self, *, agent_id: str) -> None: ...
+    agent_id: str
+
+# Reused from ratatoskr.sessions (one-way import — sessions doesn't depend on tier3):
+# SessionApiFailed(status, body) for all other non-2xx responses.
+```
+
+## Functions
+
+### FN define_agent
+
+```
+FN define_agent(
+    client: httpx.AsyncClient,
+    *, agent_name: str, system_prompt: str, model: str,
+) -> Tier3AgentInfo
+BRIEF: POST /agents/define → 201 with Tier3AgentInfo.
+
+PRE-001: agent_name matches `[a-z][a-z0-9-]{2,63}` (slug guard — client-side
+         assert; the server enforces too, but this prevents wire round-trip
+         for trivially-bad input).
+PRE-002: system_prompt is non-empty.
+PRE-003: model is non-empty.
+
+STEPS:
+  1. assert PRE-001/002/003.
+  2. body = {
+       "agent_name": agent_name,
+       "system_prompt": system_prompt,
+       "model": model,
+     }
+  3. resp = await client.post("/agents/define", json=body)
+  4. ROUTE response status:
+     201 → parse body into Tier3AgentInfo, return.
+     422 → inspect error_code:
+       layer_deferred → raise Tier3LayerDeferred(field=err.get("field"))
+       (others) → raise SessionApiFailed(status=422, body=resp.content)
+     403 + tier3_user_id_unsupported → raise Tier3UserIdUnsupported
+     429 → raise Tier3QuotaExceeded(retry_after=int(resp.headers.get("Retry-After", 0)))
+     other → raise SessionApiFailed(status, body)
+
+POST-001: returned Tier3AgentInfo has agent_id of shape "<user_id>:<agent_name>".
+```
+
+### FN patch_agent
+
+```
+FN patch_agent(
+    client: httpx.AsyncClient, agent_id: str,
+    *, system_prompt: str | None = None, model: str | None = None,
+) -> Tier3AgentInfo
+BRIEF: PATCH /agents/<id> → 200 with updated Tier3AgentInfo.
+
+PRE-001: agent_id contains `:` (Tier 3 shape).
+PRE-002: at least one of system_prompt or model is non-None (no-op patches
+         are still server-accepted but client-side assert avoids the round-trip).
+
+STEPS:
+  1. assert PRE-001/002.
+  2. body = {}; if system_prompt is not None: body["system_prompt"] = system_prompt;
+     if model is not None: body["model"] = model.
+  3. resp = await client.patch(f"/agents/{agent_id}", json=body)
+  4. ROUTE response status:
+     200 → parse, return.
+     404 → raise Tier3AgentNotFound(agent_id=agent_id)
+     422 + field_not_mutable → raise Tier3FieldNotMutable(field=err.get("field"))
+     other → raise SessionApiFailed(status, body)
+```
+
+### FN delete_agent
+
+```
+FN delete_agent(client: httpx.AsyncClient, agent_id: str) -> None
+BRIEF: DELETE /agents/<id> → 204.
+
+PRE-001: agent_id contains `:` (Tier 3 shape).
+
+STEPS:
+  1. assert PRE-001.
+  2. resp = await client.delete(f"/agents/{agent_id}")
+  3. ROUTE response status:
+     204 → return None.
+     404 → raise Tier3AgentNotFound(agent_id=agent_id)
+     other → raise SessionApiFailed(status, body)
+```
+
+## CLI surface (`python -m ratatoskr.tier3`)
+
+```
+$ python -m ratatoskr.tier3 define --name wizard \
+    --system-prompt "You are a guided-elicitation wizard..." \
+    --model qwen3.6-35-a3b
+defined ratatoskr:wizard (qwen3.6-35-a3b)
+
+$ python -m ratatoskr.tier3 patch ratatoskr:wizard --system-prompt "New prompt"
+patched ratatoskr:wizard
+
+$ python -m ratatoskr.tier3 delete ratatoskr:wizard
+deleted ratatoskr:wizard
+```
+
+Auth + server URL: same env-var fallback as `ratatoskr.cli`. Exit codes: 0 / 10 (usage) / 11 (auth) / 20 (api-failure) / 21 (network).
+
+## Invariants
+
+- **INV-001**: `define_agent` request body carries exactly `{agent_name, system_prompt, model}` — no layer fields, no `bifrost`, no `metadata`. Phase 2.0 baseline shape only.
+- **INV-002**: `patch_agent` request body carries ONLY `system_prompt` and/or `model` — every other key is omitted. Server-side 422 `field_not_mutable` is the safety net; client-side body-construction is the first line.
+- **INV-003**: `delete_agent` is fire-and-confirm — no body, no retry, no soft-delete. Cascade handling is server-side; ratatoskr doesn't track it.
+- **INV-004**: All exceptions carry a `[:1024]` body cap (when applicable) per the issue #2 convention.
+- **INV-005**: CLI auth resolution mirrors `ratatoskr.cli`: `--api-key` flag > `$WORLDTREE_API_KEY` > exit 11.
+- **INV-006**: CLI server URL resolution mirrors `ratatoskr.cli`: `--server` > `$WORLDTREE_API_URL` > `http://localhost:8000`.
+- **INV-007**: Module never imports `ratatoskr.sessions` / `ratatoskr.sse_client` / `ratatoskr.tui` (one-way: only `cli.USER_AGENT` is imported, and only by `__main__.py` for the outbound User-Agent header).
+- **INV-008**: All HTTP through caller-owned `httpx.AsyncClient` — module never constructs its own client. (`__main__` constructs one for the CLI entry point per ratatoskr.cli's pattern.)
+
+## TESTS (tests/test_tier3.py — new file)
+
+```
+- test_define_happy: 201 + full response shape → Tier3AgentInfo populated.
+- test_define_quota_exceeded: 429 + Retry-After header → Tier3QuotaExceeded(retry_after=N).
+- test_define_user_id_unsupported: 403 tier3_user_id_unsupported → Tier3UserIdUnsupported.
+- test_define_layer_deferred_persona: 422 layer_deferred → Tier3LayerDeferred (would only fire if the body sent a layer field; the module never sends one, so this asserts server-side defense but reflecting a 422 we don't actually generate. Test exercises the response path, not the request).
+- test_define_bad_slug: PRE-001 assertion fires before HTTP for agent_name="X" (uppercase) or "ab" (too short).
+- test_define_empty_prompt: PRE-002 assertion fires for empty system_prompt.
+- test_define_other_5xx: 503 → SessionApiFailed(status=503).
+- test_patch_happy_both_fields: 200 + updated body → Tier3AgentInfo.
+- test_patch_happy_single_field: 200 with only system_prompt set; body omits model.
+- test_patch_field_not_mutable: 422 field_not_mutable → Tier3FieldNotMutable.
+- test_patch_404: 404 → Tier3AgentNotFound(agent_id=...).
+- test_patch_no_args: PRE-002 assertion fires (both None).
+- test_patch_non_tier3_id: PRE-001 assertion fires for agent_id without `:`.
+- test_delete_happy: 204 → returns None.
+- test_delete_404: 404 → Tier3AgentNotFound.
+- test_delete_non_tier3_id: PRE-001 assertion fires.
+- test_delete_other_5xx: 500 → SessionApiFailed.
+- test_cli_define_happy: argv → 201 mock → stdout="defined ratatoskr:wizard (qwen3.6-35-a3b)" + exit 0.
+- test_cli_patch_happy: argv → 200 mock → stdout="patched ratatoskr:wizard" + exit 0.
+- test_cli_delete_happy: argv → 204 mock → stdout="deleted ratatoskr:wizard" + exit 0.
+- test_cli_missing_auth: no API key → stderr "[auth_error]" + exit 11.
+- test_cli_api_failed: 500 mock → stderr "[api_failed]" + exit 20.
+```
+
+## ERROR_ROUTING (module + CLI)
+
+| HTTP shape | error_code | Exception (module) | CLI label | Exit |
+|---|---|---|---|---|
+| 201 / 200 / 204 | — | (none — happy) | one-line confirmation on stdout | 0 |
+| 429 | agent_quota_exceeded | `Tier3QuotaExceeded(retry_after=N)` | `[quota_exceeded] retry_after=N` | 20 |
+| 403 | tier3_user_id_unsupported | `Tier3UserIdUnsupported` | `[user_id_unsupported]` | 20 |
+| 404 | — | `Tier3AgentNotFound(agent_id=...)` | `[agent_not_found] <id>` | 20 |
+| 422 | field_not_mutable | `Tier3FieldNotMutable(field=...)` | `[field_not_mutable] field=...` | 20 |
+| 422 | layer_deferred | `Tier3LayerDeferred(field=...)` | `[layer_deferred] field=...` | 20 |
+| any other non-2xx | — | `SessionApiFailed(status, body)` | `[api_failed] status=N body=...` | 20 |
+| httpx.ConnectError / ReadTimeout / TransportError | — | propagates | `[network_error] T: M` | 21 |
+| PRE-001/002/003 assertion violation | — | `AssertionError` | `[usage_error] <msg>` | 10 |
+| no auth | — | `_AuthError` (reused from cli) | `[auth_error] no API key` | 11 |
+
+## Layout after this module lands
+
+```
+src/ratatoskr/
+  __init__.py
+  cli.py            (existing, unchanged)
+  sessions.py       (existing, unchanged)
+  sse_client.py     (existing, unchanged)
+  tui.py            (existing, unchanged)
+  tier3.py          NEW
+  __main__/         (no change — main cli still entry-point)
+
+# CLI invocation:
+$ python -m ratatoskr.tier3 define --name wizard ...
+$ python -m ratatoskr.tier3 patch ratatoskr:wizard ...
+$ python -m ratatoskr.tier3 delete ratatoskr:wizard
+```

docs/contracts/issues/8.contract.md

@@ -0,0 +1,323 @@
+---
+contract_version: "2.1"
+target_module: "ratatoskr.sessions"
+scope: "Startup agent picker for TUI mode when `--new` is passed without `--agent`. Small surface change distributed across three existing modules via in-place contract amendments: `ratatoskr.sessions` gains `list_agents()` (GET /agents) returning `list[AgentInfo]` (new frozen dataclass with omit-when-null defaults mirroring SessionInfo's INV-001/INV-002 pattern); `ratatoskr.cli` softens `--agent` requirement from absolute to mode-conditional (`--send --new` still requires it; bare `--new` accepts None; `--session` still forbids it); `ratatoskr.tui._resolve_then_run` gains a pre-create branch that, when `args.new and args.agent_id is None`, calls `list_agents(client)` then runs a dedicated tiny `AgentPickerApp` (separate Textual `App` instance, opens before the main `RatatoskrApp`) whose `run_async()` returns the chosen `agent_id` (or `None` on Esc/Ctrl-D for clean exit). No new files; no wire-level surface change beyond the new endpoint hit. Composes naturally with #5 (`--end-user-id`): both thread through `ParsedArgs` before any App opens."
+depends_on:
+  - "httpx"
+  - "textual"
+used_by:
+  - "ratatoskr.cli"
+  - "ratatoskr.tui"
+language: "python"
+complexity: "low"
+estimated_loc: 200
+confidence: 0.85
+assumptions:
+  - "Worldtree spec pin (`docs/conversation-api-spec.md` v0.19.0, repo SHA `55101e909abcd2219833266b6f905c5bc956e0f0`) declares `GET /agents` at §832: returns 200 with a JSON array of agent objects. Three fields always present (`agent_id`, `name`, `description`); five optional with omit-when-null/omit-when-empty semantics (`version`, `capabilities`, `supported_models`, `persona_traits`, `ui_hints`). No pagination, no filters, no auth-scope requirement beyond bearer-authenticated (worldtree-dev confirmed 2026-05-23: Tier 1 `agent.list` baseline scope covers it; same auth posture as POST /sessions)."
+  - "`AgentInfo` is a frozen dataclass on `ratatoskr.sessions` (alongside `SessionInfo` / `SessionPage`) carrying all 8 fields. Origin-conditional defaults mirror INV-001/INV-002 from issue #2: required fields (`agent_id`, `name`, `description`) take the response value verbatim; optional fields default to `None` (scalar `version`) or empty container (`capabilities=[]`, `supported_models=[]`, `persona_traits={}`, `ui_hints={}`) when omitted from the response. Empty containers (NOT `None`) for collection-shaped optionals so caller code can branch on truthiness without `is None` ceremony."
+  - "`list_agents` uses the same caller-owned-client posture as `create_session` / `list_sessions`: takes `httpx.AsyncClient`, returns `list[AgentInfo]`, raises `SessionApiFailed(status, body)` on any non-200 response. No new exception type — list_agents' failure modes (auth, transport, server-side 5xx) all map cleanly to the existing `SessionApiFailed` shape. The module's posture against shared types with sse_client (`ratatoskr.sessions` issue #1 convention dependency) is preserved."
+  - "**CLI surface change is mode-conditional, not flag-removal**: `--agent` becomes optional ONLY when `--new` is passed AND `--send` is NOT passed (i.e., bare TUI-mode create). `--send --new` still raises `UsageError('--agent is required when --new is passed in --send mode')` because non-interactive --send mode has no way to prompt. `--session <id>` still forbids `--agent` (preserves issue #3 INV-004 mutual-exclusion). The single existing line `if ns.new and not ns.agent: raise UsageError(...)` in `_parse_args` STEP 3 splits into two conditionals that distinguish on `ns.send`."
+  - "**Picker is its own App, not a Screen within RatatoskrApp** (deliberate divergence from the issue body's 'pushed onto the App's screen stack' phrasing, which predated issue #6's refactor). Reason: issue #6's load-bearing invariant is that session-resolution + startup errors land on the operator's REAL stderr before any alt-screen opens. `list_agents` failures (network, auth, server error) need that same property. Doing it via a Screen inside RatatoskrApp re-introduces the alt-screen-eats-stderr problem #6 fixed. Doing it via a separate `AgentPickerApp` opened in `_resolve_then_run` (before `RatatoskrApp`) preserves #6's invariant: `list_agents` errors print to stderr and short-circuit BEFORE the picker's alt-screen opens; picker errors (which don't really exist — it's pure UI navigation) are bounded; chosen `agent_id` flows back through `app.run_async()`'s return value."
+  - "**Two alt-screen cycles is acceptable** (picker opens + closes; main RatatoskrApp opens). Textual's `App.run_async()` handles alt-screen entry + restoration cleanly per-instance. The visible-flicker cost is one quick alt-screen flash between picker dismissal and main App mount; the architectural cost of avoiding this (Screen-within-App, breaking #6) is higher than the cosmetic cost. If empirical operator feedback indicates the flicker is jarring, follow-up issue collapses to one App with two Screens AFTER re-engineering the stderr-error path."
+  - "**Picker Esc/Ctrl-D returns exit 0, NOT a `UsageError`**: when the operator dismisses the picker without choosing, the intent is 'never mind, exit cleanly' — same as Ctrl-D from the main chat pane in INV-002 of issue #4. `_resolve_then_run` returns 0 without calling `create_session` or `App.run_async()` on RatatoskrApp. No session is created server-side; no `agent_id` is required to satisfy this exit path."
+  - "**Picker layout uses ListView, not DataTable**: design-brief §5 mentions `DataTable` for the session picker but ListView is the right primitive for agent picking — single-column, keyboard-navigable, one row per agent rendered as `agent_id · name — description`. v1 picker is a flat list per the issue's out-of-scope clause (search/filter/sort/ui_hints rendering all deferred). DataTable's column-header + sortable-column ergonomics are wasted on this surface."
+  - "**Empty agent list is a clean exit, not an error**: if `GET /agents` returns `[]`, the picker writes `[no_agents] server returned empty agent list\\n` to stderr and `_resolve_then_run` returns exit code 13 (new — see ERROR_ROUTING below). The picker UI never opens in this case; no point showing an empty list with no actionable rows."
+  - "**Single agent does NOT auto-select**: if `GET /agents` returns one agent, the picker still opens with one row. Auto-select would hide the choice (and the agent's description) from the operator. The cost is one keystroke; the benefit is transparency about what's about to happen."
+  - "**`AgentInfo` field order in the dataclass matches the spec's column order** (`agent_id`, `name`, `description`, `version`, `capabilities`, `supported_models`, `persona_traits`, `ui_hints`). Mirrors how readers scanning the dataclass map mental model from spec → code."
+  - "**`AgentInfo.persona_traits` / `ui_hints` are typed as `dict[str, Any]` not nested dataclasses**: v1 picker just displays `agent_id · name — description`; the inner shape (ocean object, icon, color_hint, vibe) is opaque to ratatoskr. Future polish that renders icon/color_hint would either parse on-demand or introduce nested dataclasses then. Keeping them as dict[str, Any] avoids paying a typing tax now for a display surface that's deferred."
+  - "**`list_agents` does NOT pass query params**: spec §832 declares no pagination, no filters. The request is a bare `GET /agents` with the bearer header from the caller-owned client. If Worldtree later adds filters (e.g., `?capability=foo`), `list_agents` gains them via amendment then."
+open_questions:
+  - "Should the picker display `version` when available (e.g., `mimir v0.2.0 — Keeper of the Well of Knowledge`)? Draft: no for v1 — the issue body specifies `agent_id · name — description` exactly. Add in a follow-up if operators report ambiguity (two `mimir` rows from different deployments). Drift-check evidence first."
+  - "Should `AgentPickerApp.run_async()` return the chosen `AgentInfo` or just the `agent_id` string? Draft: just the `agent_id` string for v1 — that's all `create_session` needs. Returning the full `AgentInfo` would let `RatatoskrApp` show name/description in the identity widget without re-fetching, but the existing identity widget format is `<agent_id> · …<session_id>` so the extra metadata has no consumer yet. Defer until §5 side-panes work needs it."
+  - "Should the picker show a loading spinner while `list_agents` is in flight? Draft: no for v1 — list_agents runs BEFORE the picker App opens (per the architectural decision above), so there's no in-app loading state to show. Operator sees stderr label on failure; on success the picker opens with the list already populated. If the request latency turns out to be noticeable (e.g., >300ms), reconsider."
+prd:
+  issue: 8
+  issue_url: "https://gitea.phasefinal.com/vh/ratatoskr/issues/8"
+  body_sha256_16: "c34f4878936a4edc"
+  lock_in_comment_id: null
+  lock_in_sha256_16: null
+  lock_in_at: null
+  pinned_at: "2026-05-24T00:49:03+00:00"
+dependencies:
+  - issue: 2
+    path: "src/ratatoskr/sessions.py"
+    reason: "In-place contract amendment: new `list_agents()` function + new `AgentInfo` frozen dataclass added to the module's public surface. POST /sessions paths unchanged; no shared types with the new code beyond the module's existing `SessionApiFailed` exception (reused for non-200 responses)."
+  - issue: 3
+    path: "src/ratatoskr/cli.py"
+    reason: "In-place contract amendment: `_parse_args` STEP 3 splits the single `if ns.new and not ns.agent` check into two conditionals — `--send --new` keeps the strict requirement; bare `--new` accepts `agent_id=None` for the TUI-picker case."
+  - issue: 4
+    path: "src/ratatoskr/tui.py"
+    reason: "In-place contract amendment: new `AgentPickerApp(App[str | None])` class with ListView + Enter/Esc bindings; `_resolve_then_run` gains a pre-create branch that runs the picker when `args.new and args.agent_id is None`; on chosen `agent_id`, threads it into `create_session(client, chosen, end_user_id=args.end_user_id)`. RatatoskrApp itself is unchanged."
+---
+
+# Startup agent picker — GET /agents when --new without --agent (TUI)
+
+## Context
+
+Today, `ratatoskr --new` requires `--agent <id>`. If omitted, `_parse_args`
+raises `UsageError("--agent is required when --new is passed")`. That's
+correct for `--send --new` (non-interactive — can't prompt) but wrong
+for the TUI (operator may not know which agents are available, would
+prefer to pick from a list at startup).
+
+Worldtree's spec §832 exposes `GET /agents`. The endpoint returns a flat
+JSON array; required fields are `agent_id`, `name`, `description`;
+optional fields (`version`, `capabilities`, `supported_models`,
+`persona_traits`, `ui_hints`) follow omit-when-null/empty rules. No
+pagination, no filters, no special scope. Worldtree-dev confirmed
+2026-05-23: Tier 1 baseline auth covers it.
+
+This issue threads a small surface change through three existing modules
+in-place — no new files apart from this contract.
+
+## Data flow
+
+**Input:**
+- `httpx.AsyncClient` (caller-owned, base_url + bearer auth on the client).
+- No request body, no query params.
+
+**Output (`list_agents`):**
+- `list[AgentInfo]` — one entry per available agent, in server-declared order.
+
+**Output (`AgentPickerApp.run_async()`):**
+- `str | None` — chosen `agent_id`, or `None` on Esc/Ctrl-D dismissal.
+
+## Public surface (ratatoskr.sessions amendment)
+
+```python
+@dataclass(frozen=True)
+class AgentInfo:
+    """One agent's metadata from GET /agents.
+
+    INV-005: Required fields (`agent_id`, `name`, `description`) take the
+    response value verbatim. Optional fields default to None (`version`)
+    or an empty container (`capabilities`, `supported_models`,
+    `persona_traits`, `ui_hints`) when omitted from the server response,
+    mirroring SessionInfo's INV-001/INV-002 origin-conditional pattern.
+    """
+
+    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]
+
+
+async def list_agents(client: httpx.AsyncClient) -> list[AgentInfo]:
+    """GET /agents → list of available agents. See contract FN list_agents."""
+```
+
+## Functions
+
+### FN list_agents
+
+```
+FN list_agents(client: httpx.AsyncClient) -> list[AgentInfo]
+BRIEF: GET /agents → list of available agents. No pagination, no filters.
+
+PRE-001: client is not None.
+
+STEPS:
+  1. resp = await client.get("/agents")
+  2. IF resp.status_code != 200:
+       raise SessionApiFailed(status=resp.status_code, body=resp.content)
+  3. body = resp.json()  # expected: list[dict]
+  4. items = [
+       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
+     ]
+  5. RETURN items
+
+POST-001: every item in the return list has required fields populated.
+POST-002: optional fields default to None / [] / {} when absent from the response.
+
+ERROR_ROUTING:
+  - 200 with non-list body          → KeyError / TypeError propagates (server bug; not handled here).
+  - non-200                         → SessionApiFailed(status=N, body=resp.content)
+  - httpx.RequestError              → propagates (network failure; caller handles).
+
+TESTS:
+  - test_happy_full_shape: 200 + spec's full-shape mimir example → AgentInfo with all fields populated.
+  - test_happy_minimum_shape: 200 + spec's minimum-shape "minimal" example → AgentInfo with required + defaulted optional.
+  - test_happy_multi_agent: 200 + array of 3 agents → list of 3 AgentInfo in order.
+  - test_happy_empty: 200 + [] → empty list (no error).
+  - test_omit_capabilities: 200 + agent missing capabilities → AgentInfo.capabilities == [].
+  - test_omit_persona_traits: 200 + agent missing persona_traits → AgentInfo.persona_traits == {}.
+  - test_omit_ui_hints: 200 + agent missing ui_hints → AgentInfo.ui_hints == {}.
+  - test_500_raises: 500 → SessionApiFailed with status=500.
+  - test_401_raises: 401 → SessionApiFailed with status=401.
+```
+
+## CLI surface change (ratatoskr.cli amendment)
+
+`_parse_args` STEP 3, currently:
+
+```python
+if ns.new and not ns.agent:
+    raise UsageError("--agent is required when --new is passed")
+```
+
+becomes:
+
+```python
+if ns.new and not ns.agent:
+    if ns.send is not None:
+        # --send --new mode: non-interactive, cannot prompt for choice.
+        raise UsageError("--agent is required with --new in --send mode")
+    # else: bare --new (TUI mode) — agent_id stays None, TUI runs picker.
+```
+
+INV-004 (`--session` + `--agent` mutual exclusion) is unchanged. Existing
+`--send --new` smoke flows that pass `--agent` continue to work unchanged.
+
+ERROR_ROUTING (cli):
+- `--send --new` without `--agent` → `UsageError` → exit 10 (unchanged from today).
+- bare `--new` without `--agent` → `ParsedArgs.agent_id=None`, TUI handles.
+
+TESTS (additions to test_cli.py):
+- test_parse_send_new_without_agent_raises: `--send "hi" --new` (no --agent) → UsageError.
+- test_parse_bare_new_without_agent_accepted: `--new` (no --agent, no --send) → ParsedArgs with agent_id=None.
+- test_parse_bare_new_with_agent_accepted: `--new --agent mimir` → unchanged behavior, agent_id="mimir".
+
+## TUI surface change (ratatoskr.tui amendment)
+
+### New: AgentPickerApp
+
+```python
+class AgentPickerApp(App[str | None]):
+    """Single-purpose picker App. Opens before RatatoskrApp.
+
+    `run_async()` returns the chosen agent_id (str) or None on Esc/Ctrl-D.
+    """
+
+    BINDINGS: ClassVar[list[Binding]] = [
+        Binding("enter", "pick", "Pick", priority=True),
+        Binding("escape", "dismiss", "Cancel", priority=True),
+        Binding("ctrl+d", "dismiss", "Cancel", priority=True),
+        Binding("ctrl+c", "dismiss", "Cancel", priority=True),
+    ]
+
+    def __init__(self, agents: list[AgentInfo]) -> None:
+        super().__init__()
+        assert agents  # PRE-002 — caller guarantees non-empty
+        self.agents = agents
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("Pick an agent for the new session:", id="picker-prompt")
+        yield ListView(
+            *[
+                ListItem(Label(f"{a.agent_id} · {a.name} — {a.description}"))
+                for a in self.agents
+            ],
+            id="agent-list",
+        )
+        yield Footer()
+
+    async def on_mount(self) -> None:
+        self.query_one("#agent-list", ListView).focus()
+
+    def action_pick(self) -> None:
+        lv = self.query_one("#agent-list", ListView)
+        idx = lv.index
+        if idx is None:
+            return  # no row highlighted; ignore
+        self.exit(self.agents[idx].agent_id)
+
+    def action_dismiss(self) -> None:
+        self.exit(None)
+```
+
+### Modified: _resolve_then_run
+
+Insert a pre-create branch between the `async with httpx.AsyncClient(...)`
+and the existing `if args.new:` block:
+
+```python
+async def _resolve_then_run(args: ParsedArgs) -> int:
+    assert isinstance(args, ParsedArgs) and args.send_content is None
+    async with httpx.AsyncClient(...) as client:
+        # NEW (issue #8): startup agent picker when --new without --agent.
+        chosen_agent_id: str | None = args.agent_id
+        if args.new and args.agent_id is None:
+            try:
+                agents = await list_agents(client)
+            except SessionApiFailed as exc:
+                sys.stderr.write(
+                    f"[session_api_failed] status={exc.status} body={exc.body!r}\n"
+                )
+                return 20
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.TransportError) as exc:
+                sys.stderr.write(f"[network_error] {type(exc).__name__}: {exc}\n")
+                return 21
+            if not agents:
+                sys.stderr.write("[no_agents] server returned empty agent list\n")
+                return 13
+            picker = AgentPickerApp(agents)
+            chosen_agent_id = await picker.run_async()
+            if chosen_agent_id is None:
+                return 0  # Esc/Ctrl-D — clean exit, no session created
+        # EXISTING: create_session OR re-use --session id
+        if args.new:
+            assert chosen_agent_id is not None
+            try:
+                info = await create_session(
+                    client, chosen_agent_id, end_user_id=args.end_user_id
+                )
+            ...
+        else:
+            ...
+        app = RatatoskrApp(args, session_id=session_id, agent_id=agent_id, client=client)
+        ...
+```
+
+### ERROR_ROUTING (tui startup)
+
+| Failure | Stderr label | Exit |
+|---------|--------------|------|
+| `list_agents` → `SessionApiFailed` | `[session_api_failed] status=N body=B` | 20 |
+| `list_agents` → network error | `[network_error] T: M` | 21 |
+| empty agent list (`GET /agents` returns `[]`) | `[no_agents] server returned empty agent list` | 13 (new) |
+| picker Esc/Ctrl-D dismissal | (none — clean exit) | 0 |
+| `create_session` post-pick → `AgentNotFound` | `[agent_not_found] agent_id=X` | 12 (unchanged from #4) |
+
+INV: exit code 13 is new (no-agents). Previously unused — does not collide
+with any existing exit code in `_resolve_then_run` or `_amain`.
+
+### TESTS (additions to test_tui.py)
+
+```
+- test_picker_happy_path: list_agents returns 2 agents; AgentPickerApp opens; user picks index 0; chosen agent_id flows into create_session; main App opens.
+- test_picker_esc_clean_exit: list_agents returns 2 agents; picker opens; user presses Esc; _resolve_then_run returns 0; create_session NOT called; RatatoskrApp NOT opened.
+- test_picker_skipped_when_agent_id_provided: bare --new --agent mimir → list_agents NOT called; picker NOT opened; create_session called with "mimir".
+- test_picker_skipped_when_session_mode: --session s-1 → list_agents NOT called; picker NOT opened; no create_session.
+- test_picker_list_agents_session_api_failed: list_agents raises SessionApiFailed → stderr [session_api_failed]; exit 20; picker NOT opened; create_session NOT called.
+- test_picker_list_agents_network_error: list_agents raises ConnectError → stderr [network_error]; exit 21.
+- test_picker_empty_list: list_agents returns [] → stderr [no_agents]; exit 13; picker NOT opened; create_session NOT called.
+- test_agent_picker_app_renders_rows: AgentPickerApp with 3 agents → ListView has 3 ListItem children with expected text.
+- test_agent_picker_app_pick_returns_agent_id: simulate Enter on highlighted row → exit value == agents[idx].agent_id.
+- test_agent_picker_app_dismiss_returns_none: simulate Esc → exit value is None.
+```
+
+## Invariants
+
+- **INV-005**: `AgentInfo` field defaults are origin-conditional (mirrors INV-001/002 from #2). Required → verbatim; optional → None / [] / {}.
+- **INV-006**: `list_agents` failure modes route through `SessionApiFailed` only — no new exception type introduced.
+- **INV-007**: Picker is a separate App, opened by `_resolve_then_run` BEFORE `RatatoskrApp`. Preserves issue #6's stderr-error invariant for `list_agents` failures.
+- **INV-008**: `--agent` CLI requirement is mode-conditional: required only when `--send --new`; bare `--new` accepts None; `--session` always forbids it.
+- **INV-009**: Picker dismissal (Esc/Ctrl-D) returns clean exit 0; no session created server-side.
+- **INV-010**: Empty agent list is a clean stderr exit (code 13), not an open picker.
+- **INV-011**: Single-agent response still opens the picker — no auto-select.
+- **INV-012**: Two alt-screen cycles (picker + main App) is the explicit architectural tradeoff for preserving INV-007.

persistent-memory.md

@@ -1,6 +1,6 @@
 # Persistent memory — ratatoskr
 
-_Last updated: 2026-05-23_
+_Last updated: 2026-05-24_
 
 This file captures durable intent and supporting evidence (goals, decisions,
 foot-gun warnings, in-flight state) across context resets. Read it at session
@@ -32,77 +32,107 @@ separate dev team rather than an in-tree Worldtree tool.
 
 ## Current state / in-flight
 
-_As of 2026-05-23 (end of day, post-#12 implementation, pre-commit):_
+_As of 2026-05-25 (post-v0.8.2 drop double-print; v0.9.0 live-md next):_
 
-**Status: issue #12 (presenter contract semantics amendment)
-TDD-complete, in working tree, awaiting commit.** Seven core issues
-complete (`sse_client` #1, `sessions` #2, `cli` #3, `tui` #4,
-`--end-user-id` #5, TUI startup error visibility #6, presenter
-contract semantics amendment #12) + robustness fix #7 (MalformedSseData
-+ empty-skip). 208/208 tests GREEN; ruff clean. pyproject.toml bumped
-to v0.2.0; `uv.lock` refreshed. Working tree has 9 modified files +
-the new `docs/contracts/issues/12.contract.md` (untracked); commit not
-yet authored.
+**Status: v0.8.2 shipped.** Eleven core features complete (`sse_client`
+#1, `sessions` #2, `cli` #3, `tui` #4, `--end-user-id` #5, TUI
+startup error visibility #6, presenter contract semantics amendment
+#12, startup agent picker #8, §5 layout reshape + Tools pane #13)
++ robustness fix #7 (MalformedSseData + empty-skip) + v0.2.1 TUI
+layout fix. 236/236 tests GREEN; ruff clean.
+
+**§5 v1 entry point shipped (issue #13).** TUI now Horizontal
+two-column: left = chat surface (transcript + thinking-current +
+prompt); right = TabbedContent with single Tools tab (RichLog
+receiving ToolStart/ToolResult events). Routing-not-duplication:
+tool events leave the main transcript entirely. Ctrl+1 activates
+Tools tab without losing Input focus (INV-016). New `pane-name`
+Static in the footer (static "Tools" v1; dynamic when more tabs
+land). CLI mode (--send) unaffected by design — INV-018.
 
 Last commits on `main`:
-- `8282156` snapshot: persistent-memory Heimdall scope-model foot-gun (post-v0.1.0)
-- `804c2df` feat(sessions,cli,tui): issues #5 + #6 + worldtree-dev consumer-API follow-up (tagged v0.1.0)
+- v0.8.2 fix(tui): drop post-Done Markdown body re-render (no double-print)
+- `11ef683` fix(tui,sse): inline Text streaming + empty-id keepalive skip (v0.8.1)
+- `9fade55` feat(local_agents): JSON-backed local tier-3 index + picker merge (v0.8.0)
+- `9918c10` fix(tui): coalesce thinking deltas on `\n` (v0.7.1)
+- `c086ae2` feat(tier3): ratatoskr.tier3 module + CLI (v0.7.0)
+- `d356990` refactor(tui): thinking streams into thinking-log (v0.6.5)
+- `82437bd` style(tui): picker highlighted item → Aurora blue (v0.6.4)
+- `ac690c1` style(tui): restore Australis palette, only $background → pure black (v0.6.3)
+- `d845b20` style(tui): neutralize Australis dark palette (v0.6.2, reverted)
+- `8463eb2` style(tui): kill remaining blue + thinking-current into pane (v0.6.1)
+- `cfee89a` refactor(tui): streaming + turn headers + Thinking pane (v0.6.0)
+- `7106af5` style(tui): UI polish pass — terminal label colors, placeholders (v0.5.1)
+- `ffd22fb` refactor(tui): content-only main pane + Debug tab + chrome dark (v0.5.0)
+- `2756f5f` style(tui): apply Australis theme to TUI chrome + widgets (v0.4.1)
+- `24e4371` feat(tui): issue #13 — §5 layout reshape + Tools pane (v0.4.0)
+- `d30be12` feat(sessions,cli,tui): issue #8 — startup agent picker (v0.3.0)
+- `c85f6bd` fix(tui): anchor layout via dock so Input never moves (v0.2.1)
+- `3b9c610` feat(cli,tui): issue #12 — presenter contract semantics amendment (v0.2.0)
+- `8282156` snapshot: persistent-memory Heimdall scope-model foot-gun
+- `804c2df` feat(sessions,cli,tui): issues #5 + #6 + worldtree-dev follow-up (v0.1.0)
 
-`--send` validated end-to-end against personal Worldtree at v0.1.0
-(`http://10.250.50.152:8081`, mimir on qwen3.6-35-a3b, 2026-05-23 smoke
-returned `[done] turn_id=116 duration_ms=5467`). Lofn smoke is
-**auth-unblocked** as of 2026-05-23 — worldtree-dev confirmed our key
-(`c990f0be`) already covers Tier 1 agents via the `agent.call:*`
-baseline policy; the initial "scope-add needed" diagnosis was a phantom
-ask (see Tried-and-abandoned). The actual lofn fix shipped as issue #5
-(`--end-user-id` flag).
-
-**Async cross-frontier activity in flight:**
-- Issue #12 code-review consult posted to volva 2026-05-23 (althing
-  thread `01KSBH8GYH4G3H03T767X613W7`). Reply pending in inbox.
+**Smoke status:**
+- `--send --new --agent mimir` v0.3.0 smoke clean
+  (`[done] turn_id=141 model=qwen3.6-35-a3b duration=2.2s`).
+- Live `list_agents` smoke against personal Worldtree returned 12
+  agents (actor, bragi, cara, domari, forseti, glados, leif, lofn,
+  mimir, soong, troi, saga).
+- Picker end-to-end smoke against live Worldtree: bare `--new` →
+  list_agents → picker (auto-picked lofn programmatically since
+  driving alt-screen interactively from CLI smoke isn't possible)
+  → POST /sessions with end_user_id="ratatoskr-tui" succeeded;
+  RatatoskrApp constructed with agent_id="lofn".
+- TUI v0.2.0 was visually broken (Input pane bouncing with thinking
+  runs); v0.2.1 fixed via dock-based layout. Operator confirmed
+  "a lot better" interactively.
 
 **Outstanding operator-side todos:**
-- **Commit issue #12 work** + tag v0.2.0 + push. 9 modified files +
-  new `12.contract.md` ready.
-- **Post-v0.2.0 mimir smoke (the visual one)** — `source env.sh && uv
-  run ratatoskr --new --agent mimir --send "test"` to eyeball the new
-  rendering (`. thinking: ...` coalesce, `. worker_phase: ...` demotion,
-  `duration=5.5s` formatting, `usage 6756 in -> 126 out (...)` shape).
-  The v0.1.0 mimir smoke confirmed wire-level backwards compat but
-  did NOT exercise the v0.2.0 rendering.
-- **Post-v0.2.0 lofn smoke** — `source env.sh && uv run ratatoskr
-  --new --agent lofn --send "hello"` (env.sh ships
-  `RATATOSKR_END_USER_ID="ratatoskr-tui"`). Now unblocked on auth.
+- **Interactive §5 layout eyeball** — `source env.sh && uv run
+  ratatoskr --new --agent mimir`, ask a tool-using question
+  ("search your KB for X"). Confirm: left column shows chat /
+  thinking; right column's Tools tab shows tool_start +
+  tool_result with `· ` prefix; Ctrl+1 doesn't break input focus;
+  no width-clamp issues on the operator's terminal. Programmatic
+  smoke confirmed all the routing + binding; visual confirmation
+  pending.
+- **Post-v0.2.1 TUI multi-turn eyeball** — confirm thinking-run
+  bouncing is gone across multiple turns; the layout fix has only
+  been confirmed for a single turn so far.
 
 **Pending issues filed but not started:**
-- **Issue #8 (startup agent picker)** — filed but unscaffolded.
-  `GET /agents` is free to call (worldtree-dev confirmed); auth side
-  is unblocked. Depends on #5 composably (both thread through
-  `ParsedArgs` → `_resolve_then_run`).
 - **Issue #9 (spec-pin refresh v0.19.0 → v0.22.1)** — filed
-  2026-05-23. Documentation debt. None of the v0.20.0/v0.21.0/v0.22.0
-  changes break ratatoskr's existing surface; the pin lies about
-  what we've committed to.
-- **Issue #10 (subject:{type,id} migration)** — filed 2026-05-23 to
-  track Worldtree #196's LOCKED-but-not-shipped breaking change.
-  Don't pre-implement per worldtree-dev's explicit guidance.
+  2026-05-23. Documentation debt; defer unless we need a v0.20.0+
+  capability.
+- **Issue #10 (subject:{type,id} migration)** — filed 2026-05-23
+  to track Worldtree #196. Don't pre-implement per worldtree-dev.
 - **Issue #11 (AdminEvents pane auth prerequisite)** — filed
-  2026-05-23. Future side-pane requires `admin.events.read` scope.
+  2026-05-23. Future side-pane needs `admin.events.read` scope.
 
-Branch: `main` (dirty with #12 work pending commit). Remote:
+**Pending Worldtree-dev follow-up:**
+- worldtree-dev committed (althing `01KSBKTG096Q…`) to file a
+  Worldtree-side issue for the stall-watchdog gap (cancel-check is
+  inside the engine-event loop, so a never-yielding first-LLM-call
+  bypasses the 300s watchdog). Will file after the immediate stall
+  is cleared.
+- Ratatoskr-side companion (potential): a client-side stall watchdog
+  (e.g., 90s-no-events → `[server_stalled]` stderr label, keep
+  connection). Defer until recurrence; defense-in-depth regardless of
+  whether Worldtree fixes its own.
+
+Branch: `main` (clean). Remote:
 `origin → git@gitea.phasefinal.com:vh/ratatoskr.git`.
 
 **Next natural moves:**
 
-1. **Triage volva's #12 code-review** when the reply lands in the
-   inbox; apply tactical fixes inline, surface architectural calls.
-2. **Commit + tag v0.2.0 + push.**
-3. **Post-v0.2.0 smokes** — mimir (visual), lofn (newly unblocked).
-4. **Issue #8 (startup agent picker)** — scaffold + contract, then
-   TDD. Composes with the forward end_user_id direction (see Recent
-   decisions).
-5. **Side-pane issues** — Persona pane first (file-tail, cheap).
-6. **Issue #9 (spec-pin refresh)** — defer unless we need a v0.20.0+
+1. **Interactive picker eyeball** — operator confirms the TUI
+   picker UX (rendering, Enter pick, Esc dismiss) against personal
+   Worldtree.
+2. **§5 side-panes work** — Persona pane first per design-brief; the
+   collapsible Thinking pane + Debug pane proposals fold IN as
+   additional `TabbedContent` tabs alongside Persona/Tools/AdminEvents.
+   Reshapes layout from vertical-stack to Horizontal two-column.
+3. **Issue #9 (spec-pin refresh)** — defer unless we need a v0.20.0+
    capability (e.g., `memory_context` for Phase 2.1).
 
 ## Recent decisions
@@ -134,6 +164,8 @@ decision. Captures rationale that won't be obvious from code alone.
 - `[2026-05-23]` **Issue #5 (`--end-user-id`) implemented via TDD.** Small surface change across three modules (sessions, cli, tui): `create_session(client, agent_id, *, end_user_id=None)` widens with optional kwarg; body conditionally adds the field when non-None (INV-002: omitting != sending empty); PRE-003 asserts non-empty. `ParsedArgs.end_user_id: str | None = None` field; `--end-user-id` CLI flag with non-empty validation (mirrors `--send` check). `_amain` and `_resolve_then_run` thread `end_user_id=args.end_user_id` to their `create_session` calls. Post-#6 adjustment: the contract originally named `on_mount` as the TUI threading site, but #6 had moved session resolution to `_resolve_then_run` — same shape, different function. 7 new tests across the 3 modules.
 - `[2026-05-23]` **Worldtree-dev consult landed authoritative consumer-API guidance** (althing thread `01KSBARG2B8M8C82H6AJGJWX1B`). Key takeaways shaped follow-on work: (1) `end_user_id` is a free-form partition key for long-term memory + persona/valence state; same value → same partition, different values → fully isolated. For Vuong-debugging-Worldtree the recommended posture is a project-stable default with `--end-user-id` override. (2) No programmatic `requires_end_user_id` discovery on `GET /agents` — "try and react to 422" remains the pattern. (3) Breaking-change #196 LOCKED but not shipped: `subject:{type,id}` replaces `end_user_id` at future v0.22.x or v0.23.0; don't pre-implement. (4) Spec pin (v0.19.0) is 3 minor versions stale (current v0.22.1); none of v0.20.0/v0.21.0/v0.22.0 break ratatoskr's surface but the pin lies about what we're committed to. (5) User-Agent header: send one (`ratatoskr/<version> (vh@phasefinal.com)`). (6) `agents.call:lofn` scope needed for lofn smoke. (7) `GET /agents` requires no special scope; issue #8 unblocked on auth.
 - `[2026-05-23]` **Follow-up acted on:** User-Agent header added to both `_amain` and `_resolve_then_run` httpx.AsyncClient constructions (with `importlib.metadata` version lookup + fallback to `0.0.0`); `RATATOSKR_END_USER_ID` env-var fallback added to `_parse_args` (resolution: flag > env > None); env.sh ships `RATATOSKR_END_USER_ID="ratatoskr-tui"` as project-stable default. Original issue #5 posture rejected env-var fallback as "papering over isolation"; revised after worldtree-dev's guidance that the realistic single-operator use case wants partition continuity. Issue #5 + #3 contracts amended in-place to document the env-var fallback. Infra-ops pinged via althing for `agents.call:lofn` scope (broker pattern; they forwarded to worldtree-dev). Three Gitea issues filed: #9 (spec-pin refresh), #10 (subject:{type,id} migration tracking), #11 (AdminEvents pane auth prereq).
+- `[2026-05-23]` **v0.2.1 layout fix: dock-anchored TUI chrome so Input never moves** (commit `c85f6bd`, tag `v0.2.1`). Reported during the v0.2.0 mimir TUI smoke: Input bouncing up/down throughout a turn, tokens landing at shifting screen positions. Cause: v0.2.0's `Static(id="thinking-current")` was yielded between `hint` and `Footer` in the auto-stacked vertical flow, so each `display=True/False` toggle per thinking-run shifted Input + identity + hint vertically; RichLog growth from streaming text also drifted Input downward. Fix: `RatatoskrApp.DEFAULT_CSS` docks the chrome to screen edges — `thinking-current` docks top under Header; `transcript` (RichLog) gets `height: 1fr` and absorbs all reflows internally via its scroll viewport; `prompt`, `identity`, `hint` all dock bottom (locked above Footer). Compose order moved `thinking-current` to position 2 (right after Header) so source-order matches the dock layout. **Operator-confirmed "a lot better"** interactively. Pure UI fix; no public API change; tests pass without modification. v0.2.0 → v0.2.1 (patch). I couldn't verify in a TTY from this non-interactive session — the design was sound enough to ship blind, with operator verification post-commit. Going forward: TUI-layout patches like this are "ship + operator verifies" since the TTY is the load-bearing test surface and respx + Pilot mocks can't catch screen-relative positioning bugs.
+- `[2026-05-23]` **Sequencing decision: design-brief §5 side-panes work absorbs the inline collapsible-Thinking-pane + Debug-pane proposals; do issue #8 (startup agent picker) BEFORE §5.** Surfaced during the v0.2.1 follow-up discussion. The operator's proposal — "create a collapsible pane for all thinking tokens; text_boundary goes to a debug pane" — is exactly §5-shaped work (the design-brief proposes a `Horizontal` two-column layout with `TabbedContent` for Persona/Tools/AdminEvents/BifrostState/ServerLog). Building inline-Collapsibles now and then rebuilding as `TabbedContent` panes at §5 would be wasted work. So: do #8 first (independent surface, no layout overlap), then §5 (which folds in Thinking + Debug panes alongside the design-brief's named §5 panes). Interim acceptance: v0.2.1 fixes the structural layout-bouncing pain; transcript-dominated-by-thinking is still real but doesn't degrade further — operator can scroll back, Input doesn't move, tokens land predictably. The interim "noisy transcript" pain is real but bounded; §5 work resolves it cleanly.
 - `[2026-05-23]` **Issue #12 (presenter contract semantics amendment) implemented via TDD.** Headline: thinking deltas render as ONE coalesced growing line (CLI) / one closed RichLog entry per run + live Static(id="thinking-current") widget per-delta (TUI), not 50 lines per turn. Introduced stateful per-turn presenters: `CliPresenterState` (cli.py) and `TuiPresenterState` (tui.py), both `@dataclass(slots=True)` with thinking_buffer + thinking_open (+ text_written_since_newline for CLI). Editorial promotion line settled: load-bearing = Text/Done/Error/Cancelled (no prefix); demoted telemetry = WorkerPhase/Thinking/TextBoundary/ToolStart/ToolResult (CLI `. ` ASCII prefix; TUI `· ` Unicode dim prefix). CLI stdout/stderr newline-boundary INV-005: when text was streamed mid-line, flush a `\n` to stdout before writing terminal labels to stderr; `text_written_since_newline = not event.content.endswith("\n")` per Volva F4 fix. Helpers `_format_duration_ms` (`347ms` / `5.5s` / `1.2m` autoscale) and `_format_usage` (`6756 in -> 126 out (6882 total, 0 cached)` with arrow="->" CLI or "→" TUI). Per Vor (eitri-smithy-dev cross-frontier consult, althing 01KSBE52YZR5) + Volva paraphrase (5 contract-text ambiguities all fixed in #12.contract.md). `[create_session]` lifecycle line demoted to `. create_session:` (written directly by `_amain`, bypasses state.render). Old `_render_event` / `_render_event_to_log` functions and their TestRenderEvent/TestRenderEventToLog classes removed (no-backwards-compat rule). Contracts amended: #3 (CliPresenterState block + `_run_turn` thread state + `_amain` create_session demotion + `_format_*` helper blocks), #4 (TuiPresenterState block + `_stream_turn_worker` state construction + `compose` Static widget addition). 39 new tests; 19 obsolete tests removed; net 208 GREEN. v0.1.0 → v0.2.0 (minor; pre-amendment output shape broken intentionally — scripts grepping `[thinking] '` no longer work; that's the intended cleanup). Cross-frontier design pass with eitri-smithy-dev returned 16-of-16 confirmed decisions + 4 material divergences applied (ASCII `· ` factual fix, RichLog-one-entry-per-run vs inline-mirror, presenter-state object vs stateless, "contract semantics amendment" framing not "polish"). Calibration note: eitri-smithy-dev's value here was *architectural* (state-object pattern + chronological-vs-live decoupling) not just *tactical*; the framing rename alone justified the consult. Volva paraphrase round added 5 prose-precision fixes (INV-001 "growing display" semantics, TUI hide mechanism unification, render_error security/readability tension, newline-tracking corner case, [create_session] integration path).
 - `[2026-05-23]` **Forward direction: Ratatoskr will require `end_user_id` for EVERY access before too long.** Operator's call. Reasoning: even Tier 1 foundational agents (mimir, all Asgardians) that don't *require* `end_user_id` server-side currently fall back to a `_no_end_user` sentinel substrate partition — effectively pollution from a single-operator-debug-tool's perspective. The right shape is "every conversation has an explicit partition key." `RATATOSKR_END_USER_ID="ratatoskr-tui"` env-default in env.sh is the first step toward that posture; once we've validated the partition-isolation experience, the next move is making `end_user_id` mandatory (probably remove the `None`-default in `_parse_args`, fail-closed with a UsageError if neither flag nor env provides it). Consequence for cross-project asks: declined worldtree-dev's offer to ship `requires_end_user_id: bool` on `AgentInfoResponse` because we'd treat every value as true regardless; the try-and-react-to-422 pattern goes away from our side because we never send a request without the field. File a ratatoskr issue when scheduling the change — touches `_parse_args` validation + `_resolve_then_run` + `_amain` + tests + contract amendments to #3 / #5. Treat as a v0.2.0 minor (breaking: existing `--new --agent mimir` without env or flag would start failing). **Cross-frontier alignment (worldtree-dev ack 2026-05-23, althing 01KSBD9FPMCWJMBXNNS4B3MYBS):** the platform side agrees with this framing — `_no_end_user` is a substrate accommodation for identity-less transports, NOT a consumer model. The fallback's `_is_fallback=True` trap door (#185 INV-185-5/8) "could become operator-controlled later" per worldtree-dev, meaning Worldtree itself may tighten the substrate-fallback path. Ratatoskr's forward posture pre-empts that tightening — moving from "we send end_user_id when set" to "we never send a request without end_user_id" stays consumer-correct regardless of what Worldtree does with the fallback knob.
 
@@ -153,4 +185,5 @@ defense against re-attempting the same cul-de-sac.
 - `[2026-05-21]` **TUI session-identity rendering via `self.sub_title` + `self.hint` plain attributes.** Stored state but never rendered to a visible widget. The contract's "session-identity-always-visible" invariant was satisfied at the state-attribute level but not the user-visible-widget level. Tests asserted the attributes (which passed); Volva code-review flagged the gap. Fix: dedicated `Static(id="identity")` + `Static(id="hint")` widgets in compose; `_set_hint()` helper mirrors state → widget. Calibration evidence for the "TDD catches state, code-review catches whether the user can see it" pattern.
 - `[2026-05-23]` **Using the cross-model review agent's name directly in composed prose.** The peer review agent's name (the `althing` handle starting with "V-o-l-v-a") is one letter from a body-part term. Anthropic's content classifier does fuzzy matching and intermittently blocks responses mid-stream when the name appears in composed prose sentences (especially in meta-commentary about the agent's work). Direct-quoted tool output (e.g., the `althing-cli thread` body) passes through fine. Mitigation: use role descriptions ("the cross-model reviewer," "the paraphrase peer") in prose rather than the name; quote content via tool output. Confirmed by switching to Sonnet 4.6 for a test read — same raw content read cleanly when fetched via Bash rather than composed into an LLM response. This is a persistent environmental constraint, not a one-off.
 - `[2026-05-22]` **`json.loads(sse.data)` unguarded against empty data.** `_iter_events` unconditionally called `json.loads` on every dispatched `ServerSentEvent`. When `httpx_sse` surfaced a frame with `id:` present but `data:` empty (a known library-vs-spec divergence — RFC says don't dispatch; httpx_sse is permissive), `json.loads('')` raised `JSONDecodeError` → propagated through Textual's worker → app crash. Crashed mimir conversation at turn 93/seq 1078 after 1077 successful events. Fix: `if sse.data == '': continue` BEFORE `_parse_sse_id` (empty-data event with a malformed id is still a keepalive — don't reorder). Non-empty malformed data raises new `MalformedSseData(raw[:200])`. Don't reintroduce unconditional `json.loads(sse.data)`; always pre-check for the empty case.
+- `[2026-05-23]` **Diagnostic shorthand: "2-events-then-silence" = Worldtree-side LLM-call wedge, not ratatoskr.** If a mimir `--send` smoke shows exactly two stderr events — `. create_session: ...` followed by `. worker_phase: phase=BuildingPrompt ...` — and then nothing for >60s, the root cause is upstream of ratatoskr. Worldtree's `service.py:2560` gates the `CallingLLM` event on the engine yielding its first LLM-provider chunk; if that provider connection is wedged at the TCP level, the `async for` never iterates and the SSE stream stays silent forever. ratatoskr's `read=None` httpx timeout (the issue #1 + #4 INV-007 fix for "5s default killed mid-stream during mimir's thinking") waits patiently as designed; there's no client-side stall watchdog above the read-timeout layer. Worldtree's OWN stall watchdog (300s `_start_stall_timer`) exists but its cancel-check is INSIDE the engine-event loop, so a never-yielding first-LLM-call bypasses it. Confirmed by worldtree-dev (althing thread `01KSBKTG096Q07JVRG41JXA1DD`). **Don't waste time bisecting ratatoskr code when this shape appears** — diagnose the LLM-provider connection state at Worldtree's host. Restarting the Worldtree service (`:8081` in our case) cleared a wedged llama-swap connection. Future ratatoskr issue worth filing if recurrence: client-side stall watchdog (e.g., 90s-no-events → `[server_stalled]` stderr label, keep connection open). Also worth knowing: 10.250.50.152 hosts 3 Worldtree instances (`:8080`, `:8081`, `:8082`) — each with its own DB and key namespace. Our key is valid only on `:8081`.
 - `[2026-05-23]` **Phantom "per-Tier-1-agent scope add" pattern.** Issue #5's lofn 422 was initially diagnosed (with worldtree-dev's first reply) as needing `agents.call:lofn` added to ratatoskr's existing key. Routed through infra-ops via althing per the credential-brokerage rule; infra-ops discovered no public scope-mutation endpoint on personal Worldtree, brokered to worldtree-dev for the actual mechanism. Worldtree-dev came back with a correction: their first answer conflated two distinct Heimdall scope namespaces. **Tier 1 foundational agents** (mimir, lofn, soong, all Asgardians) are covered by a blanket `agent.call:*` (singular) baseline rule in `config/policies.yaml > tiers.<tier>.scopes` for ALL authenticated tiers including `user`. There is no per-agent grant for Tier 1 — the baseline rule covers it. **Tier 3 consumer-defined agents** (IDs containing `:`, like `vh:custom-bot`) use the plural `agents.call:<owner>:<agent>` shape granted implicitly via owning a `consumer_agents` DB row, registered through `POST /agents/define`. The two notations differ by one letter and that was the source of the confusion. **The actual lofn fix was issue #5's `--end-user-id` flag — it was always a request-body validation, not an auth-scope gate.** Don't ping infra-ops for "per-Tier-1-agent scope adds" again; the pattern is a phantom ask. Real future infra-ops asks: admin-tier key for the AdminEvents pane (`admin.events.read` scope, different tier), and Tier 3 custom-agent registration (different flow entirely, requires `POST /agents/define`).

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ratatoskr"
-version = "0.2.0"
+version = "0.8.2"
 description = "Worldtree Conversation API debug TUI — multi-pane observability dashboard"
 readme = "README.md"
 requires-python = ">=3.12"

src/ratatoskr/cli.py

@@ -124,8 +124,11 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
         raise UsageError("pass exactly one of --session or --new")
     if ns.session and ns.agent:
         raise UsageError("--agent is required with --new and forbidden with --session")
-    if ns.new and not ns.agent:
-        raise UsageError("--agent is required when --new is passed")
+    if ns.new and not ns.agent and ns.send is not None:
+        # Issue #8: --agent stays required for --send --new (non-interactive,
+        # cannot prompt). Bare --new (TUI mode) accepts None — picker drives
+        # the choice via list_agents in _resolve_then_run.
+        raise UsageError("--agent is required when --new is passed in --send mode")
 
     api_key = ns.api_key or os.environ.get("WORLDTREE_API_KEY") or ""
     if not api_key:

src/ratatoskr/local_agents.py

@@ -0,0 +1,134 @@
+"""Local index of tier-3 agents defined via `python -m ratatoskr.tier3`.
+
+Workaround for Worldtree's ``GET /agents`` not returning consumer-defined
+agents (the public list excludes tier-3 per-spec; see issue #15 smoke
+findings). Local file maintains a list of agent_ids + display metadata so
+the picker can show them alongside foundational agents.
+
+Storage shape: JSON at ``$XDG_CONFIG_HOME/ratatoskr/local_agents.json``
+(default ``~/.config/ratatoskr/local_agents.json``). Override via
+``$RATATOSKR_LOCAL_AGENTS`` env var for tests / per-machine isolation.
+
+If Worldtree later starts returning tier-3 agents in ``GET /agents``, this
+module's role narrows to redundant local cache; can be removed cleanly
+since the picker's dedup-by-agent-id keeps remote-wins behavior.
+
+Failure modes are lenient: missing file → empty index; corrupt JSON or
+schema mismatch → empty index (no crash). The picker continues to show
+foundational agents either way; the local-tier-3 surface degrades to
+"operator passes --agent ratatoskr:<name> explicitly" — the
+pre-v0.8.0 workflow.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class LocalAgentEntry:
+    """One row in the local tier-3 agent index.
+
+    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.
+      - ``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.
+    """
+
+    agent_id: str
+    agent_name: str
+    model: str
+    description: str
+    defined_at: str
+
+
+def _local_agents_path() -> Path:
+    """Resolve the local index file path with XDG + env-var override."""
+    override = os.environ.get("RATATOSKR_LOCAL_AGENTS")
+    if override:
+        return Path(override)
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else (Path.home() / ".config")
+    return base / "ratatoskr" / "local_agents.json"
+
+
+def load_local_agents() -> list[LocalAgentEntry]:
+    """Read the local index. Returns ``[]`` on missing file, corrupt JSON,
+    schema mismatch, or any read error — never raises.
+    """
+    path = _local_agents_path()
+    if not path.exists():
+        return []
+    try:
+        raw = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return []
+    if not isinstance(raw, dict) or raw.get("version") != _SCHEMA_VERSION:
+        return []
+    agents = raw.get("agents", [])
+    if not isinstance(agents, list):
+        return []
+    out: list[LocalAgentEntry] = []
+    for item in agents:
+        if not isinstance(item, dict):
+            continue
+        try:
+            out.append(LocalAgentEntry(**item))
+        except TypeError:
+            # Malformed row (missing/extra fields) — skip silently.
+            continue
+    return out
+
+
+def _save_local_agents(agents: list[LocalAgentEntry]) -> None:
+    """Persist the index. Creates parent dir as needed."""
+    path = _local_agents_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"version": _SCHEMA_VERSION, "agents": [asdict(a) for a in agents]}
+    path.write_text(json.dumps(payload, indent=2))
+
+
+def add_local_agent(entry: LocalAgentEntry) -> None:
+    """Add (or replace) an agent in the local index. agent_id is the key."""
+    agents = [a for a in load_local_agents() if a.agent_id != entry.agent_id]
+    agents.append(entry)
+    _save_local_agents(agents)
+
+
+def update_local_agent(entry: LocalAgentEntry) -> None:
+    """Update an existing entry. Identical semantics to ``add_local_agent``
+    (agent_id is the dedup key), exposed separately so callers can
+    self-document intent.
+    """
+    add_local_agent(entry)
+
+
+def remove_local_agent(agent_id: str) -> None:
+    """Remove an entry by agent_id. No-op if absent (idempotent)."""
+    agents = [a for a in load_local_agents() if a.agent_id != agent_id]
+    _save_local_agents(agents)
+
+
+def make_description(system_prompt: str) -> str:
+    """Synthesize a one-line description for the picker from a system prompt.
+
+    Strategy: first non-empty line, stripped of leading markdown heading
+    markers and whitespace, prefixed with "(tier 3) ", truncated to 80
+    chars. Falls back to "(tier 3) custom system prompt" if the prompt is
+    empty (defensive — define rejects empty prompts at PRE-002).
+    """
+    for line in system_prompt.splitlines():
+        stripped = line.lstrip("# ").strip()
+        if stripped:
+            label = f"(tier 3) {stripped}"
+            return label[:80] + ("…" if len(label) > 80 else "")
+    return "(tier 3) custom system prompt"

src/ratatoskr/sessions.py

@@ -39,6 +39,26 @@ class SessionPage:
     next_cursor: str | None
 
 
+@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]
+
+
 class AgentNotFound(Exception):
     """Raised on HTTP 404 from POST /sessions — unknown agent_id."""
 
@@ -153,3 +173,30 @@ async def create_session(
         archived=False,
         tags=[],
     )
+
+
+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
+    ]

src/ratatoskr/sse_client.py

@@ -309,6 +309,14 @@ async def _iter_events(
             # with a bad id is still a keepalive). Don't reorder.
             if sse.data == "":
                 continue
+            # v0.8.1: empty-id frames are also treated as keepalives. Worldtree
+            # SOMETIMES emits events without an `id:` line (observed mid-stream
+            # on the qwen3.6-35-a3b-heretic provider, 2026-05-25). Per the SSE
+            # RFC, events without ids are legitimate (they just don't update
+            # Last-Event-ID); the previous strict behavior crashed every turn
+            # on the offending agent. Treat same as empty-data: skip silently.
+            if sse.id == "":
+                continue
             try:
                 sse_id = _parse_sse_id(sse.id)
             except ValueError as exc:

src/ratatoskr/tier3.py

@@ -0,0 +1,471 @@
+"""Worldtree Tier 3 (consumer-defined) agent lifecycle client.
+
+Implements docs/contracts/issues/15.contract.md. Caller-owned httpx.AsyncClient
+posture (same as ratatoskr.sessions). Exposes three lifecycle operations:
+
+- ``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.sessions.create_session``.
+
+Spec reference: ``docs/conversation-api-spec.md`` §2576-2750 (Phase 2.0).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from dataclasses import dataclass
+
+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}$")
+
+
+@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,
+    model: 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 model, "model must be non-empty"
+
+    body = {
+        "agent_name": agent_name,
+        "system_prompt": system_prompt,
+        "model": model,
+    }
+    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,
+    model: 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 model is not None, (
+        "patch requires at least one of system_prompt or model"
+    )
+
+    body: dict[str, str] = {}
+    if system_prompt is not None:
+        body["system_prompt"] = system_prompt
+    if model is not None:
+        body["model"] = model
+    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)
+
+
+# ---- 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.
+
+
+class _Tier3UsageError(Exception):
+    """Argparse usage violation → exit 10."""
+
+
+class _Tier3AuthError(Exception):
+    """No API key resolvable → exit 11."""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m ratatoskr.tier3",
+        description="Worldtree Tier 3 (consumer-defined) agent lifecycle.",
+    )
+    parser.add_argument("--api-key", dest="api_key", default=None)
+    parser.add_argument("--server", dest="server", default=None)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_define = sub.add_parser("define", help="Create a Tier 3 agent.")
+    p_define.add_argument("--name", required=True, help="agent_name (slug).")
+    p_define.add_argument(
+        "--system-prompt", dest="system_prompt", required=True,
+        help="System prompt the agent ships with.",
+    )
+    p_define.add_argument(
+        "--model", required=True,
+        help="Provider model ID (NOT a profile alias; e.g., qwen3.6-35-a3b).",
+    )
+
+    p_patch = sub.add_parser("patch", help="Mutate system_prompt and/or model.")
+    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("--model", default=None)
+
+    p_delete = sub.add_parser("delete", help="Hard-delete a Tier 3 agent.")
+    p_delete.add_argument("agent_id", help='Full "<user_id>:<agent_name>" form.')
+
+    return parser
+
+
+def _resolve_auth(ns: argparse.Namespace) -> tuple[str, str]:
+    """Resolve API key + server URL with the same env-var fallback as cli.py."""
+    import os
+
+    api_key = ns.api_key or os.environ.get("WORLDTREE_API_KEY") or ""
+    if not api_key:
+        raise _Tier3AuthError("no API key (set --api-key or WORLDTREE_API_KEY)")
+    server_url = (
+        ns.server or os.environ.get("WORLDTREE_API_URL") or "http://localhost:8000"
+    )
+    return api_key, server_url
+
+
+async def _run_define(ns: argparse.Namespace) -> int:
+    api_key, server_url = _resolve_auth(ns)
+    from ratatoskr.cli import USER_AGENT
+    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(
+            client,
+            agent_name=ns.name,
+            system_prompt=ns.system_prompt,
+            model=ns.model,
+        )
+        # 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,
+            )
+        )
+        print(f"defined {info.agent_id} ({info.model})")
+        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.local_agents import (
+        LocalAgentEntry,
+        make_description,
+        update_local_agent,
+    )
+
+    if ns.system_prompt is None and ns.model is None:
+        raise _Tier3UsageError(
+            "patch requires at least one of --system-prompt or --model"
+        )
+    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(
+            client,
+            ns.agent_id,
+            system_prompt=ns.system_prompt,
+            model=ns.model,
+        )
+        # 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,
+            )
+        )
+        print(f"patched {info.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.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)
+        # 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}")
+        return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Sync entry point — argparse + dispatch + error → exit-code mapping.
+
+    Mirrors ratatoskr.cli.main()'s error-routing matrix:
+      0  happy
+      10 usage error
+      11 auth error
+      20 api-failure (typed exception or generic SessionApiFailed)
+      21 network error
+    """
+    import asyncio
+    import sys
+
+    parser = _build_parser()
+    try:
+        ns = parser.parse_args(argv)
+    except SystemExit as exc:
+        return int(exc.code) if exc.code is not None else 0
+
+    handler = {
+        "define": _run_define,
+        "patch": _run_patch,
+        "delete": _run_delete,
+    }[ns.cmd]
+
+    try:
+        return asyncio.run(handler(ns))
+    except _Tier3UsageError as exc:
+        sys.stderr.write(f"[usage_error] {exc}\n")
+        return 10
+    except _Tier3AuthError as exc:
+        sys.stderr.write(f"[auth_error] {exc}\n")
+        return 11
+    except AssertionError as exc:
+        sys.stderr.write(f"[usage_error] {exc}\n")
+        return 10
+    except Tier3QuotaExceeded as exc:
+        sys.stderr.write(f"[quota_exceeded] retry_after={exc.retry_after}\n")
+        return 20
+    except Tier3UserIdUnsupported:
+        sys.stderr.write("[user_id_unsupported]\n")
+        return 20
+    except Tier3AgentNotFound as exc:
+        sys.stderr.write(f"[agent_not_found] {exc.agent_id}\n")
+        return 20
+    except Tier3FieldNotMutable as exc:
+        sys.stderr.write(f"[field_not_mutable] field={exc.field}\n")
+        return 20
+    except Tier3LayerDeferred as exc:
+        sys.stderr.write(f"[layer_deferred] field={exc.field}\n")
+        return 20
+    except SessionApiFailed as exc:
+        sys.stderr.write(
+            f"[api_failed] status={exc.status} body={exc.body!r}\n"
+        )
+        return 20
+    except (httpx.ConnectError, httpx.ReadTimeout, httpx.TransportError) as exc:
+        sys.stderr.write(f"[network_error] {type(exc).__name__}: {exc}\n")
+        return 21
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())

src/ratatoskr/tui.py

@@ -10,16 +10,34 @@ from __future__ import annotations
 
 import asyncio
 import sys
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import ClassVar, Literal
 
 import httpx
 from textual.app import App, ComposeResult
 from textual.binding import Binding
-from textual.widgets import Footer, Header, Input, RichLog, Static
+from textual.containers import Horizontal, Vertical
+from textual.theme import Theme
+from textual.widgets import (
+    Footer,
+    Header,
+    Input,
+    ListItem,
+    ListView,
+    RichLog,
+    Static,
+    TabbedContent,
+    TabPane,
+)
 
 from ratatoskr.cli import USER_AGENT, ParsedArgs, _format_duration_ms, _format_usage
-from ratatoskr.sessions import AgentNotFound, SessionApiFailed, create_session
+from ratatoskr.sessions import (
+    AgentInfo,
+    AgentNotFound,
+    SessionApiFailed,
+    create_session,
+    list_agents,
+)
 from ratatoskr.sse_client import (
     CancelAlreadyCompleted,
     CancelFailed,
@@ -43,6 +61,74 @@ from ratatoskr.sse_client import (
     stream_turn,
 )
 
+# ---- Australis theme (https://github.com/lkraven/australis) ------------------
+#
+# The Australis Dark color theme, inspired by the Southern Lights. 16 cool-tone
+# terminal colors with medium contrast. Preference order: blue > cyan > green
+# for primary surfaces; Dawn accents (red/yellow/magenta) used sparingly for
+# terminal-event labels (error/cancelled).
+#
+# **v0.6.3 single deviation from spec**: `$background` is `#000000` (pure
+# black), NOT Australis Ice black `#222531`. The Ice black is RGB(34,37,49)
+# — blue dominant — and at App-wide scale the cumulative cast reads as
+# "the whole app is blue" to operators (even though no single surface is
+# "blue" in the strict-color sense). Pure black for the App background
+# kills that perception. EVERY OTHER Australis value — Aurora accents,
+# Sea darks for chrome (surface/panel), Ice white foreground, Dawn
+# accents — stays verbatim per spec.
+#
+# Mapping to Textual's Theme semantic tokens:
+#   primary    = Aurora blue (#6388D8) — focus rings, active selection.
+#   secondary  = Aurora cyan (#00b1a8) — secondary highlights.
+#   accent     = Aurora bright cyan (#42dcd1) — bright accents.
+#   success    = Aurora green (#16B866) — [done] label.
+#   warning    = Dawn yellow (#e1c631) — [cancelled] label.
+#   error      = Dawn red (#ff491a) — [error] label.
+#   foreground = Ice white (#a9bcc3) — default text.
+#   background = pure black (#000000) — App background (v0.6.3 deviation).
+#   surface    = Sea bright black (#373b46) — raised chrome.
+#   panel      = Sea dark 30 (#414751) — borders, separators.
+
+AUSTRALIS_THEME = Theme(
+    name="australis",
+    primary="#6388D8",
+    secondary="#00b1a8",
+    accent="#42dcd1",
+    success="#16B866",
+    warning="#e1c631",
+    error="#ff491a",
+    foreground="#a9bcc3",
+    background="#000000",
+    surface="#373b46",
+    panel="#414751",
+    dark=True,
+    variables={
+        # Sea contrast palette — usable via $au-dark-50 etc. in TCSS.
+        "au-dark-30": "#414751",
+        "au-dark-40": "#565f69",
+        "au-dark-50": "#6e7882",
+        "au-dark-60": "#86929d",
+        "au-bright-70": "#9daeb6",
+        "au-bright-80": "#b3cbcf",
+        "au-bright-white": "#cce7ec",
+        "au-bright-blue": "#a4c4ff",
+        "au-bright-cyan": "#42dcd1",
+        "au-bright-green": "#51e08a",
+    },
+)
+
+
+# Direct hex constants for Rich Text styling (Done/Error/Cancelled labels +
+# transcript user-prompt echo). Themes set TCSS variables; Rich's RichText
+# style strings live outside the theme system, so we resolve to hex here.
+_AU_SUCCESS = "#16B866"
+_AU_ERROR = "#ff491a"
+_AU_WARNING = "#e1c631"
+_AU_USER_ECHO = "#42dcd1"  # Aurora bright cyan — operator's voice
+_AU_DEMOTED = "#86929d"  # Sea dark 60 — demoted telemetry
+_AU_DEMOTED_FAINT = "#6e7882"  # Sea dark 50 — empty-state placeholders
+
+
 # ---- Issue #12 presenter contract semantics amendment -------------------------
 #
 # TuiPresenterState replaces the stateless _render_event_to_log with a stateful
@@ -99,22 +185,46 @@ class TuiPresenterState:
     See `docs/contracts/issues/12.contract.md` for the full spec.
     """
 
-    thinking_buffer: list[str] = field(default_factory=list)
     thinking_open: bool = False
+    # Thinking-run counter for turn-scoped start/end markers.
+    thinking_run_index: int = 0
+    # v0.7.1: thinking-content accumulator. Worldtree emits Thinking deltas
+    # at token granularity; flushing each delta as its own RichLog line
+    # produces per-token-per-newline visual spam. Buffer here and flush
+    # only on `\n` boundaries (one written line per natural paragraph) or
+    # when the run closes (any leftover tail).
+    thinking_chunk_buffer: str = ""
+    # v0.8.1: same pattern for Text deltas. Pre-v0.8.1 the Text deltas
+    # streamed into a dedicated #current-text Static below the transcript;
+    # that Static (docked-bottom, height: auto) grew during streaming and
+    # visually OVERLAPPED the transcript above (Textual didn't dynamically
+    # resize the 1fr transcript while the dock-bottom child expanded).
+    # The Static is gone in v0.8.1 — Text deltas coalesce on `\n` and write
+    # directly to `log` (transcript), the same shape thinking uses.
+    text_chunk_buffer: str = ""
 
     def render(
         self,
         event: Event,
         *,
         log: RichLog,
-        thinking_widget: Static,
+        tools_log: RichLog,
+        debug_log: RichLog,
+        thinking_log: RichLog,
         raw: bool,
     ) -> None:
         """Render one Worldtree SSE event with the TUI hierarchy + coalescing.
 
-        Two-views-of-thinking decoupling: per-delta updates go to
-        `thinking_widget`; one closed entry per run goes to `log`.
-        Exceptions are caught at the presenter boundary (INV-009 fallback).
+        v0.8.1 routing:
+          - `log` (transcript) = chat content: user-prompt echo (written
+            outside the presenter), coalesced Text deltas, terminal labels,
+            optional post-Done Markdown body.
+          - `tools_log` = ToolStart + ToolResult.
+          - `debug_log` = WorkerPhase + TextBoundary.
+          - `thinking_log` = streaming Thinking deltas inline (coalesced on
+            `\n`). Rule(start)/Rule(end) wrap each run.
+
+        Exceptions caught at the presenter boundary (INV-009 fallback).
         """
         assert isinstance(
             event,
@@ -126,80 +236,122 @@ class TuiPresenterState:
         from rich.text import Text as RichText
 
         def _dim(s: str) -> RichText:
-            """Wrap a demoted-telemetry line in dim style for the RichLog."""
-            return RichText(s, style="dim")
+            """Wrap a demoted-telemetry line in Australis Sea dark-60 grey."""
+            return RichText(s, style=_AU_DEMOTED)
 
         try:
-            # Thinking events: accumulate into buffer, update widget per delta.
+            # v0.7.1: Thinking deltas coalesce by newline before flushing.
+            # Worldtree emits Thinking events at token granularity; per-delta
+            # RichLog writes produce one visual line per token (per-token-per-
+            # newline spam). Buffer the deltas and flush only on `\n` (one
+            # written line per natural paragraph) or run close.
             if isinstance(event, Thinking):
+                from rich.rule import Rule
+
                 if not self.thinking_open:
-                    thinking_widget.display = True
+                    self.thinking_run_index += 1
+                    turn_id = event.sse_id.turn_id
+                    thinking_log.write(Rule(
+                        title=f"turn {turn_id} · thinking #{self.thinking_run_index} start",
+                        style=_AU_DEMOTED,
+                    ))
                     self.thinking_open = True
-                self.thinking_buffer.append(event.content)
-                acc = "".join(self.thinking_buffer)
-                display_text = ("…" + acc[-200:]) if len(acc) > 200 else acc
-                thinking_widget.update(display_text)
+                self.thinking_chunk_buffer += event.content
+                # Flush every complete line in the buffer. Whatever's after
+                # the final `\n` stays buffered for the next delta or close.
+                while "\n" in self.thinking_chunk_buffer:
+                    line, _, rest = self.thinking_chunk_buffer.partition("\n")
+                    if line:  # skip empty lines (blank paragraph separators)
+                        thinking_log.write(line)
+                    self.thinking_chunk_buffer = rest
                 return
-            # Non-thinking event: close any open thinking run (one RichLog entry).
+            # Non-thinking event: close any open thinking run with Rule(end).
             if self.thinking_open:
-                full_thinking = "".join(self.thinking_buffer)
-                log.write(_dim(f"· thinking: {full_thinking}"))
-                self.thinking_buffer.clear()
+                from rich.rule import Rule
+
+                # Flush the tail (content with no trailing `\n`) before the
+                # end rule so nothing gets lost on close.
+                if self.thinking_chunk_buffer:
+                    thinking_log.write(self.thinking_chunk_buffer)
+                    self.thinking_chunk_buffer = ""
+                turn_id = event.sse_id.turn_id if hasattr(event, "sse_id") else (
+                    event.turn_id if hasattr(event, "turn_id") else "?"
+                )
+                thinking_log.write(Rule(
+                    title=f"turn {turn_id} · thinking #{self.thinking_run_index} end",
+                    style=_AU_DEMOTED,
+                ))
                 self.thinking_open = False
-                thinking_widget.update("")
-                thinking_widget.display = False
             # Now render the non-thinking event itself.
             if isinstance(event, Text):
-                # Streamed text content — no prefix, no demotion.
-                log.write(event.content)
+                # v0.8.1: stream Text deltas into transcript directly,
+                # coalesced on `\n`. Same pattern as Thinking (v0.7.1).
+                # The pre-v0.8.1 #current-text Static is gone — its dock-
+                # bottom growth was overlapping the transcript visually.
+                self.text_chunk_buffer += event.content
+                while "\n" in self.text_chunk_buffer:
+                    line, _, rest = self.text_chunk_buffer.partition("\n")
+                    if line:
+                        log.write(line)
+                    self.text_chunk_buffer = rest
                 return
             if isinstance(event, (Done, Error, Cancelled)):
-                # Terminal events: load-bearing label (no demotion).
+                # Terminal event: flush any remaining text tail before the
+                # label / Markdown body lands.
+                if self.text_chunk_buffer:
+                    log.write(self.text_chunk_buffer)
+                    self.text_chunk_buffer = ""
+                # Terminal labels tinted per outcome (Aurora green / Dawn red
+                # / Dawn yellow) for at-a-glance scanning.
                 if isinstance(event, Done):
-                    log.write(
+                    log.write(RichText(
                         f"[done] turn_id={event.sse_id.turn_id} model={event.model} "
                         f"duration={_format_duration_ms(event.duration_ms)} "
-                        f"usage {_format_usage(event.usage, arrow='→')}"
-                    )
-                    if not raw:
-                        from rich.markdown import Markdown
-                        from rich.rule import Rule
-
-                        log.write(Rule())
-                        log.write(Markdown(event.response))
+                        f"usage {_format_usage(event.usage, arrow='→')}",
+                        style=_AU_SUCCESS,
+                    ))
+                    # v0.8.2: post-Done Markdown body re-render dropped. Pre-
+                    # v0.8.2 the transcript got BOTH the streamed text AND
+                    # the Markdown(response) re-render — same content twice,
+                    # operator-flagged as "double prints". The streamed text
+                    # IS the response now; markdown formatting (bold, lists,
+                    # code) renders as plain text. Matches thinking pane's
+                    # stream-as-content semantics (no post-close re-render).
                 elif isinstance(event, Error):
-                    log.write(
+                    log.write(RichText(
                         f"[error] turn_id={event.sse_id.turn_id} code={event.error_code} "
-                        f"message={event.message!r}"
-                    )
+                        f"message={event.message!r}",
+                        style=_AU_ERROR,
+                    ))
                 else:  # Cancelled
-                    log.write(
+                    log.write(RichText(
                         f"[cancelled] turn_id={event.turn_id} reason={event.reason!r} "
-                        f"partial_message_id={event.partial_message_id}"
-                    )
-                # Belt-and-braces (Volva F3): ensure widget cleared+hidden on EVERY
-                # terminal event, even if thinking_open was False — per STEPS 5-6.
-                thinking_widget.update("")
-                thinking_widget.display = False
+                        f"partial_message_id={event.partial_message_id}",
+                        style=_AU_WARNING,
+                    ))
                 return
             if isinstance(event, WorkerPhase):
-                log.write(_dim(
+                # v0.5.0: telemetry → Debug pane, not transcript.
+                debug_log.write(_dim(
                     f"· worker_phase: phase={event.phase} turn_id={event.turn_id}"
                 ))
                 return
             if isinstance(event, ToolStart):
-                log.write(_dim(
+                # Issue #13 INV-014: tool events route to the Tools pane.
+                tools_log.write(_dim(
                     f"· tool_start: name={event.name} args={event.arguments!r}"
                 ))
                 return
             if isinstance(event, ToolResult):
-                log.write(_dim(
+                # Issue #13 INV-014: tool events route to the Tools pane.
+                tools_log.write(_dim(
                     f"· tool_result: name={event.name} duration_ms={event.duration_ms} "
                     f"result={event.result!r:.200}"
                 ))
                 return
             if isinstance(event, TextBoundary):
-                log.write(_dim(
+                # v0.5.0: telemetry → Debug pane, not transcript.
+                debug_log.write(_dim(
                     f"· text_boundary: kind={event.kind} char_offset={event.char_offset}"
                 ))
                 return
@@ -207,16 +359,275 @@ class TuiPresenterState:
             # INV-009 + POST-007 fallback: write pre-amendment plain-label line for
             # the original event AND a render_error line with the class name only
             # (NO exception message — security clause). Volva F1 fix.
-            log.write(_plain_label(event))
-            log.write(f"[render_error] {type(exc).__name__}")
+            #
+            # v0.6.0 routing-under-failure preservation — fallback writes go
+            # to the same destination the successful render would have used:
+            #   - ToolStart/ToolResult       → tools_log
+            #   - Thinking                   → thinking_log
+            #   - WorkerPhase/TextBoundary   → debug_log
+            #   - everything else            → log
+            if isinstance(event, (ToolStart, ToolResult)):
+                target = tools_log
+            elif isinstance(event, Thinking):
+                target = thinking_log
+            elif isinstance(event, (WorkerPhase, TextBoundary)):
+                target = debug_log
+            else:
+                target = log
+            target.write(_plain_label(event))
+            target.write(f"[render_error] {type(exc).__name__}")
+
+
+class AgentPickerApp(App[str | None]):
+    """Startup agent picker (issue #8). Opens before RatatoskrApp when --new
+    is passed without --agent. `run_async()` returns the chosen agent_id (str)
+    or None on Esc/Ctrl-D dismissal.
+
+    Architecturally separate from RatatoskrApp (deliberate per issue #8
+    INV-007): keeps list_agents failures landing on real stderr before any
+    alt-screen opens, preserving issue #6's invariant.
+    """
+
+    DEFAULT_CSS = """
+    /* v0.6.1: kill Textual's $primary-blue tints everywhere — Header sub-
+       widgets (HeaderIcon etc.) have their own $primary tinting that the
+       parent `Header { background: $surface }` rule alone doesn't cover.
+       Sub-selectors force the cool palette down to every level. */
+    Header, HeaderIcon, HeaderTitle, HeaderClock {
+        background: $surface;
+        color: $au-bright-blue;
+    }
+    Footer {
+        background: $surface;
+    }
+    /* v0.6.1: scrollbar uses Textual's $primary-tint by default. Force
+       Australis Sea darks so the scrollbar gutter doesn't read as a blue
+       strip. Applied to ListView (the scrollable widget here). */
+    ListView {
+        scrollbar-background: $background;
+        scrollbar-background-hover: $background;
+        scrollbar-background-active: $background;
+        scrollbar-color: $au-dark-50;
+        scrollbar-color-hover: $au-dark-60;
+        scrollbar-color-active: $au-bright-cyan;
+    }
+    #picker-prompt {
+        dock: top;
+        height: 1;
+        padding: 0 1;
+        color: $au-bright-cyan;
+        background: $surface;
+    }
+    #agent-list {
+        height: 1fr;
+        background: $background;
+    }
+    /* Multi-line agent items. Each ListItem is auto-height so the full
+       description wraps below the agent_id/name line — no truncation.
+       v0.6.4: lock bg to $background so Textual's auto background-tint on
+       focus doesn't bleed through unwanted color into the non-highlighted
+       items. */
+    #agent-list > ListItem {
+        height: auto;
+        padding: 1 1;
+        background: $background;
+    }
+    /* v0.6.4: highlighted item gets Aurora blue background (Textual's
+       default $block-cursor-background = $primary). Override only the
+       text-color descendants so id-line/desc stay readable on blue. The
+       background itself comes from Textual's default ListItem.-highlight
+       rule — we removed our previous overriding selectors.
+
+       Textual's class is `-highlight` (single dash). Use plain descendant
+       combinator to bypass internal DOM wrappers. */
+    #agent-list:focus ListItem.-highlight {
+        background: $primary;
+    }
+    #agent-list:focus ListItem.-highlight .agent-id-line {
+        color: $au-bright-white;
+        text-style: bold;
+    }
+    #agent-list:focus ListItem.-highlight .agent-desc {
+        color: $au-bright-80;
+    }
+    /* Default (unhighlighted) item text styling. */
+    .agent-id-line {
+        color: $au-bright-blue;
+        text-style: bold;
+    }
+    .agent-desc {
+        color: $au-bright-70;
+    }
+    """
+
+    BINDINGS: ClassVar[list[Binding]] = [
+        Binding("enter", "pick", "Pick", priority=True),
+        Binding("escape", "dismiss", "Cancel", priority=True),
+        Binding("ctrl+d", "dismiss", "Cancel", priority=True),
+        Binding("ctrl+c", "dismiss", "Cancel", priority=True),
+    ]
+
+    def __init__(self, agents: list[AgentInfo]) -> None:
+        super().__init__()
+        # PRE-002: caller (_resolve_then_run) checks for empty list and emits
+        # [no_agents] before constructing the picker.
+        assert agents
+        self.agents = agents
+        self.register_theme(AUSTRALIS_THEME)
+        self.theme = "australis"
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("Pick an agent for the new session:", id="picker-prompt")
+        # v0.6.0: each ListItem has two Static children — the id/name line
+        # in bold blue + the wrapped description in muted dark-60. No
+        # description truncation; tall items breathe so the operator can
+        # actually read what each agent does.
+        yield ListView(
+            *[
+                ListItem(
+                    Static(f"{a.agent_id} · {a.name}", classes="agent-id-line"),
+                    Static(a.description, classes="agent-desc"),
+                )
+                for a in self.agents
+            ],
+            id="agent-list",
+        )
+        yield Footer()
+
+    async def on_mount(self) -> None:
+        self.query_one("#agent-list", ListView).focus()
+
+    def action_pick(self) -> None:
+        lv = self.query_one("#agent-list", ListView)
+        idx = lv.index
+        if idx is None:
+            return  # nothing highlighted; ignore
+        self.exit(self.agents[idx].agent_id)
+
+    def action_dismiss(self) -> None:
+        self.exit(None)
 
 
 class RatatoskrApp(App[int]):
     """Textual TUI shell — single chat pane."""
 
+    # Issue #13 + v0.5.0 follow-up: Horizontal two-column layout per
+    # design-brief §5. Left column (2fr) is the **content-only** chat
+    # surface — assistant text, user prompt echo, [done]/[error]/[cancelled]
+    # terminal labels, post-Done markdown render. Right column (1fr) houses
+    # ALL telemetry: live thinking preview docked above TabbedContent;
+    # tab strip carries Tools (ToolStart/ToolResult) + Debug (Thinking
+    # closed runs + WorkerPhase + TextBoundary).
+    #
+    # v0.5.0 routing change: thinking-current Static moved from left column
+    # to right column header so the left column is genuinely content-only;
+    # closed thinking runs go to debug-log instead of transcript.
+    #
+    # v0.5.0 chrome fix: Header/Footer backgrounds explicitly set to $surface
+    # (Sea bright-black #373b46) overriding Textual's default $primary-blue
+    # tinting. TabbedContent active-tab tinting also softened.
+    #
+    # Australis theme variables ($primary/$accent/$au-dark-60/$au-bright-cyan/
+    # etc.) carry colors so a future theme swap rebinds centrally.
+    DEFAULT_CSS = """
+    /* v0.6.1: kill Textual's default $primary-blue tinting on chrome —
+       Header sub-widgets (HeaderIcon, HeaderTitle, HeaderClock) each carry
+       their own $primary tint that the parent `Header { background }` rule
+       doesn't override; sub-selectors force the cool palette down. */
+    Header, HeaderIcon, HeaderTitle, HeaderClock {
+        background: $surface;
+        color: $au-bright-blue;
+    }
+    Footer {
+        background: $surface;
+    }
+    /* v0.6.1: scrollbars default to $primary-tint blue. Force Sea darks
+       on the scrollable widgets (RichLog instances). */
+    RichLog {
+        scrollbar-background: $background;
+        scrollbar-background-hover: $background;
+        scrollbar-background-active: $background;
+        scrollbar-color: $au-dark-50;
+        scrollbar-color-hover: $au-dark-60;
+        scrollbar-color-active: $au-bright-cyan;
+    }
+    #main-row {
+        height: 1fr;
+    }
+    #left-column {
+        width: 2fr;
+        border-right: solid $panel;
+    }
+    #right-column {
+        width: 1fr;
+    }
+    /* v0.6.5: thinking-current Static removed; thinking now streams
+       directly into thinking-log so the whole pane scrolls naturally. */
+    #transcript {
+        height: 1fr;
+        background: $background;
+        padding: 0 1;
+    }
+    /* v0.8.1: #current-text Static removed. Streaming text now coalesces
+       on `\n` and writes directly to #transcript (same pattern as v0.7.1
+       thinking fix). Eliminates the dock-bottom-growth-overlap bug. */
+    #tools-log, #debug-log, #thinking-log {
+        background: $background;
+        padding: 0 1;
+    }
+    /* Tab strip + active-tab underline — kill blue, use Australis cyan. */
+    #side-panes > ContentTabs {
+        background: $surface;
+    }
+    #side-panes ContentTab.-active {
+        color: $au-bright-cyan;
+        text-style: bold;
+    }
+    #side-panes Underline > .underline--bar {
+        color: $au-bright-cyan;
+    }
+    #prompt {
+        dock: bottom;
+        border: tall $panel;
+    }
+    /* v0.6.0: focused border uses Australis bright-cyan instead of $primary
+       (Aurora blue) — kills the lingering blue tint the user flagged. */
+    #prompt:focus {
+        border: tall $au-bright-cyan;
+    }
+    /* Placeholder text in the Input — dimmer than typed content. */
+    #prompt > .input--placeholder {
+        color: $au-dark-50;
+    }
+    #identity {
+        dock: bottom;
+        height: 1;
+        color: $au-bright-blue;
+        padding: 0 1;
+    }
+    #pane-name {
+        dock: bottom;
+        height: 1;
+        color: $au-bright-cyan;
+        padding: 0 1;
+    }
+    #hint {
+        dock: bottom;
+        height: 1;
+        color: $au-dark-60;
+        padding: 0 1;
+    }
+    """
+
     BINDINGS: ClassVar[list[Binding]] = [
         Binding("ctrl+c", "interrupt", "Cancel / Exit", priority=True),
         Binding("ctrl+d", "quit", "Exit immediately", priority=True),
+        # §5 keybinding family Ctrl+1..5 jumps between side panes
+        # without losing Input focus (INV-016).
+        Binding("ctrl+1", "focus_tools", "Tools tab", priority=False),
+        Binding("ctrl+2", "focus_debug", "Debug tab", priority=False),
+        Binding("ctrl+3", "focus_thinking", "Thinking tab", priority=False),
     ]
 
     HINT_IDLE = "Ctrl-C twice to exit"
@@ -240,24 +651,52 @@ class RatatoskrApp(App[int]):
         self.active_turn_id: int | None = None
         self.stream_worker = None
         self.hint: str = self.HINT_IDLE
+        self.register_theme(AUSTRALIS_THEME)
+        self.theme = "australis"
 
     def compose(self) -> ComposeResult:
         yield Header()
-        # markup=False so labeled lines like "[cancel_failed] ..." render verbatim
-        # (Rich would otherwise interpret square-bracket spans as style markup and
-        # strip them). The post-Done markdown render uses Markdown() directly which
-        # is a Rich Renderable and renders correctly without widget-level markup=True.
-        yield RichLog(id="transcript", wrap=True, markup=False, highlight=False)
-        yield Input(id="prompt", placeholder="Type a message and press Enter")
-        # INV-002 + INV-003: visible identity + hint widgets (Footer-area rendering).
-        # Textual's built-in Footer renders BINDINGS descriptions; these Static widgets
-        # carry the session-identity and Ctrl-C-state strings the contract requires be
-        # always-visible.
+        # v0.6.0 layout: left column is content-only (transcript + streaming
+        # text Static + prompt). Right column hosts thinking-current live
+        # preview above TabbedContent cycling Tools / Debug / Thinking.
+        #
+        # The current-text Static buffers in-flight assistant tokens so
+        # streaming doesn't spam the RichLog with one line per delta —
+        # the operator sees a single growing live line, then on Done the
+        # Static clears and the final Markdown body lands in the transcript.
+        #
+        # markup=False on RichLog so labeled lines render verbatim; the
+        # post-Done Markdown() / Rule() renders are Rich Renderables and
+        # work without widget-level markup=True.
+        with Horizontal(id="main-row"):
+            with Vertical(id="left-column"):
+                yield RichLog(id="transcript", wrap=True, markup=False, highlight=False)
+                yield Input(id="prompt", placeholder="Type a message and press Enter")
+            with Vertical(id="right-column"):
+                with TabbedContent(id="side-panes"):
+                    with TabPane("Tools", id="tools-tab"):
+                        yield RichLog(
+                            id="tools-log", wrap=True, markup=False, highlight=False
+                        )
+                    with TabPane("Debug", id="debug-tab"):
+                        yield RichLog(
+                            id="debug-log", wrap=True, markup=False, highlight=False
+                        )
+                    with TabPane("Thinking", id="thinking-tab"):
+                        # v0.6.5: thinking streams directly into this
+                        # RichLog (no separate bottom Static). Each delta
+                        # writes a line; Rule(start)/Rule(end) mark run
+                        # boundaries. The whole pane scrolls naturally
+                        # as content arrives — no more "200-char tail
+                        # window scrolling at the bottom".
+                        yield RichLog(
+                            id="thinking-log", wrap=True, markup=False, highlight=False
+                        )
+        # INV-002 + INV-003: visible identity + hint widgets (Footer-area).
+        # pane-name widget displays current side-pane name.
         yield Static("", id="identity")
+        yield Static("Tools", id="pane-name")
         yield Static(self.HINT_IDLE, id="hint")
-        # Issue #12: live thinking widget — hidden by default, shown per-delta
-        # during a thinking run, cleared+hidden at turn terminal.
-        yield Static("", id="thinking-current")
         yield Footer()
 
     async def on_mount(self) -> None:
@@ -271,11 +710,48 @@ class RatatoskrApp(App[int]):
         identity = f"{agent_slot} · …{self.session_id[-8:]}"
         self.sub_title = identity  # mirror to Header subtitle for redundancy
         self.query_one("#identity", Static).update(identity)
-        # Issue #12: thinking widget hidden until a thinking event fires.
-        self.query_one("#thinking-current", Static).display = False
+        # v0.5.1 polish: empty-state placeholder lines so the operator sees
+        # the pane is intentionally empty (not broken) before any turn fires.
+        # Wrapped in Australis dark-50 italic so they read distinctly as
+        # placeholder text, not real telemetry. Disappear naturally as the
+        # log fills with real events (the placeholders scroll off the top).
+        from rich.text import Text as RichText
+        placeholder_style = f"{_AU_DEMOTED_FAINT} italic"
+        self.query_one("#tools-log", RichLog).write(
+            RichText("(no tool events yet — start a turn that uses tools)",
+                     style=placeholder_style)
+        )
+        self.query_one("#debug-log", RichLog).write(
+            RichText("(waiting for worker_phase + text_boundary telemetry)",
+                     style=placeholder_style)
+        )
+        self.query_one("#thinking-log", RichLog).write(
+            RichText("(no chain-of-thought captured yet — start a turn)",
+                     style=placeholder_style)
+        )
         self.state = "idle"
         self._set_hint(self.HINT_IDLE)
 
+    def _write_turn_headers(self, turn_id: int) -> None:
+        """v0.6.0: Write `── turn N ──` Rule headers across every pane so
+        operators can visually correlate sections during cross-pane
+        debugging. Called from `_stream_turn_worker` on first event of
+        each new turn (idempotent per turn via active_turn_id guard).
+        """
+        from rich.rule import Rule
+
+        title = f"turn {turn_id}"
+        rule = Rule(title=title, style=_AU_DEMOTED)
+        try:
+            self.query_one("#transcript", RichLog).write(rule)
+            self.query_one("#tools-log", RichLog).write(rule)
+            self.query_one("#debug-log", RichLog).write(rule)
+            self.query_one("#thinking-log", RichLog).write(rule)
+        except Exception:
+            # Defensive: widget tree may be tearing down — never let a
+            # turn-header write block the SSE consumer.
+            pass
+
     def _set_hint(self, hint: str) -> None:
         """Set the hint state attribute AND update the visible Static widget."""
         self.hint = hint
@@ -297,7 +773,10 @@ class RatatoskrApp(App[int]):
         content = event.input.value.strip()
         if not content:
             return
-        log.write(f"❯ {content}")  # noqa: RUF001 — intentional INV-006 prefix
+        # v0.4.1 retheme: operator's voice gets Australis bright cyan so it
+        # stands out against the default-foreground assistant text below it.
+        from rich.text import Text as RichText
+        log.write(RichText(f"❯ {content}", style=_AU_USER_ECHO))  # noqa: RUF001
         event.input.value = ""
         self.state = "streaming"
         self._set_hint(self.HINT_STREAMING)
@@ -311,14 +790,25 @@ class RatatoskrApp(App[int]):
         assert self.client is not None
         assert content
         log = self.query_one("#transcript", RichLog)
-        thinking_widget = self.query_one("#thinking-current", Static)
+        tools_log = self.query_one("#tools-log", RichLog)
+        debug_log = self.query_one("#debug-log", RichLog)
+        thinking_log = self.query_one("#thinking-log", RichLog)
         presenter = TuiPresenterState()
         try:
             async for event in stream_turn(self.client, self.session_id, content):
                 if self.active_turn_id is None:
                     self.active_turn_id = event.sse_id.turn_id
+                    # v0.6.0: turn-ID headers across all panes so the
+                    # operator can visually correlate sections during
+                    # cross-pane debugging.
+                    self._write_turn_headers(self.active_turn_id)
                 presenter.render(
-                    event, log=log, thinking_widget=thinking_widget, raw=self.args.raw
+                    event,
+                    log=log,
+                    tools_log=tools_log,
+                    debug_log=debug_log,
+                    thinking_log=thinking_log,
+                    raw=self.args.raw,
                 )
                 if isinstance(event, (Done, Error, Cancelled)):
                     break
@@ -369,6 +859,27 @@ class RatatoskrApp(App[int]):
             self.stream_worker.cancel()
         self.exit(0)
 
+    def action_focus_tools(self) -> None:
+        """Issue #13: Ctrl+1 activates the Tools tab. INV-016 preserves Input focus.
+
+        Current Textual behavior preserves Input focus when TabbedContent.active is
+        set programmatically. If a future Textual regresses on that, add an
+        explicit `self.query_one('#prompt', Input).focus()` after the assignment
+        — `test_ctrl_1_preserves_input_focus` is the regression guard.
+        """
+        self.query_one("#side-panes", TabbedContent).active = "tools-tab"
+        self.query_one("#pane-name", Static).update("Tools")
+
+    def action_focus_debug(self) -> None:
+        """v0.5.0: Ctrl+2 activates the Debug tab. INV-016 preserves Input focus."""
+        self.query_one("#side-panes", TabbedContent).active = "debug-tab"
+        self.query_one("#pane-name", Static).update("Debug")
+
+    def action_focus_thinking(self) -> None:
+        """v0.6.0: Ctrl+3 activates the Thinking tab. INV-016 preserves Input focus."""
+        self.query_one("#side-panes", TabbedContent).active = "thinking-tab"
+        self.query_one("#pane-name", Static).update("Thinking")
+
 
 def run_tui(args: ParsedArgs) -> int:
     """Sync entry point — delegates to the async resolve-then-run flow.
@@ -404,11 +915,58 @@ async def _resolve_then_run(args: ParsedArgs) -> int:
         # Default 5s read timeout would kill mid-stream; disable it.
         timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0),
     ) as client:
+        # Issue #8: startup agent picker — fetch GET /agents and prompt when
+        # --new is passed without --agent. list_agents errors land on real
+        # stderr before any alt-screen opens (preserves issue #6 INV-001).
+        #
+        # v0.8.0: merge in local tier-3 agent index. Worldtree's GET /agents
+        # doesn't return consumer-defined agents (issue #15 smoke finding);
+        # ratatoskr keeps its own JSON-backed index of agents the operator
+        # defined via `python -m ratatoskr.tier3 define`. Merged here so the
+        # picker shows foundational + local-tier-3 in one list. Dedup by
+        # agent_id (remote wins on conflict, since a server-listed agent
+        # is the authoritative source).
+        chosen_agent_id: str | None = args.agent_id
+        if args.new and args.agent_id is None:
+            try:
+                agents = await list_agents(client)
+            except SessionApiFailed as exc:
+                sys.stderr.write(
+                    f"[session_api_failed] status={exc.status} body={exc.body!r}\n"
+                )
+                return 20
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.TransportError) as exc:
+                sys.stderr.write(f"[network_error] {type(exc).__name__}: {exc}\n")
+                return 21
+            # v0.8.0: append local tier-3 entries not already in the remote list.
+            from ratatoskr.local_agents import load_local_agents
+
+            remote_ids = {a.agent_id for a in agents}
+            for entry in load_local_agents():
+                if entry.agent_id in remote_ids:
+                    continue
+                agents.append(AgentInfo(
+                    agent_id=entry.agent_id,
+                    name=entry.agent_name,
+                    description=entry.description,
+                    version=None,
+                    capabilities=[],
+                    supported_models=[],
+                    persona_traits={},
+                    ui_hints={},
+                ))
+            if not agents:
+                sys.stderr.write("[no_agents] server returned empty agent list\n")
+                return 13
+            picker = AgentPickerApp(agents)
+            chosen_agent_id = await picker.run_async()
+            if chosen_agent_id is None:
+                return 0  # Esc / Ctrl-D — clean exit, no session created
         if args.new:
-            assert args.agent_id is not None
+            assert chosen_agent_id is not None
             try:
                 info = await create_session(
-                    client, args.agent_id, end_user_id=args.end_user_id
+                    client, chosen_agent_id, end_user_id=args.end_user_id
                 )
             except AgentNotFound as exc:
                 sys.stderr.write(f"[agent_not_found] agent_id={exc.agent_id}\n")

tests/test_cli.py

@@ -176,11 +176,37 @@ class TestParseArgs:
         with pytest.raises(UsageError, match="pass exactly one"):
             _parse_args(["--send", "hi", "--api-key", "k"])
 
-    def test_usage_new_without_agent(self) -> None:
-        """usage_new_without_agent: --new without --agent → UsageError."""
+    def test_usage_send_new_without_agent(self) -> None:
+        """send_new_without_agent (issue #8): --send --new without --agent → UsageError.
+
+        --send mode is non-interactive — cannot prompt; --agent stays required.
+        """
         with pytest.raises(UsageError, match="--agent is required when --new"):
             _parse_args(["--send", "hi", "--new", "--api-key", "k"])
 
+    def test_parse_bare_new_without_agent_accepted(self) -> None:
+        """bare_new_without_agent (issue #8): --new without --send or --agent → agent_id=None.
+
+        TUI mode CAN prompt; startup picker handles the choice. _parse_args
+        accepts None here and the TUI's _resolve_then_run drives the picker.
+        """
+        args = _parse_args(["--new", "--api-key", "k"])
+        assert args.new is True
+        assert args.agent_id is None
+        assert args.send_content is None
+
+    def test_parse_bare_new_with_agent_accepted(self) -> None:
+        """bare_new_with_agent (issue #8): --new --agent mimir (no --send) → picker skipped.
+
+        Existing TUI launch path with an explicit agent_id continues to work
+        — _resolve_then_run sees `args.agent_id is not None` and skips the
+        picker entirely.
+        """
+        args = _parse_args(["--new", "--agent", "mimir", "--api-key", "k"])
+        assert args.new is True
+        assert args.agent_id == "mimir"
+        assert args.send_content is None
+
     def test_usage_session_with_agent(self) -> None:
         """usage_session_with_agent: --session AND --agent → UsageError."""
         with pytest.raises(UsageError, match="forbidden with --session"):

tests/test_local_agents.py

@@ -0,0 +1,187 @@
+"""Tests for ratatoskr.local_agents.
+
+Use ``$RATATOSKR_LOCAL_AGENTS`` env-var override + pytest tmp_path to
+isolate from the operator's real ``~/.config/ratatoskr/local_agents.json``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from ratatoskr.local_agents import (
+    LocalAgentEntry,
+    _local_agents_path,
+    add_local_agent,
+    load_local_agents,
+    make_description,
+    remove_local_agent,
+    update_local_agent,
+)
+
+
+@pytest.fixture
+def local_path(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Point $RATATOSKR_LOCAL_AGENTS at a fresh tmp file for the test."""
+    path = tmp_path / "local_agents.json"
+    monkeypatch.setenv("RATATOSKR_LOCAL_AGENTS", str(path))
+    return path
+
+
+def _entry(
+    agent_id: str = "ratatoskr:wizard",
+    agent_name: str = "wizard",
+    model: 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,
+        description=description,
+        defined_at=defined_at,
+    )
+
+
+class TestPathResolution:
+    def test_env_override(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("RATATOSKR_LOCAL_AGENTS", "/tmp/custom-agents.json")
+        assert _local_agents_path() == Path("/tmp/custom-agents.json")
+
+    def test_xdg_config_home(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("RATATOSKR_LOCAL_AGENTS", raising=False)
+        monkeypatch.setenv("XDG_CONFIG_HOME", "/tmp/xdg-config")
+        assert (
+            _local_agents_path()
+            == Path("/tmp/xdg-config/ratatoskr/local_agents.json")
+        )
+
+    def test_default_home(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("RATATOSKR_LOCAL_AGENTS", raising=False)
+        monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+        path = _local_agents_path()
+        assert path == Path.home() / ".config" / "ratatoskr" / "local_agents.json"
+
+
+class TestLoadEmpty:
+    def test_missing_file_returns_empty(self, local_path: Path) -> None:
+        assert not local_path.exists()
+        assert load_local_agents() == []
+
+    def test_corrupt_json_returns_empty(self, local_path: Path) -> None:
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        local_path.write_text("not json at all")
+        assert load_local_agents() == []
+
+    def test_wrong_schema_version_returns_empty(self, local_path: Path) -> None:
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        local_path.write_text(json.dumps({"version": 999, "agents": []}))
+        assert load_local_agents() == []
+
+    def test_missing_version_key_returns_empty(self, local_path: Path) -> None:
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        local_path.write_text(json.dumps({"agents": []}))
+        assert load_local_agents() == []
+
+    def test_malformed_row_skipped(self, local_path: Path) -> None:
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        local_path.write_text(
+            json.dumps(
+                {
+                    "version": 1,
+                    "agents": [
+                        {"agent_id": "incomplete"},  # missing required fields
+                        {
+                            "agent_id": "ratatoskr:good",
+                            "agent_name": "good",
+                            "model": "m",
+                            "description": "d",
+                            "defined_at": "t",
+                        },
+                    ],
+                }
+            )
+        )
+        entries = load_local_agents()
+        assert len(entries) == 1
+        assert entries[0].agent_id == "ratatoskr:good"
+
+
+class TestAdd:
+    def test_add_one(self, local_path: Path) -> None:
+        add_local_agent(_entry())
+        entries = load_local_agents()
+        assert len(entries) == 1
+        assert entries[0].agent_id == "ratatoskr:wizard"
+
+    def test_add_two_different(self, local_path: Path) -> None:
+        add_local_agent(_entry(agent_id="ratatoskr:a", agent_name="a"))
+        add_local_agent(_entry(agent_id="ratatoskr:b", agent_name="b"))
+        ids = {e.agent_id for e in load_local_agents()}
+        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"))
+        entries = load_local_agents()
+        assert len(entries) == 1
+        assert entries[0].model == "new-model"
+
+    def test_creates_parent_dirs(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        nested = tmp_path / "deep" / "nested" / "path" / "agents.json"
+        monkeypatch.setenv("RATATOSKR_LOCAL_AGENTS", str(nested))
+        add_local_agent(_entry())
+        assert nested.exists()
+
+
+class TestUpdate:
+    def test_update_changes_existing(self, local_path: Path) -> None:
+        add_local_agent(_entry(model="v1"))
+        update_local_agent(_entry(model="v2"))
+        entries = load_local_agents()
+        assert len(entries) == 1
+        assert entries[0].model == "v2"
+
+
+class TestRemove:
+    def test_remove_existing(self, local_path: Path) -> None:
+        add_local_agent(_entry())
+        remove_local_agent("ratatoskr:wizard")
+        assert load_local_agents() == []
+
+    def test_remove_missing_is_noop(self, local_path: Path) -> None:
+        add_local_agent(_entry())
+        remove_local_agent("ratatoskr:doesnotexist")
+        assert len(load_local_agents()) == 1
+
+
+class TestMakeDescription:
+    def test_first_nonempty_line(self) -> None:
+        prompt = "\n\n# IDENTITY\nYou are a test agent..."
+        desc = make_description(prompt)
+        assert desc.startswith("(tier 3) IDENTITY")
+
+    def test_strips_heading_markers(self) -> None:
+        prompt = "# A nice heading\nMore prompt..."
+        desc = make_description(prompt)
+        assert "(tier 3) A nice heading" == desc
+
+    def test_truncates_long(self) -> None:
+        prompt = "x" * 200
+        desc = make_description(prompt)
+        # 80 char cap including the prefix
+        assert len(desc) == 81  # 80 + ellipsis char
+        assert desc.endswith("…")
+
+    def test_empty_prompt_fallback(self) -> None:
+        desc = make_description("")
+        assert desc == "(tier 3) custom system prompt"
+
+    def test_whitespace_only_fallback(self) -> None:
+        desc = make_description("   \n\n  ")
+        assert desc == "(tier 3) custom system prompt"

tests/test_sessions.py

@@ -5,11 +5,13 @@ import pytest
 import respx
 
 from ratatoskr.sessions import (
+    AgentInfo,
     AgentNotFound,
     InvalidCursor,
     SessionApiFailed,
     SessionPage,
     create_session,
+    list_agents,
     list_sessions,
 )
 
@@ -412,3 +414,145 @@ class TestListSessions:
             with pytest.raises(AssertionError):
                 await list_sessions(client, cursor="")
         assert route.call_count == 0
+
+
+# ---- Issue #8: list_agents + AgentInfo --------------------------------------
+
+
+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

tests/test_sse_client.py

@@ -711,6 +711,47 @@ def _sse_raw_chunk(sse_id: str, raw_data: str) -> bytes:
     return f"id: {sse_id}\ndata: {raw_data}\n\n".encode()
 
 
+def _sse_no_id_chunk(data: str) -> bytes:
+    """SSE frame with NO id line + arbitrary data (v0.8.1: keepalive shape)."""
+    return f"data: {data}\n\n".encode()
+
+
+class TestEmptyIdSkipped:
+    @respx.mock
+    async def test_empty_id_on_first_event_skipped(self) -> None:
+        """empty_id_on_first_event_skipped [v0.8.1]: stream starts with an
+        event carrying NO `id:` line → httpx_sse exposes sse.id == ''
+        (no prior id to inherit). Pre-v0.8.1: MalformedSseId raw='' crashed
+        the turn. v0.8.1: treat same as empty-data keepalive — skip silently.
+
+        Observed 2026-05-25 on Worldtree's qwen3.6-35-a3b-heretic provider:
+        the first stream frame had no id line, every turn died with
+        `[malformed_sse_id] raw=''`.
+        """
+        from ratatoskr.sse_client import Done as _Done
+        from ratatoskr.sse_client import Text as _Text
+
+        # First frame: no id line (httpx_sse → sse.id = ""). Skip it.
+        # Subsequent frames have ids; normal processing resumes.
+        stream = (
+            _sse_no_id_chunk('{"type":"keepalive"}')  # ← skipped (sse.id == "")
+            + _sse_chunk("42:1", {"type": "text", "content": "first"})
+            + _sse_chunk("42:2", _DONE_42_6)
+        )
+        respx.post("https://w.example/sessions/s1/messages").mock(
+            return_value=httpx.Response(
+                200, headers={"content-type": "text/event-stream"}, content=stream
+            )
+        )
+        async with httpx.AsyncClient(base_url="https://w.example") as client:
+            events = [e async for e in stream_turn(client, "s1", "hi")]
+        # 2 events — the no-id frame is invisible (no MalformedSseId crash).
+        assert len(events) == 2
+        assert isinstance(events[0], _Text)
+        assert events[0].content == "first"
+        assert isinstance(events[1], _Done)
+
+
 class TestEmptyDataSkipped:
     @respx.mock
     async def test_empty_data_skipped(self) -> None:

tests/test_tier3.py

@@ -0,0 +1,491 @@
+"""Tests for ratatoskr.tier3 per docs/contracts/issues/15.contract.md."""
+
+from pathlib import Path
+
+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,
+)
+
+_FULL_AGENT_RESP = {
+    "agent_id": "ratatoskr:wizard",
+    "user_id": "ratatoskr",
+    "agent_name": "wizard",
+    "system_prompt": "You are a wizard.",
+    "model": "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.",
+                model="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.",
+                model="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.",
+            "model": "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",
+                    model="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", model="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", model="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", model="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", model="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="", model="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", model="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",
+                model="different-model",
+            )
+        body = _json.loads(route.calls[0].request.content)
+        assert body == {"system_prompt": "new prompt", "model": "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 model → 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
+) -> "Path":
+    """Isolate the v0.8.0 local-tier-3 index from the operator's real file."""
+    path = tmp_path / "local_agents.json"
+    monkeypatch.setenv("RATATOSKR_LOCAL_AGENTS", str(path))
+    return path
+
+
+class TestCli:
+    @respx.mock
+    def test_cli_define_happy(
+        self,
+        capsys: pytest.CaptureFixture[str],
+        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).
+        """
+        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=_FULL_AGENT_RESP)
+        )
+        rc = main([
+            "define",
+            "--name", "wizard",
+            "--system-prompt", "You are a wizard.",
+            "--model", "qwen3.6-35-a3b",
+        ])
+        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"
+
+    @respx.mock
+    def test_cli_patch_happy(
+        self,
+        capsys: pytest.CaptureFixture[str],
+        monkeypatch: pytest.MonkeyPatch,
+        _isolated_local_agents: "Path",
+    ) -> None:
+        """cli_patch_happy [happy]: argv → 200 mock → stdout confirmation;
+        local index refreshed with the post-patch state.
+        """
+        from ratatoskr.local_agents import load_local_agents
+
+        monkeypatch.setenv("WORLDTREE_API_URL", "https://w.example")
+        monkeypatch.setenv("WORLDTREE_API_KEY", "k")
+        respx.patch("https://w.example/agents/ratatoskr:wizard").mock(
+            return_value=httpx.Response(200, json=_FULL_AGENT_RESP)
+        )
+        rc = main(["patch", "ratatoskr:wizard", "--system-prompt", "new"])
+        out = capsys.readouterr()
+        assert rc == 0
+        assert out.out.strip() == "patched ratatoskr:wizard"
+        entries = load_local_agents()
+        assert len(entries) == 1
+        assert entries[0].agent_id == "ratatoskr:wizard"
+
+    @respx.mock
+    def test_cli_delete_happy(
+        self,
+        capsys: pytest.CaptureFixture[str],
+        monkeypatch: pytest.MonkeyPatch,
+        _isolated_local_agents: "Path",
+    ) -> None:
+        """cli_delete_happy [happy]: argv → 204 mock → stdout confirmation;
+        local index entry removed (v0.8.0 hook).
+        """
+        from ratatoskr.local_agents import (
+            LocalAgentEntry,
+            add_local_agent,
+            load_local_agents,
+        )
+
+        # Pre-populate so we can verify removal.
+        add_local_agent(LocalAgentEntry(
+            agent_id="ratatoskr:wizard",
+            agent_name="wizard",
+            model="m",
+            description="d",
+            defined_at="t",
+        ))
+        monkeypatch.setenv("WORLDTREE_API_URL", "https://w.example")
+        monkeypatch.setenv("WORLDTREE_API_KEY", "k")
+        respx.delete("https://w.example/agents/ratatoskr:wizard").mock(
+            return_value=httpx.Response(204)
+        )
+        rc = main(["delete", "ratatoskr:wizard"])
+        out = capsys.readouterr()
+        assert rc == 0
+        assert out.out.strip() == "deleted ratatoskr:wizard"
+        assert load_local_agents() == []
+
+    def test_cli_missing_auth(
+        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """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",
+            "--model", "m",
+        ])
+        err = capsys.readouterr().err
+        assert rc == 11
+        assert "[auth_error]" in err
+
+    @respx.mock
+    def test_cli_api_failed(
+        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """cli_api_failed [error]: 500 → stderr [api_failed] + exit 20."""
+        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(500, content=b"upstream out")
+        )
+        rc = main([
+            "define",
+            "--name", "wizard",
+            "--system-prompt", "x",
+            "--model", "m",
+        ])
+        err = capsys.readouterr().err
+        assert rc == 20
+        assert "[api_failed]" in err
+
+    @respx.mock
+    def test_cli_quota_exceeded(
+        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """cli_quota_exceeded [error]: 429 → stderr [quota_exceeded] + exit 20."""
+        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(
+                429,
+                headers={"Retry-After": "0"},
+                json={"detail": {"error_code": "agent_quota_exceeded"}},
+            )
+        )
+        rc = main([
+            "define",
+            "--name", "wizard",
+            "--system-prompt", "x",
+            "--model", "m",
+        ])
+        err = capsys.readouterr().err
+        assert rc == 20
+        assert "[quota_exceeded]" in err
+
+    def test_cli_patch_no_fields(
+        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """cli_patch_no_fields [error]: patch with no flags → [usage_error] + exit 10."""
+        monkeypatch.setenv("WORLDTREE_API_URL", "https://w.example")
+        monkeypatch.setenv("WORLDTREE_API_KEY", "k")
+        rc = main(["patch", "ratatoskr:wizard"])
+        err = capsys.readouterr().err
+        assert rc == 10
+        assert "[usage_error]" in err

uv.lock

@@ -968,7 +968,7 @@ wheels = [
 
 [[package]]
 name = "ratatoskr"
-version = "0.2.0"
+version = "0.8.2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },