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

Panel (Gróa+Hulda+Regin, 5/5/5, no false positives) confirmed two 3/3 crash
sites where open-world dict reads violate the declared "degrade, never crash the
presenter" invariant — the wt adapter tests + the live smoke used full server
dicts, so partial/drifted wire responses were never exercised:

- FIX (tier3.py _run_define/_run_patch): the CLI hard-indexed the open-world
  define/patch dicts (`info["agent_id"]` / `["role"]` / `["agent_name"]`), so a
  partial 2xx → KeyError escaping main()'s exit matrix as a raw traceback (exit 1);
  and `make_description(info.get("system_prompt", ""))` fed None to .splitlines()
  on a present-but-null field → AttributeError. Now reads via `_str_field` (absent/
  null/non-str → default), degrades role to '?', indexes only a well-formed identity,
  and maps a no-usable-agent_id 2xx to [api_failed] exit 20 (controlled, not a crash).
- FIX (web/server.py _agents_endpoint): the upstream dedup hard-indexed each item
  (`{a["agent_id"] for a in upstream}` + `_as_dict`), so a malformed item (`[{}]`,
  `["str"]`, `{"name":…}`, non-str agent_id) or a non-list envelope → 500 before the
  local fallback merged. Now filters to well-formed mappings first; a non-list
  upstream degrades to the local-only list.
- FIX (wt.py _error_field_from_body): type-check the parsed `field` is a str (the
  exception surface is `field: str | None`, the CLI prints it) — restores the retired
  hand-rolled `_extract_error_field` isinstance guard.

Held (triaged, no change): the 429→Tier3QuotaExceeded / bare-404→Tier3AgentNotFound
maps are ungated-by-error_code BY CONTRACT DESIGN (§ Error map route+status rows; the
SDK's ApiError floor drops Retry-After, so retry_after=0 is canonical) — the arms
flagged them spec-free; Heid's source-check confirmed intended. Dual-keying define's
429 for full row consistency is an available tightening (contract amendment), surfaced
not applied. The persona-endpoint SessionApiFailed gap the arms also caught was
already closed in the prior code-review fixup (aed9429).

Suite 475 green (+5).

docs/contracts/worldtree_sdk_cutover.contract.md

@@ -239,6 +239,13 @@ re-anchor its coverage-map rows.
   (respx `httpx.ConnectError` side-effect) is the RED that proves this.
 - **`agents.get(agent_id)`** (SDK `GET /agents/{id}`) is NOT wrapped — ratatoskr has no
   `get_agent` consumer; only list/persona_state/define/patch/delete are in coverage.
+- **Client-side Tier-3-id PRE on `patch_agent` / `delete_agent`.** Both assert
+  `":" in agent_id` pre-HTTP (a Tier-3 id is always `<user_id>:<agent_name>`, ADR-0019),
+  so a non-colon id fails fast with an `AssertionError` rather than reaching the SDK's
+  route-discriminated 404 → `Tier3AgentNotFound`. Intentional fail-fast on a
+  wrong-shaped id (carried over from the retired hand-rolled wrappers); documented here
+  per the heid-code-review slice-4 precision flag (the § Error map 404 rows assume a
+  well-formed Tier-3 id reaches the route).
 
 ## Out of scope
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ratatoskr"
-version = "0.21.13"
+version = "0.21.15"
 description = "Worldtree Conversation API debug console (web + headless CLI) — multi-pane observability"
 readme = "README.md"
 requires-python = ">=3.12"

src/ratatoskr/tier3.py

@@ -17,6 +17,9 @@ mappings. ``wt`` imports this module's exceptions at module level; this module i
 from __future__ import annotations
 
 import argparse
+import sys
+from collections.abc import Mapping
+from typing import Any
 
 import httpx
 
@@ -31,6 +34,15 @@ from ratatoskr.sessions import (
     Tier3UserIdUnsupported,
 )
 
+
+def _str_field(info: Mapping[str, Any], key: str, *, default: str = "") -> str:
+    """A string field off an open-world response dict, or `default` when the key is
+    absent / null / non-string — so a partial or drifted 2xx define/patch response
+    degrades rather than KeyError/AttributeError-crashing the CLI presenter (the
+    "open-world reads degrade, never crash the presenter" invariant; heid-bug-hunt)."""
+    value = info.get(key)
+    return value if isinstance(value, str) else default
+
 # ---- CLI (`python -m ratatoskr.tier3 <subcommand>`) ------------------------
 #
 # Auth + server URL resolution mirrors ratatoskr.cli verbatim. Exit codes
@@ -122,18 +134,27 @@ async def _run_define(ns: argparse.Namespace) -> int:
             system_prompt=ns.system_prompt,
             role=ns.role,
         )
