switchroom 0.20.20 → 0.20.22

package/telegram-plugin/dist/gateway/gateway.js

@@ -21745,22 +21745,22 @@ var init_schema = __esm(() => {
     observation_scopes: ObservationScopesSchema,
     observation_scope_strategy: ObservationScopeStrategySchema,
     recall: exports_external.object({
-      max_memories: exports_external.number().int().min(0).optional().describe("Cap on the number of memories injected into the prompt by " + "auto-recall, regardless of token budget. Plugin default is 12. " + "0 disables the cap (all memories Hindsight returns are injected)."),
+      max_memories: exports_external.number().int().min(0).optional().describe("Cap on the number of memories injected into the prompt by " + "auto-recall, regardless of token budget. The vendor plugin ships " + "12; switchroom's resolver default is 8 when this is unset, and the " + "live fleet raises it via `defaults.memory.recall.max_memories`. " + "0 disables the cap (all memories Hindsight returns are injected)."),
       cache_ttl_secs: exports_external.number().int().min(0).optional().describe("Per-session recall cache TTL in seconds. When > 0, identical " + "(prompt, bank) within the same session reuse the cached recall " + "result instead of round-tripping to Hindsight. 0 disables. " + "Default is 600 (10 min) for switchroom-managed agents."),
       hook_timeout_seconds: exports_external.number().int().min(1).optional().describe("Ceiling (seconds) Claude Code gives the UserPromptSubmit recall " + "hook before killing it. Stamped into the installed plugin's " + "hooks/hooks.json, so it survives `switchroom apply` reinstalling " + "the plugin. Default 12. Raising it lets slow banks finish at the " + "cost of pre-turn dead air; `parallel_deadline_seconds` and " + "`request_timeout_seconds` are both kept under it. A value below " + "3s is raised to 3s and reported: the fan-out deadline must be at " + "least 1s AND still leave 2s of post-deadline headroom, so a " + "lower ceiling admits no usable envelope at all."),
       parallel_deadline_seconds: exports_external.number().int().min(1).optional().describe("Shared deadline (seconds) for the whole parallel multi-bank " + "recall fan-out. Slots unfinished when it elapses are abandoned " + "and reported as timed out. Defaults to `hook_timeout_seconds` " + "minus 2s of headroom for block formatting, cache write and " + "stdout flush, so a straggler bank can never push the hook past " + "its ceiling. Set explicitly to override that derivation; a value " + "that would leave less than 2s under the hook ceiling \u2014 including " + "one set EQUAL to it \u2014 is clamped back to `hook_timeout_seconds` " + "minus 2, and the clamp is reported. Equality is not allowed: at " + "zero headroom the hook is killed mid-write and the turn loses " + "both the memories and the recall_log row explaining why."),
       query_max_tokens: exports_external.number().int().min(0).optional().describe("Cap on the number of DISTINCT BM25 terms the recall hook may " + "put on the wire. `recallMaxQueryChars` bounds characters, which " + "is not the cost driver: Hindsight OR-joins every query token " + "into one tsquery and Postgres native FTS ranks the entire " + "matched set before the top-60 heapsort, so cost tracks TERMS. " + "An 800-char composed query is ~96 distinct terms and matched " + "119,510 of 135,565 rows on the `overlord` bank (14.0s for the " + "3-arm " + "BM25 UNION), past the per-bank timeout \u2014 96.8% of that agent's " + "own-bank recalls returned nothing. Plugin default is 24 " + "(measured 48,433 rows / 2.7s on the same bank). Terms are " + "chosen recency-first (the latest turn beats prior context), " + "then by selectivity. 0 disables shaping (rollback lever)."),
       query_stop_terms: exports_external.array(exports_external.string().min(1).regex(/^[\w./-]+$/)).optional().describe("Extra terms dropped from the BM25 recall query, on top of the " + "built-in English stopword list. For BANK-SPECIFIC " + "high-document-frequency words a generic stoplist cannot know " + "about: on `overlord`, `switchroom` matches 20% of the bank and " + "`agent` another 20%, purely because that is what the corpus is " + "about, and each such term drags tens of thousands of rows into " + "the ranking. Defaults to []."),
       request_timeout_seconds: exports_external.number().int().min(1).optional().describe("Per-bank HTTP read timeout, in seconds, for one recall " + "request. Even parallelised, each bank carries its own deadline " + "so ONE hung bank returns empty instead of consuming the shared " + "deadline and starving its siblings. The plugin default is 12 " + "(raised from a hardcoded 8 in #3757, which fired on 96.8% of " + "one agent's own-bank recalls). Switchroom defaults it to the " + "effective `parallel_deadline_seconds` instead \u2014 10 at the " + "shipped ceiling \u2014 because the shared fan-out deadline is " + "already the tighter outer guard, so a per-bank value above it " + "can never bind. An explicitly configured value above the " + "effective deadline is clamped down to it, and the clamp is " + "reported."),
-      own_bank_min_slots: exports_external.number().int().min(0).optional().describe("Slots inside `max_memories` reserved as a FLOOR for the agent's " + "own bank when recall fans out to more than one bank. The merged " + "set is sorted globally by relevance and head-sliced, which is " + "winner-take-all across banks: when both banks return more " + "candidates than the cap, one bank's score distribution can fill " + "every slot and the agent gets a dossier about its operator with " + "none of its own session memory. A floor, not a quota: at most " + "this many slots, only if the own bank returned that many, and " + "only up to HALF the cap shared with `additional_bank_min_slots` " + "\u2014 the rest is always won on pure relevance, so composition still " + "moves with the scores. Fixes score-based crowd-out only; a " + "timed-out bank returns no candidates and reservation is a no-op " + "there. 0 disables (default). Switchroom-managed agents use 2 " + "against the fleet-deployed cap of 6."),
-      additional_bank_min_slots: exports_external.number().int().min(0).optional().describe("Slots inside `max_memories` reserved as a FLOOR for the " + "additional (profile / shared / sender) banks. Symmetric with " + "`own_bank_min_slots` \u2014 same floor-not-quota semantics, and the " + "two share the same half-of-cap reservation budget. When they sum " + "above that budget the own-bank floor is honoured first. 0 " + "disables (default). Switchroom-managed agents use 1 against the " + "fleet-deployed cap of 6. Observe `injected_own_bank_count` / " + "`injected_additional_bank_count` via " + "`switchroom memory recall-log`."),
+      own_bank_min_slots: exports_external.number().int().min(0).optional().describe("Slots inside `max_memories` reserved as a FLOOR for the agent's " + "own bank when recall fans out to more than one bank. The merged " + "set is sorted globally by relevance and head-sliced, which is " + "winner-take-all across banks: when both banks return more " + "candidates than the cap, one bank's score distribution can fill " + "every slot and the agent gets a dossier about its operator with " + "none of its own session memory. A floor, not a quota: at most " + "this many slots, only if the own bank returned that many, and " + "only up to HALF the cap shared with `additional_bank_min_slots` " + "\u2014 the rest is always won on pure relevance, so composition still " + "moves with the scores. Fixes score-based crowd-out only; a " + "timed-out bank returns no candidates and reservation is a no-op " + "there. 0 disables (default). Switchroom-managed agents DERIVE this " + "default from the count cap (\u2248 \u2153 of the effective `max_memories`, " + "floored at 1) so it tracks the cap instead of going stale when the " + "fleet raises it; an explicit value set here still wins over that " + "derived default."),
+      additional_bank_min_slots: exports_external.number().int().min(0).optional().describe("Slots inside `max_memories` reserved as a FLOOR for the " + "additional (profile / shared / sender) banks. Symmetric with " + "`own_bank_min_slots` \u2014 same floor-not-quota semantics, and the " + "two share the same half-of-cap reservation budget. When they sum " + "above that budget the own-bank floor is honoured first. 0 " + "disables (default). Switchroom-managed agents DERIVE this default " + "from the count cap (\u2248 \u2159 of the effective `max_memories`, floored " + "at 1) so it tracks the cap instead of going stale; an explicit " + "value set here still wins. Observe `injected_own_bank_count` / " + "`injected_additional_bank_count` via " + "`switchroom memory recall-log`."),
       min_score: exports_external.number().min(0).optional().describe("Absolute floor on a memory's engine relevance score " + "(`scores.final`) for it to be injected. 0 disables (default, " + "and the shipped fleet behaviour). Exists for one measured " + "failure: when the agent's own bank times out, recall still " + "injects side-bank residue under the banner 'Relevant memories " + "from past conversations' \u2014 98.4% of degraded turns have a best " + "injected score below 0.01, against 28.4% of healthy ones. Six " + "noise memories are worse than none, because the agent cannot " + "tell them apart. Below-floor results are dropped BEFORE " + "rendering, and when the floor empties the set the turn says so " + "rather than going silent. Do NOT read this as a general " + "precision control: `scores.final` is not calibrated across " + "queries, and #3761 measured that an unconditional 0.01 floor " + "empties ~28% of HEALTHY recalls \u2014 which is why " + "`min_score_scope` defaults to degraded turns only. Observe " + "`dropped_below_min_score` via `switchroom memory recall-log`."),
       min_score_scope: exports_external.enum(["degraded", "all"]).optional().describe('Which turns `min_score` binds on. "degraded" (default) \u2014 only ' + "turns where the agent's OWN bank timed out or was unreachable, " + "the population where a below-floor score actually predicts " + "noise and where the agent already receives the degraded-recall " + 'disclosure. "all" \u2014 every turn; only for an operator who has ' + "measured their own bank's score distribution, since it " + "re-creates the empty-recall failure of #3541 at any floor " + "calibrated on degraded data. No effect while `min_score` is 0."),
       types: exports_external.array(exports_external.string()).optional().describe("Hindsight fact types to recall. Switchroom default is " + '["world", "experience", "observation"] \u2014 the synthesized ' + "`observation` tier is on by default. Set to " + '["world", "experience"] to opt out of observation-backed ' + "recall for this agent (or fleet-wide under defaults)."),
       additional_banks: exports_external.array(exports_external.string()).optional().describe("Extra Hindsight banks to recall from on every turn, merged into " + "the agent's own bank results \u2014 e.g. a shared operator/household " + "profile bank authored via `switchroom memory profile`. Each is " + "recalled with the `request_timeout_seconds` per-bank timeout " + "(defaults to the effective `parallel_deadline_seconds`, 10s at " + "the shipped ceiling) and is non-fatal on failure. Stays " + "within the single tenant: all banks are the operator's data, in " + "the operator's Hindsight instance (see the `single-tenant` " + "invariant). Defaults to [] (no extra banks)."),
       sender_banks: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Per-speaker recall routing: a map of Telegram sender \u2192 extra " + "recall bank. When a message arrives, the agent also recalls the " + "speaker's bank (matched by Telegram username \u2014 a leading @ is " + "optional \u2014 or numeric user_id), merged " + "into its own results \u2014 so each trusted user gets their own " + "profile context. Additive recall scoping within the single " + "tenant: never an access boundary (who may drive an agent stays " + "the per-agent user assignment in `access.allowFrom`). Author the " + "banks via `switchroom memory profile`."),
       skip_trivial: exports_external.boolean().optional().describe("Skip recall on plausibly-stateless trivial turns (time/date/" + "greeting). Switchroom default true \u2014 saves the recall arm + " + "injected tokens on turns that never need memory, guarded so it " + "never skips a turn that references user/project/session state. " + "Set false to always run recall."),
-      budget: exports_external.enum(["low", "mid", "high"]).optional().describe('How hard Hindsight searches. "low" (switchroom default) = ' + 'vector retrieval only, ~1-2s. "mid" adds the LLM rerank pass ' + "and measured ~5s of hook latency on real fleet turns \u2014 the " + "second-largest contributor to perceived dead air after model " + 'TTFT. "high" is thorough and slower still. Raise it for an ' + "agent whose recall quality matters more than its reply latency " + "(a research or audit role); leave it at low for chat."),
+      budget: exports_external.enum(["low", "mid", "high"]).optional().describe("How deep Hindsight's recall search goes. It tunes the CANDIDATE-" + "POOL depth retrieved before reranking \u2014 low (switchroom default) " + "= 100, mid = 300, high = 1000 candidates. The local cross-encoder " + "reranker (ms-marco-MiniLM) runs at EVERY tier; budget does not " + "gate it on or off, and there is no LLM rerank pass in the recall " + "path (the LLM serves reflect/retain/consolidation, not recall " + "ranking). Higher tiers cost more latency purely from the deeper " + "pool: mid measured ~5s of hook latency on real fleet turns (3\u00d7 " + "the retrieval+rerank pool, not an added model call), the second-" + "largest contributor to perceived dead air after model TTFT. Raise " + "it for an agent whose recall quality matters more than its reply " + "latency (a research or audit role); leave it at low for chat."),
       max_tokens: exports_external.number().int().min(1).optional().describe("Token budget for the injected memory block. Default 1024. This " + "is the TOKEN bound; `max_memories` is the separate COUNT bound " + "and the tighter of the two wins. Raise it only alongside " + "`max_memories` \u2014 on its own it buys nothing once the count cap " + "binds."),
       prefer_observations: exports_external.boolean().optional().describe("Bias recall toward the synthesized `observation` tier, " + "backfilling the slots freed by superseded raw facts for denser " + "coverage inside the same budget. Default true. Set false to " + "rank raw `world`/`experience` facts on equal footing \u2014 useful " + "when auditing what the consolidation engine actually stored, or " + "if a bank's observations are stale."),
       context_turns: exports_external.number().int().min(1).optional().describe("How many recent human turns are composed into the recall query. " + 'Default 2, so a bare follow-up ("and the port?") embeds with ' + "its antecedent instead of recalling on the pronoun alone. 1 = " + "the latest turn only. Raising it costs BM25 terms, which is the " + "real recall cost driver \u2014 `query_max_tokens` still bounds the " + "result, so a large value mostly shifts which terms survive."),
@@ -87850,7 +87850,7 @@ init_generation_stamp();
 var HINDSIGHT_RECALL_TAG_WEIGHT_SEED = Object.freeze({ sidechain: 0.8 });
 var HINDSIGHT_RECALL_PROMPT_PREAMBLE_DEFAULT = "Relevant memories from past conversations (prioritize recent when " + "conflicting). Only use memories that are directly useful to continue " + "this conversation; ignore the rest:";
 var RECALL_PASSTHROUGH_DEFAULTS = Object.freeze({
-  budget: "low",
+  budget: "mid",
   maxTokens: 1024,
   preferObservations: true,
   contextTurns: 2,
@@ -103483,10 +103483,10 @@ function startOutboxSweep(deps) {
 }
 
 // ../src/build-info.ts
-var VERSION2 = "0.20.20";
-var COMMIT_SHA = "f444ea4a";
-var COMMIT_DATE = "2026-08-09T02:39:19Z";
-var LATEST_PR = 4564;
+var VERSION2 = "0.20.22";
+var COMMIT_SHA = "ad3f50bd";
+var COMMIT_DATE = "2026-08-09T18:15:22Z";
+var LATEST_PR = 4577;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts

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