switchroom 0.19.27 → 0.19.29

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.
 
@@ -556,6 +562,112 @@ def _dir_bytes(d: str, names) -> int:
     return total
 
 
+def _append_ledger(line: str) -> None:
+    """Append one line to ``pending-evictions.log``, rotating at its cap.
+
+    Split out of ``_log_eviction`` (#3688 review R1-M2) so the OTHER way a
+    payload leaves this module for good — ``_trim_dir`` shedding an archived
+    copy — can be ledgered on exactly the same terms instead of leaving no
+    durable trace at all. Best-effort: a ledger that cannot be written *or
+    read back* must never take the caller down with it — hence the guard
+    catches ``ValueError`` as well as ``OSError`` (see there).
+
+    ROTATION PRIORITISES ``evicted=`` INSIDE THE SAME BUDGET, and that is a
+    direct consequence of sharing the file. Before #3688 every line here
+    was an eviction, so "keep the newest ``EVICTIONS_LOG_KEEP_LINES``
+    lines" and "keep the newest 2,000 evictions" were the same sentence.
+    They are not any more: a single ``collapse_duplicates`` run over the
+    measured 1,060-file backlog writes ~192 ``trimmed=`` lines, and a plain
+    tail-rotate would let that noise push real ``evicted=`` lines out of
+    the 7-day window ``switchroom doctor`` reads — i.e. adding
+    observability for the BENIGN channel would have removed it for the one
+    channel that means memory is actually gone.
+
+    So the keep window is filled evictions-first and only then topped up
+    with the newest remaining lines. The budget is unchanged at
+    ``EVICTIONS_LOG_KEEP_LINES`` lines TOTAL — a ledger of nothing but
+    evictions rotates exactly as it did before #3688 — and chronological
+    order is preserved because the selection is by index over the original
+    lines, which ``switchroom doctor``'s ``$1 >= cutoff`` awk depends on.
+    """
+    log = evictions_log_path()
+    try:
+        with open(log, "a", encoding="utf-8") as f:
+            print(line, file=f)
+        # Bounded, not append-forever. `switchroom doctor` windows this by
+        # timestamp so a single legitimate eviction can't turn the row red
+        # permanently, but the FILE still needs a ceiling of its own.
+        if os.path.getsize(log) > EVICTIONS_LOG_MAX_BYTES:
+            with open(log, encoding="utf-8") as f:
+                lines = f.readlines()
+            evictions = [i for i, ln in enumerate(lines) if "evicted=" in ln]
+            others = [i for i, ln in enumerate(lines) if "evicted=" not in ln]
+            keep_idx = set(evictions[-EVICTIONS_LOG_KEEP_LINES:])
+            room = EVICTIONS_LOG_KEEP_LINES - len(keep_idx)
+            if room > 0:
+                keep_idx.update(others[-room:])
+            kept = [ln for i, ln in enumerate(lines) if i in keep_idx]
+            tmp = log + ".tmp"
+            with open(tmp, "w", encoding="utf-8") as f:
+                f.writelines(kept)
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, log)
+    except (OSError, ValueError):
+        # ValueError, not just OSError, because BOTH codec errors are
+        # ValueError subclasses and neither is an OSError (#3688 re-review
+        # B1). The rotate READS the ledger back (``readlines()`` above) —
+        # something no revision before #3688 did — so a ledger holding one
+        # non-UTF-8 byte raises ``UnicodeDecodeError`` here, and a name
+        # carrying a surrogate raises ``UnicodeEncodeError`` at the
+        # ``print`` above. Under a bare ``except OSError`` both escape this
+        # "best-effort" guard: ``_trim_dir`` → ``_log_archive_trim`` → here
+        # runs inside ``archive_reconciled``/``enqueue``, so one corrupt
+        # ledger byte would take down every drain — on the sidecar,
+        # identically, every 900s forever. A ledger that cannot be written
+        # must never take the caller down with it, and that has to include
+        # the codec.
+        pass
+
+
+def _log_archive_trim(
+    name: str, size: int, reason: str, archive: str, depth: int, nbytes: int
+) -> None:
+    """Ledger ONE archived copy shed by ``_trim_dir``.
+
+    Until #3688 review R1-M2 a trim was stderr-only: an entry could enter
+    ``pending-duplicate/`` (or ``pending-evicted/``, or
+    ``pending-reconciled/``) and then be deleted from it with no durable
+    record anywhere, while an *eviction* — the other end of the same
+    payload's life — has had ``pending-evictions.log`` since #3599. stderr
+    is gone with the process; the ledger is what an operator can still read
+    a week later. Same file, because it answers one question ("what left
+    this agent's queue, and when").
+
+    THE FIRST TOKEN IS DELIBERATELY ``trimmed=``, NOT ``evicted=``.
+    ``switchroom doctor``'s probe counts eviction ledger lines with
+    ``awk '$1 >= cutoff && /evicted=/'`` (src/cli/doctor.ts, see
+    ``buildPendingRetainsProbeScript``), and that count FAILS the
+    pending-retains row. A trim is not an eviction — nothing was shed from
+    the live queue and, for ``pending-duplicate/``, a byte-identical copy is
+    still queued — so a trim must not be able to turn that row red. No field
+    on this line may ever be formatted such that ``evicted=`` appears in it;
+    ``ArchiveTrimLedgerTest`` pins that.
+    """
+    _append_ledger(
+        "%s trimmed=%s bytes=%d archive=%s reason=archive-%s "
+        "archive_depth=%d archive_bytes=%d"
+        % (
+            time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            name,
+            size,
+            archive,
+            reason,
+            depth,
+            nbytes,
+        )
+    )
+
+
 def _trim_dir(a: str, max_entries: int, max_bytes: int) -> int:
     """Keep ``a`` under its count/byte caps, deleting OLDEST first.
 
@@ -610,6 +722,21 @@ def _trim_dir(a: str, max_entries: int, max_bytes: int) -> int:
     ``pending-evicted/`` is a different story again — see ``_evict_to_fit``:
     an entry only reaches it through the ledgered eviction path, and under
     sustained ENOSPC it may not reach it at all.
+
+    EVERY DROP IS LEDGERED, AND ONLY A DROP (#3688 review R1-M2, tightened
+    by re-review B2). One ``trimmed=… archive=…`` line per shed copy goes
+    to ``pending-evictions.log`` via ``_log_archive_trim``, so the trim
+    horizon above is observable after the fact and not only in a stderr
+    stream nobody kept. That line is deliberately NOT counted as an
+    eviction by doctor — see ``_log_archive_trim``.
+
+    A victim whose ``os.remove`` FAILS (EACCES, read-only mount) is neither
+    ledgered nor counted nor named on stderr: it is still on disk, so a
+    ``trimmed=`` line for it would be a false claim of deletion in exactly
+    the record an operator consults after suspected loss, and the returned
+    count is what callers report as "copies shed". ``TrimDirBoundaryTest``
+    pins that a failed remove yields ``0``, no ledger line, and every file
+    still present.
     """
     # `.json` ONLY, and that is load-bearing beyond "skip stray files": a
     # `.dead` marker is named `<entry>.json.dead`, so it can never be
