switchroom 0.19.26 → 0.19.28

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

@@ -556,6 +556,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 +716,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 +743,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 +878,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 +937,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 +957,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 +1228,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/recall.py

@@ -580,6 +580,101 @@ def _injected_score_stats(results) -> dict:
         return empty
 
 
+# Switchroom #3837 — opt-in absolute score floor (`recallMinScore`).
+#
+# READ #3761 FIRST. It removed the lexical `recallMinOverlap` gate and stated
+# "no replacement floor", on a 330-query replay showing that for EVERY floor
+# value tested `top1lost% == zero%`: a floor at 0.001 took zero-result recalls
+# from 5.8% to 28.2%, at 0.05 to 40.6%. That measurement stands and this change
+# does not contradict it — which is why the floor ships DISABLED (0.0) and why
+# its default scope is not "every turn".
+#
+# What #3761 did not separate is the CONDITION of the bank read. Measured
+# fleet-wide from `recall_log.jsonl` on 2026-07-27 and recorded independently
+# in `src/hindsight-watch/thresholds.ts` (RECALL_SCORE_P50_PAGE):
+#
+#   own bank HEALTHY  (n=74)   p50 injected_score_max 0.0850   28.4% below 0.01
+#   own bank DEGRADED (n=247)  p50 injected_score_max 0.0006   98.4% below 0.01
+#
+# A ~140x separation in the p50, and the below-0.01 fraction separates
+# 28.4% vs 98.4%. Two conclusions follow, and only the second is actionable:
+#
+#   * On a HEALTHY turn a low `scores.final` does NOT imply noise. The healthy
+#     distribution is bimodal, p10 0.0005 to p90 0.9259 — the score is not
+#     calibrated across queries, so 28.4% of perfectly good turns would be
+#     emptied by a 0.01 floor. That is #3761's result, reproduced. A floor
+#     applied unconditionally re-creates #3541.
+#   * On a DEGRADED turn — the agent's own bank timed out or was unreachable,
+#     so what survives is side-bank residue — 98.4% of injected sets have a
+#     best score below 0.01, and the turn ALREADY carries
+#     `degraded_recall_notice`. Withholding that residue costs at most the
+#     1.6% tail and replaces "six memories presented as recall" with the
+#     honest "recall was DEGRADED, treat absence as UNKNOWN" the agent can
+#     act on. Injecting noise under the banner of recall is strictly worse
+#     than injecting nothing WITH a disclosure, because the agent cannot tell
+#     the two apart; injecting nothing WITHOUT a disclosure is the failure
+#     mode #3619 fixed and is not re-introduced here.
+#
+# Hence `recallMinScoreScope`, default "degraded": when the operator sets a
+# floor, it binds only on turns where the own-bank read was degraded, which is
+# the population the evidence supports. "all" widens it to every turn for an
+# operator who has measured their own bank and wants it — no fleet default
+# recommends that today.
+#
+# Nothing is dropped silently. When the floor empties a non-empty set the turn
+# emits `min_score_withheld_notice` (and the degraded notice too, when that
+# fired), so an empty recall is never mistaken for an empty memory. Per-turn
+# telemetry lands on `recall_log.jsonl` as `min_score_floor`,
+# `min_score_scope`, `min_score_applied` and `dropped_below_min_score`,
+# alongside the existing `injected_score_*` fields — the same instrument the
+# problem was measured with, so the effect is measurable the same way.
+def _filter_by_min_score(results, threshold: float):
+    """Drop results whose engine score (`scores.final`) is below `threshold`.
+
+    Returns ``(kept, dropped)``. ``threshold <= 0`` short-circuits to
+    passthrough with no iteration cost, so the disabled default cannot alter
+    the injected set.
+
+    A result carrying NO usable score is KEPT, never dropped. `-inf` is the
+    sentinel `_result_final_score` returns for a malformed or score-less
+    entry, and "the engine gave us no score" is not evidence of irrelevance —
+    dropping on it would turn a response-shape change upstream into silent
+    total recall loss. Same reasoning as the sort, which parks score-less
+    entries last rather than discarding them.
+    """
+    if threshold <= 0:
+        return results, 0
+    kept = []
+    dropped = 0
+    for m in results:
+        score = _result_final_score(m)
+        if score == float("-inf") or score >= threshold:
+            kept.append(m)
+        else:
+            dropped += 1
+    return kept, dropped
+
+
+def min_score_withheld_notice(dropped: int, threshold: float) -> str:
+    """One line telling the agent that recall HAD candidates and withheld them.
+
+    Only meaningful when the floor emptied the injected set. The distinction
+    it preserves is #3619's: "I could not retrieve anything worth trusting" is
+    not "there is nothing to remember", and an agent that cannot tell those
+    apart asserts the second. Kept to a single short line — this fires on an
+    already-thin turn.
+    """
+    if dropped <= 0:
+        return ""
+    return (
+        f"[Hindsight] Memory recall returned {dropped} candidate "
+        f"{'memory' if dropped == 1 else 'memories'}, all scoring below the "
+        f"configured relevance floor ({threshold:g}), so none were injected. "
+        f"Treat an absence of relevant memory as UNKNOWN, not as 'nothing was "
+        f"remembered'."
+    )
+
+
 def _sort_by_final_score(results):
     """Sort merged multi-bank results by `scores.final` descending, in place.
 
@@ -1676,6 +1771,15 @@ def main():
                 # No directives block is built on a cache hit.
                 "directives_omitted": None,
                 "demoted_count": 0,
+                # #3837 score-floor fields, present for a uniformly queryable
+                # schema. A cache hit replays a formatted context block, not a
+                # result set, so the floor cannot have run: None (not 0.0/False)
+                # so a cache-hit row is never counted as an observed
+                # floor-disabled turn.
+                "min_score_floor": None,
+                "min_score_scope": None,
+                "min_score_applied": None,
+                "dropped_below_min_score": None,
                 "capped": False,
                 # #3541 quality telemetry — present for a uniformly queryable
                 # schema. A cache hit replays a formatted context block, not a
@@ -2146,6 +2250,45 @@ def main():
     # regardless of source bank. Stable sort: ties keep own-bank-first order.
     _sort_by_final_score(results)
 
+    # Switchroom #3619 — DEGRADED-RECALL DISCLOSURE. Computed HERE rather than
+    # at emit time because the #3837 score floor is scoped by it: the same
+    # single source of truth for "the agent's own bank did not answer" decides
+    # both whether the floor binds and what the agent is told. See
+    # `degraded_recall_notice` for why only the agent's OWN bank counts.
+    degraded_block = degraded_recall_notice(bank_id, bank_timings)
+
+    # Switchroom #3837 — opt-in absolute score floor. Runs AFTER the tag
+    # weights and the relevance sort (so it judges the same effective
+    # `scores.final` the ranking used) and BEFORE the head-slice cap, so the
+    # cap sees only survivors. Disabled by default (`recallMinScore` 0.0);
+    # when set it binds on degraded turns only unless the operator widens
+    # `recallMinScoreScope` to "all". The design note above
+    # `_filter_by_min_score` carries the measurement, and why #3761's "no
+    # replacement floor" finding is not contradicted by this.
+    min_score_floor = config.get("recallMinScore", 0.0)
+    if isinstance(min_score_floor, bool) or not isinstance(min_score_floor, (int, float)):
+        min_score_floor = 0.0
+    min_score_floor = float(min_score_floor)
+    min_score_scope = config.get("recallMinScoreScope", "degraded")
+    if min_score_scope not in ("degraded", "all"):
+        min_score_scope = "degraded"
+    min_score_applied = min_score_floor > 0 and (
+        min_score_scope == "all" or bool(degraded_block)
+    )
+    dropped_below_min_score = 0
+    if min_score_applied:
+        pre_min_score_count = len(results)
+        results, dropped_below_min_score = _filter_by_min_score(
+            results, min_score_floor
+        )
+        if dropped_below_min_score > 0:
+            debug_log(
+                config,
+                f"Score floor dropped {dropped_below_min_score}/"
+                f"{pre_min_score_count} memories below scores.final "
+                f"{min_score_floor} (scope={min_score_scope})",
+            )
+
     # Switchroom-local: client-side count cap. Plugin v0.4.0 has no
     # `recallTopK` in the Claude Code integration (Openclaw-only), and a
     # token budget alone doesn't bound count — a single long memory can
@@ -2333,6 +2476,19 @@ def main():
         # doctor's directive-count check will be FAILing too.
         "directives_omitted": count_omitted_directives(directives),
         "demoted_count": demoted_count,
+        # Switchroom #3837 — score-floor telemetry, deliberately alongside the
+        # `injected_score_*` fields below: those are what the floor was derived
+        # from, and these are what says whether it bound and what it cost.
+        # `min_score_floor` is the configured value (0.0 = disabled),
+        # `min_score_scope` the population it may bind on, `min_score_applied`
+        # whether it actually ran this turn, and `dropped_below_min_score` how
+        # many results it removed. dropped > 0 with result_count 0 is the case
+        # the feature exists for: candidates existed, all were noise, none were
+        # injected, and the agent was told so.
+        "min_score_floor": min_score_floor,
+        "min_score_scope": min_score_scope,
+        "min_score_applied": min_score_applied,
+        "dropped_below_min_score": dropped_below_min_score,
         "capped": capped,
         "pre_cap_count": pre_cap_count,
         "memory_ids": [
@@ -2430,10 +2586,17 @@ def main():
         "error": recall_error_summary(bank_id, bank_timings, directives_timed_out),
     })
 
-    # Switchroom #3619 — DEGRADED-RECALL DISCLOSURE. See
-    # `degraded_recall_notice` for why this exists and why only the agent's
-    # OWN bank counts.
-    degraded_block = degraded_recall_notice(bank_id, bank_timings)
+    # (`degraded_block` — the #3619 disclosure — was computed before the score
+    # floor above, which is scoped by it.)
+    #
+    # Switchroom #3837 — when the floor emptied a non-empty set, say so. Not
+    # emitted when survivors remain: a partial drop still injects real
+    # memories and does not change how the turn should be read.
+    withheld_block = (
+        min_score_withheld_notice(dropped_below_min_score, min_score_floor)
+        if not results
+        else ""
+    )
 
     # If no block has content, there's nothing to inject — exit
     # silently to avoid emitting an empty hookSpecificOutput. #2848: unless
@@ -2441,10 +2604,13 @@ def main():
     # (a correction with no memories/directives still needs the reminder).
     # #3619: a degraded own-bank read is likewise worth emitting alone — that
     # is precisely the turn on which the agent must not assume it remembers.
+    # #3837: so is a set the score floor withheld entirely.
     if not directives_block and not memories_block and not transcript_fallback_block:
-        if degraded_block or nudge_block:
+        if degraded_block or withheld_block or nudge_block:
             _emit_cached_context(
-                "\n\n".join([b for b in (degraded_block, nudge_block) if b])
+                "\n\n".join(
+                    [b for b in (degraded_block, withheld_block, nudge_block) if b]
+                )
             )
         return
 
@@ -2500,7 +2666,10 @@ def main():
         "hookSpecificOutput": {
             "hookEventName": "UserPromptSubmit",
             "additionalContext": _combine_context(
-                _combine_context(degraded_block, context_message), nudge_block
+                _combine_context(
+                    _combine_context(degraded_block, withheld_block), context_message
+                ),
+                nudge_block,
             ),
         }
     }

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

@@ -0,0 +1,170 @@
+"""Switchroom #3841 — the recall knobs switchroom.yaml exports must actually
+land in the loaded config.
+
+Three of them (`recallPreferObservations`, `recallRoles`,
+`recallPromptPreamble`) had a config key and a `recall.py` read but NO entry in
+`ENV_OVERRIDES`, so there was no channel from switchroom.yaml at all: the only
+way to change them was to hand-edit the installed plugin, which
+`switchroom apply` reverts by re-copying this tree.
+
+The rest already had entries and only needed the yaml surface — they are
+asserted here too, because the failure they guard against is silent in exactly
+the same way. `start.sh` exports a NAME; if that name is not a key of
+`ENV_OVERRIDES`, `load_config()` ignores it, the plugin default stands, and the
+operator's switchroom.yaml reads as though it were in force. Nothing errors.
+
+Stdlib-only.
+"""
+
+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)
+
+from lib.config import DEFAULTS, ENV_OVERRIDES, load_config  # noqa: E402
+
+
+# Every env var `profiles/_base/start.sh.hbs` exports for the #3841
+# passthrough, with the config key it must reach.
+PASSTHROUGH_ENV = {
+    "HINDSIGHT_RECALL_BUDGET": "recallBudget",
+    "HINDSIGHT_RECALL_MAX_TOKENS": "recallMaxTokens",
+    "HINDSIGHT_RECALL_PREFER_OBSERVATIONS": "recallPreferObservations",
+    "HINDSIGHT_RECALL_CONTEXT_TURNS": "recallContextTurns",
+    "HINDSIGHT_RECALL_ROLES": "recallRoles",
+    "HINDSIGHT_RECALL_PROMPT_PREAMBLE": "recallPromptPreamble",
+    "HINDSIGHT_RECALL_MAX_QUERY_CHARS": "recallMaxQueryChars",
+    "HINDSIGHT_RECALL_TRANSCRIPT_TAIL_BYTES": "recallTranscriptTailBytes",
+    "HINDSIGHT_RECALL_TAGS": "recallTags",
+    "HINDSIGHT_RECALL_TAGS_MATCH": "recallTagsMatch",
+    "HINDSIGHT_RECALL_TAG_GROUPS": "recallTagGroups",
+    "HINDSIGHT_RECALL_TAG_WEIGHTS": "recallTagWeights",
+    "HINDSIGHT_RECALL_ADDITIONAL_BANK_FILTERS": "recallAdditionalBankFilters",
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK": "recallTranscriptFallback",
+    "HINDSIGHT_RECALL_PARALLEL": "recallParallel",
+}
+
+
+def _load_with(env):
+    """load_config() with a hermetic environment (no plugin/user settings)."""
+    with mock.patch.dict(os.environ, env, clear=True):
+        # Point CLAUDE_PLUGIN_ROOT at a directory with no settings.json so the
+        # result is DEFAULTS + env only, and no developer's real
+        # ~/.hindsight/claude-code.json can leak in.
+        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 EveryExportedNameHasAChannel(unittest.TestCase):
+    def test_all_passthrough_env_names_are_wired(self):
+        missing = [name for name in PASSTHROUGH_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 PASSTHROUGH_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 PASSTHROUGH_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_prefer_observations_can_be_turned_off(self):
+        self.assertTrue(DEFAULTS["recallPreferObservations"])
+        cfg = _load_with({"HINDSIGHT_RECALL_PREFER_OBSERVATIONS": "false"})
+        self.assertIs(cfg["recallPreferObservations"], False)
+
+    def test_roles_accepts_the_exported_json_array(self):
+        cfg = _load_with({"HINDSIGHT_RECALL_ROLES": '["user"]'})
+        self.assertEqual(cfg["recallRoles"], ["user"])
+
+    def test_prompt_preamble_replaces_the_banner(self):
+        cfg = _load_with({"HINDSIGHT_RECALL_PROMPT_PREAMBLE": "Past context:"})
+        self.assertEqual(cfg["recallPromptPreamble"], "Past context:")
+
+    def test_tag_weights_accepts_the_exported_json_object(self):
+        cfg = _load_with({"HINDSIGHT_RECALL_TAG_WEIGHTS": '{"sidechain": 0.8}'})
+        self.assertEqual(cfg["recallTagWeights"], {"sidechain": 0.8})
+
+    def test_tag_groups_accepts_both_shapes(self):
+        as_list = _load_with({"HINDSIGHT_RECALL_TAG_GROUPS": '[["a","b"],["c"]]'})
+        self.assertEqual(as_list["recallTagGroups"], [["a", "b"], ["c"]])
+        as_map = _load_with({"HINDSIGHT_RECALL_TAG_GROUPS": '{"g": ["a"]}'})
+        self.assertEqual(as_map["recallTagGroups"], {"g": ["a"]})
+
+    def test_empty_collection_exports_assign_rather_than_being_skipped(self):
+        # `[]` / `{}` are what switchroom exports when the operator configured
+        # nothing. They must ASSIGN (making env authoritative over a stale
+        # ~/.hindsight/claude-code.json), not be dropped like an empty string.
+        cfg = _load_with(
+            {
+                "HINDSIGHT_RECALL_TAGS": "[]",
+                "HINDSIGHT_RECALL_TAG_GROUPS": "{}",
+                "HINDSIGHT_RECALL_ADDITIONAL_BANK_FILTERS": "{}",
+            }
+        )
+        self.assertEqual(cfg["recallTags"], [])
+        self.assertEqual(cfg["recallTagGroups"], {})
+        self.assertEqual(cfg["recallAdditionalBankFilters"], {})
+
+    def test_exported_defaults_reproduce_the_shipped_config(self):
+        """The no-config path: exporting today's effective values changes nothing.
+
+        This is the whole contract of the passthrough — an operator who sets no
+        `memory.recall.*` key must get the same loaded config as an agent
+        running before the exports existed.
+        """
+        baseline = _load_with({})
+        exported = _load_with(
+            {
+                "HINDSIGHT_RECALL_BUDGET": baseline["recallBudget"],
+                "HINDSIGHT_RECALL_MAX_TOKENS": str(baseline["recallMaxTokens"]),
+                "HINDSIGHT_RECALL_PREFER_OBSERVATIONS": str(
+                    baseline["recallPreferObservations"]
+                ).lower(),
+                "HINDSIGHT_RECALL_CONTEXT_TURNS": str(baseline["recallContextTurns"]),
+                "HINDSIGHT_RECALL_ROLES": json.dumps(baseline["recallRoles"]),
+                "HINDSIGHT_RECALL_PROMPT_PREAMBLE": baseline["recallPromptPreamble"],
+                "HINDSIGHT_RECALL_MAX_QUERY_CHARS": str(baseline["recallMaxQueryChars"]),
+                "HINDSIGHT_RECALL_TRANSCRIPT_TAIL_BYTES": str(
+                    baseline["recallTranscriptTailBytes"]
+                ),
+                "HINDSIGHT_RECALL_TAGS": json.dumps(baseline["recallTags"]),
+                "HINDSIGHT_RECALL_TAGS_MATCH": baseline["recallTagsMatch"],
+                # settings.json ships null / DEFAULTS carries None; `{}` is the
+                # same thing to recall.py (`config.get(...) or None`) and unlike
+                # `null` it actually assigns.
+                "HINDSIGHT_RECALL_TAG_GROUPS": "{}",
+                "HINDSIGHT_RECALL_TAG_WEIGHTS": json.dumps(baseline["recallTagWeights"]),
+                "HINDSIGHT_RECALL_ADDITIONAL_BANK_FILTERS": json.dumps(
+                    baseline["recallAdditionalBankFilters"]
+                ),
+                "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK": str(
+                    baseline["recallTranscriptFallback"]
+                ).lower(),
+                "HINDSIGHT_RECALL_PARALLEL": str(baseline["recallParallel"]).lower(),
+            }
+        )
+        for key in PASSTHROUGH_ENV.values():
+            with self.subTest(key=key):
+                if key == "recallTagGroups":
+                    # None vs {} — equivalent at every read site (`or None`).
+                    self.assertFalse(baseline[key])
+                    self.assertFalse(exported[key])
+                    continue
+                self.assertEqual(exported[key], baseline[key])
+
+
+if __name__ == "__main__":
+    unittest.main()