switchroom 0.19.28 → 0.19.30

package/vendor/hindsight-memory/scripts/lib/config.py

@@ -172,6 +172,15 @@ DEFAULTS = {
     "retainContext": "claude-code",
     "retainTags": [],
     "retainMetadata": {},
+    # Switchroom-local: per-row Hindsight `observation_scopes` on every retain.
+    # `"shared"` makes consolidation write this item's observations into ONE
+    # global untagged scope instead of a scope per tag — what a set of agents
+    # pooling one bank needs. `None` (the default) omits the field from the
+    # wire body entirely, leaving the engine's own default in force. Set by
+    # start.sh from `agents.<name>.memory.observation_scopes` (cascading
+    # through `defaults.memory.observation_scopes`) via
+    # HINDSIGHT_OBSERVATION_SCOPES, exported ONLY when the operator opted in.
+    "observationScopes": None,
     # Switchroom hindsight-leverage E2 / PR9 (#398) — lesson & anti-pattern
     # tagging at retain time. When on (default), build_retain_payload scans the
     # formatted transcript slice for explicit lesson / anti-pattern markers and
@@ -319,6 +328,11 @@ ENV_OVERRIDES = {
     "HINDSIGHT_AUTO_RECALL": ("autoRecall", bool),
     "HINDSIGHT_AUTO_RETAIN": ("autoRetain", bool),
     "HINDSIGHT_RETAIN_MODE": ("retainMode", str),
+    # Switchroom-local: per-row observation scope on retains. Set by start.sh
+    # from agents.<name>.memory.observation_scopes (cascading through
+    # defaults.memory.observation_scopes) ONLY when the operator set it; unset
+    # leaves `observationScopes` None and the field off the wire entirely.
+    "HINDSIGHT_OBSERVATION_SCOPES": ("observationScopes", str),
     # Switchroom hindsight-leverage E2 / PR9 (#398) — lesson/anti-pattern tagging
     # + recall demotion toggles and overrides.
     "HINDSIGHT_LESSON_TAGGING": ("lessonTagging", bool),
@@ -422,6 +436,83 @@ ENV_OVERRIDES = {
 }
 
 
+#: Switchroom-local: the `observation_scopes` values Hindsight accepts as a
+#: bare string (`MemoryItem.observation_scopes`, typed
+#: `Literal["per_tag","combined","all_combinations","shared"] | list[list[str]]
+#: | None` server-side). The explicit list-of-lists tag matrix is deliberately
+#: NOT exposed through switchroom config: unbounded, no safe fleet-wide
+#: default, no caller needs it. Paired with `OBSERVATION_SCOPES` in
+#: src/memory/observation-scopes.ts, which the zod enum reads — widening the
+#: set means widening BOTH.
+OBSERVATION_SCOPES_VALUES = ("per_tag", "combined", "all_combinations", "shared")
+
+
+def classify_observation_scopes(config: dict):
+    """Classify ``observationScopes`` WITHOUT raising: ``(value, error)``.
+
+    Exactly one of the two is non-``None``:
+
+    * ``(None, None)``   — unset. Do not put the field on the wire at all;
+      the shipped default, byte-for-byte the pre-plumbing request body.
+    * ``(value, None)``  — a valid member of :data:`OBSERVATION_SCOPES_VALUES`.
+    * ``(None, reason)`` — an off-list or non-string value, with a
+      human-readable reason naming the accepted set.
+
+    THIS FUNCTION MUST NEVER RAISE, and callers on the retain path must never
+    turn its ``error`` into one. A bad scope is a misconfiguration; losing the
+    turn is data loss. Those are not the same severity and must not share a
+    failure mode — see ``retain.build_retain_payload`` for the consequence
+    chain (a raise there propagated out of ``run_retain`` and past
+    ``retain.main``'s ``pending_enqueue``, so the turn was never queued,
+    the watermark never advanced, and the boot reconciler swallowed the same
+    raise into ``debug_log`` — the memory was gone, permanently and silently).
+    That is switchroom #3244's shape, which this very feature cites.
+
+    An empty/whitespace-only value is treated as UNSET, matching the plugin's
+    existing "an empty export hands authority back to the config file" idiom
+    (see ``_cast_env``): an absent knob, not a typo'd one.
+    """
+    raw = config.get("observationScopes")
+    if raw is None:
+        return None, None
+    if not isinstance(raw, str):
+        return None, (
+            "observationScopes must be a string, one of "
+            f"{', '.join(OBSERVATION_SCOPES_VALUES)}; got {type(raw).__name__} ({raw!r}). "
+            "Set it via `memory.observation_scopes` in switchroom.yaml."
+        )
+    value = raw.strip()
+    if not value:
+        return None, None
+    if value not in OBSERVATION_SCOPES_VALUES:
+        return None, (
+            f"observationScopes={raw!r} is not a valid Hindsight observation scope. "
+            f"Accepted values: {', '.join(OBSERVATION_SCOPES_VALUES)}. "
+            "Set it via `memory.observation_scopes` in switchroom.yaml "
+            "(a typo there is rejected at `switchroom apply`)."
+        )
+    return value, None
+
+
+def resolve_observation_scopes(config: dict):
+    """Strict form of :func:`classify_observation_scopes` — raises on a bad value.
+
+    ``None`` means "do not put the field on the wire at all".
+
+    Raises ``ValueError`` on any value outside
+    :data:`OBSERVATION_SCOPES_VALUES`. This is the VALIDATOR, for callers that
+    genuinely want to fail — a config check, a test, a hand-run script that
+    should stop before it writes anything. **It is deliberately NOT what the
+    retain path calls**: a retain must never be destroyed by a config typo, so
+    ``retain.build_retain_payload`` uses the non-raising classifier and shouts
+    instead. See ``classify_observation_scopes``.
+    """
+    value, error = classify_observation_scopes(config)
+    if error:
+        raise ValueError(error)
+    return value
+
+
 def _cast_env(value: str, typ):
     """Cast environment variable string to target type. Returns None on failure."""
     try:

package/vendor/hindsight-memory/scripts/lib/pending.py

@@ -41,12 +41,18 @@ Each entry is a JSON file ``<unix-ms>-<short-uuid>.json`` containing::
       "context":     "<retainContext>",
       "metadata":    {...},
       "tags":        [...] or null,
+      "observation_scopes": "<scope>" or null,
       "failed_at":   "<ISO-8601 UTC>",
       "error_class": "<exception class name>",
       "error_message": "<str(e)>",
       "attempt_count": 1
     }
 
+``observation_scopes`` is ABSENT from every entry queued by a build that
+predates it, and those entries are on disk right now. Readers must use
+``entry.get("observation_scopes")``, never ``entry[...]`` — a KeyError in
+``drain_pending._retry_one`` would strand the last on-disk copy of a turn.
+
 The file is written via ``write tmp + rename`` so concurrent agents
 sharing ``$HOME`` (legacy installs) never observe a half-written entry.
 

package/vendor/hindsight-memory/scripts/reconcile_tail.py

@@ -312,6 +312,7 @@ def _post_inline(
                 tags=payload["tags"],
                 timeout=15,
                 async_processing=False,
+                observation_scopes=payload.get("observation_scopes"),
             )
         except Exception as e:
             debug_log(config, f"reconcile_tail: inline POST failed, enqueuing: {e}")

package/vendor/hindsight-memory/scripts/retain.py

@@ -28,7 +28,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from lib import watermark
 from lib.bank import derive_bank_id, ensure_bank_mission
 from lib.client import HindsightClient
-from lib.config import debug_log, load_config
+from lib.config import classify_observation_scopes, debug_log, load_config
 from lib.content import (
     prepare_retention_transcript,
     slice_last_turns_by_user_boundary,
@@ -266,6 +266,14 @@ def build_retain_payload(
 
     Returns ``{payload, document_id, message_count, last_uuid, ordered_uuids,
     transcript}`` or ``None`` when the slice formats to nothing.
+
+    NEVER raises on a bad ``observationScopes``. Every retain producer builds
+    its payload here, so this seam sees the typo — but it is also the seam the
+    memory itself is made at, and a config typo must not be able to destroy
+    one. An off-list value is dropped from the payload (so the engine's own
+    default stands, exactly as before this feature existed) and shouted about
+    on stderr; the memory is still built, still POSTed, still queued on
+    failure. See ``lib.config.classify_observation_scopes``.
     """
     retain_roles = config.get("retainRoles", ["user", "assistant"])
     include_tool_calls = config.get("retainToolCalls", True)
@@ -359,6 +367,36 @@ def build_retain_payload(
     except Exception:
         pass
 
+    # Per-row observation scope (switchroom). None unless the operator set
+    # memory.observation_scopes — and a None is dropped at the wire by
+    # HindsightClient._retain_one, so the default request body is unchanged.
+    # Carried ON THE PAYLOAD so it survives the pending-retains queue: a retain
+    # that fails and drains hours later must land in the SAME scope it would
+    # have landed in inline.
+    #
+    # CLASSIFIED, NOT VALIDATED. This is the one seam every retain producer
+    # funnels through, which makes it the tempting place to reject a typo — and
+    # the worst possible place to raise from. Raising here does not "fail the
+    # retain", it DELETES the turn: the exception propagates out of run_retain,
+    # past retain.main's pending_enqueue (so nothing is queued and the
+    # watermark never advances), session_end.py catches it with no payload to
+    # queue, and session_start.py's reconciler swallows it into debug_log and
+    # aborts the loop that would have re-derived it. Every producer loses its
+    # memory outright, silently, for as long as the bad value sits in the
+    # config — switchroom #3244's exact shape.
+    #
+    # So a bad value degrades to the PRE-FEATURE behaviour (field omitted, the
+    # engine's own default scope stands) and is shouted about on stderr. Wrong
+    # scope is recoverable; a lost turn is not.
+    scope, scope_error = classify_observation_scopes(config)
+    if scope_error:
+        print(
+            f"[Hindsight] observation_scopes IGNORED for this retain: {scope_error} "
+            "The memory is being retained at the engine's default scope rather "
+            "than dropped — fix the value, then `switchroom apply` and restart "
+            "the agent.",
+            file=sys.stderr,
+        )
     payload = {
         "api_url": api_url,
         "api_token": api_token,
@@ -368,6 +406,7 @@ def build_retain_payload(
         "context": config.get("retainContext", "claude-code"),
         "metadata": metadata,
         "tags": tags,
+        "observation_scopes": scope,
     }
     return {
         "payload": payload,
@@ -573,6 +612,7 @@ def run_retain(hook_input: dict, force: bool = False) -> dict:
                 tags=payload["tags"],
                 timeout=15,
                 async_processing=False,
+                observation_scopes=payload.get("observation_scopes"),
             )
         except Exception as e:
             print(f"[Hindsight] Retain failed: {e}", file=sys.stderr)

package/vendor/hindsight-memory/scripts/subagent_retain.py

@@ -443,6 +443,7 @@ def run_subagent_retain(hook_input: dict) -> dict:
                 tags=payload["tags"],
                 timeout=15,
                 async_processing=False,
+                observation_scopes=payload.get("observation_scopes"),
             )
         except Exception as e:
             print(f"[Hindsight] Sidechain retain failed: {e}", file=sys.stderr)

package/vendor/hindsight-memory/scripts/tests/test_backfill.py

@@ -35,6 +35,8 @@ class FakeDaemon:
 
     def __init__(self):
         self.docs = {}                 # document_id -> {content, ...}
+        # switchroom: the observation_scopes kwarg each POST carried.
+        self.observation_scopes_seen = []
         self.posts = []                # [(document_id, async_processing)]
         self.mission_patches = []      # set_bank_mission calls (must stay empty)
         self.fail = False
@@ -42,7 +44,9 @@ class FakeDaemon:
         self._inflight = 0
 
     def retain(self, bank_id, content, document_id="conversation", context=None,
-               metadata=None, tags=None, timeout=15, async_processing=True):
+               metadata=None, tags=None, timeout=15, async_processing=True,
+               observation_scopes=None):
+        self.observation_scopes_seen.append(observation_scopes)
         self._inflight += 1
         self.max_inflight_seen = max(self.max_inflight_seen, self._inflight)
         try:
@@ -167,6 +171,24 @@ class TestBackfill(BackfillTestBase):
         self.assertTrue(self.daemon.posts)
         self.assertTrue(all(async_flag is False for _, async_flag in self.daemon.posts))
 
+    # -- switchroom: per-row observation scope on the backfill path ---------
+    def test_backfill_omits_the_scope_when_unconfigured(self):
+        self._transcript("clerk", "sess-plain", 4)
+        bf.Backfill(self._config(), commit=True, delay_ms=0).run()
+        self.assertTrue(self.daemon.observation_scopes_seen)
+        self.assertTrue(all(s is None for s in self.daemon.observation_scopes_seen))
+
+    def test_backfill_posts_the_configured_scope(self):
+        # The backfill enumerates its own retain kwargs; a miss here would
+        # scatter every recovered historical slice into per-tag scopes while
+        # live retains pooled into the shared one.
+        os.environ["HINDSIGHT_OBSERVATION_SCOPES"] = "shared"
+        self.addCleanup(os.environ.pop, "HINDSIGHT_OBSERVATION_SCOPES", None)
+        self._transcript("clerk", "sess-scoped", 4)
+        bf.Backfill(self._config(), commit=True, delay_ms=0).run()
+        self.assertTrue(self.daemon.observation_scopes_seen)
+        self.assertTrue(all(s == "shared" for s in self.daemon.observation_scopes_seen))
+
     # -- Dedups against a pre-existing document with the same deterministic id
     def test_dedups_against_preexisting_document_id(self):
         path = self._transcript("clerk", "sess-dup", 3)

package/vendor/hindsight-memory/scripts/tests/test_backfill_from_logs.py

@@ -53,12 +53,16 @@ class FakeDaemon:
     def __init__(self):
         self.docs = {}
         self.posts = []
+        # switchroom: the observation_scopes kwarg each POST carried.
+        self.observation_scopes_seen = []
         self.max_inflight_seen = 0
         self._inflight = 0
         self.membership_error = False
 
     def retain(self, bank_id, content, document_id="conversation", context=None,
-               metadata=None, tags=None, timeout=15, async_processing=True):
+               metadata=None, tags=None, timeout=15, async_processing=True,
+               observation_scopes=None):
+        self.observation_scopes_seen.append(observation_scopes)
         self._inflight += 1
         self.max_inflight_seen = max(self.max_inflight_seen, self._inflight)
         try:

package/vendor/hindsight-memory/scripts/tests/test_observation_scopes.py

@@ -0,0 +1,325 @@
+"""Switchroom — per-row ``observation_scopes`` plumbing on the retain path.
+
+Hindsight stores an ``observation_scopes`` field per retained row.
+``"shared"`` makes consolidation write that item's observations into ONE
+global untagged scope instead of a scope per tag. The plugin could not send
+the field at all before this change, so a bank could never be pooled.
+
+The load-bearing properties, each asserted as an OUTCOME on the wire body or
+on the kwargs a callsite hands ``client.retain()``:
+
+1. **Unset is byte-identical to before.** With no config the key is ABSENT
+   from the POST body — not present-and-null — so the engine default stands.
+2. **Set reaches the wire**, on every part of a split retain.
+3. **It survives the pending queue.** The scope is carried on the payload,
+   so a retain that fails now and drains hours later lands in the same scope
+   it would have landed in inline.
+4. **Old queue entries still drain.** Entries written by a pre-feature build
+   are on disk right now and carry no such key; the drain must read them
+   with ``.get`` and post ``None``, never raise.
+
+Stdlib-only; runs under ``python3 -m unittest discover tests/``.
+"""
+
+import contextlib
+import io
+import json
+import os
+import sys
+import unittest
+from unittest import mock
+
+SCRIPTS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, SCRIPTS_DIR)
+
+import drain_pending  # noqa: E402
+import retain  # noqa: E402
+from lib.client import HindsightClient  # noqa: E402
+from lib.config import (  # noqa: E402
+    OBSERVATION_SCOPES_VALUES,
+    load_config,
+    resolve_observation_scopes,
+)
+from lib.retain_split import retain_content_limit  # noqa: E402
+
+
+class _RecordingClient(HindsightClient):
+    """Captures the request bodies instead of putting them on a socket."""
+
+    def __init__(self, *a, **kw):
+        super().__init__(*a, **kw)
+        self.bodies = []
+
+    def _request(self, method, path, body=None, timeout=30):
+        self.bodies.append(body)
+        return {"ok": True}
+
+
+def _transcript(n_turns: int) -> list:
+    out = []
+    for i in range(n_turns):
+        out.append({"role": "user", "content": f"user turn {i}", "uuid": f"u{i}"})
+        out.append({"role": "assistant", "content": f"assistant turn {i}", "uuid": f"a{i}"})
+    return out
+
+
+class WireBody(unittest.TestCase):
+    """What actually goes on the wire."""
+
+    def setUp(self):
+        self.client = _RecordingClient("http://hindsight.invalid")
+
+    def test_unset_omits_the_key_entirely(self):
+        self.client.retain("bank", "some transcript", document_id="doc")
+        item = self.client.bodies[0]["items"][0]
+        # Not `is None` — ABSENT. A null would be a value the engine has to
+        # interpret; the pre-feature body simply had no such key.
+        self.assertNotIn("observation_scopes", item)
+
+    def test_explicit_none_omits_the_key_entirely(self):
+        # The default config value is None and every callsite forwards it, so
+        # the None path is the one the whole fleet takes.
+        self.client.retain(
+            "bank", "some transcript", document_id="doc", observation_scopes=None
+        )
+        self.assertNotIn("observation_scopes", self.client.bodies[0]["items"][0])
+
+    def test_unset_body_is_identical_to_a_pre_feature_body(self):
+        self.client.retain(
+            "bank", "t", document_id="doc", context="claude-code",
+            metadata={"m": "1"}, tags=["x"],
+        )
+        self.assertEqual(
+            self.client.bodies[0],
+            {
+                "items": [{
+                    "content": "t",
+                    "document_id": "doc",
+                    "metadata": {"m": "1"},
+                    "context": "claude-code",
+                    "tags": ["x"],
+                }],
+                "async": True,
+            },
+        )
+
+    def test_set_value_reaches_the_item(self):
+        self.client.retain(
+            "bank", "some transcript", document_id="doc", observation_scopes="shared"
+        )
+        self.assertEqual(
+            self.client.bodies[0]["items"][0]["observation_scopes"], "shared"
+        )
+
+    def test_every_part_of_a_split_retain_carries_it(self):
+        # A split that lands parts in DIFFERENT scopes would silently shard one
+        # memory across scopes — the exact drift this pins.
+        big = "z" * (retain_content_limit() * 3)
+        self.client.retain("bank", big, document_id="doc", observation_scopes="shared")
+        self.assertGreater(len(self.client.bodies), 1)
+        for body in self.client.bodies:
+            self.assertEqual(body["items"][0]["observation_scopes"], "shared")
+
+
+class ConfigResolution(unittest.TestCase):
+    """``observationScopes`` default + the HINDSIGHT_OBSERVATION_SCOPES env."""
+
+    def test_default_is_none(self):
+        with mock.patch.dict(os.environ, {}, clear=True):
+            self.assertIsNone(load_config().get("observationScopes"))
+
+    def test_env_override_sets_it(self):
+        with mock.patch.dict(os.environ, {"HINDSIGHT_OBSERVATION_SCOPES": "shared"},
+                             clear=True):
+            self.assertEqual(load_config().get("observationScopes"), "shared")
+
+
+class PayloadBuild(unittest.TestCase):
+    """``build_retain_payload`` is the single producer for every retain path."""
+
+    _BASE = {"retainRoles": ["user", "assistant"], "retainContext": "claude-code"}
+
+    def _build(self, config_extra):
+        config = dict(self._BASE, **config_extra)
+        return retain.build_retain_payload(
+            config, "sess", _transcript(2), _transcript(2),
+            bank_id="bank", api_url="http://fake", api_token=None,
+        )["payload"]
+
+    def test_payload_carries_none_when_unconfigured(self):
+        self.assertIsNone(self._build({})["observation_scopes"])
+
+    def test_payload_carries_the_configured_scope(self):
+        self.assertEqual(
+            self._build({"observationScopes": "shared"})["observation_scopes"],
+            "shared",
+        )
+
+
+class DrainOfQueuedEntries(unittest.TestCase):
+    """``drain_pending._retry_one`` — the durability path, over MIXED entries."""
+
+    def setUp(self):
+        self.calls = []
+        outer = self
+
+        class _Client:
+            def __init__(self, *a, **kw):
+                pass
+
+            def retain(self, **kwargs):
+                outer.calls.append(kwargs)
+                return {"ok": True}
+
+        self.patch = mock.patch.object(drain_pending, "HindsightClient", _Client)
+        self.patch.start()
+        self.addCleanup(self.patch.stop)
+
+    _LEGACY = {
+        "api_url": "http://fake",
+        "api_token": None,
+        "bank_id": "bank",
+        "document_id": "doc",
+        "content": "old transcript",
+        "context": "claude-code",
+        "metadata": {},
+        "tags": None,
+    }
+
+    def test_entry_written_before_the_feature_drains_with_none(self):
+        # These entries are on disk RIGHT NOW. A KeyError here would strand the
+        # last on-disk copy of a turn, which is the #3244 silent-loss shape.
+        drain_pending._retry_one(dict(self._LEGACY), timeout=15)
+        self.assertEqual(self.calls[0]["content"], "old transcript")
+        self.assertIsNone(self.calls[0]["observation_scopes"])
+
+    def test_entry_carrying_a_scope_drains_into_that_scope(self):
+        entry = dict(self._LEGACY, observation_scopes="shared")
+        drain_pending._retry_one(entry, timeout=15)
+        self.assertEqual(self.calls[0]["observation_scopes"], "shared")
+
+    def test_scope_survives_a_json_round_trip_through_the_queue_file(self):
+        # The queue is JSON on disk; the scope must come back out of it.
+        entry = json.loads(json.dumps(dict(self._LEGACY, observation_scopes="shared")))
+        drain_pending._retry_one(entry, timeout=15)
+        self.assertEqual(self.calls[0]["observation_scopes"], "shared")
+
+
+class ValueValidation(unittest.TestCase):
+    """An off-list scope must not reach the wire — and must not cost a memory.
+
+    The value is invisible after the write: a typo would keep retaining
+    happily, the engine would apply its own default scope, and the damage
+    (a bank whose observations never merged) surfaces only much later. The
+    `memory.observation_scopes` zod enum is the primary gate, but it cannot
+    see a hand-edited settings.json or a raw HINDSIGHT_OBSERVATION_SCOPES
+    export — which is why this second gate exists here.
+
+    TWO different obligations, and they are not the same severity:
+
+    * `resolve_observation_scopes` is the strict VALIDATOR and RAISES. Callers
+      that can safely stop (a config check, a hand-run script) use it.
+    * the retain path uses the non-raising classifier, drops the bad field and
+      shouts. A misconfigured scope is recoverable; a deleted turn is not, and
+      raising at the build seam deleted turns — see
+      `test_a_typo_never_reaches_the_payload_BUT_the_memory_survives`.
+    """
+
+    _BASE = {"retainRoles": ["user", "assistant"], "retainContext": "claude-code"}
+
+    def _build(self, config_extra):
+        config = dict(self._BASE, **config_extra)
+        return retain.build_retain_payload(
+            config, "sess", _transcript(2), _transcript(2),
+            bank_id="bank", api_url="http://fake", api_token=None,
+        )["payload"]
+
+    def test_every_accepted_value_resolves_to_itself(self):
+        for value in OBSERVATION_SCOPES_VALUES:
+            with self.subTest(value=value):
+                self.assertEqual(
+                    resolve_observation_scopes({"observationScopes": value}), value
+                )
+
+    def test_unset_and_empty_resolve_to_none(self):
+        # Empty is UNSET, not a typo — matches the plugin's "an empty export
+        # hands authority back to the config file" idiom.
+        self.assertIsNone(resolve_observation_scopes({}))
+        self.assertIsNone(resolve_observation_scopes({"observationScopes": None}))
+        self.assertIsNone(resolve_observation_scopes({"observationScopes": ""}))
+        self.assertIsNone(resolve_observation_scopes({"observationScopes": "   "}))
+
+    def test_typo_raises_and_names_the_accepted_set(self):
+        with self.assertRaises(ValueError) as ctx:
+            resolve_observation_scopes({"observationScopes": "shred"})
+        msg = str(ctx.exception)
+        self.assertIn("shred", msg)
+        for value in OBSERVATION_SCOPES_VALUES:
+            self.assertIn(value, msg)
+
+    def test_wrong_case_raises(self):
+        with self.assertRaises(ValueError):
+            resolve_observation_scopes({"observationScopes": "Shared"})
+
+    def test_non_string_raises(self):
+        with self.assertRaises(ValueError):
+            resolve_observation_scopes({"observationScopes": ["shared"]})
+
+    def test_a_typo_never_reaches_the_payload_BUT_the_memory_survives(self):
+        # Two outcomes, and the second is the load-bearing one.
+        #
+        # (a) The bad value does not ride to the wire — `observation_scopes` is
+        #     None, so `HindsightClient._retain_one` omits the key and the
+        #     engine's own default scope stands. That is the pre-feature
+        #     behaviour, and it is a *recoverable* misconfiguration.
+        #
+        # (b) The PAYLOAD IS STILL BUILT. `build_retain_payload` raising here
+        #     was a far worse bug than the one it fixed: the raise unwound past
+        #     `retain.main`'s `pending_enqueue`, so the turn was never POSTed,
+        #     never queued and never re-derivable — permanent silent memory
+        #     loss for as long as the typo sat in the config. A config typo
+        #     must never be able to delete a memory. End-to-end coverage of
+        #     the same guarantee lives in
+        #     tests/test_reconcile_durability.py::TestObservationScopes.
+        payload = self._build({"observationScopes": "shred"})
+        self.assertIsNone(payload["observation_scopes"])
+        self.assertIn("user turn 0", payload["content"])
+        self.assertTrue(payload["document_id"])
+
+    def test_a_typo_never_reaches_the_wire(self):
+        client = _RecordingClient("http://fake")
+        payload = self._build({"observationScopes": "per-tag"})  # hyphen, not underscore
+        client.retain(
+            payload["bank_id"],
+            payload["content"],
+            document_id=payload["document_id"],
+            observation_scopes=payload["observation_scopes"],
+        )
+        self.assertEqual(len(client.bodies), 1)
+        # ABSENT, not null: the request body is the pre-feature one.
+        self.assertNotIn("observation_scopes", client.bodies[0]["items"][0])
+
+    def test_a_typo_is_shouted_about_rather_than_swallowed(self):
+        # A silent downgrade to the engine default is the ORIGINAL defect this
+        # feature exists to prevent. Degrading quietly would just reintroduce
+        # it, so the build seam must say so on stderr every time it fires.
+        err = io.StringIO()
+        with contextlib.redirect_stderr(err):
+            self._build({"observationScopes": "shred"})
+        msg = err.getvalue()
+        self.assertIn("shred", msg)
+        self.assertIn("observation_scopes", msg)
+        for value in OBSERVATION_SCOPES_VALUES:
+            self.assertIn(value, msg)
+
+    def test_env_var_typo_is_caught_too(self):
+        # The env path bypasses zod entirely, so this is the only gate on it.
+        with mock.patch.dict(os.environ, {"HINDSIGHT_OBSERVATION_SCOPES": "shred"},
+                             clear=True):
+            with self.assertRaises(ValueError):
+                resolve_observation_scopes(load_config())
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()