@@ -622,14 +749,35 @@ def _trim_dir(a: str, max_entries: int, max_bytes: int) -> int:
     except OSError:
         return 0
     dropped = []
-    while names and (
-        len(names) > max_entries or _dir_bytes(a, names) > max_bytes
-    ):
+    label = os.path.basename(a.rstrip("/"))
+    nbytes = _dir_bytes(a, names)
+    while names and (len(names) > max_entries or nbytes > max_bytes):
+        reason = "count" if len(names) > max_entries else "bytes"
+        victim = names.pop(0)
+        vpath = os.path.join(a, victim)
         try:
-            os.remove(os.path.join(a, names[0]))
+            vsize = os.path.getsize(vpath)
         except OSError:
-            pass
-        dropped.append(names.pop(0))
+            vsize = 0
+        try:
+            os.remove(vpath)
+        except OSError:
+            # The copy is still on disk, so the running total would drift.
+            # Re-measure rather than assume — this preserves the original
+            # recompute-every-iteration semantics on the one path where a
+            # decrement would be wrong (EACCES / read-only mount).
+            nbytes = _dir_bytes(a, names)
+            # NOT counted and NOT ledgered (#3688 re-review B2). The ledger
+            # is the forensic record an operator reads AFTER suspected data
+            # loss; a `trimmed=` line for a copy still sitting on disk sends
+            # them hunting a payload that never left, and the returned count
+            # (and the stderr line below) would name files that were not
+            # dropped. A ledger that claims deletions which never happened
+            # is worse than no ledger.
+            continue
+        nbytes -= vsize
+        dropped.append(victim)
+        _log_archive_trim(victim, vsize, reason, label, len(names), nbytes)
     if dropped:
         shown = ", ".join(dropped[:10])
         if len(dropped) > 10:
