switchroom 0.20.21 → 0.21.0

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

@@ -171,6 +171,7 @@ from concurrent.futures import ThreadPoolExecutor
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
+from lib import watermark
 from lib.client import HindsightClient
 from lib.config import debug_log, load_config
 from lib.pending import (
@@ -770,6 +771,72 @@ def _record_failure(
     return err_class
 
 
+def _reconcile_index(entries: list[tuple[str, dict]]) -> dict:
+    """``session_id -> set(abs_path)`` for reconcile-sourced queue entries.
+
+    Powers the no-loss sibling guard in ``_commit_reconcile_watermark``. Only
+    entries reconcile stamped (``reconcile_session_id``, switchroom #4571) are
+    indexed; everything else is ignored, so a non-reconcile queue entry for the
+    same session never blocks — its turns are covered by the reconcile slice's
+    own document, not by it.
+    """
+    idx: dict[str, set[str]] = {}
+    for path, entry in entries:
+        sid = entry.get("reconcile_session_id")
+        if sid:
+            idx.setdefault(sid, set()).add(os.path.abspath(path))
+    return idx
+
+
+def _commit_reconcile_watermark(entry: dict, path: str, index: dict) -> None:
+    """Advance the transcript watermark for a just-confirmed reconcile entry.
+
+    switchroom #4571. Called ONLY from a confirmed-durable retire branch — a
+    synchronous (``async_processing=False``) retain 200, or a presence GET that
+    returned True — so reaching here means this entry's content is durable. A
+    no-op for a non-reconcile entry (no ``reconcile_session_id``).
+
+    NO-LOSS GUARD. The watermark is a single "last contiguously-committed entry"
+    pointer, so it may only ever advance to the TRANSCRIPT TAIL, and only once
+    NO other slice of the same session is still queued:
+
+    * ``reconcile_is_tail`` False → an older turn-cap-split remainder that ends
+      mid-transcript; advancing to it would skip the newer turns after it.
+    * a live sibling in ``index`` → an unconfirmed earlier remainder OR a
+      size-split part of this same tail; advancing now could jump the watermark
+      past turns that are not yet durable.
+
+    Either way we leave the watermark and accept a redundant re-enqueue on the
+    next boot. ``watermark.commit`` is monotonic + idempotent and refuses
+    backward/compacted moves, so over-conservatism only ever costs repeat work,
+    never a lost turn — and that is the side to err on.
+    """
+    sid = entry.get("reconcile_session_id")
+    if not sid:
+        return
+    live = index.get(sid)
+    if live is not None:
+        # This entry is now durable + archived; drop it from the live set so a
+        # sibling that drains AFTER it is no longer blocked by it.
+        live.discard(os.path.abspath(path))
+    if not entry.get("reconcile_is_tail"):
+        return
+    last_uuid = entry.get("reconcile_last_uuid")
+    if not last_uuid:
+        return
+    if live:  # an earlier remainder / split part of this session is still queued
+        return
+    try:
+        watermark.commit(
+            sid,
+            last_uuid,
+            entry.get("document_id", ""),
+            ordered_uuids=entry.get("reconcile_ordered_uuids"),
+        )
+    except Exception:  # pragma: no cover - a watermark write must never fail a drain
+        pass
+
+
 def _new_summary() -> dict:
     return {
         "drained": 0,
@@ -892,7 +959,12 @@ def _drain_inhook_impl(config: dict, force: bool = False) -> dict:
     # behind them — see ``_drain_order``. Matters even more here than in the
     # backlog drain: the in-hook budget is ~4s, so a single entry at the head
     # that always burns its clamped timeout consumes the entire run.
-    entries = _park_broken(_drain_order(iter_entries()), summary, force)
+    all_entries = iter_entries()
+    # Built from the FULL queue (before parking): a parked reconcile entry is
+    # still queued and unconfirmed, so it must still block a sibling's watermark
+    # advance (#4571).
+    reconcile_index = _reconcile_index(all_entries)
+    entries = _park_broken(_drain_order(all_entries), summary, force)
     if not entries:
         debug_log(
             config,
@@ -938,6 +1010,7 @@ def _drain_inhook_impl(config: dict, force: bool = False) -> dict:
             if _document_state(entry, timeout=_clamp(timeout, budget, started)) is True:
                 if archive_reconciled(path):
                     summary["reconciled"] += 1
+                    _commit_reconcile_watermark(entry, path, reconcile_index)
                 else:
                     # Archive unwritable: the entry is STILL QUEUED (it is
                     # never deleted), so calling it reconciled would be a lie.
@@ -1003,6 +1076,7 @@ def _drain_inhook_impl(config: dict, force: bool = False) -> dict:
         # horizon costs.
         if archive_reconciled(path):
             summary["drained"] += 1
+            _commit_reconcile_watermark(entry, path, reconcile_index)
         else:
             summary["archive_failed"] += 1
         consecutive_failures = 0
@@ -1056,7 +1130,7 @@ def _phase_failed(summary: dict, phase: str, e: BaseException, cost: str) -> Non
     )
 
 
-def _reconcile_phase(config: dict, summary: dict, dry_run: bool) -> None:
+def _reconcile_phase(config: dict, summary: dict, dry_run: bool, reconcile_index: dict) -> None:
     """PHASE 1 — free pass: drop entries whose document already exists.
 
     This is the phase that makes backlog replay affordable. 70.4% of a
@@ -1082,8 +1156,11 @@ def _reconcile_phase(config: dict, summary: dict, dry_run: bool) -> None:
             continue
         state = _document_state(entry)
         if state is True:
-            if dry_run or archive_reconciled(path):
+            if dry_run:
+                summary["reconciled"] += 1
+            elif archive_reconciled(path):
                 summary["reconciled"] += 1
+                _commit_reconcile_watermark(entry, path, reconcile_index)
             else:
                 summary["archive_failed"] += 1
         elif state is None:
@@ -1264,8 +1341,14 @@ def _drain_backlog_impl(
                 f"archived, not deleted"
             )
 
+    # Built AFTER the pre-drain phases (collapse / re-split may have changed the
+    # queue) and shared across the reconcile pass and phase 2, so a sibling that
+    # phase 1 retires is dropped from the live set before phase 2 evaluates the
+    # tail's watermark advance (#4571).
+    reconcile_index = _reconcile_index(iter_entries())
+
     if phase in ("reconcile", "both"):
-        _reconcile_phase(config, summary, dry_run)
+        _reconcile_phase(config, summary, dry_run, reconcile_index)
     if phase == "reconcile":
         return summary
 
@@ -1356,6 +1439,7 @@ def _drain_backlog_impl(
                 if _document_state(entry) is True:
                     if archive_reconciled(path):
                         summary["drained"] += 1
+                        _commit_reconcile_watermark(entry, path, reconcile_index)
                     else:
                         summary["archive_failed"] += 1
                 else:

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

@@ -48,16 +48,19 @@ DEFAULT_VOLATILE_SCOPE_PATTERNS = (
 DEFAULTS = {
     # Recall
     "autoRecall": True,
-    # Switchroom default: "low" — vector search only, no LLM reranking.
-    # Cuts the recall hook latency from ~5s (mid budget) to ~1-2s (low).
-    # Operators who want richer recall can set HINDSIGHT_RECALL_BUDGET=mid
-    # via per-agent env or write `recallBudget: "mid"` into the user
-    # config file. Forensics on real klanker turns showed mid-budget
-    # recall was ~5s of wall-clock latency dominated by the LLM filter
-    # pass; for chat-pattern agents the vector hits alone are fine and
-    # the 5s is the second-largest contributor to perceived dead air
-    # (after the model TTFT).
-    "recallBudget": "low",
+    # Switchroom fleet default: "mid". The budget sets candidate DEPTH — how
+    # many nodes the engine pulls across all TEMPR retrieval stages before
+    # ranking (recall_budget_fixed_low=100 / _mid=300 / _high=1000 units,
+    # hindsight_api engine/memory_engine.py). It does NOT gate the reranker:
+    # the cross-encoder runs at EVERY budget level and is bounded separately by
+    # RERANKER_MAX_CANDIDATES (HINDSIGHT_API_RERANKER_MAX_CANDIDATES, default
+    # 300), so "low" is not "vector-only, no rerank" — it is a shallower
+    # candidate pool feeding the same rerank+score pipeline. "mid" (300 nodes)
+    # is upstream's own default and the balanced point: deeper recall than
+    # "low" without "high"'s 1000-node cold-page tail. Operators who want the
+    # shallow/fast pool back set HINDSIGHT_RECALL_BUDGET=low via per-agent env
+    # or write `recallBudget: "low"` into the user config file.
+    "recallBudget": "mid",
     "recallMaxTokens": 1024,
     # Switchroom-local: cap on the number of memories injected into the
     # `<hindsight_memories>` block, regardless of token budget. Plugin v0.4.0
@@ -206,7 +209,17 @@ DEFAULTS = {
     "retainEveryNTurns": 10,
     "retainOverlapTurns": 2,
     "retainToolCalls": True,
-    "retainContext": "claude-code",
+    # Switchroom — speaker-aware retain context. Resolved per-retain via
+    # build_retain_payload's _resolve_template, which fills {agent} from
+    # SWITCHROOM_AGENT_NAME and {bank_id} from the target bank. Tells the
+    # consolidation LLM who is speaking on each line so first-person agent
+    # actions ("experience") are not confused with the operator's world facts.
+    "retainContext": (
+        "Transcript of Claude Code agent '{agent}' ({bank_id}). "
+        "'assistant'/tool lines are the agent's own first-person actions "
+        "(experience); 'user' lines are the human operator speaking (their "
+        "statements are world facts)."
+    ),
     "retainTags": [],
     "retainMetadata": {},
     # Switchroom-local: per-row Hindsight `observation_scopes` on every retain.
@@ -396,6 +409,23 @@ ENV_OVERRIDES = {
     "HINDSIGHT_AUTO_RECALL": ("autoRecall", bool),
     "HINDSIGHT_AUTO_RETAIN": ("autoRetain", bool),
     "HINDSIGHT_RETAIN_MODE": ("retainMode", str),
+    # Switchroom-local: auto-retain cadence knobs. These had a DEFAULTS entry and
+    # a settings.json stamp (applyHindsightSettingsOverrides) but NO env channel,
+    # so env — the TOP of the config precedence chain (DEFAULTS → settings.json →
+    # ~/.hindsight/claude-code.json → env) — could not reach them at all. That
+    # broke parity with the recall knobs and left the only override paths as a
+    # settings.json rewrite (scaffold-time) or a hand-edit that `switchroom apply`
+    # re-copies away. Adding the env keys lets `memory.retain.*` (or an agent
+    # `env:` map, or a docker-exec'd retain that does not inherit the supervised
+    # env) drive them, and makes the env value authoritative when set.
+    # `retainEveryNTurns` / `retainOverlapTurns` mirror the yaml surface
+    # (`memory.retain.every_n_turns` / `.overlap_turns`); `retainContext` /
+    # `retainTags` have no yaml surface yet but gain the same env channel as the
+    # other retain knobs for consistency and exec-path overrides.
+    "HINDSIGHT_RETAIN_EVERY_N_TURNS": ("retainEveryNTurns", int),
+    "HINDSIGHT_RETAIN_OVERLAP_TURNS": ("retainOverlapTurns", int),
+    "HINDSIGHT_RETAIN_CONTEXT": ("retainContext", str),
+    "HINDSIGHT_RETAIN_TAGS": ("retainTags", list),
     # 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
@@ -520,6 +550,77 @@ ENV_OVERRIDES = {
 OBSERVATION_SCOPES_VALUES = ("per_tag", "combined", "all_combinations", "shared")
 
 
+#: Switchroom-local: the fact types Hindsight's recall endpoint accepts. Sending
+#: any other value makes the 0.9.0 engine return HTTP 422 ("Invalid fact type(s):
+#: … Must be one of: experience, observation, world") — a validation that was
+#: silently tolerated before vectorize-io/hindsight#3062. A 422 fails the WHOLE
+#: recall for the turn, so an operator typo in `memory.recall.types` (e.g.
+#: "observations", "fact") would otherwise kill memory injection on EVERY turn.
+#: Verified against the live engine's 422 detail string and /openapi.json
+#: RecallRequest; widening this set means widening it server-side too.
+RECALL_FACT_TYPES = ("world", "experience", "observation")
+
+#: The recall types used when a configured `recallTypes` filters down to empty
+#: (mirrors the `recallTypes` DEFAULTS entry). Falling back to this — rather than
+#: sending an empty/invalid set — keeps recall running with the shipped behaviour
+#: instead of degrading to nothing.
+DEFAULT_RECALL_FACT_TYPES = ("world", "experience")
+
+
+def filter_recall_types(config: dict):
+    """Filter ``recallTypes`` to the set Hindsight's recall endpoint accepts.
+
+    Returns the value to send as the recall ``types`` argument. THIS FUNCTION
+    MUST NEVER RAISE: an invalid ``memory.recall.types`` value is a
+    misconfiguration, and both raising here and passing the bad value through
+    have the same catastrophic outcome — a 422 that fails the recall and drops
+    memory injection for the turn. This mirrors the degrade-don't-raise contract
+    of :func:`compute_observation_scopes` (a bad config degrades the FEATURE,
+    never loses the turn).
+
+    * ``None`` / unset → ``None``: omit the field entirely, letting the engine
+      apply its own default (world + experience). Byte-identical to the wire
+      body a pre-filter client sent.
+    * a list/tuple     → keep the members in :data:`RECALL_FACT_TYPES` (order
+      and de-duplicated), dropping every unknown value WITH a stderr warning
+      that names it. If nothing valid survives, fall back to
+      :data:`DEFAULT_RECALL_FACT_TYPES` so recall still runs.
+    * anything else     → shout and fall back to :data:`DEFAULT_RECALL_FACT_TYPES`.
+    """
+    raw = config.get("recallTypes")
+    if raw is None:
+        return None
+    if not isinstance(raw, (list, tuple)):
+        print(
+            f"[Hindsight] recallTypes={raw!r} is not a list; falling back to "
+            f"{list(DEFAULT_RECALL_FACT_TYPES)}. Set it via `memory.recall.types` "
+            "in switchroom.yaml.",
+            file=sys.stderr,
+        )
+        return list(DEFAULT_RECALL_FACT_TYPES)
+    valid = []
+    for fact_type in raw:
+        if isinstance(fact_type, str) and fact_type in RECALL_FACT_TYPES:
+            if fact_type not in valid:
+                valid.append(fact_type)
+        else:
+            print(
+                f"[Hindsight] recallTypes entry {fact_type!r} is not a valid "
+                f"Hindsight fact type ({', '.join(RECALL_FACT_TYPES)}); dropping "
+                "it. An invalid type 422s the recall and drops memory injection "
+                "for the turn — fix it via `memory.recall.types` in switchroom.yaml.",
+                file=sys.stderr,
+            )
+    if not valid:
+        print(
+            f"[Hindsight] recallTypes={raw!r} left no valid fact types after "
+            f"filtering; falling back to {list(DEFAULT_RECALL_FACT_TYPES)}.",
+            file=sys.stderr,
+        )
+        return list(DEFAULT_RECALL_FACT_TYPES)
+    return valid
+
+
 def classify_observation_scopes(config: dict):
     """Classify ``observationScopes`` WITHOUT raising: ``(value, error)``.
 

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

@@ -59,7 +59,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 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 debug_log, filter_recall_types, load_config
 from lib.content import (
     _extract_text_content,
     compose_recall_query,
@@ -2091,6 +2091,15 @@ def main():
     if recall_request_timeout <= 0:
         recall_request_timeout = 12.0
 
+    # Fail-safe the recall `types` BEFORE any bank task runs: the 0.9.0 engine
+    # 422s an invalid fact type (e.g. an operator typo "observations"/"fact" in
+    # memory.recall.types), which fails the whole recall and drops memory
+    # injection for the turn. filter_recall_types drops unknowns (shouting on
+    # stderr) and falls back to the default set if the filter empties it — it
+    # never raises. Computed once here so every bank in the fan-out sends the
+    # same validated set.
+    resolved_recall_types = filter_recall_types(config)
+
     def _make_bank_task(target_bank_id, b_tags, b_tags_match, b_tag_groups, timeout_override=None):
         def _bank_task():
             return client.recall(
@@ -2098,7 +2107,7 @@ def main():
                 query=search_query,
                 max_tokens=config.get("recallMaxTokens", 1024),
                 budget=config.get("recallBudget", "mid"),
-                types=config.get("recallTypes"),
+                types=resolved_recall_types,
                 # Upstream 962140eef — optional per-bank tag filters (resolved
                 # above the cache check; part of the cache key).
                 tags=b_tags,

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

@@ -127,6 +127,36 @@ def _session_id_from_path(path: str) -> str:
     return os.path.splitext(os.path.basename(path))[0]
 
 
+def _annotate_reconcile_payload(payload: dict, session_id: str, built: dict) -> dict:
+    """Stamp watermark-anchoring fields onto a QUEUED reconcile payload.
+
+    switchroom #4571 — the recurring ``pending-retains`` spike. A slice that
+    reconcile enqueues (over-budget / out-of-lookback) or defers (turn-cap
+    split) is later drained by ``drain_pending.py`` on a confirmed 200, but the
+    drain had no way to know WHICH session/uuid the entry anchored, so it never
+    advanced the transcript watermark for these paths. Reconcile's gap detection
+    is watermark-keyed, so on the next boot it re-derives the identical tail and
+    re-enqueues it — a false-alarm queue spike that recurs every boot (no memory
+    is lost: enqueue dedupe + the archive protect it, but the depth trips the
+    memory-queue watchdog). These fields let the drain advance the watermark once
+    the slice is confirmed durable, under the no-loss guard in
+    ``drain_pending._commit_reconcile_watermark``.
+
+    ``reconcile_is_tail`` is the load-bearing one: only a slice whose last uuid
+    is the TRANSCRIPT tail may ever anchor the watermark. An older remainder
+    (turn-cap split) ends mid-transcript, so advancing to it would skip the
+    newer turns that follow it.
+    """
+    ordered = built.get("ordered_uuids") or []
+    last_uuid = built.get("last_uuid")
+    tail_uuid = ordered[-1] if ordered else None
+    payload["reconcile_session_id"] = session_id
+    payload["reconcile_last_uuid"] = last_uuid
+    payload["reconcile_ordered_uuids"] = ordered
+    payload["reconcile_is_tail"] = bool(last_uuid) and last_uuid == tail_uuid
+    return payload
+
+
 def reconcile(config: dict | None = None, hook_input: dict | None = None) -> dict:
     """Diff watermarks vs transcript tails and recover un-committed work.
 
@@ -297,6 +327,11 @@ def _post_inline(
         return "skip"
     payload = built["payload"]
     document_id = built["document_id"]
+    # Stamp the watermark-anchoring fields so that IF this slice falls through
+    # to the pending queue (lock busy / POST failed) the drain can advance the
+    # watermark once it lands, instead of leaving reconcile to re-enqueue it
+    # every boot (switchroom #4571).
+    _annotate_reconcile_payload(payload, session_id, built)
 
     with inflight_lock(blocking=True) as acquired:
         if not acquired:  # pragma: no cover - blocking acquire fails open
@@ -350,6 +385,7 @@ def _enqueue_slice(config, session_id, path, all_messages, slice_messages, bank_
     )
     if built is None:
         return False
+    _annotate_reconcile_payload(built["payload"], session_id, built)
     queued = pending_enqueue(built["payload"], RuntimeError("reconcile deferred (bound/budget)"))
     if queued is None:
         debug_log(config, "reconcile_tail: pending-retains full, could not enqueue remainder")

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

@@ -549,6 +549,11 @@ def build_retain_payload(
         "bank_id": bank_id,
         "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
         "user_id": os.environ.get("HINDSIGHT_USER_ID", ""),
+        # Switchroom — the agent's own name, so a speaker-aware retainContext
+        # template can name whose first-person experience this transcript is.
+        # Empty outside switchroom (no SWITCHROOM_AGENT_NAME); a template that
+        # references {agent} then renders an empty slot, which is harmless.
+        "agent": os.environ.get("SWITCHROOM_AGENT_NAME", ""),
     }
 
     def _resolve_template(value: str) -> str:
@@ -682,7 +687,7 @@ def build_retain_payload(
         "bank_id": bank_id,
         "content": transcript,
         "document_id": document_id,
-        "context": config.get("retainContext", "claude-code"),
+        "context": _resolve_template(config.get("retainContext", "claude-code")),
         "metadata": metadata,
         "tags": tags,
         "observation_scopes": scope,

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

@@ -0,0 +1,99 @@
+"""Switchroom — the auto-retain cadence knobs must have an env channel.
+
+`retainEveryNTurns`, `retainOverlapTurns`, `retainContext`, and `retainTags`
+had a DEFAULTS entry and (for the cadence pair) a settings.json stamp, but NO
+entry in `ENV_OVERRIDES`. Env is the TOP of the plugin's config precedence
+chain (DEFAULTS -> settings.json -> ~/.hindsight/claude-code.json -> env), so
+without an env key an operator's `HINDSIGHT_RETAIN_*` could not reach the
+plugin at all, and a docker-exec'd retain that does not inherit the supervised
+settings could not be steered either.
+
+The outcome under test: `HINDSIGHT_RETAIN_EVERY_N_TURNS` (and its siblings)
+actually OVERRIDE the resolved config value, and env wins over the shipped
+default.
+
+Stdlib-only.
+"""
+
+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)
+
+from lib.config import DEFAULTS, ENV_OVERRIDES, load_config  # noqa: E402
+
+
+# Every retain-cadence env var, with the config key it must reach.
+RETAIN_ENV = {
+    "HINDSIGHT_RETAIN_EVERY_N_TURNS": "retainEveryNTurns",
+    "HINDSIGHT_RETAIN_OVERLAP_TURNS": "retainOverlapTurns",
+    "HINDSIGHT_RETAIN_CONTEXT": "retainContext",
+    "HINDSIGHT_RETAIN_TAGS": "retainTags",
+}
+
+
+def _load_with(env):
+    """load_config() with a hermetic environment (no plugin/user settings)."""
+    with mock.patch.dict(os.environ, env, clear=True):
+        os.environ["CLAUDE_PLUGIN_ROOT"] = os.path.join(SCRIPTS_DIR, "does-not-exist")
+        os.environ["HOME"] = os.path.join(SCRIPTS_DIR, "does-not-exist")
+        return load_config()
+
+
+class EveryRetainNameHasAChannel(unittest.TestCase):
+    def test_all_retain_env_names_are_wired(self):
+        missing = [name for name in RETAIN_ENV if name not in ENV_OVERRIDES]
+        self.assertEqual(missing, [], f"exported but never read: {missing}")
+
+    def test_each_name_maps_to_the_expected_config_key(self):
+        for name, key in RETAIN_ENV.items():
+            with self.subTest(name=name):
+                self.assertEqual(ENV_OVERRIDES[name][0], key)
+
+    def test_every_target_key_exists_in_defaults(self):
+        for name, key in RETAIN_ENV.items():
+            with self.subTest(name=name):
+                self.assertIn(key, DEFAULTS)
+
+
+class ValuesActuallyLand(unittest.TestCase):
+    """The outcome that matters: the loaded config carries the exported value."""
+
+    def test_every_n_turns_env_overrides_the_resolved_value(self):
+        # The headline outcome: HINDSIGHT_RETAIN_EVERY_N_TURNS wins over the
+        # shipped default, and lands as an int.
+        override = DEFAULTS["retainEveryNTurns"] + 5
+        cfg = _load_with({"HINDSIGHT_RETAIN_EVERY_N_TURNS": str(override)})
+        self.assertEqual(cfg["retainEveryNTurns"], override)
+        self.assertIsInstance(cfg["retainEveryNTurns"], int)
+        self.assertNotEqual(cfg["retainEveryNTurns"], DEFAULTS["retainEveryNTurns"])
+
+    def test_overlap_turns_env_overrides_the_resolved_value(self):
+        cfg = _load_with({"HINDSIGHT_RETAIN_OVERLAP_TURNS": "4"})
+        self.assertEqual(cfg["retainOverlapTurns"], 4)
+
+    def test_context_env_overrides_the_resolved_value(self):
+        cfg = _load_with({"HINDSIGHT_RETAIN_CONTEXT": "codex"})
+        self.assertEqual(cfg["retainContext"], "codex")
+
+    def test_tags_env_accepts_a_json_array(self):
+        cfg = _load_with({"HINDSIGHT_RETAIN_TAGS": '["source:transcript"]'})
+        self.assertEqual(cfg["retainTags"], ["source:transcript"])
+
+    def test_tags_env_accepts_a_comma_separated_list(self):
+        cfg = _load_with({"HINDSIGHT_RETAIN_TAGS": "a,b"})
+        self.assertEqual(cfg["retainTags"], ["a", "b"])
+
+    def test_no_retain_env_reproduces_the_default(self):
+        baseline = _load_with({})
+        for key in RETAIN_ENV.values():
+            with self.subTest(key=key):
+                self.assertEqual(baseline[key], DEFAULTS[key])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,81 @@
+"""Switchroom — recall `types` must be fail-safe against an invalid fact type.
+
+The 0.9.0 Hindsight engine returns HTTP 422 ("Invalid fact type(s): … Must be
+one of: experience, observation, world") for an unknown recall `fact_type`,
+which fails the WHOLE recall for the turn. Before this guard, recall.py sent
+`types=config.get("recallTypes")` unvalidated, so an operator typo in
+`memory.recall.types` (e.g. "observations", "fact") would 422 and drop memory
+injection on every turn.
+
+The outcome under test: a config carrying an invalid type resolves — via
+`filter_recall_types` — to a FILTERED, valid `types` list (never a 422-bound
+call), and never raises. Mirrors the degrade-don't-raise contract of
+`compute_observation_scopes`.
+
+Stdlib-only.
+"""
+
+import os
+import sys
+import unittest
+
+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)
+
+from lib.config import (  # noqa: E402
+    DEFAULT_RECALL_FACT_TYPES,
+    RECALL_FACT_TYPES,
+    filter_recall_types,
+)
+
+
+class FilterRecallTypes(unittest.TestCase):
+    def test_valid_set_matches_the_engine(self):
+        # Guards against client/server drift: verified against the live engine's
+        # own 422 detail string ("experience, observation, world").
+        self.assertEqual(set(RECALL_FACT_TYPES), {"world", "experience", "observation"})
+
+    def test_invalid_type_is_dropped_leaving_a_valid_list(self):
+        # The exact defect: an operator typo mixed with a valid type. The bad
+        # value is dropped; the good one survives — NOT a 422-bound call.
+        resolved = filter_recall_types({"recallTypes": ["observations", "world"]})
+        self.assertEqual(resolved, ["world"])
+        for t in resolved:
+            self.assertIn(t, RECALL_FACT_TYPES)
+
+    def test_all_invalid_falls_back_to_the_default_set(self):
+        # If nothing valid survives, recall must still RUN — fall back to the
+        # shipped default rather than send an empty/invalid set.
+        resolved = filter_recall_types({"recallTypes": ["fact", "observations"]})
+        self.assertEqual(resolved, list(DEFAULT_RECALL_FACT_TYPES))
+
+    def test_valid_types_pass_through_deduplicated_in_order(self):
+        resolved = filter_recall_types(
+            {"recallTypes": ["world", "experience", "world", "observation"]}
+        )
+        self.assertEqual(resolved, ["world", "experience", "observation"])
+
+    def test_unset_returns_none_so_the_field_is_omitted(self):
+        # None -> omit `types` entirely, letting the engine apply its own default.
+        self.assertIsNone(filter_recall_types({}))
+        self.assertIsNone(filter_recall_types({"recallTypes": None}))
+
+    def test_non_list_value_falls_back_without_raising(self):
+        # A scalar where a list was expected is a config mistake, not a crash.
+        resolved = filter_recall_types({"recallTypes": "observation"})
+        self.assertEqual(resolved, list(DEFAULT_RECALL_FACT_TYPES))
+
+    def test_non_string_members_are_dropped(self):
+        resolved = filter_recall_types({"recallTypes": [None, 42, "observation"]})
+        self.assertEqual(resolved, ["observation"])
+
+    def test_never_raises_on_pathological_input(self):
+        for bad in ({}, {"recallTypes": {}}, {"recallTypes": 0}, {"recallTypes": [[]]}):
+            with self.subTest(bad=bad):
+                # Must return a value, never propagate an exception.
+                filter_recall_types(bad)
+
+
+if __name__ == "__main__":
+    unittest.main()