-        # v0.8.0: persist to local index so the picker can show it. The SDK returns
-        # the open-world define dict — read `role` (echoed post-b128), not `model`.
-        add_local_agent(
-            LocalAgentEntry(
-                agent_id=info["agent_id"],
-                agent_name=info["agent_name"],
-                role=info["role"],
-                description=make_description(info.get("system_prompt", "")),
-                defined_at=info.get("created_at", ""),
+        # Open-world define dict — read defensively (echoes `role` post-b128, not
+        # `model`). A partial/drifted 2xx must not crash the presenter.
+        agent_id = _str_field(info, "agent_id")
+        if not agent_id:  # a 2xx with no usable agent_id is a malformed success
+            sys.stderr.write(f"[api_failed] define returned no usable agent_id: {info!r}\n")
+            return 20
+        role = _str_field(info, "role", default="?")
+        agent_name = _str_field(info, "agent_name")
+        # v0.8.0: persist to local index so the picker can show it — only for a
+        # well-formed identity (agent_id + agent_name); else skip the write, still print.
+        if agent_name:
+            add_local_agent(
+                LocalAgentEntry(
+                    agent_id=agent_id,
+                    agent_name=agent_name,
+                    role=role,
+                    description=make_description(_str_field(info, "system_prompt")),
+                    defined_at=_str_field(info, "created_at"),
+                )
             )
-        )
-        print(f"defined {info['agent_id']} ({info['role']})")
+        print(f"defined {agent_id} ({role})")
         return 0
 
 
@@ -158,17 +179,24 @@ async def _run_patch(ns: argparse.Namespace) -> int:
             system_prompt=ns.system_prompt,
             role=ns.role,
         )
-        # v0.8.0: refresh local index with the post-patch state.
-        update_local_agent(
-            LocalAgentEntry(
-                agent_id=info["agent_id"],
-                agent_name=info["agent_name"],
-                role=info["role"],
-                description=make_description(info.get("system_prompt", "")),
-                defined_at=info.get("updated_at", ""),
+        # Open-world patch dict — read defensively (same degrade-not-crash posture).
+        agent_id = _str_field(info, "agent_id")
+        if not agent_id:  # a 2xx with no usable agent_id is a malformed success
+            sys.stderr.write(f"[api_failed] patch returned no usable agent_id: {info!r}\n")
+            return 20
+        agent_name = _str_field(info, "agent_name")
+        # v0.8.0: refresh local index with the post-patch state (well-formed identity only).
+        if agent_name:
+            update_local_agent(
+                LocalAgentEntry(
+                    agent_id=agent_id,
+                    agent_name=agent_name,
+                    role=_str_field(info, "role", default="?"),
+                    description=make_description(_str_field(info, "system_prompt")),
+                    defined_at=_str_field(info, "updated_at"),
+                )
             )
-        )
-        print(f"patched {info['agent_id']}")
+        print(f"patched {agent_id}")
         return 0
 
 

src/ratatoskr/web/server.py

@@ -141,11 +141,18 @@ async def _agents_endpoint(request: Request) -> JSONResponse:
             {"error_code": "network_error", "message": str(exc)},
             status_code=502,
         )