@@ -736,6 +884,47 @@ def archive_duplicate(path: str) -> Optional[str]:
     return dest
 
 
+def _attempt_count(entry: dict) -> int:
+    """How many retries this copy has BURNED, for survivor selection.
+
+    Not ``int(entry.get("attempt_count", 1) or 1)`` (#3688 review R1-L3).
+    That expression had two defects, both latent rather than reachable
+    today — ``_build_entry`` seeds ``1`` and ``update_attempt`` only ever
+    increments — which is exactly why they need pinning rather than
+    ignoring: nothing would have caught them turning real.
+
+    * ``0 or 1`` is ``1``, so a NEVER-ATTEMPTED copy scored the same as one
+      that had already burned an attempt, and lost the tie-break to it if
+      it happened to be the newer file. That is backwards from the rule
+      ``collapse_duplicates`` documents ("the copy with the most retries
+      left before ``MAX_ATTEMPTS`` wins") — a 0 must beat a 1.
+    * ``int("many")`` RAISES. A single semantically-malformed entry — valid
+      JSON, so ``iter_entries`` hands it over rather than quarantining it —
+      took the whole collapse pass down with it, and with it (before the
+      guard in ``drain_pending._drain_backlog_impl``) the whole drain.
+      Unparseable now scores ``MAX_ATTEMPTS``: we cannot tell how many
+      attempts it has left, so it is never PREFERRED as the survivor, but
+      it is never the reason a collapse fails either. Losing it costs
+      nothing anyway — every copy in a group is byte-identical, and the
+      loser is archived, not deleted.
+
+    A missing or ``None`` count reads as ``1``, matching what
+    ``_build_entry`` writes, so an entry from an older build that predates
+    the field is treated as freshly queued rather than exhausted.
+    """
+    raw = entry.get("attempt_count", 1)
+    if raw is None:
+        return 1
+    # bool is an int subclass; True would silently score 1. Neither True nor
+    # False is an attempt count, so both take the unparseable branch.
+    if isinstance(raw, bool):
+        return MAX_ATTEMPTS
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return MAX_ATTEMPTS
+
+
 def collapse_duplicates() -> int:
     """Collapse entries sharing ``(bank_id, part_position, sha256(content))``.
 
@@ -754,7 +943,8 @@ def collapse_duplicates() -> int:
     memory; the one with the most attempts left is the one most likely to
     get there before ``MAX_ATTEMPTS`` promotes it to ``.dead``. Picking the
     oldest outright would systematically keep the most-attempted copy —
-    exactly backwards.
+    exactly backwards. ``_attempt_count`` defines "lowest", including what
+    a ``0`` and what a malformed count are worth.
 
     An entry whose key is ``None`` (no ``content``) is never grouped: its
     identity cannot be established, so it is always kept.
@@ -773,10 +963,7 @@ def collapse_duplicates() -> int:
     for key, members in groups.items():
         if len(members) < 2:
             continue
-        survivor = min(
-            members,
-            key=lambda m: (int(m[2].get("attempt_count", 1) or 1), m[0]),
-        )
+        survivor = min(members, key=lambda m: (_attempt_count(m[2]), m[0]))
         for member in members:
             if member is survivor:
                 continue
@@ -1047,23 +1234,7 @@ def _log_eviction(name: str, size: int, reason: str, depth: int, nbytes: int) ->
         depth,
         nbytes,
     )
-    log = evictions_log_path()
-    try:
-        with open(log, "a", encoding="utf-8") as f:
-            print(line, file=f)
-        # Bounded, not append-forever. `switchroom doctor` windows this by
-        # timestamp so a single legitimate eviction can't turn the row red
-        # permanently, but the FILE still needs a ceiling of its own.
-        if os.path.getsize(log) > EVICTIONS_LOG_MAX_BYTES:
-            with open(log, encoding="utf-8") as f:
-                kept = f.readlines()[-(EVICTIONS_LOG_KEEP_LINES):]
-            tmp = log + ".tmp"
-            with open(tmp, "w", encoding="utf-8") as f:
-                f.writelines(kept)
-            os.chmod(tmp, 0o600)
-            os.replace(tmp, log)
-    except OSError:
-        pass
+    _append_ledger(line)
     print(
         "[Hindsight] pending-retains FULL - evicted OLDEST entry to keep the "
         "newest memory: %s (%d bytes, %s; queue now %d entries / %d bytes). "

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: