feat(#2 ): consume GET /me + GET /capabilities via --whoami one-shot

v1 coverage-audit slice (capabilities+me). Both endpoints had no caller; add them as cheap boot-time debug primitives. - sessions.py: get_me (GET /me — identity/whoami) + get_capabilities (GET /capabilities — Echo ephemeral-template discovery). Mirror get_persona_state: 200 -> parsed dict verbatim, non-200 -> SessionApiFailed. Freeform dicts (frozen OpenAPI types both as objects). - cli.py: new --whoami one-shot mode (mirrors --send). Fetches both, prints an identity + capabilities report, exits. Standalone probe: mutually exclusive with --send/--session/--new/--agent; opens no session. New ParsedArgs.whoami field + main() dispatch. - Contract #2 amended (2 FNs) + validated. TDD: 5 wrapper tests + 5 cli tests (validation + mode + error). Coverage map: REST 9/40. Suite 538 green; touched code ruff-clean. Audit note: /capabilities is the Echo ephemeral-template discovery endpoint, not a generic server-caps endpoint (coverage-map framing corrected). TUI-surfacing of /me + /capabilities deferred.
feat(#6 ): startup session picker for bare TUI mode
2026-06-30 22:21:59 -07:00 · 2026-06-30 22:05:14 -07:00 · 2026-06-30 15:46:04 -07:00 · 2026-06-30 15:42:33 -07:00 · 2026-06-30 15:32:15 -07:00 · 2026-06-30 15:28:52 -07:00
20 changed files with 9654 additions and 41 deletions
@@ -89,3 +89,37 @@ canonical_path = "scripts/contract_drift_check.py"
 consumer_path = "scripts/contract_drift_check.py"
 pinned_sha256_16 = "23271287ac488da4"
 pinned_at = "2026-05-17T05:30:00+00:00"
 # ---------------------------------------------------------------------------
 # Worldtree Conversation-API surface (vendored from ~/development/Worldtree).
 # The v1 wire is FROZEN (Worldtree #326 / v1-schema-freeze-manifest.md). The
 # machine-readable OpenAPI + SSE schema are the authoritative drift GATES; the
 # prose markdown is the human reference and is allowed to lag (tolerate_drift).
 # These are what ratatoskr's v1 coverage map (docs/coverage-map.md) audits
 # against. Pin target: Worldtree 5810a26 (v1.0.0b2).
 # ---------------------------------------------------------------------------
 [[pins]]
 id = "worldtree-conversation-api-openapi-v2"
 canonical_source = "Worldtree"
 canonical_path = "docs/conversation-api-openapi.json"
 consumer_path = "docs/conversation-api-openapi.json"
 pinned_sha256_16 = "dbdf4e24c8b06c92"
 pinned_at = "2026-06-30T22:25:56+00:00"
 [[pins]]
 id = "worldtree-conversation-api-sse-events-v1"
 canonical_source = "Worldtree"
 canonical_path = "docs/conversation-api-sse-events.schema.json"
 consumer_path = "docs/conversation-api-sse-events.schema.json"
 pinned_sha256_16 = "9deeebf404d72f9a"
 pinned_at = "2026-06-30T22:25:56+00:00"
 [[pins]]
 id = "worldtree-conversation-api-spec-v1"
 canonical_source = "Worldtree"
 canonical_path = "docs/conversation-api-spec.md"
 consumer_path = "docs/conversation-api-spec.md"
 pinned_sha256_16 = "2d111a3b8322b7d1"
 pinned_at = "2026-06-30T22:25:56+00:00"
 tolerate_drift = true  # prose reference; OpenAPI+SSE are the gates
@@ -7,24 +7,32 @@ documents the pin, the vendored artifacts, and the bump procedure.
 | Field | Value |
 |---|---|
-| Worldtree git SHA | `f1b59f8cd6fe41e497d0be9dad9d3110451f0d9a` |
+| Worldtree git SHA | `5810a26b38a5ea6630892f9a39756f57c5b7b41e` |
-| Worldtree HEAD message | `Merge #299: adopt bifrost v0.6 memory scope wire (scope_any/scope_all)` |
+| Worldtree HEAD message | `memory: snapshot — v1.0.0b2 shipped complete (demo + personal green); consumer loop closed` |
-| Pinned on | 2026-06-17 |
+| Pinned on | 2026-06-30 |
-| Pinned by | ratatoskr-dev (bump for #297/#298 — cold recall closed end-to-end) |
+| Pinned by | ratatoskr-dev (v1 coverage-audit — re-pin to the FROZEN OpenAPI 2.2.0 + SSE schema) |
-| Worldtree version at pin | `v0.35.16` |
+| Worldtree version at pin | `v1.0.0b2` |
 ## Pin history
 | Date | SHA | Version | Notable deltas consumed |
 |---|---|---|---|
 | 2026-06-30 | `5810a26` | v1.0.0b2 | **Re-pin to Worldtree's FROZEN v1 surface (#326), as part of the v1 coverage-audit.** Vendored the machine-readable artifacts — `conversation-api-openapi.json` (OpenAPI **2.2.0**, 40 path-groups) + `conversation-api-sse-events.schema.json` (11 events) — now the **authoritative drift gates** (pinned in `.corviduo-canonicals.toml`, CI-checked by `canonical_drift.py`). The prose `conversation-api-spec.md` is **byte-identical** to the v0.35.16 pin (last WT markdown edit 2026-05-31), kept as the human reference (`tolerate_drift`). b2 deltas already consumed in code: 409/503 eager turn-launch statuses (#331, v0.18.3/.4) + the unified error envelope (#328). 7 endpoints documented only in the OpenAPI, not the prose, all classified in `docs/coverage-map.md`: `admin/keys/bulk`, `admin/persona/{archive,erase}`, `admin/usage`, `embed`, `judgments`, `me/usage`. No client-breaking change — `pin:`-only, no version bump. |
 | 2026-06-17 | `f1b59f8` | v0.35.16 | **#297 + #298/#299 — Worldtree adopts the bifrost v0.6 scope wire (emits `scope_any`/`scope_all`) + client-side per-scope-value union recall. With our v0.17.6 provider this closes cold cross-session recall end-to-end.** Catch-up bump (v0.29.0→v0.35.16). Intervening client-facing deltas reviewed, none break our consumer: #211 agent rename (`saga`→`echo`, `actor`→`mask` — slugs only); #245 `end_user_id` persistence + memory-scope resolver; #187/#188/#219 Tier-3 define/PATCH policy (additive); `bifrost` binding field + `ephemeral_does_not_accept_bifrost` 422 now documented (the #17 surface). Error codes stable; no ratatoskr code change required. |
 | 2026-05-25 | `da93ca7` | v0.28.0 | #204 — new SSE event `affect_update` (current/scheduled), new endpoint `GET /agents/{id}/persona_state`, auth-model doc edits |
 | 2026-05-20 | `55101e9` | v0.19.0 | initial scaffold pin |
 ## Vendored artifacts
- `docs/conversation-api-spec.md` — copy of `Worldtree/docs/conversation-api-spec.md` at the pinned SHA. This is the **client-facing interface contract** Ratatoskr is built against.
+**Authoritative (FROZEN, machine-readable — the drift gates):**
- `docs/conversation_api.contract.md` — copy of `Worldtree/docs/contracts/conversation_api.contract.md` at the pinned SHA. The **server-side contract** including INV-001..INV-052 and amendments. Useful for understanding load-bearing server invariants (e.g., INV-014 turn-id-public, INV-046 admin-events-envelope-stable, INV-049 admin-events-pii-discipline) when designing client behavior against them.
+
 - `docs/conversation-api-openapi.json` — copy of `Worldtree/docs/conversation-api-openapi.json` (OpenAPI `info.version` **2.2.0**). The frozen v1 REST wire (40 path-groups). Pinned `worldtree-conversation-api-openapi-v2` in `.corviduo-canonicals.toml`; drift gated by `canonical_drift.py`.
 - `docs/conversation-api-sse-events.schema.json` — copy of `Worldtree/docs/conversation-api-sse-events.schema.json`. The frozen SSE event schema (11 discriminated event types). Pinned `worldtree-conversation-api-sse-events-v1`.
 **Reference (prose; allowed to lag — `tolerate_drift`):**
 - `docs/conversation-api-spec.md` — copy of `Worldtree/docs/conversation-api-spec.md` at the pinned SHA. The **client-facing prose narrative**. Byte-frozen at v0.35.16-era content (last WT edit 2026-05-31); the OpenAPI/SSE JSON above are the source of truth where they diverge. Pinned `worldtree-conversation-api-spec-v1` (tolerate_drift).
 - `docs/conversation_api.contract.md` — copy of `Worldtree/docs/contracts/conversation_api.contract.md` at the pinned SHA (byte-identical at b2 — server contract unchanged since the v0.35.16 pin). The **server-side contract** including INV-001..INV-052 and amendments. Useful for understanding load-bearing server invariants (e.g., INV-014 turn-id-public, INV-046 admin-events-envelope-stable, INV-049 admin-events-pii-discipline) when designing client behavior against them. Not in the canonical manifest (reference-only).
 Both files are vendored — they reflect Worldtree at the pinned SHA, not
 the live `~/development/Worldtree` checkout. Update them only when
@@ -297,3 +297,51 @@ TESTS:
  trailing_whitespace [adversarial]: "42:3 " → ValueError (strict; do not strip; the server emits clean ids)
  truncation [security]: input is 5000-char string with no colon → ValueError message includes only `raw[:64]` (not the full 5000)
 ```
 ## Amendment 2026-06-30 — shared resume orchestration (v1 coverage-audit, slice b1)
 The original contract specs resume as **caller-owned** (§Resume semantics: "the
 caller MAY invoke `reconnect_turn`"). The v1 coverage-audit found `reconnect_turn`
 had **no caller** — every presenter (cli/tui/web) let a mid-stream drop propagate
 instead of resuming, so the "reference SSE-resume implementation" (design-brief
 §3/§8d) was unreachable. Per design-brief §8b ("share the consumer, branch the
 presenter") the resume loop is a **single shared orchestration surface**, not
 duplicated per presenter. This adds `stream_turn_resilient` as that surface;
 presenters call it instead of `stream_turn` when they want transparent reconnect.
 `stream_turn` and `reconnect_turn` are unchanged (still the primitives); this is
 purely additive.
 ```contract
 FN stream_turn_resilient(client: httpx.AsyncClient, session_id: str, content: str, *, max_reconnects: int = 5) -> AsyncIterator[Event]
 BRIEF: The shared resume-orchestration wrapper over stream_turn + reconnect_turn. Yields a SINGLE continuous typed Event stream; on SseConnectionDropped (mid-stream drop OR clean EOF before terminal), transparently resumes via reconnect_turn from the last-seen sse_id, up to max_reconnects times, until a terminal Done/Error/Cancelled arrives. The one surface all presenters consume for resilient streaming (design-brief §8b). Cross-process resume stays deferred to v2 (§8d): last-seen lives only in this generator's frame.
 PRE: [PRE-001 hard] client is not None -- assert client is not None
 PRE: [PRE-002 hard] session_id is non-empty str -- assert session_id and isinstance(session_id, str)
 PRE: [PRE-003 hard] content is non-empty str -- assert content and isinstance(content, str)
 PRE: [PRE-004 hard] max_reconnects is a non-negative int -- assert isinstance(max_reconnects, int) and max_reconnects >= 0
 POST: [POST-001 return_value] yielded events are the concatenation of each attempt's events in wire order; the wrapper does NOT re-yield events it already saw (the server replays only seq>last_seen) -- assert seq is non-decreasing within a turn_id across the seam
 POST: [POST-002 return_value] a fully-consumed stream terminates at exactly one Done/Error/Cancelled (INV-001 holds across reconnects) -- assert isinstance(events[-1], (Done, Error, Cancelled))
 POST: [POST-003 state_change] reconnect_turn is invoked with last_event_id == f"{last_seen.turn_id}:{last_seen.seq}" of the most recently yielded event -- assert the Last-Event-ID header on attempt N+1 == the last sse_id yielded before the drop
 ERROR_ROUTING:
  SseConnectionDropped (from stream_turn or reconnect_turn):
    local_handling: IF a last-seen sse_id exists AND reconnects < max_reconnects → increment reconnects, resume via reconnect_turn(last_event_id=f"{turn_id}:{seq}"); ELSE re-raise
    flow_control: continue (resume) | abort (re-raise when no last-seen id, or budget exhausted)
    state_recovery: server replays buffered events seq>last_seen then streams live (spec §Reconnect flow)
  ResumeBufferExpired | ResumeTurnFinished | InvalidLastEventId | TurnIdFlip | SseConnectFailed (from reconnect_turn):
    local_handling: propagate unchanged — NOT a transient drop; caller policy is abandon/restart (§Resume semantics "surface, not recover")
    flow_control: abort
    state_recovery: none
 STEPS:
  1. [setup, flexibility=prescriptive] Validate PRE-001..PRE-004; SET last_seen=None, reconnects=0, gen=stream_turn(client, session_id, content)
  2. [loop, flexibility=prescriptive] async-for event in gen: SET last_seen=event.sse_id; YIELD event. On clean generator completion (terminal reached): RETURN.
  3. [branch, flexibility=prescriptive] ON SseConnectionDropped d: SET seen = last_seen or d.last_seen_sse_id. IF seen is None OR reconnects >= max_reconnects: RE-RAISE. ELSE: reconnects += 1; gen = reconnect_turn(client, session_id, content, last_event_id=f"{seen.turn_id}:{seen.seq}"); GOTO step 2.
  4. [error_handler, flexibility=prescriptive] Any non-drop exception from gen (ResumeBufferExpired/ResumeTurnFinished/InvalidLastEventId/TurnIdFlip/SseConnectFailed) is NOT caught — it propagates unchanged.
 TESTS:
  happy_no_drop [happy]: stream yields text(42:1), done(42:2) cleanly → wrapper yields exactly those 2; endpoint hit ONCE (no reconnect).
  resume_after_one_drop [scenario,tracer]: attempt 1 yields text(42:1) then RemoteProtocolError; reconnect replays text(42:2)+done(42:3) → wrapper yields 42:1,42:2,42:3 as ONE stream; 2nd request carried Last-Event-ID "42:1".
  resume_after_clean_eof [scenario]: attempt 1 yields text(42:1) then clean EOF (no terminal); reconnect yields done(42:2) → continuous (resumes on the INV-001 clean-eof drop too).
  two_drops_then_done [scenario]: drops after 42:1 then after 42:2; third attempt yields done(42:3) → all 3 events; reconnects==2; Last-Event-ID headers "42:1" then "42:2".
  unresumable_zero_event_drop [adversarial]: attempt 1 drops with ZERO events seen (last_seen None) → SseConnectionDropped propagates; only 1 request issued.
  max_reconnects_exhausted [adversarial]: every attempt drops after one event; max_reconnects=2 → after initial + 2 reconnects (3 requests), SseConnectionDropped propagates.
  buffer_expired_propagates [error]: attempt 1 drops after 42:1; reconnect returns 412 → ResumeBufferExpired propagates (not retried as a transient drop).
  zero_budget_no_resume [adversarial]: max_reconnects=0; attempt 1 drops after 42:1 → SseConnectionDropped propagates immediately (no reconnect attempted).
 ```
@@ -206,3 +206,48 @@ TESTS:
  limit_above_max [adversarial]: limit=300 → AssertionError; no HTTP issued
  empty_cursor [adversarial]: cursor="" → AssertionError; no HTTP issued
 ```
 ## Amendment 2026-06-30 — boot-time introspection reads (v1 coverage-audit: capabilities+me)
 The v1 coverage-audit added two read-only server-introspection endpoints as
 cheap debug primitives (surfaced via a new `ratatoskr --whoami` one-shot). Both
 mirror `get_persona_state`: GET, 200 → parsed dict verbatim, any non-200 →
 `SessionApiFailed`. The frozen OpenAPI types both responses as freeform objects,
 so the wrappers return `dict[str, Any]` (not a typed dataclass).
 ```contract
 FN get_me(client: httpx.AsyncClient) -> dict[str, Any]
 BRIEF: GET /me — the authenticated principal's identity + key metadata (spec §GET /me). Boot-time whoami: verify the key without agent-config side effects. Returns parsed JSON verbatim; spec documents {user_id, scopes, tier, display_name?, key_id?, key_label?, ...} with optional fields OMITTED (not null). Read-only, rate-exempt, no audit emission.
 PRE: [PRE-001 hard] client is not None -- assert client is not None
 POST: [POST-001 return_value] on 200 returns resp.json() unmodified -- assert result == resp.json()
 ERROR_ROUTING:
  HTTP non-200 (incl. 401 bad/absent key when auth enabled):
    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
    flow_control: abort
    state_recovery: none (caller decides: bad key → re-key; degraded tier="unknown" is still a 200)
 STEPS:
  1. [setup, prescriptive] assert client is not None
  2. [sequential, prescriptive] resp = await client.get("/me")
  3. [branch, prescriptive] IF resp.status_code == 200: RETURN resp.json(); ELSE RAISE SessionApiFailed
 TESTS:
  happy_authenticated [happy,tracer]: 200 {user_id, scopes, tier, key_id} → dict returned verbatim
  anonymous_dev_mode: 200 {user_id:"anonymous", tier:"anonymous"} → dict; no key_* fields (omitted)
  401_raises [error]: 401 → SessionApiFailed(status=401)
 FN get_capabilities(client: httpx.AsyncClient) -> dict[str, Any]
 BRIEF: GET /capabilities — server capability discovery (spec §Ephemeral Templates). Returns {ephemeral_templates: {echo: {allowed_models, default_model, system_prompt_max_bytes}}}. Any authenticated caller may read it (no instantiate scope). Parsed dict verbatim; any non-200 → SessionApiFailed.
 PRE: [PRE-001 hard] client is not None -- assert client is not None
 POST: [POST-001 return_value] on 200 returns resp.json() unmodified -- assert result == resp.json()
 ERROR_ROUTING:
  HTTP non-200:
    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
    flow_control: abort
    state_recovery: none
 STEPS:
  1. [setup, prescriptive] assert client is not None
  2. [sequential, prescriptive] resp = await client.get("/capabilities")
  3. [branch, prescriptive] IF resp.status_code == 200: RETURN resp.json(); ELSE RAISE SessionApiFailed
 TESTS:
  happy [happy]: 200 {ephemeral_templates:{echo:{...}}} → dict returned verbatim
  non_200_raises [error]: 500 → SessionApiFailed(status=500)
 ```
@@ -372,3 +372,64 @@ test layer.
 - Issue #7 (mid-stream robustness, `MalformedSseData`) — landed; #6's
  pre/in-alt-screen split is orthogonal to #7's empty-data/malformed
  distinction (different error layers entirely).
 ## Amendment 2026-06-30 — startup session picker (v1 coverage-audit, slice b2)
 The v1 coverage-audit found `list_sessions` had **no caller** — the startup
 session picker (design-brief §4: "single-session-per-launch, with a startup
 picker invoked when more than one session exists ... plus flags `--session`/
 `--new` to skip it") was never built. Bare TUI mode (neither `--session` nor
 `--new`) was a hard usage error. This adds the picker as a pre-alt-screen
 resolution step in `_resolve_then_run`, mirroring the existing `AgentPickerApp`.
 **Locked design (design-brief §4):** the picker is **resume-only** (§4 negative
 clause "no in-app session creation — `--new` flag only"); shown only when **>1**
 session exists (exactly 1 auto-resumes; the launch intent is "resume the last
 session I was poking at"). `--agent` stays a `--new` companion (forbidden in bare
 mode). **bare + 0 sessions → error** `[no_sessions]` directing the operator to
 `--new` (honors the "no in-app creation" clause; the friendlier
 auto-fall-through-to-new alternative is deferred pending operator confirmation).
 ### `_parse` validation relaxation (ratatoskr.cli._parse)
 - Bare TUI mode (`send is None` AND no `--session` AND no `--new`) is now VALID
  → triggers the picker. (Previously `raise UsageError("pass exactly one of
  --session or --new")` unconditionally.)
 - `--send` mode still requires exactly one of `--session`/`--new` (non-
  interactive: no picker can open) → `UsageError("--send requires --session or
  --new")`.
 - `--session` + `--new` stays mutually exclusive.
 - `--agent` in bare mode → `UsageError` (`--agent` belongs to `--new`).
 ```contract
 FN SessionPickerApp.__init__(self, sessions: list[SessionInfo]) -> None
 BRIEF: Textual App[str | None] startup session picker (mirrors AgentPickerApp, issue #8). Opens before RatatoskrApp when bare TUI mode resolves >1 session. `run_async()` returns the chosen session_id (str) or None on Esc/Ctrl-D/Ctrl-C dismissal. Architecturally separate from RatatoskrApp (list_sessions failures + dismissal land before any alt-screen — preserves #6 INV-001).
 PRE: [PRE-001 hard] sessions is non-empty -- assert sessions (caller resolves 0-session and 1-session cases BEFORE constructing the picker)
 POST: [POST-001 return_value] run_async() returns sessions[i].session_id for the highlighted row on `pick`, or None on dismiss -- assert result in {s.session_id for s in sessions} | {None}
 STEPS:
  1. [setup, prescriptive] Store sessions; register the Australis theme (mirror AgentPickerApp).
  2. [sequential, prescriptive] compose: Header + prompt Static + ListView of one ListItem per session (id-short + agent_id + last_active/name lines) + Footer.
  3. [sequential, prescriptive] BINDINGS: enter→action_pick, escape/ctrl+d/ctrl+c→action_dismiss.
  4. [branch, prescriptive] action_pick: read ListView.index; if None return (nothing highlighted); else exit(sessions[index].session_id). action_dismiss: exit(None).
 TESTS:
  pick_returns_session_id [happy,tracer]: SessionPickerApp([s0, s1]); pilot highlights row 1 + press enter → run_async() returns s1.session_id.
  dismiss_returns_none [happy]: press escape → run_async() returns None.
  ctrl_d_dismisses [adversarial]: press ctrl+d → None.
 FN _resolve_then_run(args) — bare-mode extension (session picker)
 BRIEF: Before the existing new/resume branches, resolve bare TUI mode (not args.new AND args.session_id is None) via list_sessions + the picker. Sets a local `effective_new` and `resolved_session_id`; the existing branches then run unchanged on those locals.
 STEPS (inserted at the top of the `async with client` block):
  1. [setup, prescriptive] SET effective_new = args.new; resolved_session_id = args.session_id.
  2. [branch, prescriptive] IF (not args.new) AND (args.session_id is None):  # bare mode
       a. CALL list_sessions(client) → page; ON SessionApiFailed → stderr `[session_api_failed]` + return 20; ON network error → `[network_error]` + return 21.
       b. IF not page.items: stderr `[no_sessions] no sessions to resume; launch with --new --agent <id>` + return 14.
       c. ELIF len(page.items) == 1: SET resolved_session_id = page.items[0].session_id.  # §4: picker only when >1
       d. ELSE: SET resolved_session_id = await SessionPickerApp(page.items).run_async(); IF None → return 0 (Esc/Ctrl-D clean exit).
  3. [sequential, prescriptive] Replace the two `if args.new` predicates with `if effective_new`; the resume `else` branch asserts + uses `resolved_session_id`.
 TESTS (in the `_resolve_then_run` block):
  bare_zero_sessions_errors [error]: bare args; list_sessions → 0 items → stderr contains `[no_sessions]`; return 14; NO POST /sessions, NO picker.
  bare_one_session_auto_resumes [scenario]: bare args; list_sessions → 1 item (sid="s-solo") → RatatoskrApp constructed with session_id="s-solo"; NO picker shown.
  bare_multi_opens_picker [scenario,tracer]: bare args; list_sessions → 2 items; picker returns items[1].session_id → RatatoskrApp constructed with that session_id.
  bare_picker_dismiss_exits_zero [scenario]: bare args; 2 items; picker returns None → return 0; RatatoskrApp NOT constructed.
  bare_list_sessions_api_failure [error]: bare args; list_sessions raises SessionApiFailed(500) → stderr `[session_api_failed]`; return 20.
 ```
@@ -0,0 +1,265 @@
 {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Server-Sent Events emitted on POST /sessions/{id}/messages. Each event is an object discriminated on `type`; all carry `turn_id`.",
  "discriminator": {
    "propertyName": "type"
  },
  "oneOf": [
    {
      "additionalProperties": true,
      "properties": {
        "phase": {
          "enum": [
            "BuildingPrompt",
            "CallingLLM",
            "ProcessingTools",
            "Streaming",
            "Finishing"
          ],
          "type": "string"
        },
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "worker_phase"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "awaiting_llm_first_token"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "content": {
          "type": "string"
        },
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "thinking"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "content": {
          "type": "string"
        },
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "text"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "text_boundary"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "name": {
          "type": "string"
        },
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "tool_start"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "name": {
          "type": "string"
        },
        "result": {},
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "tool_result"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "affect_update"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "done"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "phase": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        },
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "cancelled"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": true,
      "properties": {
        "error_code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "turn_id": {
          "description": "The turn this event belongs to.",
          "type": [
            "integer",
            "string"
          ]
        },
        "type": {
          "const": "error"
        }
      },
      "required": [
        "type",
        "turn_id"
      ],
      "type": "object"
    }
  ],
  "title": "Worldtree Conversation API — SSE turn-stream events"
 }
@@ -0,0 +1,247 @@
 # Ratatoskr v1 coverage map
 _The v1 convergence-target ledger. Ratatoskr has **no self-defined feature
 roadmap**: v1 = consume all of Worldtree's I/O points, reached when Worldtree
 hits 1.0 (operator, 2026-06-19; auto-memory
 `project-ratatoskr-v1-derived-from-worldtree-io-coverage`). This file is that
 coverage map — every Worldtree v1-frozen I/O point × ratatoskr's coverage
 status, so "are we at v1?" is a ledger lookup, not a judgement call._
 **First authored:** 2026-06-30 (the v1 coverage-audit kickoff).
 ---
 ## Frozen target
 Worldtree is at **v1.0.0b2** — approaching 1.0, with its wire surfaces now
 **FROZEN** (Worldtree `docs/v1-schema-freeze-manifest.md`, #326). The audit
 anchors against the frozen machine-readable artifacts, NOT the prose markdown:
 | Worldtree v1 surface | Frozen anchor | Ratatoskr role |
 |---|---|---|
 | Conversation REST API | OpenAPI `info.version` **2.2.0** (`Worldtree/docs/conversation-api-openapi.json`, sha `dbdf4e24…`) — **40 path×method groups** | **client** (debug TUI / web) |
 | Conversation SSE events | `conversation-api-sse-events.schema.json` (sha `9deeebf4…`) — **11 discriminated event types** | **client** |
 | Bifrost wire (consumer protocol) | wire **v0.6** STABLE/FROZEN (`bifrost==1.0.0`) — memory + affect planes | **provider** (Worldtree dispatches into us) |
 > **Pin drift (finding P-1) — REMEDIATED 2026-06-30.** Ratatoskr formerly
 > vendored only the **prose markdown** (`docs/conversation-api-spec.md`), which
 > is byte-identical to live Worldtree's but frozen at v0.35.16-era content (last
 > WT edit 2026-05-31) and does **not** document the b2 surface (7 endpoints
 > below, the 409/503 on messages-POST #331, the unified error envelope #328, the
 > SSE schema). Remediated: the **OpenAPI 2.2.0 + SSE-schema JSON are now vendored
 > and pinned** (`.corviduo-canonicals.toml` → `canonical_drift.py` gate); the
 > prose markdown is the `tolerate_drift` reference. Spec pin advanced to
 > 5810a26 (v1.0.0b2). See § Pin remediation.
 **7 endpoints new in b2 OpenAPI, absent from our vendored markdown:**
 `/admin/keys/bulk`, `/admin/persona/archive`, `/admin/persona/erase`,
 `/admin/usage`, `/embed`, `/judgments`, `/me/usage`.
 ---
 ## Scorecard
 **Scope mandate: A (ledger-mandate), locked by operator 2026-06-30.** v1 "done"
 = every frozen I/O point is **classified** (covered or excluded-with-rationale),
 zero unaccounted. NOT "feature-complete client." All scope-pending rows are now
 resolved (§ Surface 1, scope-resolution table).
 | Surface | Points | ✅ covered-live | ⬜ gap (in-scope) | 🚫 excluded-by-design |
 |---|---|---|---|---|
 | REST (OpenAPI 2.2.0, path groups) | 40 | 9 | 9 | 22 |
 | SSE events | 11 | 11 | 0 | 0 |
 | Bifrost provider planes | 8 verbs | 8 | 0 | (10 gated verbs deferred) |
 **Legend.** ✅ consumed in code AND live-proven against real Worldtree · ⬜ a
 debug-observability I/O point we should cover but don't yet (the convergence
 frontier) · 🚫 deliberate non-goal per the design-brief negative clauses + the A
 mandate. Counts are at the **path-group** level; mixed-method groups are
 footnoted (e.g. `/sessions` POST is ✅ but its `GET` picker is an unwired
 sub-gap).
 ---
 ## Surface 1 — Conversation REST API (OpenAPI 2.2.0)
 ### Covered — client path (ratatoskr's core identity)
 | Endpoint | Status | Where consumed | Note |
 |---|---|---|---|
 | `POST /sessions` | ✅ | `sessions.py:307` → `cli.py:482`,`tui.py:1508`,`web/server.py:155` | + `end_user_id`, `bifrost` binding; 404→AgentNotFound, 502→BifrostHandshakeFailed |
 | `POST /sessions/{id}/messages` (turn stream, SSE) | ✅ | `sse_client.py:484` `stream_turn` → cli/tui/web | the primary surface; 409→AgentNotAvailable, 503→TurnLaunchUnavailable (b2 #331) |
 | `POST /sessions/{id}/turns/{turn_id}/cancel` | ✅ | `sse_client.py:581` → cli/tui/web | two-stage Ctrl-C; 404/409 mapped |
 | `GET /agents` | ✅ | `sessions.py:341` → `tui.py:1472`,`web/server.py:100` | Tier-1 roster; merged with local index |
 | `GET /agents/{id}/persona_state` | ✅ | `sessions.py:384` → `tui.py:1132`,`web/server.py:386` | persona hydrate; 404/403 mapped |
 | `POST /agents/define` | ✅ | `tier3.py:175` → `_run_define` | Tier-3 create |
 | `PATCH /agents/{id}` | ✅ | `tier3.py:219` → `_run_patch` | Tier-3 mutate (system_prompt/model) |
 | `DELETE /agents/{id}` | ✅ | `tier3.py:242` → `_run_delete` | Tier-3 hard-delete |
 | `GET /me` | ✅ | `sessions.py:411` `get_me` → `cli.py` `--whoami` | identity/whoami probe; 401→SessionApiFailed |
 | `GET /capabilities` | ✅ | `sessions.py:428` `get_capabilities` → `cli.py` `--whoami` | Echo ephemeral-template discovery |
 **Sub-gaps inside ✅ path groups** (the method we use is live; a sibling method
 on the same path is an unwired frontier item — see frontier Tier 1):
 - `GET /sessions` — `sessions.py:198` `list_sessions` exists, **no caller**: the
  startup session-picker (design-brief §4 v1) was never wired.
 - `POST /sessions/{id}/messages` + `Last-Event-ID` — `sse_client.py:524`
  `reconnect_turn` exists, **no caller**: the reference SSE-resume impl
  (design-brief §8d) was never wired.
 - `GET /agents/{id}` — consumer-agent lookup (`GET /agents/<owner>:<name>` with
  the owner key) is **manual-curl-only**, not in code.
 ### In-scope gaps — the convergence frontier (debug-observability path)
 **Tier 1 — the debug-observability core (design-brief'd for v1, unbuilt):**
 | Endpoint | Status | Why in-scope |
 |---|---|---|
 | `GET /admin/events` | ⬜ | design-brief §5 v1 **AdminEvents pane**; = issue **#11**, **blocked** on `admin.events.read` scope (infra-ops) |
 | `GET /admin/sessions/{id}/bifrost` | ⬜ | design-brief §5 v1 **BifrostState widget** — never built; admin-key-gated |
 | `GET /admin/sessions/{id}/tools` | ⬜ | design-brief §5 v1 **Tools widget** — never built; admin-key-gated |
 | (`GET /sessions` picker · resume) | ⬜ | sub-gaps above — presenter-wiring only, wrappers exist |
 **Tier 2 — rounds out I/O coverage under A (postdates the design-brief):**
 | Endpoint | Status | Why in-scope |
 |---|---|---|
 | `GET /sessions/{id}/tools` | ⬜ | Tier-3 owner-scoped tool introspection (#183) — reachable with the **consumer key** (no admin scope), the unblocked tool-introspection path |
 | `POST /sessions/{id}/persona_state` (write) | ⬜ | affect-injection is debug-relevant; pairs with our provider affect plane |
 | `POST /characters` · `DELETE /characters/{id}` · `GET /characters/{id}/state` · `GET /models/available-for-characters` | ⬜ | transient-characters (Echo) is a session-creation **routing path** a debug client should be able to drive a turn through |
 ### Excluded by design — the design-brief negative clauses
 | Endpoint(s) | Status | Rationale (design-brief / memory) |
 |---|---|---|
 | `PATCH /sessions/{id}` · `DELETE /sessions/{id}` | 🚫 | §4: rename/delete happen outside the tool (`sessions_cli.py`) |
 | `GET /sessions/{id}/messages` (history) | 🚫 | §6: single-session live transcript, no history fetch |
 | `GET /sessions/{id}` | 🚫 | session detail — identity is footer-visible, no detail view |
 | `GET /sessions/{id}/tool-events` | 🚫 | §5: tool calls observed **inline from SSE** `tool_start`/`tool_result`; persisted-events endpoint is opt-in only |
 | `GET/POST /admin/keys` · `DELETE/POST /admin/keys/{id}` · `POST /admin/keys/{id}/rotate` · `DELETE/POST /admin/keys/bulk` · `POST /admin/keys/bulk/rotate` | 🚫 | §6: **NOT a Worldtree-admin tool** (key mgmt) |
 | `POST /admin/sessions/{id}/retire` | 🚫 | admin session mutation |
 | `POST /admin/persona/{archive,erase}` | 🚫 | admin persona GDPR ops (new in b2) |
 | `POST /admin/users/{id}/tier` | 🚫 | admin user mgmt |
 | `GET /me/usage` · `GET /admin/usage` | 🚫 | usage metering — not turn-flow observability (new in b2) |
 | `GET /healthz` · `GET /readyz` | 🚫 | liveness probes — low debug value (could become a connect preflight; park) |
 | `GET /search` | 🚫 | §5: consumer-product feature, not turn-flow (was "defer to v2") |
 | `GET/POST /uploads` · `DELETE/GET /uploads/{id}` | 🚫 | §6: no uploads — consumer-product feature |
 | `GET /pending` · `GET /sessions/{id}/pending` | 🚫 | §5: poll-only, no turn-flow signal (was "optional, skip") |
 | `POST /embed` | 🚫 | embedding utility — no turn flows through it |
 | `POST /judgments` | 🚫 | LLM-as-judge A/B eval (`response_a`/`response_b`/`rubric`) — standalone eval utility, not turn-flow |
 ### Scope-resolution record (the 11 ❓ rows, resolved under A)
 The 2026-05-20 design-brief deferred several surfaces; the 2026-06-19 reframe
 ("v1 = full I/O coverage") put them back in tension. **Resolved 2026-06-30 under
 mandate A** (debug-observability identity intact; classify, don't build-all):
 | Endpoint(s) | Resolution |
 |---|---|
 | `GET /search` · `uploads` (×2) · `pending` (×2) · `POST /embed` · `POST /judgments` | 🚫 **excluded** — consumer-product / eval / poll utilities, not turn-flow observability |
 | `characters` (×4) · `POST /sessions/{id}/persona_state` | ⬜ **in-scope** (frontier Tier 2) — session-routing + affect-injection debug paths |
 Nothing remains ❓. The ⬜-vs-🚫 line follows the debug-observability test: *does
 a turn flow through it / is it a layer worth watching live?*
 ---
 ## Surface 2 — SSE events (11/11 ✅)
 Every frozen SSE event type is parsed in `sse_client.py:_envelope_for_type`
 (342-411) and rendered by all three presenters (cli/tui/web). **Full coverage.**
 `text` · `worker_phase` · `thinking` · `text_boundary` · `tool_start` ·
 `tool_result` · `done` · `error` · `cancelled` · `awaiting_llm_first_token` ·
 `affect_update`
 > Caveat (not a gap): `affect_update` is wire-verified to emit **zero** events
 > for consumer (Tier-3) agents — the persona-strip SSE path never populates for
 > them (memory 2026-06-18). The handler is correct; the upstream emitter is
 > silent. PAD for consumer agents is surfaced via our own provider read route
 > (`GET /affect/state/{id}`, #18 D2), not this event.
 ---
 ## Surface 3 — Bifrost provider planes (8/8 ✅, live-proven)
 Ratatoskr **implements** the provider side; Worldtree dispatches into it.
 Live-proven end-to-end through real WT turns (#17/#18 smokes; combined `:8392`
 WT-driven smoke 2026-06-20).
 **Memory plane** — covers the entire `bifrost.memory.MemoryDataStore` protocol
 (required: `describe_store`, `get`, `get_many`, `search`, `upsert_many`) **plus**
 `delete_many`:
 | Verb | Where | |
 |---|---|---|
 | `describe_store` | `memory_store.py:140` | advertises caps (sync) |
 | `search` | `memory_store.py:224` | vector recall; scope_all AND / scope_any OR |
 | `get` / `get_many` | `memory_store.py:293` / `:305` | point reads |
 | `upsert_many` | `memory_store.py:150` | idempotent batch write; optimistic lock |
 | `delete_many` | `memory_store.py:314` | transactional delete |
 **Affect plane** — covers `bifrost…InMemoryAffectStore` (`emit`, `fetch`):
 | Verb | Where | |
 |---|---|---|
 | `emit` | `affect_store.py:47` | conduit-opaque snapshot upsert (LWW) |
 | `fetch` | `affect_store.py:116` | `{found, snapshot}`; mandatory since bifrost 0.10.0 strong-or-absent gate |
 Plus the non-wire PAD read route `GET /affect/state/{agent_id}`
 (`affect_store.py:189`) and the combined `:8392` endpoint advertising both caps
 by store-presence (`combined.py:46`).
 **Deferred-gated (advertised-unsupported, correctly out-of-scope for the basic
 plane):** `scan`, `get_edges_for`, `upsert_edges`, `mark_invalid`,
 `mark_superseded`, `patch_many`, `commit_checkpoint`, `lease_job`,
 `read_checkpoint`, `health`. These live only in the bifrost reference
 *extended* store, not the `MemoryDataStore` protocol; deferred per the #294
 re-scope (memory 2026-06-15). Re-evaluate only if Worldtree's Tier-3 path
 starts exercising them.
 ---
 ## Convergence frontier (the v1 to-do)
 **Tier 1 — debug-observability core**, in dependency order:
 1. **Session picker + SSE-resume** — wrappers exist (`list_sessions`,
   `reconnect_turn`), need presenter wiring only. **Cheapest; unblocked.**
 2. **`GET /capabilities` + `GET /me`** — cheap debug primitives. Unblocked.
 3. **BifrostState + Tools widgets** (`GET /admin/sessions/{id}/{bifrost,tools}`)
   — design-brief'd v1, unbuilt. Admin-key-gated reads.
 4. **#11 — AdminEvents pane** — **blocked** on an `admin.events.read` scope grant
   (infra-ops). The single externally-blocked item; everything else can ship
   without it.
 **Tier 2 — rounds out coverage** (lower priority):
 5. **`GET /sessions/{id}/tools`** — owner-scoped tool introspection; consumer-key
   reachable (no admin scope), so unblocked.
 6. **Transient-characters routing** (4 endpoints) + **`POST /sessions/{id}/persona_state`**.
 ---
 ## Pin remediation (finding P-1) — DONE 2026-06-30
 Re-pinned to the frozen machine-readable artifacts (the chosen option):
 `conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json`
 are vendored under `docs/` and pinned in `.corviduo-canonicals.toml`
 (`worldtree-conversation-api-openapi-v2`, `-sse-events-v1`), drift-gated by
 `canonical_drift.py`. The prose markdown stays as a `tolerate_drift` reference
 (`-spec-v1`). `pyproject.toml` spec pin advanced f1b59f8 → 5810a26 (v1.0.0b2);
 `docs/SPEC-PIN.md` records the bump. This map now audits a frozen, diffable
 target — re-running the audit is a `canonical_drift.py` check away.
 ---
 ## Decisions
 1. **Scope mandate — RESOLVED 2026-06-30: A (ledger-mandate).** v1 "done" = every
   frozen I/O point classified, zero unaccounted; NOT feature-complete client.
   The ⬜-vs-🚫 line for the 11 formerly-pending rows is locked above (§
   Scope-resolution record).
 2. **Pin remediation (P-1) — RESOLVED 2026-06-30 (re-pin to machine-readable).**
   Vendored `conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json`
   as the authoritative drift gates (pinned in `.corviduo-canonicals.toml`,
   `canonical_drift.py` green); prose markdown kept as `tolerate_drift`
   reference. Spec pin advanced f1b59f8 (v0.35.16) → 5810a26 (v1.0.0b2). This
   map now audits against a frozen, diffable target.
@@ -1,6 +1,6 @@
 # Persistent memory — ratatoskr
-_Last updated: 2026-06-20_
+_Last updated: 2026-06-30_
 This file captures durable intent and supporting evidence (goals, decisions,
 foot-gun warnings, in-flight state) across context resets. Read it at session
@@ -138,6 +138,22 @@ decision. Captures rationale that won't be obvious from code alone.
 - `[2026-06-19]` **Ratatoskr v1 is DERIVED from Worldtree I/O coverage (operator) — no self-defined feature ROADMAP.** v1 = consume all of Worldtree's I/O points, reached when Worldtree hits 1.0; the convergence target is a coverage map, not a 3–7 capability list. [auto-memory `project-ratatoskr-v1-derived-from-worldtree-io-coverage`]
 - `[2026-06-20]` **#18's final leg PROVEN — composite `:8392` WT-driven smoke ran end-to-end + persisted.** infra-ops allowlisted `10.100.10.50:8392` on the personal WT (`01KVHWJGTT…`); a real WT turn (session `b83a66b6`, `ratatoskr:sindra`, fresh end_user `resmoke-choco-1`) dispatched the full both-plane lifecycle through ONE endpoint — handshake (both caps) → `affect.fetch` + `memory.search` → `affect.emit` (`stored:true`) → `memory.upsert_many` (`upserted:1`) — both writes verified in our SQLite (`affect_snapshots` PAD row + `memory_chunks` chunk `2df1b79…`). First attempt blocked by a `model_unavailable` outage on the personal WT (both agents' models down), operator-fixed mid-session, then clean. The composite has no open legs.
 - `[2026-06-20]` **#17 CLOSED in the tracker.** Shipped end-to-end (`v0.17.8`–`.13` + op-feed field fix `v0.17.17`); the 2026-06-20 composite smoke re-exercised its op-feed live. Closing comment captures the full both-plane proof. Open issues now just #11 (scope-blocked) + #10 (watch).
 - `[2026-06-20]` **Sindra has real PAD but ~empty memory — the affect/memory persistence asymmetry, confirmed on real sessions.** affect EMITS every turn (persona always accumulates: vuong 8→14 interactions across the session); memory only writes on a PROMOTION trigger (salience / turn_count≥6 / idle-≥10min flush). Two real vuong sessions through the combined bind (`04d6414c`, `433541fe`) drove affect emits + memory SEARCHES but ZERO promotion upserts → `memory.db` holds only the smoke fixture, zero vuong chunks. Operator: acceptable (server-takedown = "Sindra bonked on the head"; transient memory loss WAD). Operational catch: combined-as-default web bind saves persona reliably but silently LOSES memory if a session closes before a promotion trigger fires.
 - `[2026-06-29]` **Web SPA combined-bind default (`v0.18.1`, `719e4d6`) — operator-caught gap.** #18 shipped the composite `:8392` provider but never exposed it in the web bind dropdown (only memory/affect single-plane). Added `combined (:8392)` as the DEFAULT option (both planes in one session), kept single-plane for isolation diagnostics; wired `endpoint_for_plane` combined→8392 + server validation + the dropdown. Direct TDD; #17 contract updated (the governing spec for the web bind). Restarted `:8765` on current code (env.sh + provider.env + `RATATOSKR_AFFECT_READ_URL=:8392`).
 - `[2026-06-29]` **bifrost repinned 1.0.0 (`v0.18.2`, `af67ad9`).** bifrost-dev shipped its first stable release; wire v0.6 now STABLE/FROZEN. Non-breaking (byte-identical to 0.10.0); switched the floor pin → exact `==1.0.0` per the stable-substrate posture. Post-1.0 breaking changes ride a bifrost MAJOR + new wire (v0.7+); a v0.6-pinned consumer is stable indefinitely. (Also this session: althing migrated to v0.15.0+ lean-bus / schema v4 — moderation retired, chamber/redis ripped; our tooling auto-updated to 0.17.4.)
 - `[2026-06-30]` **Worldtree v1.0.0b1→b2 consumer adaptation: eager turn-launch statuses (`v0.18.3` `b2e4901`, `v0.18.4` `e4317f6`).** Worldtree #331 decoupled turn execution from the SSE connection → turn-launch failures now arrive EAGERLY as a status before any stream: 409 `agent_not_available` (pre-b1 a 200 + in-stream error event), 503 retryable. Mapped both in `stream_turn` to typed `SseConnectFailed` subclasses keyed on STATUS, parsing the `{detail:{error_code,message}}` envelope — POST-003 preserved (no synthetic event yielded), existing handlers still catch (the design fork vs yield-an-Error-event was decided by POST-003). **DEFERRED follow-ups** (tracked here; bundle with the v1 coverage-audit): (1) live-prove the 409/503 end-to-end on personal-b2 (now unblocked — personal on b2, my key works there); (2) full `conversation-api-spec.md` markdown re-vendor to the b2 era (ratatoskr vendors the markdown, not the OpenAPI JSON).
 - `[2026-06-30]` **Verify-against-the-real-spec-before-committing caught a real upstream gap.** Holding the v0.18.3 commit to verify against demo's OpenAPI surfaced that the FROZEN OpenAPI 2.1.0 didn't document the 409/503 the heads-up described (`agent_not_available` was in the ErrorCode enum, but NO 503/turn-launch code). worldtree-dev confirmed it was THEIR gap (#331 added the statuses without extending the #328 `openapi()` override), shipped the fix in **v1.0.0b2 / OpenAPI 2.2.0** (409/503 now enumerated, 503 code finalized as `not_ready`). "The consumer-oracle earning its keep." Lesson: a provider's prose heads-up can diverge from its frozen machine-readable spec — verify the actual spec before committing a consumer adaptation.
 - `[2026-06-30]` **regard is a DEAD AXIS in Worldtree's emitted affect (caught provider-side; worldtree-dev confirmed + escalated to Vuong).** Across all our affect snapshots, `valence[].regard` is EXACTLY 0.15 regardless of agent/end_user/interaction_count, while familiarity accumulates (vuong 0.18→0.69 over 14 turns). Root cause (worldtree-dev, code-grounded): 0.15 = `base_regard = agreeableness*0.3` (sindra A=0.5); regard's only human-writer `update_regard` early-returns unless an emotion is `about="other"`, but the Vili appraiser's `ViliResponse` schema has NO directedness axis (everything hardcoded `about="situation"`) — producer side lost in the #265 Vili rework; consumer machinery intact. NOT WAD; the fix (reintroduce other-directed classification) is an affect-model change touching every agent + a directedness-classification design call → worldtree-dev filing an issue to Vuong. [the consumer/provider thesis paying off again]
 - `[2026-06-30]` **v1 coverage-audit kicked off; coverage ledger written (`docs/coverage-map.md`) — the first one.** Every Worldtree v1-FROZEN I/O point × ratatoskr status. Anchored on WT's frozen machine-readable artifacts (OpenAPI **2.2.0** `conversation-api-openapi.json` = 40 REST path-groups + SSE schema = 11 events + bifrost wire v0.6), NOT the stale vendored prose markdown. Result: **SSE 11/11 ✅; Bifrost provider planes 8/8 ✅ live-proven** (covers the full `bifrost.memory.MemoryDataStore` protocol = describe_store/get/get_many/search/upsert_many + delete_many, and affect emit/fetch; **`health` is extended-reference-store-only, NOT in the base protocol → correctly deferred, NOT a gap** — settles the prior "health" ambiguity); **client REST 7/40 ✅ live, 11 ⬜ in-scope, 22 🚫 excluded.**
 - `[2026-06-30]` **Scope mandate A locked (operator): v1 "done" = every frozen I/O point CLASSIFIED (covered-or-excluded-with-rationale), zero unaccounted — NOT a feature-complete client.** The coverage map is a LEDGER, not a build-everything mandate. Reconciles the 2026-06-19 "consume all I/O" reframe with the 2026-05-20 design-brief's "NOT an admin tool" + deferral negative clauses (which predate both the provider identity and the reframe). Resolved the 11 design-brief-vs-reframe ❓ rows via the debug-observability test (*does a turn flow through it?*): 🚫 search / uploads / pending / embed / judgments (consumer-product + eval utilities); ⬜ transient-characters routing (4) + persona_state-write (Tier-2 frontier). **Frontier Tier 1 (all unblocked except #11):** session-picker + SSE-resume (wrappers `list_sessions`/`reconnect_turn` exist with NO caller — presenter-wiring only) → `GET /capabilities` + `GET /me` → BifrostState/Tools widgets (`GET /admin/sessions/{id}/{bifrost,tools}`, admin-key) → **#11 AdminEvents BLOCKED on `admin.events.read` scope**. The 3 admin-observability widgets + picker + resume were design-brief §5/§4/§8d v1 items that **were never built**.
 - `[2026-06-30]` **Finding P-1 (pin drift) + pin-remediation PENDING.** We vendor the PROSE markdown (`docs/conversation-api-spec.md`), which is **byte-identical to live WT's** but frozen at v0.35.16-era content (last WT edit 2026-05-31) — it does NOT capture b2: 7 new endpoints (admin/keys/bulk, admin/persona/{archive,erase}, admin/usage, embed, judgments, me/usage), the 409/503 on messages-POST (#331), the unified error envelope (#328), or the SSE schema. **WT's authoritative v1 truth is now the FROZEN OpenAPI 2.2.0 + SSE-schema JSON** (`Worldtree/docs/v1-schema-freeze-manifest.md`). So the previously-deferred "re-vendor markdown to b2" is a **near-no-op** (markdown content identical). **Pending operator nod:** re-pin to the machine-readable artifacts (recommended — drift-checkable via `canonical_drift.py`, makes the coverage map reproducible vs a frozen diffable target) vs markdown-only. Deferred (not auto-applied) because it adds vendored artifacts + a canonical-sync pin = substrate change with CI-gating reach. **→ RESOLVED 2026-06-30 (operator: "a then b").** Vendored `conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json` + re-copied the prose markdown; pinned all three in `.corviduo-canonicals.toml` (OpenAPI+SSE = strict drift gates, markdown = `tolerate_drift` reference); advanced `worldtree-spec-rev` f1b59f8→5810a26 + `worldtree-version` v0.29.0(STALE, never bumped from the v0.35.16 pin)→v1.0.0b2 + `pinned-on`→2026-06-30; SPEC-PIN.md history row added. `canonical_drift.py` green (10/10). `pin:`-only, no version bump (no client-facing code change; the b2 409/503 + error-envelope were already consumed in v0.18.3/.4).
 - `[2026-06-30]` **(b) Tier-1 frontier SCOPED, ready for a contract-first TDD cycle (next focused work).** The primitives already exist + are contracted + tested; the gap is PRESENTER-level wiring. Two slices: **(b1) SSE-resume** — contract #1 (`ratatoskr.sse_client`) DELIBERATELY makes resume caller-owned ("on `SseConnectionDropped`, the caller MAY invoke `reconnect_turn`"); `reconnect_turn` (sse_client.py:524) has NO caller. Gap = a SHARED resume-orchestration wrapper (catch `SseConnectionDropped` → track last-seen `sse_id` → `reconnect_turn` → continue), consumed by all 3 presenters per design-brief §8b "share the consumer, branch the presenter" (NOT per-presenter — that forks the consumer). New function block → **amend contract #1** (additive FN, e.g. `stream_turn_resilient`) then TDD (RED: drop-mid-stream→resume continuity; GREEN: wrapper; wire `cli --send` first as the tracer). Resume design pre-locked: in-process Last-Event-ID only, cross-process deferred to v2 (design-brief §8d). **(b2) session-picker** — `list_sessions` (sessions.py:198) has NO caller; add a Textual DataTable startup picker (>1 session) + `--session <id>`/`--new` CLI flags (design-brief §4, decisions pre-locked). Both pre-locked → heid-contract-review likely skippable as ceremony (small additive amendments to mature specs); heid-code-review still valuable. **#11 AdminEvents stays BLOCKED** on `admin.events.read` scope (infra-ops).
 - `[2026-06-30]` **(b1) SSE-resume SHIPPED (`v0.18.5`) — `stream_turn_resilient` (sse_client.py).** The shared resume-orchestration surface (design-brief §8b): wraps `stream_turn`+`reconnect_turn`, catches `SseConnectionDropped` (mid-stream drop OR clean-EOF-before-terminal) → resumes from last-seen `sse_id` via `reconnect_turn` (Last-Event-ID), up to `max_reconnects` (default 5); non-drop reconnect failures (412/410/400/TurnIdFlip/SseConnectFailed) PROPAGATE per contract #1's "surface, not recover". `last_seen` persists ACROSS attempts (a zero-event reconnect drop falls back to the prior attempt's id). Direct in-session TDD against a contract-#1 amendment (8 cases incl. two-drops, max-reconnects-exhausted, zero-budget, buffer-expired-propagates, unresumable-zero-event). Wired ALL THREE presenters through it (`v0.18.6`): `cli --send` (`cli.py:396`), TUI (`tui.py:1321`), web (`web/server.py:294`) — each a name-for-name `stream_turn`→`stream_turn_resilient` swap (the §8b "all presenters share the consumer" promise, fully kept; the TUI is the primary resume beneficiary — long-lived sessions / laptop-suspend). Suite 518 green; ruff+mypy clean on touched code (pre-existing cli.py:400/543 mypy warts left untouched per surgical rule); contract #1 validates OK. **heid-code-review NOT run** (small additive well-TDD'd wrapper; offered to operator). **b2 (session-picker + `--session`/`--new` flags) still pending.**
 - `[2026-06-30]` **(b2) session-picker SHIPPED (`v0.18.7`) — bare TUI mode → startup picker (design-brief §4).** `list_sessions` had NO caller; now bare TUI mode (no `--session`/`--new`) resolves via `list_sessions` in `_resolve_then_run`: **0 sessions → `[no_sessions]` error, exit 14** (resume-only, honors §4 "no in-app session creation — `--new` flag only"); **exactly 1 → auto-resume** (§4 "picker only when >1"); **≥2 → new `SessionPickerApp`** (Textual `App[str|None]`, mirrors `AgentPickerApp`; ListView of sessions) → resume the pick (Esc/Ctrl-D → exit 0). cli `_parse` relaxed: bare TUI now VALID (was "pass exactly one" error); `--send` still requires one flag (non-interactive, no picker); `--agent` forbidden in bare mode; `run_tui` PRE-002 XOR→"not both". Direct in-session TDD (contract #6 amendment, validated OK): 3 widget pilot tests + 5 `_resolve_then_run` resolution tests + 3 cli validation tests. Suite **528 green**; touched code ruff-clean (mypy: only the `BINDINGS` list-invariance warning every App in tui.py already carries — consistent). **DESIGN NOTE — bare+0-sessions → error (clause-consistent). The friendlier auto-fall-through-to-new alternative is DEFERRED pending operator preference (it would create a session without `--new`, against the §4 negative clause).** **Frontier now: `GET /capabilities`+`GET /me` → BifrostState/Tools widgets (`GET /admin/sessions/{id}/{bifrost,tools}`, admin-key) → #11 AdminEvents (BLOCKED on `admin.events.read`).** heid-code-review NOT run on b1 or b2 (offered).
 - `[2026-06-30]` **capabilities+me slice SHIPPED (`v0.18.8`) — `GET /me` + `GET /capabilities` consumed via a new `--whoami` one-shot.** `get_me`/`get_capabilities` added to sessions.py (mirror `get_persona_state`: 200→dict verbatim, non-200→`SessionApiFailed`; freeform dicts per the frozen OpenAPI). New `ratatoskr --whoami` CLI mode (mirrors `--send`'s non-interactive shape) fetches both + prints an identity+capabilities report; standalone probe (mutually exclusive with `--send`/`--session`/`--new`/`--agent`, opens no session; new `ParsedArgs.whoami` field + main() dispatch). **`/capabilities` is the Echo EPHEMERAL-TEMPLATE discovery endpoint** (`{ephemeral_templates:{echo:{allowed_models,default_model,system_prompt_max_bytes}}}`), NOT a generic server-caps endpoint (audit finding — the coverage-map's earlier "server capability discovery" framing was imprecise). `/me` = whoami (`{user_id,scopes,tier,key_id?,...}`, optionals omitted-not-null). Contract-skip privilege invoked (low-effort GET wrappers) but contract #2 amended (2 FNs, validated OK) to keep the sessions spec canonical + honest test citations. TDD: 5 wrapper tests + 5 cli tests (validation + mode + error). Suite **538 green**; touched code ruff-clean (mypy: only `no-any-return` on `resp.json()`→dict, identical to the pre-existing `get_persona_state`). **Coverage: REST 9/40 ✅ (up from 7).** TUI-surfacing of /me (footer identity line) + /capabilities DEFERRED — the one-shot is the minimal tracer. **Frontier now: BifrostState + Tools widgets (`GET /admin/sessions/{id}/{bifrost,tools}`, admin-key-gated) → #11 AdminEvents (BLOCKED on `admin.events.read`).**
 _41 older entries (2026-05-* — the original debug-TUI/web build era) archived to archival-memory.md._
@@ -173,5 +189,7 @@ defense against re-attempting the same cul-de-sac.
 - `[2026-06-19]` **heid-code-review pulled MORE weight than its own "marginal" self-assessment.** The panel returned zero drift, but its single test-fidelity finding CASCADED into 2 real latent-bug fixes when applied (the memory `check_same_thread` bug + Regin's op-feed field-name bug). **Lesson: a contract-fidelity nudge can transitively expose bugs the test never reached — don't dismiss a "marginal" finding by its count.**
 - `[2026-06-20]` **The post-turn-async timing trap bit AGAIN — even a 35s post-`[done]` read missed the promotion `upsert_many` by ~2s** (it landed `19:48:58`; the read was ~`19:48:56`). A 15s-interval background poll caught it on the first tick. Same family as the affect.emit / async-promotion traps already logged — re-confirmed that "wait once then read" is fragile for post-turn writes; **poll a window, don't snapshot once.** (The affect.emit write, by contrast, DID land inside the 35s window — promotion is the slower of the two post-turn writes.)
 - `[2026-06-30]` **Heimdall keys are PER-INSTANCE — a key minted on one Worldtree 401s on another.** Our Conversation-API key works on personal `:8081` but 401s `auth_invalid` on demo `:8080` (per-instance Heimdall user store + pepper; fresh deploys start with an EMPTY key store). Same as the admin key (personal-only). **To live-drive a given instance you need a key minted FOR that instance** (request via infra-ops). Couldn't live-prove the b2 409 on demo for this reason → deferred to personal-b2 where we have access.
 - `[2026-06-30]` **`tea comment <N>` hangs on Gitea** (the whole compound bash auto-backgrounded + stuck on the open `tea` call). The #11 prereq comment hung; killed it + posted via the Gitea HTTP API directly (`POST /api/v1/repos/vh/ratatoskr/issues/<N>/comments`, token from `~/.config/tea/config.yml`). **For issue comments, prefer the Gitea API over `tea comment` when `tea` is flaky** (CLAUDE.md already says use HTTP for comment-EDITS; this extends it to ADD when tea hangs). Verify-then-post (check the comment didn't already land) to avoid a double-post after a kill.
 _18 older entries (2026-05-* — the original debug-TUI/web build era) archived to archival-memory.md._
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 [project]
 name = "ratatoskr"
-version = "0.18.4"
+version = "0.18.8"
 description = "Worldtree Conversation API debug TUI — multi-pane observability dashboard"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -60,9 +60,9 @@ Repository = "https://gitea.phasefinal.com/vh/ratatoskr"
 # Ratatoskr is built against Worldtree at this commit; the vendored
 # spec snapshot in docs/ reflects that SHA.
 [tool.ratatoskr.spec-pin]
-worldtree-spec-rev = "f1b59f8cd6fe41e497d0be9dad9d3110451f0d9a"
+worldtree-spec-rev = "5810a26b38a5ea6630892f9a39756f57c5b7b41e"
-worldtree-version = "v0.29.0"
+worldtree-version = "v1.0.0b2"
-pinned-on = "2026-05-26"
+pinned-on = "2026-06-30"
 # Bifrost lives on the auth-gated gitea PyPI index (not public PyPI).
 # uv reads the credential from UV_INDEX_GITEA_USERNAME / _PASSWORD or ~/.netrc.
@@ -12,7 +12,7 @@ import signal
 import sys
 from dataclasses import dataclass, field
 from importlib.metadata import PackageNotFoundError, version
-from typing import TextIO
+from typing import Any, TextIO
 import httpx
@@ -24,6 +24,8 @@ from ratatoskr.sessions import (
    SessionApiFailed,
    create_session,
    endpoint_for_plane,
    get_capabilities,
    get_me,
 )
 from ratatoskr.sse_client import (
    AffectUpdate,
@@ -47,7 +49,7 @@ from ratatoskr.sse_client import (
    TurnIdFlip,
    WorkerPhase,
    cancel_turn,
-    stream_turn,
+    stream_turn_resilient,
 )
@@ -97,6 +99,9 @@ class ParsedArgs:
    bifrost: BifrostBinding | None = None
    bifrost_plane: str | None = None
    consumer_key: str | None = None
    # Standalone boot-time orientation probe: GET /me + GET /capabilities, print,
    # exit. Mutually exclusive with the session/turn flags (opens no session).
    whoami: bool = False
 class _ArgparseError(Exception):
@@ -121,6 +126,7 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
    parser.add_argument("--api-key", dest="api_key")
    parser.add_argument("--server")
    parser.add_argument("--raw", action="store_true")
    parser.add_argument("--whoami", action="store_true")
    # Issue #5: required for per-end-user agents (lofn etc.); optional otherwise (mimir).
    parser.add_argument("--end-user-id", dest="end_user_id", default=None)
    # Issue #17: bind the created session to our own Bifrost provider plane.
@@ -141,10 +147,25 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
    # Issue #5 INV-001: --end-user-id, if passed, MUST be non-empty (mirrors --send).
    if ns.end_user_id is not None and not ns.end_user_id:
        raise UsageError("--end-user-id must be non-empty when passed")
    if ns.whoami:
        # Standalone boot-time probe (GET /me + /capabilities): opens no session.
        if ns.send is not None or ns.session or ns.new or ns.agent:
            raise UsageError(
                "--whoami is a standalone probe (no --send/--session/--new/--agent)"
            )
    else:
        if ns.session and ns.new:
-        raise UsageError("--session and --new are mutually exclusive; pass exactly one")
+            raise UsageError("--session and --new are mutually exclusive")
        if not ns.session and not ns.new:
-        raise UsageError("pass exactly one of --session or --new")
+            # Bare TUI mode → startup session picker (design-brief §4). --send is
            # non-interactive (no picker can open), so it still requires one flag;
            # --agent belongs with --new (bare mode resumes, it doesn't create).
            if ns.send is not None:
                raise UsageError("--send requires --session or --new (no interactive picker)")
            if ns.agent:
                raise UsageError(
                    "--agent belongs with --new; bare TUI mode opens the session picker"
                )
        if ns.session and ns.agent:
            raise UsageError("--agent is required with --new and forbidden with --session")
        if ns.new and not ns.agent and ns.send is not None:
@@ -200,6 +221,7 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
        bifrost=bifrost,
        bifrost_plane=bifrost_plane,
        consumer_key=consumer_key,
        whoami=ns.whoami,
    )
@@ -393,7 +415,7 @@ async def _run_turn(
    cancelling = False
    sigint_task: asyncio.Task[bool] | None = None
    cancel_task: asyncio.Task[None] | None = None  # strong ref to fire-and-forget cancel
-    aiter_obj = stream_turn(client, session_id, content).__aiter__()
+    aiter_obj = stream_turn_resilient(client, session_id, content).__aiter__()
    try:
        while True:
@@ -550,6 +572,56 @@ async def _amain(args: ParsedArgs) -> int:
            loop.remove_signal_handler(signal.SIGINT)
 def _format_whoami(me: dict[str, Any], caps: dict[str, Any]) -> str:
    """Render the --whoami report: identity (GET /me) + server capabilities."""
    lines = ["identity:"]
    lines.append(f"  user_id: {me.get('user_id', '?')}")
    lines.append(f"  tier: {me.get('tier', '?')}")
    lines.append(f"  scopes: {', '.join(me.get('scopes', [])) or '(none)'}")
    for k in ("display_name", "key_id", "key_label"):
        if k in me:
            lines.append(f"  {k}: {me[k]}")
    lines.append("capabilities:")
    templates = caps.get("ephemeral_templates", {})
    if templates:
        for name, spec in templates.items():
            models = ", ".join(spec.get("allowed_models", []))
            lines.append(
                f"  ephemeral_template {name}: default={spec.get('default_model', '?')} "
                f"max_bytes={spec.get('system_prompt_max_bytes', '?')} models=[{models}]"
            )
    else:
        lines.append("  (no ephemeral templates advertised)")
    return "\n".join(lines) + "\n"
 async def _whoami(args: ParsedArgs) -> int:
    """--whoami one-shot: GET /me + GET /capabilities, print a compact report, exit.
    A boot-time orientation probe (mirrors --send's non-interactive shape):
    "who am I against this server, and what does it offer." Opens no session.
    Errors land on stderr with the same [session_api_failed] / [network_error]
    vocab + exit codes as the other modes.
    """
    assert isinstance(args, ParsedArgs)
    async with httpx.AsyncClient(
        base_url=args.server_url,
        headers={"Authorization": f"Bearer {args.api_key}", "User-Agent": USER_AGENT},
        timeout=httpx.Timeout(connect=10.0, read=10.0, write=10.0, pool=10.0),
    ) as client:
        try:
            me = await get_me(client)
            caps = await get_capabilities(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
        sys.stdout.write(_format_whoami(me, caps))
    return 0
 def main(argv: list[str] | None = None) -> int:
    """Sync entry point. Maps UsageError/_AuthError to exit codes BEFORE the event loop."""
    assert argv is None or all(isinstance(a, str) for a in argv)
@@ -565,6 +637,8 @@ def main(argv: list[str] | None = None) -> int:
        # argparse's --help / --version short-circuit via SystemExit(0). Pass the code
        # through verbatim — argparse already printed help to stdout.
        return int(exc.code) if exc.code is not None else 0
    if args.whoami:
        return asyncio.run(_whoami(args))
    if args.send_content is None:
        # TUI mode — lazy import preserves INV-001 (no textual in cli at module scope).
        from ratatoskr.tui import run_tui
@@ -406,3 +406,35 @@ async def get_persona_state(
    if resp.status_code == 403 and error_code == "auth_scope_denied":
        raise AuthScopeDenied(scope="persona.read")
    raise SessionApiFailed(status=resp.status_code, body=resp.content)
 async def get_me(client: httpx.AsyncClient) -> dict[str, Any]:
    """GET /me — the authenticated principal's identity + key metadata (spec §GET /me).
    Boot-time whoami: verify the key without agent-config side effects. Returns
    the parsed dict verbatim (freeform per the frozen OpenAPI; the spec documents
    `{user_id, scopes, tier, display_name?, key_id?, key_label?, ...}`, optional
    fields omitted-not-null). 401 (bad/absent key when auth is enabled) — like
    every other non-200 — surfaces as SessionApiFailed (get_persona_state
    precedent). Read-only, rate-exempt, no audit emission.
    """
    assert client is not None
    resp = await client.get("/me")
    if resp.status_code == 200:
        return resp.json()
    raise SessionApiFailed(status=resp.status_code, body=resp.content)
 async def get_capabilities(client: httpx.AsyncClient) -> dict[str, Any]:
    """GET /capabilities — server capability discovery (spec §Ephemeral Templates).
    Returns `{ephemeral_templates: {echo: {allowed_models, default_model,
    system_prompt_max_bytes}}}` — what the server offers before a client decides
    to instantiate. Any authenticated caller may read it (no scope). Parsed dict
    verbatim; any non-200 → SessionApiFailed.
    """
    assert client is not None
    resp = await client.get("/capabilities")
    if resp.status_code == 200:
        return resp.json()
    raise SessionApiFailed(status=resp.status_code, body=resp.content)
@@ -549,6 +549,55 @@ async def reconnect_turn(
            yield event
 async def stream_turn_resilient(
    client: httpx.AsyncClient,
    session_id: str,
    content: str,
    *,
    max_reconnects: int = 5,
 ) -> AsyncIterator[Event]:
    """Resume-orchestration wrapper over stream_turn + reconnect_turn.
    Yields ONE continuous Event stream; on `SseConnectionDropped` (mid-stream
    drop or clean EOF before a terminal), resumes from the last-seen `sse_id`
    via `reconnect_turn`, up to `max_reconnects` times, until a terminal
    Done/Error/Cancelled arrives. The single shared surface presenters consume
    for resilient streaming (design-brief §8b: "share the consumer, branch the
    presenter"). Cross-process resume stays deferred to v2 (§8d): `last_seen`
    lives only in this generator's frame. See contract FN stream_turn_resilient
    (amendment 2026-06-30).
    """
    assert client is not None
    assert session_id and isinstance(session_id, str)
    assert content and isinstance(content, str)
    assert isinstance(max_reconnects, int) and max_reconnects >= 0
    last_seen: SseId | None = None
    reconnects = 0
    gen = stream_turn(client, session_id, content)
    while True:
        try:
            async for event in gen:
                last_seen = event.sse_id
                yield event
            return  # generator completed cleanly → terminal event reached (INV-001)
        except SseConnectionDropped as drop:
            # Prefer the id we tracked from a yielded event; fall back to the one
            # the drop carries (covers a drop on the very first frame). Non-drop
            # reconnect failures (412/410/400/flip) are NOT caught here — they
            # propagate per the contract's "surface, not recover" policy.
            seen = last_seen or drop.last_seen_sse_id
            if seen is None or reconnects >= max_reconnects:
                raise
            reconnects += 1
            gen = reconnect_turn(
                client,
                session_id,
                content,
                last_event_id=f"{seen.turn_id}:{seen.seq}",
            )
 def _parse_sse_id(raw: str) -> SseId:
    """Parse the SSE wire `id:` as composite `{turn_id}:{seq}`. See contract FN _parse_sse_id."""
    assert isinstance(raw, str)
@@ -42,9 +42,11 @@ from ratatoskr.sessions import (
    BifrostHandshakeFailed,
    PersonaNotConfigured,
    SessionApiFailed,
    SessionInfo,
    create_session,
    get_persona_state,
    list_agents,
    list_sessions,
 )
 from ratatoskr.sse_client import (
    AffectUpdate,
@@ -68,7 +70,7 @@ from ratatoskr.sse_client import (
    TurnIdFlip,
    WorkerPhase,
    cancel_turn,
-    stream_turn,
+    stream_turn_resilient,
 )
 # ---- Australis theme (https://github.com/lkraven/australis) ------------------
@@ -798,6 +800,128 @@ class AgentPickerApp(App[str | None]):
        self.exit(None)
 def _session_desc(s: SessionInfo) -> str:
    """One-line session summary for the picker's second row."""
    tail = f"session {s.session_id} · last active {s.last_active}"
    if s.message_count is not None:
        tail += f" · {s.message_count} msgs"
    return tail
 class SessionPickerApp(App[str | None]):
    """Startup session picker (design-brief §4, slice b2). Opens before
    RatatoskrApp when bare TUI mode resolves >1 session. `run_async()` returns
    the chosen session_id (str) or None on Esc/Ctrl-D/Ctrl-C dismissal.
    Resume-only (design-brief §4 negative clause "no in-app session creation —
    --new flag only"): the picker chooses among EXISTING sessions; starting a
    fresh one is the --new flag's job. Architecturally separate from
    RatatoskrApp (mirrors AgentPickerApp): list_sessions failures + dismissal
    land before any alt-screen opens (preserves #6 INV-001).
    """
    DEFAULT_CSS = """
    Header, HeaderIcon, HeaderTitle, HeaderClock {
        background: $surface;
        color: $au-bright-blue;
    }
    Footer {
        background: $surface;
    }
    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;
    }
    #session-list {
        height: 1fr;
        background: $background;
    }
    #session-list > ListItem {
        height: auto;
        padding: 1 1;
        background: $background;
    }
    #session-list:focus ListItem.-highlight {
        background: $primary;
    }
    #session-list:focus ListItem.-highlight .session-id-line {
        color: $au-bright-white;
        text-style: bold;
    }
    #session-list:focus ListItem.-highlight .session-desc {
        color: $au-bright-80;
    }
    .session-id-line {
        color: $au-bright-blue;
        text-style: bold;
    }
    .session-desc {
        color: $au-bright-70;
    }
    """
    BINDINGS: ClassVar[list[Binding]] = [
        Binding("enter", "pick", "Resume", 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, sessions: list[SessionInfo]) -> None:
        super().__init__()
        # PRE-001: caller (_resolve_then_run) resolves the 0-session and
        # 1-session cases BEFORE constructing the picker.
        assert sessions
        self.sessions = sessions
        self.register_theme(AUSTRALIS_THEME)
        self.theme = "australis"
    def compose(self) -> ComposeResult:
        yield Header()
        yield Static(
            "Pick a session to resume (relaunch with --new for a fresh one):",
            id="picker-prompt",
        )
        yield ListView(
            *[
                ListItem(
                    Static(
                        f"{s.name or s.session_id} · {s.agent_id}",
                        classes="session-id-line",
                    ),
                    Static(_session_desc(s), classes="session-desc"),
                )
                for s in self.sessions
            ],
            id="session-list",
        )
        yield Footer()
    async def on_mount(self) -> None:
        self.query_one("#session-list", ListView).focus()
    def action_pick(self) -> None:
        lv = self.query_one("#session-list", ListView)
        idx = lv.index
        if idx is None:
            return  # nothing highlighted; ignore
        self.exit(self.sessions[idx].session_id)
    def action_dismiss(self) -> None:
        self.exit(None)
 class RatatoskrApp(App[int]):
    """Textual TUI shell — single chat pane."""
@@ -1318,7 +1442,7 @@ class RatatoskrApp(App[int]):
                pass
        try:
-            async for event in stream_turn(self.client, self.session_id, content):
+            async for event in stream_turn_resilient(self.client, self.session_id, content):
                if self.active_turn_id is None:
                    self.active_turn_id = event.sse_id.turn_id
                    self._write_turn_headers(self.active_turn_id)
@@ -1430,8 +1554,9 @@ def run_tui(args: ParsedArgs) -> int:
    """
    # PRE-001: TUI-mode marker (issue #4 contract)
    assert isinstance(args, ParsedArgs) and args.send_content is None
-    # PRE-002: Exactly one of session_id / new must be set (xor)
+    # PRE-002 (slice b2): --session and --new are mutually exclusive, but NEITHER
-    assert bool(args.session_id) != bool(args.new)
+    # is now valid — bare TUI mode opens the startup session picker (§4).
    assert not (args.session_id and args.new)
    return asyncio.run(_resolve_then_run(args))
@@ -1467,6 +1592,35 @@ async def _resolve_then_run(args: ParsedArgs) -> int:
        # agent_id (remote wins on conflict, since a server-listed agent
        # is the authoritative source).
        chosen_agent_id: str | None = args.agent_id
        # slice b2: bare TUI mode (no --session, no --new) → startup session
        # picker (design-brief §4). Resolve into a concrete session_id BEFORE
        # the new/resume branches. Resume-only: bare + 0 sessions is an error
        # (creating a session is the --new flag's job).
        resolved_session_id: str | None = args.session_id
        if not args.new and args.session_id is None:
            try:
                page = await list_sessions(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 page.items:
                sys.stderr.write(
                    "[no_sessions] no sessions to resume; "
                    "launch with --new --agent <id>\n"
                )
                return 14
            if len(page.items) == 1:
                # §4: picker only when >1 — a single session auto-resumes.
                resolved_session_id = page.items[0].session_id
            else:
                resolved_session_id = await SessionPickerApp(page.items).run_async()
                if resolved_session_id is None:
                    return 0  # Esc / Ctrl-D — clean exit, no session opened
        if args.new and args.agent_id is None:
            try:
                agents = await list_agents(client)
@@ -1551,8 +1705,8 @@ async def _resolve_then_run(args: ParsedArgs) -> int:
            session_id = info.session_id
            agent_id: str | None = info.agent_id
        else:
-            assert args.session_id is not None
+            assert resolved_session_id is not None
-            session_id = args.session_id
+            session_id = resolved_session_id
            agent_id = args.agent_id  # may be None — INV-002 carve-out preserved
        app = RatatoskrApp(args, session_id=session_id, agent_id=agent_id, client=client)
        exit_code = await app.run_async()
@@ -50,7 +50,7 @@ from ratatoskr.sse_client import (
    SseConnectionDropped,
    TurnIdFlip,
    cancel_turn,
-    stream_turn,
+    stream_turn_resilient,
 )
@@ -291,7 +291,7 @@ async def _stream_turn_endpoint(request: Request) -> StreamingResponse:
        try:
            handle.status = "streaming"
            try:
-                async for event in stream_turn(client, session_id, handle.content):
+                async for event in stream_turn_resilient(client, session_id, handle.content):
                    # v0.16.0: capture the upstream (Worldtree-assigned)
                    # turn_id from the first event so cancel paths target
                    # the real upstream turn, not our local counter.
@@ -175,10 +175,29 @@ class TestParseArgs:
            )
    def test_usage_neither_session_nor_new(self) -> None:
-        """usage_neither_session_nor_new: neither flag → UsageError('pass exactly one')."""
+        """usage_neither_session_nor_new: --send with neither flag → UsageError.
-        with pytest.raises(UsageError, match="pass exactly one"):
+
        --send is non-interactive (no picker can open), so a session must be
        named. Bare TUI mode (no --send) is now valid → session picker (§4).
        """
        with pytest.raises(UsageError, match="--send requires"):
            _parse_args(["--send", "hi", "--api-key", "k"])
    def test_bare_tui_mode_accepted(self) -> None:
        """bare_tui_mode (slice b2): no --send, no --session, no --new → valid;
        _resolve_then_run drives the startup session picker (design-brief §4)."""
        args = _parse_args(["--api-key", "k"])
        assert args.send_content is None
        assert args.session_id is None
        assert args.new is False
        assert args.agent_id is None
    def test_usage_bare_tui_with_agent(self) -> None:
        """bare_tui_with_agent (slice b2): bare TUI + --agent → UsageError
        (--agent belongs with --new; bare mode opens the resume picker)."""
        with pytest.raises(UsageError, match="belongs with --new"):
            _parse_args(["--agent", "mimir", "--api-key", "k"])
    def test_usage_send_new_without_agent(self) -> None:
        """send_new_without_agent (issue #8): --send --new without --agent → UsageError.
@@ -1319,10 +1338,15 @@ class TestMain:
        rc = main(["--send", "hi", "--new", "--agent", "m", "--api-key", "k"])
        assert rc == 0
-    def test_usage_error_no_send(
+    def test_empty_argv_fails_on_auth(
        self, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
    ) -> None:
-        """usage_error_no_send: empty argv → exit 10; stderr [usage_error]; _amain never called."""
+        """empty argv → exit 11 [auth_error]; _amain never called.
        Since slice b2 bare TUI mode (no --send/--session/--new) is VALID (it
        opens the session picker), so empty argv is no longer a usage error —
        it now fails on the missing API key instead (still before _amain).
        """
        amain_calls: list[int] = []
        async def fake_amain(args: ParsedArgs) -> int:
@@ -1331,8 +1355,8 @@ class TestMain:
        monkeypatch.setattr(cli_mod, "_amain", fake_amain)
        rc = main([])
-        assert rc == 10
+        assert rc == 11
-        assert "[usage_error]" in capsys.readouterr().err
+        assert "[auth_error]" in capsys.readouterr().err
        assert amain_calls == []
    def test_usage_error_both_session_and_new(
@@ -1540,3 +1564,72 @@ class TestBifrostBindCli:
        )
        rc = await _amain(args)
        assert rc == 22
 class TestWhoami:
    """--whoami one-shot probe (slice: capabilities+me): GET /me + GET /capabilities."""
    def test_whoami_standalone_accepted(self) -> None:
        """whoami_standalone_accepted: --whoami alone → valid; whoami=True, no turn flags."""
        args = _parse_args(["--whoami", "--api-key", "k"])
        assert args.whoami is True
        assert args.send_content is None
        assert args.session_id is None
        assert args.new is False
    def test_whoami_with_send_rejected(self) -> None:
        """whoami_with_send_rejected [adversarial]: --whoami + --send → UsageError."""
        with pytest.raises(UsageError, match="standalone probe"):
            _parse_args(["--whoami", "--send", "hi", "--api-key", "k"])
    def test_whoami_with_new_rejected(self) -> None:
        """whoami_with_new_rejected [adversarial]: --whoami + --new → UsageError."""
        with pytest.raises(UsageError, match="standalone probe"):
            _parse_args(["--whoami", "--new", "--agent", "m", "--api-key", "k"])
    @respx.mock
    def test_whoami_mode_prints_report(self, capsys: pytest.CaptureFixture[str]) -> None:
        """whoami_mode_prints_report [happy,tracer]: /me + /capabilities → stdout report; exit 0."""
        respx.get("https://w.example/me").mock(
            return_value=httpx.Response(
                200,
                json={
                    "user_id": "alice",
                    "scopes": ["conversations.read", "conversations.write"],
                    "tier": "user",
                    "key_id": "a1b2c3d4",
                },
            )
        )
        respx.get("https://w.example/capabilities").mock(
            return_value=httpx.Response(
                200,
                json={
                    "ephemeral_templates": {
                        "echo": {
                            "allowed_models": ["glm5-turbo"],
                            "default_model": "glm5-turbo",
                            "system_prompt_max_bytes": 32768,
                        }
                    }
                },
            )
        )
        rc = main(["--whoami", "--api-key", "k", "--server", "https://w.example"])
        assert rc == 0
        out = capsys.readouterr().out
        assert "user_id: alice" in out
        assert "tier: user" in out
        assert "key_id: a1b2c3d4" in out
        assert "ephemeral_template echo" in out
        assert "glm5-turbo" in out
    @respx.mock
    def test_whoami_me_auth_failure_exits_20(self, capsys: pytest.CaptureFixture[str]) -> None:
        """whoami_me_auth_failure [error]: /me 401 → exit 20 [session_api_failed]."""
        respx.get("https://w.example/me").mock(
            return_value=httpx.Response(401, json={"detail": "auth_invalid"})
        )
        rc = main(["--whoami", "--api-key", "k", "--server", "https://w.example"])
        assert rc == 20
        assert "[session_api_failed]" in capsys.readouterr().err
@@ -18,6 +18,8 @@ from ratatoskr.sessions import (
    SessionPage,
    create_session,
    endpoint_for_plane,
    get_capabilities,
    get_me,
    get_persona_state,
    list_agents,
    list_sessions,
@@ -896,3 +898,96 @@ class TestGetPersonaState:
            with pytest.raises(PersonaNotConfigured) as exc_info:
                await get_persona_state(client, "domari")
        assert exc_info.value.agent_id == "domari"
 class TestGetMe:
    """docs/contracts/issues/2.contract.md FN get_me (slice: capabilities+me)."""
    @respx.mock
    async def test_happy_authenticated(self) -> None:
        """happy_authenticated [happy,tracer]: 200 → parsed identity dict verbatim."""
        respx.get("https://w.example/me").mock(
            return_value=httpx.Response(
                200,
                json={
                    "user_id": "alice",
                    "scopes": ["conversations.read", "conversations.write"],
                    "tier": "user",
                    "key_id": "a1b2c3d4",
                    "key_label": "alice phone",
                },
            )
        )
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            me = await get_me(client)
        assert me["user_id"] == "alice"
        assert me["tier"] == "user"
        assert me["key_id"] == "a1b2c3d4"
        assert me["scopes"] == ["conversations.read", "conversations.write"]
    @respx.mock
    async def test_anonymous_dev_mode(self) -> None:
        """anonymous_dev_mode: 200 anonymous shape → dict with tier=anonymous."""
        respx.get("https://w.example/me").mock(
            return_value=httpx.Response(
                200,
                json={
                    "user_id": "anonymous",
                    "scopes": ["conversations.read"],
                    "tier": "anonymous",
                },
            )
        )
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            me = await get_me(client)
        assert me["tier"] == "anonymous"
        assert "key_id" not in me  # optional fields omitted, not null
    @respx.mock
    async def test_401_raises_session_api_failed(self) -> None:
        """401_raises [error]: bad/absent key → SessionApiFailed(status=401)."""
        respx.get("https://w.example/me").mock(
            return_value=httpx.Response(401, json={"detail": "auth_invalid"})
        )
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            with pytest.raises(SessionApiFailed) as exc:
                await get_me(client)
        assert exc.value.status == 401
 class TestGetCapabilities:
    """docs/contracts/issues/2.contract.md FN get_capabilities (slice: capabilities+me)."""
    @respx.mock
    async def test_happy(self) -> None:
        """happy [happy]: 200 → ephemeral_templates dict verbatim."""
        respx.get("https://w.example/capabilities").mock(
            return_value=httpx.Response(
                200,
                json={
                    "ephemeral_templates": {
                        "echo": {
                            "allowed_models": ["glm5-turbo", "glm4.7"],
                            "default_model": "glm5-turbo",
                            "system_prompt_max_bytes": 32768,
                        }
                    }
                },
            )
        )
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            caps = await get_capabilities(client)
        echo = caps["ephemeral_templates"]["echo"]
        assert echo["default_model"] == "glm5-turbo"
        assert echo["system_prompt_max_bytes"] == 32768
    @respx.mock
    async def test_non_200_raises(self) -> None:
        """non_200_raises [error]: 500 → SessionApiFailed(status=500)."""
        respx.get("https://w.example/capabilities").mock(
            return_value=httpx.Response(500, content=b"boom")
        )
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            with pytest.raises(SessionApiFailed) as exc:
                await get_capabilities(client)
        assert exc.value.status == 500
@@ -19,6 +19,7 @@ from ratatoskr.sse_client import (
    ResumeBufferExpired,
    ResumeTurnFinished,
    SseConnectFailed,
    SseConnectionDropped,
    SseId,
    Text,
    TurnIdFlip,
@@ -27,6 +28,7 @@ from ratatoskr.sse_client import (
    cancel_turn,
    reconnect_turn,
    stream_turn,
    stream_turn_resilient,
 )
 _DONE_42_6 = {
@@ -51,6 +53,36 @@ def _sse_chunk(sse_id: str, body: dict[str, object]) -> bytes:
    return f"id: {sse_id}\ndata: {json.dumps(body)}\n\n".encode()
 _EVENT_STREAM = {"content-type": "text/event-stream"}
 class _DropStream(httpx.AsyncByteStream):
    """Yield the given chunks, then raise a mid-stream drop (RemoteProtocolError).
    Mirrors the inline `_DropAfter` used by TestStreamTurn.test_connection_drop;
    hoisted to module scope because the resilient-wrapper tests reuse it.
    """
    def __init__(self, chunks: list[bytes]) -> None:
        self._chunks = chunks
    async def __aiter__(self):  # type: ignore[no-untyped-def]
        for c in self._chunks:
            yield c
        raise httpx.RemoteProtocolError("simulated mid-stream drop")
    async def aclose(self) -> None:
        return None
 def _drop_response(chunks: list[bytes]) -> httpx.Response:
    return httpx.Response(200, headers=_EVENT_STREAM, stream=_DropStream(chunks))
 def _stream_response(content: bytes) -> httpx.Response:
    return httpx.Response(200, headers=_EVENT_STREAM, content=content)
 class TestParseSseId:
    def test_happy_simple(self) -> None:
        """happy_simple [happy,tracer]: '42:3' -> SseId(turn_id=42, seq=3)."""
@@ -1108,3 +1140,124 @@ class TestAwaitingLlmFirstToken:
        elapsed = [b.elapsed_ms_since_building_prompt for b in beats]
        assert elapsed == sorted(elapsed)  # monotonically increasing
        assert all(b.turn_id == 42 for b in beats)
 _URL = "https://w.example/sessions/s1/messages"
 class TestStreamTurnResilient:
    """docs/contracts/issues/1.contract.md FN stream_turn_resilient (amendment 2026-06-30)."""
    @respx.mock
    async def test_happy_no_drop(self) -> None:
        """happy_no_drop [happy]: clean stream passes through; no reconnect issued."""
        stream = _sse_chunk("42:1", {"type": "text", "content": "a"}) + _sse_chunk(
            "42:2", _DONE_42_6
        )
        route = respx.post(_URL).mock(return_value=_stream_response(stream))
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            events = [e async for e in stream_turn_resilient(client, "s1", "hi")]
        assert [e.sse_id for e in events] == [SseId(42, 1), SseId(42, 2)]
        assert isinstance(events[-1], Done)
        assert route.call_count == 1  # POST-001: no reconnect on a clean stream
    @respx.mock
    async def test_resume_after_one_drop(self) -> None:
        """resume_after_one_drop [tracer]: a mid-stream drop resumes via reconnect; one stream."""
        first = _drop_response([_sse_chunk("42:1", {"type": "text", "content": "a"})])
        resume = _stream_response(
            _sse_chunk("42:2", {"type": "text", "content": "b"})
            + _sse_chunk("42:3", _DONE_42_6)
        )
        route = respx.post(_URL).mock(side_effect=[first, resume])
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            events = [e async for e in stream_turn_resilient(client, "s1", "hi")]
        assert [e.sse_id for e in events] == [SseId(42, 1), SseId(42, 2), SseId(42, 3)]
        assert isinstance(events[-1], Done)
        assert route.call_count == 2
        # POST-003: reconnect carries the last yielded pre-drop event's id.
        assert route.calls[1].request.headers.get("Last-Event-ID") == "42:1"
        # PRE/wire: first attempt does NOT carry a Last-Event-ID.
        assert route.calls[0].request.headers.get("Last-Event-ID") is None
    @respx.mock
    async def test_resume_after_clean_eof(self) -> None:
        """resume_after_clean_eof: a clean EOF before terminal also triggers resume (INV-001)."""
        first = _stream_response(_sse_chunk("42:1", {"type": "text", "content": "a"}))
        resume = _stream_response(_sse_chunk("42:2", _DONE_42_6))
        route = respx.post(_URL).mock(side_effect=[first, resume])
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            events = [e async for e in stream_turn_resilient(client, "s1", "hi")]
        assert [e.sse_id for e in events] == [SseId(42, 1), SseId(42, 2)]
        assert isinstance(events[-1], Done)
        assert route.calls[1].request.headers.get("Last-Event-ID") == "42:1"
    @respx.mock
    async def test_two_drops_then_done(self) -> None:
        """two_drops_then_done: two transient drops, third attempt completes; ids thread through."""
        a1 = _drop_response([_sse_chunk("42:1", {"type": "text", "content": "a"})])
        a2 = _drop_response([_sse_chunk("42:2", {"type": "text", "content": "b"})])
        a3 = _stream_response(_sse_chunk("42:3", _DONE_42_6))
        route = respx.post(_URL).mock(side_effect=[a1, a2, a3])
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            events = [e async for e in stream_turn_resilient(client, "s1", "hi")]
        assert [e.sse_id for e in events] == [SseId(42, 1), SseId(42, 2), SseId(42, 3)]
        assert route.call_count == 3
        assert route.calls[1].request.headers.get("Last-Event-ID") == "42:1"
        assert route.calls[2].request.headers.get("Last-Event-ID") == "42:2"
    @respx.mock
    async def test_unresumable_zero_event_drop(self) -> None:
        """unresumable_zero_event_drop [adversarial]: drop before any event → propagate."""
        route = respx.post(_URL).mock(side_effect=[_drop_response([])])
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            with pytest.raises(SseConnectionDropped):
                _ = [e async for e in stream_turn_resilient(client, "s1", "hi")]
        assert route.call_count == 1  # no id to resume from → no reconnect
    @respx.mock
    async def test_max_reconnects_exhausted(self) -> None:
        """max_reconnects_exhausted [adversarial]: every attempt drops; budget caps reconnects."""
        side = [
            _drop_response([_sse_chunk(f"42:{n}", {"type": "text", "content": "x"})])
            for n in (1, 2, 3)
        ]
        route = respx.post(_URL).mock(side_effect=side)
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            with pytest.raises(SseConnectionDropped):
                _ = [
                    e
                    async for e in stream_turn_resilient(
                        client, "s1", "hi", max_reconnects=2
                    )
                ]
        assert route.call_count == 3  # initial + 2 reconnects, then give up
    @respx.mock
    async def test_zero_budget_no_resume(self) -> None:
        """zero_budget_no_resume [adversarial]: max_reconnects=0 → first drop propagates."""
        first = _drop_response([_sse_chunk("42:1", {"type": "text", "content": "a"})])
        route = respx.post(_URL).mock(side_effect=[first])
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            with pytest.raises(SseConnectionDropped):
                _ = [
                    e
                    async for e in stream_turn_resilient(
                        client, "s1", "hi", max_reconnects=0
                    )
                ]
        assert route.call_count == 1
    @respx.mock
    async def test_buffer_expired_propagates(self) -> None:
        """buffer_expired_propagates [error]: a 412 on reconnect surfaces, not retried."""
        first = _drop_response([_sse_chunk("42:1", {"type": "text", "content": "a"})])
        resume = httpx.Response(412, json={"turn_id": 42, "buffered_from_seq": 7})
        route = respx.post(_URL).mock(side_effect=[first, resume])
        async with httpx.AsyncClient(base_url="https://w.example") as client:
            collected: list[object] = []
            with pytest.raises(ResumeBufferExpired):
                async for e in stream_turn_resilient(client, "s1", "hi"):
                    collected.append(e)
        assert [e.sse_id for e in collected] == [SseId(42, 1)]  # type: ignore[attr-defined]
        assert route.call_count == 2
@@ -2945,3 +2945,225 @@ class TestTuiBifrostBind:
        err = capsys.readouterr().err
        assert "bifrost: status=bound" in err
        assert "plane=memory" in err
 class TestSessionPickerApp:
    """docs/contracts/issues/6.contract.md FN SessionPickerApp (amendment slice b2)."""
    @staticmethod
    def _two():
        from ratatoskr.sessions import SessionInfo
        return [
            SessionInfo(
                session_id="s-first-0001", agent_id="mimir", created_at="t0",
                last_active="t1", metadata={}, message_count=3, name=None,
                archived=False, tags=[],
            ),
            SessionInfo(
                session_id="s-second-002", agent_id="echo", created_at="t0",
                last_active="t2", metadata={}, message_count=None, name="probe",
                archived=False, tags=[],
            ),
        ]
    def test_pick_returns_session_id(self) -> None:
        """pick_returns_session_id [happy,tracer]: idx 1 + Enter → exit value == that session_id."""
        from ratatoskr.tui import SessionPickerApp
        app = SessionPickerApp(self._two())
        async def drive() -> str | None:
            async with app.run_test() as pilot:
                from textual.widgets import ListView
                lv = app.query_one("#session-list", ListView)
                lv.index = 1
                await pilot.pause()
                await pilot.press("enter")
                await pilot.pause()
            return app.return_value
        import asyncio
        assert asyncio.run(drive()) == "s-second-002"
    def test_esc_returns_none(self) -> None:
        """esc_returns_none [happy]: Esc → exit value is None (dismiss, resume nothing)."""
        from ratatoskr.tui import SessionPickerApp
        app = SessionPickerApp(self._two())
        async def drive() -> str | None:
            async with app.run_test() as pilot:
                await pilot.press("escape")
                await pilot.pause()
            return app.return_value
        import asyncio
        assert asyncio.run(drive()) is None
    def test_ctrl_d_returns_none(self) -> None:
        """ctrl_d_returns_none [adversarial]: Ctrl-D → None."""
        from ratatoskr.tui import SessionPickerApp
        app = SessionPickerApp(self._two())
        async def drive() -> str | None:
            async with app.run_test() as pilot:
                await pilot.press("ctrl+d")
                await pilot.pause()
            return app.return_value
        import asyncio
        assert asyncio.run(drive()) is None
 class TestBareSessionPicker:
    """docs/contracts/issues/6.contract.md amendment (slice b2): _resolve_then_run bare mode."""
    @staticmethod
    def _bare_args() -> ParsedArgs:
        return ParsedArgs(
            send_content=None, session_id=None, new=False, agent_id=None,
            api_key="k", server_url="https://w.example", raw=False,
            end_user_id=None, bifrost=None, bifrost_plane=None, consumer_key=None,
        )
    @staticmethod
    def _sess(sid: str, agent: str = "mimir"):
        from ratatoskr.sessions import SessionInfo
        return SessionInfo(
            session_id=sid, agent_id=agent, created_at="t0", last_active="t1",
            metadata={}, message_count=1, name=None, archived=False, tags=[],
        )
    def test_bare_zero_sessions_errors(
        self, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
    ) -> None:
        """bare_zero_sessions_errors [error]: 0 sessions → exit 14 [no_sessions]; App not opened."""
        import ratatoskr.tui as tui_mod
        from ratatoskr.sessions import SessionPage
        async def fake_list(client, **kw):
            return SessionPage(items=[], next_cursor=None)
        monkeypatch.setattr(tui_mod, "list_sessions", fake_list)
        opened: list[int] = []
        async def spy(self, *a, **k):
            opened.append(1)
            return 0
        monkeypatch.setattr(RatatoskrApp, "run_async", spy)
        rc = run_tui(self._bare_args())
        assert rc == 14
        assert "[no_sessions]" in capsys.readouterr().err
        assert not opened
    def test_bare_one_session_auto_resumes(self, monkeypatch: pytest.MonkeyPatch) -> None:
        """bare_one_session_auto_resumes: exactly 1 → auto-resume, no picker (§4 >1 rule)."""
        import ratatoskr.tui as tui_mod
        from ratatoskr.sessions import SessionPage
        from ratatoskr.tui import SessionPickerApp
        async def fake_list(client, **kw):
            return SessionPage(items=[self._sess("s-solo")], next_cursor=None)
        monkeypatch.setattr(tui_mod, "list_sessions", fake_list)
        picker_used: list[int] = []
        async def spy_picker(self, *a, **k):
            picker_used.append(1)
            return None
        monkeypatch.setattr(SessionPickerApp, "run_async", spy_picker)
        snap: dict = {}
        async def cap(self, *a, **k):
            snap["sid"] = self.session_id
            return 0
        monkeypatch.setattr(RatatoskrApp, "run_async", cap)
        rc = run_tui(self._bare_args())
        assert rc == 0
        assert snap["sid"] == "s-solo"
        assert not picker_used
    def test_bare_multi_opens_picker(self, monkeypatch: pytest.MonkeyPatch) -> None:
        """bare_multi_opens_picker [scenario,tracer]: >1 → picker; its choice resumes."""
        import ratatoskr.tui as tui_mod
        from ratatoskr.sessions import SessionPage
        from ratatoskr.tui import SessionPickerApp
        async def fake_list(client, **kw):
            return SessionPage(items=[self._sess("s-a"), self._sess("s-b")], next_cursor=None)
        monkeypatch.setattr(tui_mod, "list_sessions", fake_list)
        async def pick_b(self, *a, **k):
            return "s-b"
        monkeypatch.setattr(SessionPickerApp, "run_async", pick_b)
        snap: dict = {}
        async def cap(self, *a, **k):
            snap["sid"] = self.session_id
            return 0
        monkeypatch.setattr(RatatoskrApp, "run_async", cap)
        rc = run_tui(self._bare_args())
        assert rc == 0
        assert snap["sid"] == "s-b"
    def test_bare_picker_dismiss_exits_zero(self, monkeypatch: pytest.MonkeyPatch) -> None:
        """bare_picker_dismiss_exits_zero [scenario]: picker None → exit 0; App not opened."""
        import ratatoskr.tui as tui_mod
        from ratatoskr.sessions import SessionPage
        from ratatoskr.tui import SessionPickerApp
        async def fake_list(client, **kw):
            return SessionPage(items=[self._sess("s-a"), self._sess("s-b")], next_cursor=None)
        monkeypatch.setattr(tui_mod, "list_sessions", fake_list)
        async def pick_none(self, *a, **k):
            return None
        monkeypatch.setattr(SessionPickerApp, "run_async", pick_none)
        opened: list[int] = []
        async def spy(self, *a, **k):
            opened.append(1)
            return 0
        monkeypatch.setattr(RatatoskrApp, "run_async", spy)
        rc = run_tui(self._bare_args())
        assert rc == 0
        assert not opened
    def test_bare_list_sessions_api_failure(
        self, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
    ) -> None:
        """bare_list_sessions_api_failure [error]: list_sessions 500 → exit 20; App not opened."""
        import ratatoskr.tui as tui_mod
        from ratatoskr.sessions import SessionApiFailed
        async def fake_list(client, **kw):
            raise SessionApiFailed(status=500, body=b"boom")
        monkeypatch.setattr(tui_mod, "list_sessions", fake_list)
        opened: list[int] = []
        async def spy(self, *a, **k):
            opened.append(1)
            return 0
        monkeypatch.setattr(RatatoskrApp, "run_async", spy)
        rc = run_tui(self._bare_args())
        assert rc == 20
        assert "[session_api_failed]" in capsys.readouterr().err
        assert not opened
@@ -1052,7 +1052,7 @@ wheels = [
 [[package]]
 name = "ratatoskr"
-version = "0.18.4"
+version = "0.18.8"
 source = { editable = "." }
 dependencies = [
    { name = "httpx" },
Author	SHA1	Message	Date
vh	387ac4ab2c	feat(#2 ): consume GET /me + GET /capabilities via --whoami one-shot v1 coverage-audit slice (capabilities+me). Both endpoints had no caller; add them as cheap boot-time debug primitives. - sessions.py: get_me (GET /me — identity/whoami) + get_capabilities (GET /capabilities — Echo ephemeral-template discovery). Mirror get_persona_state: 200 -> parsed dict verbatim, non-200 -> SessionApiFailed. Freeform dicts (frozen OpenAPI types both as objects). - cli.py: new --whoami one-shot mode (mirrors --send). Fetches both, prints an identity + capabilities report, exits. Standalone probe: mutually exclusive with --send/--session/--new/--agent; opens no session. New ParsedArgs.whoami field + main() dispatch. - Contract #2 amended (2 FNs) + validated. TDD: 5 wrapper tests + 5 cli tests (validation + mode + error). Coverage map: REST 9/40. Suite 538 green; touched code ruff-clean. Audit note: /capabilities is the Echo ephemeral-template discovery endpoint, not a generic server-caps endpoint (coverage-map framing corrected). TUI-surfacing of /me + /capabilities deferred.	2026-06-30 22:21:59 -07:00
vh	5c1b9816d4	feat(#6 ): startup session picker for bare TUI mode v1 coverage-audit slice b2. The audit found list_sessions had no caller — the startup session picker (design-brief §4) was never built; bare TUI mode was a hard usage error. Add SessionPickerApp (mirrors AgentPickerApp) and resolve bare mode in _resolve_then_run. - Bare TUI mode (no --session/--new) now valid → session picker. Resolution: 0 sessions -> [no_sessions] exit 14 (resume-only per §4 "no in-app creation, --new only"); exactly 1 -> auto-resume (§4 "picker only when >1"); >=2 -> SessionPickerApp -> resume pick (Esc/Ctrl-D -> exit 0). - cli._parse: bare TUI valid; --send still requires one flag; --agent forbidden in bare mode. run_tui PRE-002 xor -> mutually-exclusive. - Contract #6 amended (SessionPickerApp + bare-mode resolution) + validated. TDD: 3 picker pilot tests + 5 resolution tests + 3 cli validation tests. Suite 528 green; touched code ruff-clean. Design note: bare + 0 sessions errors (honors §4's no-in-app-creation clause); the friendlier auto-fall-through-to-new is deferred pending operator preference.	2026-06-30 22:05:14 -07:00
vh	2ba4244e9e	feat(#1 ): route TUI + web presenters through stream_turn_resilient Complete b1's design-brief §8b promise ("all presenters share the consumer"): the TUI and web SSE consumers now resume transparently on a mid-stream drop, same as cli --send (v0.18.5). The TUI is the primary beneficiary — long-lived dev sessions across laptop suspend. Name-for-name swap of stream_turn -> stream_turn_resilient at the two remaining consumer loops (tui.py:1321, web/server.py:294) + their imports. No behavioral change on the happy path (resilient == stream when there is no drop); suite 518 green; touched lines ruff+mypy clean (pre-existing tui/web lint debt left untouched per surgical rule).	2026-06-30 15:46:04 -07:00
vh	0c7660791f	feat(#1 ): shared SSE resume orchestration; wire cli --send v1 coverage-audit slice b1. The audit found reconnect_turn had no caller — every presenter dropped the stream on disconnect instead of resuming, leaving the "reference SSE-resume implementation" (design- brief §3/§8d) unreachable. Add stream_turn_resilient as the single shared resume surface (design-brief §8b "share the consumer, branch the presenter") and route cli --send through it. - stream_turn_resilient wraps stream_turn + reconnect_turn: on SseConnectionDropped (mid-stream drop or clean EOF before terminal), resume from the last-seen sse_id via reconnect_turn (Last-Event-ID), up to max_reconnects (default 5). last_seen persists across attempts. - Non-drop reconnect failures (412/410/400/TurnIdFlip/SseConnectFailed) propagate unchanged, per contract #1's "surface, not recover". - cli.py: --send consumer now drives stream_turn_resilient (transparent reconnect). tui/web still consume bare stream_turn (follow-up). - Contract #1 amended (FN stream_turn_resilient) + validated; 8 TDD cases (happy, resume-after-1/2-drops, clean-EOF resume, unresumable zero-event, max-reconnects-exhausted, zero-budget, buffer-expired- propagates). Suite 518 green; ruff + mypy clean on touched code.	2026-06-30 15:42:33 -07:00
vh	1f289098ba	memory: scope (b) Tier-1 frontier — SSE-resume + session-picker slices Capture the contract-first plan for the two presenter-wiring gaps (resume-orchestration wrapper per design-brief 8b; picker + CLI flags per 4) so the next focused TDD cycle has the slice plan resident.	2026-06-30 15:32:15 -07:00
vh	b798068932	pin: re-pin to Worldtree's FROZEN v1 surface (OpenAPI 2.2.0 + SSE schema) v1 coverage-audit remediation P-1: vendor the authoritative machine- readable artifacts and pin them for drift-checking, advancing the spec pin from v0.35.16 (f1b59f8) to v1.0.0b2 (5810a26). - Vendor docs/conversation-api-openapi.json (OpenAPI 2.2.0, 40 path- groups) + docs/conversation-api-sse-events.schema.json (11 events). - Pin all three Conversation-API artifacts in .corviduo-canonicals.toml: OpenAPI + SSE schema as strict drift gates (canonical_drift.py), the prose markdown as tolerate_drift reference. Drift check green (10/10). - pyproject: worldtree-spec-rev -> 5810a26, worldtree-version -> v1.0.0b2 (was stale at v0.29.0), pinned-on -> 2026-06-30. - SPEC-PIN.md: current-pin table + history row + vendored-artifacts list. - coverage-map.md: P-1 marked remediated; the map now audits a frozen, diffable target. The prose markdown is byte-identical to v0.35.16 (last WT edit 2026-05-31); the b2 surface lives only in the OpenAPI. No client- facing code change (the b2 409/503 + unified error envelope were already consumed in v0.18.3/.4) -> pin-only, no version bump.	2026-06-30 15:28:52 -07:00
vh	93e4176346	docs: author v1 coverage-map ledger; lock scope mandate A First coverage map — every Worldtree v1-FROZEN I/O point x ratatoskr status. Anchored on WT's frozen machine-readable artifacts (OpenAPI 2.2.0 = 40 REST path-groups + SSE schema = 11 events + bifrost wire v0.6), not the stale vendored prose markdown. - SSE 11/11 and Bifrost provider planes 8/8 covered + live-proven; client REST 7/40 live, 11 in-scope frontier, 22 excluded-by-design. - Scope mandate A (operator): v1 done = every frozen point classified (covered-or-excluded-with-rationale), zero unaccounted; not a feature-complete client. - Finding P-1: vendored prose markdown is byte-identical to live WT but frozen at v0.35.16-era content; b2's surface lives in the OpenAPI 2.2.0 + SSE-schema JSON we don't vendor. Pin-remediation pending operator nod. No version bump (docs-only).	2026-06-30 14:41:06 -07:00
vh	a358cc9150	memory: snapshot — b1→b2 409/503 adaptation + bifrost 1.0.0 + combined-bind default + admin key + regard-dead-axis finding Worldtree on v1.0.0b2 (both demo + personal); ratatoskr v0.18.4 all pushed. Session arc: web combined-bind default (v0.18.1), bifrost 1.0.0 repin (v0.18.2), b1/b2 eager 409/503 status mapping (v0.18.3/.4), readonly-admin key collected (#11 prereq cleared), and the regard-dead-axis finding (provider-side catch -> worldtree-dev escalating to Vuong). Next substantive effort = the v1 coverage-audit (folds in the deferred live-409 + b2 spec re-vendor).	2026-06-30 13:57:04 -07:00