-    # Open-world upstream dicts (parity: no AgentInfo normalization); read `agent_id`
-    # as a mapping key. Local tier3 entries dedup against the upstream ids (remote-wins).
-    upstream_ids = {a["agent_id"] for a in upstream}
+    # Open-world upstream (parity: no AgentInfo normalization). Degrade, never crash:
+    # a non-list envelope OR a malformed item (missing/non-str agent_id, non-mapping)
+    # is dropped rather than KeyError/TypeError'ing the endpoint into a 500 before the
+    # local fallback merges (heid-bug-hunt: the "open-world reads degrade" invariant).
+    upstream_items = upstream if isinstance(upstream, list) else []
+    well_formed = [
+        a for a in upstream_items
+        if isinstance(a, Mapping) and isinstance(a.get("agent_id"), str)
+    ]
+    upstream_ids = {a["agent_id"] for a in well_formed}
     local = _local_agents.load_local_agents()
-    merged = [_as_dict(a) for a in upstream] + [
+    merged = [_as_dict(a) for a in well_formed] + [
         _as_dict(le) for le in local if le.agent_id not in upstream_ids
     ]
     return JSONResponse(merged, status_code=200)
@@ -448,6 +455,15 @@ async def _persona_state_endpoint(request: Request) -> JSONResponse:
         return JSONResponse({"error_code": "agent_not_available"}, status_code=404)
     except AuthScopeDenied:
         return JSONResponse({"error_code": "auth_scope_denied"}, status_code=403)
+    except wt.SessionApiFailed as exc:
+        # An unmatched upstream ApiError (a 500, or a coded-but-unmapped 4xx) →
+        # controlled envelope, for parity with _agents_endpoint / create / admin
+        # (heid-code-review slice-4: the persona endpoint was the lone sibling that
+        # let it escape as a raw 500 — a latent pre-cutover gap, closed here).
+        return JSONResponse(
+            {"error_code": "session_api_failed", "status": exc.status},
+            status_code=exc.status,
+        )
     except (httpx.RequestError, ConnectFailed) as exc:
         # SDK normalizes a transport failure to ConnectFailed(status=0) (slice-3
         # foot-gun); surface the network envelope rather than a 500 crash.

src/ratatoskr/wt.py

@@ -464,7 +464,10 @@ def _error_field_from_body(body: str | None) -> str | None:
     field = err.get("field")
     if field is None and isinstance(err.get("detail"), dict):
         field = err["detail"].get("field")
-    return field
+    # The exception surface declares `field: str | None` (and the CLI prints it), so a
+    # non-string envelope value (`{"field": {…}}` / `{"field": 1}`) collapses to None —
+    # same guard the retired hand-rolled `_extract_error_field` applied (heid-bug-hunt).
+    return field if isinstance(field, str) else None
 
 
 async def list_agents(client: WorldtreeClient) -> Sequence[Mapping[str, Any]]:

tests/test_tier3.py

@@ -235,3 +235,52 @@ class TestCli:
         err = capsys.readouterr().err
         assert rc == 10
         assert "[usage_error]" in err
+
+    @respx.mock
+    def test_cli_define_partial_response_degrades(
+        self,
+        capsys: pytest.CaptureFixture[str],
+        monkeypatch: pytest.MonkeyPatch,
+        _isolated_local_agents: "Path",
+    ) -> None:
+        """cli_define_partial [error]: a 201 missing `role` + a NULL system_prompt
+        degrades (role '?', description-safe) and exits 0 — never a KeyError/
+        AttributeError traceback (heid-bug-hunt open-world invariant)."""
+        from ratatoskr.local_agents import load_local_agents
+
+        monkeypatch.setenv("WORLDTREE_API_URL", "https://w.example")
+        monkeypatch.setenv("WORLDTREE_API_KEY", "k")
+        respx.post("https://w.example/agents/define").mock(
+            return_value=httpx.Response(201, json={
+                "agent_id": "ratatoskr:wizard", "agent_name": "wizard",
+                "system_prompt": None,  # present-but-null: .get(...,'') would NOT default
+            })
+        )
+        rc = main([
+            "define", "--name", "wizard", "--system-prompt", "x", "--role", "m",
+        ])
+        out = capsys.readouterr()
+        assert rc == 0
+        assert out.out.strip() == "defined ratatoskr:wizard (?)"
+        # Well-formed identity → still indexed (role degraded to '?').
+        entries = load_local_agents()
+        assert len(entries) == 1
+        assert entries[0].role == "?"
+
+    @respx.mock
+    def test_cli_define_no_agent_id_is_api_failure(
+        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """cli_define_no_agent_id [error]: a 2xx with no usable agent_id → [api_failed]
+        + exit 20 (controlled), not an uncaught traceback."""
+        monkeypatch.setenv("WORLDTREE_API_URL", "https://w.example")
+        monkeypatch.setenv("WORLDTREE_API_KEY", "k")
+        respx.post("https://w.example/agents/define").mock(
+            return_value=httpx.Response(201, json={"role": "m"})  # no agent_id
+        )
+        rc = main([
+            "define", "--name", "wizard", "--system-prompt", "x", "--role", "m",
+        ])
+        err = capsys.readouterr().err
+        assert rc == 20
+        assert "[api_failed]" in err

tests/test_web_server.py

@@ -132,6 +132,57 @@ class TestAgentsEndpoint:
         # Upstream entry wins (it's first in the merge); local is deduped
         assert body[0]["name"] == "Sindra-from-server"
 
+    @respx.mock
+    def test_malformed_upstream_items_degrade_not_500(self, monkeypatch, tmp_path) -> None:
+        """malformed_upstream [error]: a non-mapping / agent_id-less upstream item is
+        dropped, not crashed on — the endpoint degrades to the well-formed + local
+        merge (heid-bug-hunt: open-world reads degrade, never crash)."""
+        monkeypatch.setenv("RATATOSKR_LOCAL_AGENTS", str(tmp_path / "local_agents.json"))
+        respx.get("https://w.example/agents").mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {"agent_id": "mimir", "name": "Mimir", "description": "k"},
+                    {},                       # no agent_id — dropped
+                    {"name": "Ghost"},        # no agent_id — dropped
+                    "not-a-mapping",          # non-mapping — dropped
+                    {"agent_id": 123},        # non-str agent_id — dropped
+                ],
+            )
+        )
+        from ratatoskr.local_agents import LocalAgentEntry, add_local_agent
+        add_local_agent(LocalAgentEntry(
+            agent_id="ratatoskr:local", agent_name="local", role="m",
+            description="d", defined_at="t",
+        ))
+        from ratatoskr.web.server import create_app
+        app = create_app(_mock_client_factory())
+        resp = TestClient(app).get("/api/agents")
+        assert resp.status_code == 200
+        ids = {a["agent_id"] for a in resp.json()}
+        # Only the one well-formed upstream item + the local entry survive.
+        assert ids == {"mimir", "ratatoskr:local"}
+
+    @respx.mock
+    def test_non_list_upstream_falls_back_to_local(self, monkeypatch, tmp_path) -> None:
+        """non_list_upstream [error]: an envelope (non-list) upstream body degrades to
+        the local-only list rather than iterating dict keys into a crash."""
+        monkeypatch.setenv("RATATOSKR_LOCAL_AGENTS", str(tmp_path / "local_agents.json"))
+        respx.get("https://w.example/agents").mock(
+            return_value=httpx.Response(200, json={"items": [{"agent_id": "mimir"}]})
+        )
+        from ratatoskr.local_agents import LocalAgentEntry, add_local_agent
+        add_local_agent(LocalAgentEntry(
+            agent_id="ratatoskr:local", agent_name="local", role="m",
+            description="d", defined_at="t",
+        ))
+        from ratatoskr.web.server import create_app
+        app = create_app(_mock_client_factory())
+        resp = TestClient(app).get("/api/agents")
+        assert resp.status_code == 200
+        ids = {a["agent_id"] for a in resp.json()}
+        assert ids == {"ratatoskr:local"}
+
 
 _CREATE_OK = {
     "session_id": "s-1",
@@ -290,6 +341,20 @@ class TestPersonaStateEndpoint:
         assert resp.status_code == 403
         assert resp.json()["error_code"] == "auth_scope_denied"
 
+    @respx.mock
+    def test_unmatched_error_maps_to_session_api_failed(self) -> None:
+        """unmatched_error [error]: an upstream 500 (unmapped ApiError) → the
+        session_api_failed envelope carrying the upstream status, for parity with
+        _agents_endpoint (heid-code-review slice-4 fixup — was a raw 500 escape)."""
+        respx.get("https://w.example/agents/mimir/persona_state").mock(
+            return_value=httpx.Response(500, content=b"upstream out")
+        )
+        from ratatoskr.web.server import create_app
+        app = create_app(_mock_client_factory())
+        resp = TestClient(app).get("/api/agents/mimir/persona_state")
+        assert resp.status_code == 500
+        assert resp.json()["error_code"] == "session_api_failed"
+
 
 class TestSubmitTurnEndpoint:
     """submit_turn_endpoint FN — allocate turn_id, register in turn_registry."""

tests/test_wt.py

@@ -695,6 +695,41 @@ class TestDefineAgent:
             await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
         assert ei.value.field == "persona"
 
+    async def test_layer_deferred_flat_field_body(self) -> None:
+        # _error_field_from_body also handles a flat top-level `field` (both-shape
+        # unwrap) — locks the contract's "detail.field / flat field" claim.
+        fake = _FakeAgents(error=ApiError(
+            "layer_deferred", "no", status=422, body='{"field": "valence"}',
+        ))
+        with pytest.raises(Tier3LayerDeferred) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.field == "valence"
+
+    async def test_layer_deferred_non_string_field_is_none(self) -> None:
+        # A non-string `field` value collapses to None — the exception surface is
+        # `field: str | None` and the CLI prints it (heid-bug-hunt hardening).
+        fake = _FakeAgents(error=ApiError(
+            "layer_deferred", "no", status=422, body='{"detail": {"field": {"x": 1}}}',
+        ))
+        with pytest.raises(Tier3LayerDeferred) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.field is None
+
+    async def test_403_wrong_code_maps_to_default(self) -> None:
+        # Dual-key negative: a 403 whose code is NOT tier3_user_id_unsupported →
+        # generic default, not a spurious Tier3UserIdUnsupported (INV-CUT-2).
+        fake = _FakeAgents(error=ApiError("auth_revoked", "no", status=403))
+        with pytest.raises(SessionApiFailed) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.status == 403
+
+    async def test_422_wrong_code_maps_to_default(self) -> None:
+        # Dual-key negative: a 422 whose code is NOT layer_deferred → default.
+        fake = _FakeAgents(error=ApiError("validation_failed", "no", status=422))
+        with pytest.raises(SessionApiFailed) as ei:
+            await define_agent(_wta(fake), agent_name="wizard", system_prompt="x", role="m")
+        assert ei.value.status == 422
+
     async def test_bad_slug_asserts_no_call(self) -> None:
         fake = _FakeAgents(result={})
         with pytest.raises(AssertionError):
@@ -761,6 +796,14 @@ class TestPatchAgent:
             await patch_agent(_wta(fake), "ratatoskr:wizard", system_prompt="x")
         assert ei.value.field == "agent_name"
 
+    async def test_422_wrong_code_maps_to_default(self) -> None:
+        # Dual-key negative: a 422 whose code is NOT field_not_mutable → default,
+        # not a spurious Tier3FieldNotMutable (INV-CUT-2).
+        fake = _FakeAgents(error=ApiError("validation_failed", "no", status=422))
+        with pytest.raises(SessionApiFailed) as ei:
+            await patch_agent(_wta(fake), "ratatoskr:wizard", system_prompt="x")
+        assert ei.value.status == 422
+
     async def test_no_fields_asserts_no_call(self) -> None:
         fake = _FakeAgents(result={})
         with pytest.raises(AssertionError):

uv.lock

@@ -472,7 +472,7 @@ wheels = [
 
 [[package]]
 name = "ratatoskr"
-version = "0.21.13"
+version = "0.21.15"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },