switchroom 0.19.28 → 0.19.29

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()

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

@@ -12,6 +12,8 @@ single deterministic id), 6 (watermark monotonicity + uuid-not-found), 7
 bound ENQUEUES the remainder).
 """
 
+import contextlib
+import io
 import json
 import os
 import shutil
@@ -41,12 +43,16 @@ class FakeDaemon:
 
     def __init__(self):
         self.docs = {}          # document_id -> {content, metadata, async}
+        # switchroom: the observation_scopes kwarg each POST carried.
+        self.observation_scopes_seen = []
         self.posts = []         # [(document_id, async_processing)]
         self.fail = False
         self.drop_async = 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.posts.append((document_id, async_processing))
         if self.fail:
             raise RuntimeError("simulated daemon failure")
@@ -390,6 +396,159 @@ class TestSidechainSkip(DurabilityTestBase):
             self.assertIn(f"user turn {i}", blob)
 
 
+class TestObservationScopes(DurabilityTestBase):
+    """switchroom — the per-row observation scope on the LIVE retain paths.
+
+    Asserts the OUTCOME on the wire: what scope the Stop hook, the boot
+    reconciler, and the pending-queue drain actually POST with. Each of those
+    is a separate hand-enumerated kwarg list, so each needs its own pin — a
+    miss on any one silently drops that path back to per-tag scopes.
+    """
+
+    def _hook(self, session="scopesess", n=5):
+        tpath = os.path.join(self.transcripts, f"{session}.jsonl")
+        _write_transcript(tpath, n, session_prefix=session)
+        return {"session_id": session, "transcript_path": tpath, "cwd": "/x"}
+
+    def _set_scope(self, value):
+        os.environ["HINDSIGHT_OBSERVATION_SCOPES"] = value
+        self.addCleanup(os.environ.pop, "HINDSIGHT_OBSERVATION_SCOPES", None)
+
+    # -- default: nothing changes -------------------------------------------
+    def test_unconfigured_stop_retain_posts_no_scope(self):
+        hook = self._hook("plainsess")
+        with mock.patch("retain.increment_turn_count", return_value=3), \
+             mock.patch("sys.stdin", _stdin(hook)):
+            retain.main()
+        self.assertTrue(self.daemon.observation_scopes_seen)
+        self.assertTrue(all(s is None for s in self.daemon.observation_scopes_seen))
+
+    # -- Stop hook (retain.py) ----------------------------------------------
+    def test_configured_stop_retain_posts_the_scope(self):
+        self._set_scope("shared")
+        hook = self._hook("livesess")
+        with mock.patch("retain.increment_turn_count", return_value=3), \
+             mock.patch("sys.stdin", _stdin(hook)):
+            retain.main()
+        self.assertTrue(self.daemon.observation_scopes_seen)
+        self.assertTrue(all(s == "shared" for s in self.daemon.observation_scopes_seen))
+
+    # -- boot reconciler (reconcile_tail.py) --------------------------------
+    def test_configured_boot_reconcile_posts_the_scope(self):
+        self._set_scope("shared")
+        hook = self._hook("reconsess")
+        reconcile_tail.reconcile(self._config(), hook_input=hook)
+        self.assertTrue(self.daemon.observation_scopes_seen)
+        self.assertTrue(all(s == "shared" for s in self.daemon.observation_scopes_seen))
+
+    # -- durability: the scope survives the pending queue --------------------
+    def test_scope_survives_failure_enqueue_and_drain(self):
+        self._set_scope("shared")
+        hook = self._hook("failsess")
+
+        # The daemon refuses, so the Stop retain is ENQUEUED rather than landed.
+        self.daemon.fail = True
+        with mock.patch("retain.increment_turn_count", return_value=3), \
+             mock.patch("sys.stdin", _stdin(hook)):
+            retain.main()
+        entries = self._pending_entries()
+        self.assertEqual(len(entries), 1)
+        _path, entry = entries[0]
+        # The queued entry carries the scope, so the drain does not have to
+        # re-resolve config that may have changed since.
+        self.assertEqual(entry["observation_scopes"], "shared")
+
+        # Drain it hours later: it lands in the SAME scope.
+        import drain_pending
+        seen = []
+
+        class _Client:
+            def __init__(self, *a, **kw):
+                pass
+
+            def retain(self, **kwargs):
+                seen.append(kwargs.get("observation_scopes"))
+                return {"ok": True}
+
+        with mock.patch.object(drain_pending, "HindsightClient", _Client):
+            drain_pending._retry_one(entry, timeout=15)
+        self.assertEqual(seen, ["shared"])
+
+    # -- a typo must never destroy a memory ---------------------------------
+    #
+    # These are the regression tests for the worst bug the validation
+    # introduced. `build_retain_payload` used to RAISE on an off-list value.
+    # It is called from `run_retain`, which `retain.main` calls WITHOUT a
+    # try/except before its `pending_enqueue` — so the raise unwound past the
+    # enqueue: nothing POSTed, nothing queued, watermark not advanced, the turn
+    # gone. `session_end.py` caught it but had no payload to queue, and
+    # `session_start.py` swallowed the same raise into `debug_log` and aborted
+    # the reconcile loop that would have re-derived it. Every producer lost its
+    # memory outright, permanently and silently, for as long as the bad value
+    # sat in the config — switchroom #3244's shape, which this feature cites.
+    #
+    # A misconfigured scope is recoverable. A deleted turn is not. So a bad
+    # value degrades to the PRE-FEATURE behaviour (no field on the wire, the
+    # engine's own default scope) and is shouted about on stderr.
+
+    def test_a_typo_does_not_destroy_the_live_stop_retain(self):
+        self._set_scope("shred")  # not "shared"
+        hook = self._hook("typolivesess")
+        err = io.StringIO()
+        with mock.patch("retain.increment_turn_count", return_value=3), \
+             mock.patch("sys.stdin", _stdin(hook)), \
+             contextlib.redirect_stderr(err):
+            retain.main()
+
+        # OUTCOME 1: the memory LANDED. Not "an exception was caught" — the
+        # turns are in the bank.
+        # (chunked mode with retainEveryNTurns=3 slices the last 3 turns)
+        blob = self.daemon.content_blob()
+        self.assertIn("user turn 4", blob)
+        # OUTCOME 2: at the engine's own default scope (field omitted), which
+        # is exactly what an unconfigured agent does.
+        self.assertTrue(self.daemon.observation_scopes_seen)
+        self.assertTrue(all(s is None for s in self.daemon.observation_scopes_seen))
+        # OUTCOME 3: and it was loud. A silent downgrade would be the original
+        # "typo ignored forever" defect.
+        self.assertIn("shred", err.getvalue())
+        self.assertIn("observation_scopes", err.getvalue())
+
+    def test_a_typo_does_not_destroy_a_FAILED_stop_retain(self):
+        # The reviewer's reproduction: with the raise in place this enqueued 0
+        # entries and left the watermark unmoved, so the turn was lost for good.
+        self._set_scope("shred")
+        hook = self._hook("typofailsess")
+
+        self.daemon.fail = True
+        with mock.patch("retain.increment_turn_count", return_value=3), \
+             mock.patch("sys.stdin", _stdin(hook)), \
+             contextlib.redirect_stderr(io.StringIO()):
+            retain.main()
+
+        # OUTCOME: the payload was still built and still ENQUEUED, so the next
+        # SessionStart drain replays it. This is the assertion that matters —
+        # the memory has a durable on-disk copy.
+        entries = self._pending_entries()
+        self.assertEqual(len(entries), 1)
+        _path, entry = entries[0]
+        self.assertIn("user turn 4", entry["content"])
+        self.assertIsNone(entry["observation_scopes"])
+
+    def test_a_typo_does_not_destroy_the_boot_reconcile(self):
+        # session_start.py swallows a reconcile raise into debug_log AND aborts
+        # the loop on the first bad payload, so the recovery path that would
+        # re-derive lost turns did nothing either.
+        self._set_scope("shred")
+        hook = self._hook("typoreconsess")
+        with contextlib.redirect_stderr(io.StringIO()):
+            reconcile_tail.reconcile(self._config(), hook_input=hook)
+        blob = self.daemon.content_blob()
+        self.assertIn("user turn 0", blob)
+        self.assertTrue(self.daemon.observation_scopes_seen)
+        self.assertTrue(all(s is None for s in self.daemon.observation_scopes_seen))
+
+
 def _stdin(obj):
     import io
     return io.StringIO(json.dumps(obj))