switchroom 0.20.21 → 0.20.22

package/dist/auth-broker/index.js

@@ -19033,7 +19033,7 @@ function allocateAgentUid(name) {
 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,

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.20.21", COMMIT_SHA = "23a6ce6c";
+var VERSION = "0.20.22", COMMIT_SHA = "ad3f50bd";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -21194,7 +21194,7 @@ var init_hindsight_recall_passthrough = __esm(() => {
   RECALL_BUDGETS = ["low", "mid", "high"];
   RECALL_TAGS_MATCH_MODES = ["any", "all", "any_strict", "all_strict"];
   RECALL_PASSTHROUGH_DEFAULTS = Object.freeze({
-    budget: "low",
+    budget: "mid",
     maxTokens: 1024,
     preferObservations: true,
     contextTurns: 2,

package/dist/host-control/main.js

@@ -21565,13 +21565,13 @@ function allocateAgentUid(name) {
 }
 
 // src/build-info.ts
-var VERSION = "0.20.21";
+var VERSION = "0.20.22";
 
 // src/setup/hindsight-recall-passthrough.ts
 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,

package/dist/vault/approvals/kernel-server.js

@@ -19466,7 +19466,7 @@ function allocateAgentUid(name) {
 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,

package/dist/vault/broker/server.js

@@ -19707,7 +19707,7 @@ function allocateAgentUid(name) {
 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,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.20.21",
+  "version": "0.20.22",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

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

@@ -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.21";
-var COMMIT_SHA = "23a6ce6c";
-var COMMIT_DATE = "2026-08-09T06:14:45Z";
-var LATEST_PR = 4569;
+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()

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

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

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

@@ -565,6 +565,119 @@ class TestObservationScopes(DurabilityTestBase):
         self.assertTrue(all(s is None for s in self.daemon.observation_scopes_seen))
 
 
+class TestDrainAdvancesWatermark(DurabilityTestBase):
+    """switchroom #4571 — the drain must advance the transcript watermark for a
+    reconcile-sourced slice it confirms durable, so reconcile stops re-deriving
+    and re-enqueueing the identical tail on every boot (the recurring
+    ``pending-retains`` spike). And it must NOT advance while an earlier sibling
+    of the same session is still queued (the no-loss guard).
+    """
+
+    # -- the fix: an enqueued tail, once drained, advances the watermark --------
+    def test_enqueued_tail_drained_advances_watermark_and_stops_reenqueue(self):
+        # This test FAILS on HEAD: the drain never commits the watermark for an
+        # enqueued reconcile slice, so `watermark.load` stays None after the
+        # drain and the second reconcile re-enqueues the same tail.
+        session = "drainA"
+        tpath = os.path.join(self.transcripts, f"{session}.jsonl")
+        _write_transcript(tpath, 3, session_prefix=session)
+        hook = {"session_id": session, "transcript_path": tpath, "cwd": "/x"}
+
+        # Force the out-of-lookback ENQUEUE path (no inline POST): lookback=0
+        # makes every transcript "too old", so reconcile enqueues the full tail
+        # and defers it to the drain — exactly the path that never committed.
+        with mock.patch.dict(os.environ, {"HINDSIGHT_RECONCILE_LOOKBACK_H": "0"}):
+            s1 = reconcile_tail.reconcile(self._config(), hook_input=hook)
+        self.assertEqual(s1["enqueued"], 1)
+        self.assertEqual(len(self._pending_entries()), 1)
+        # Nothing posted inline, so the watermark is still unset.
+        self.assertIsNone(watermark.load(session))
+
+        # Drain against a healthy daemon: the tail lands durably AND (the fix)
+        # the watermark advances to the transcript tail.
+        from drain_pending import drain
+        drain(self._config())
+        self.assertEqual(len(self._pending_entries()), 0)
+        wm = watermark.load(session)
+        self.assertIsNotNone(
+            wm,
+            "drain must advance the watermark for a confirmed-durable reconcile "
+            "tail (#4571) — without it, reconcile re-enqueues every boot",
+        )
+        self.assertEqual(wm["last_uuid"], f"{session}-a2")
+
+        # Second reconcile pass (still out of lookback) is now skipped_clean:
+        # the tail is watermarked, so it is NOT re-derived or re-enqueued.
+        with mock.patch.dict(os.environ, {"HINDSIGHT_RECONCILE_LOOKBACK_H": "0"}):
+            s2 = reconcile_tail.reconcile(self._config(), hook_input=hook)
+        self.assertEqual(s2["skipped_clean"], 1)
+        self.assertEqual(s2["enqueued"], 0)
+        self.assertEqual(len(self._pending_entries()), 0)
+
+    # -- the no-loss guard: an earlier sibling blocks the tail's advance --------
+    def test_tail_drain_does_not_advance_while_earlier_sibling_queued(self):
+        session = "drainB"
+        ordered = [
+            f"{session}-u0", f"{session}-a0", f"{session}-u1",
+            f"{session}-a1", f"{session}-u2", f"{session}-a2",
+        ]
+        older_doc = f"{session}-r{session}-u0-{session}-a1"
+        tail_doc = f"{session}-r{session}-u0-{session}-a2"
+
+        from lib import pending
+
+        def _payload(doc, content, last_uuid, is_tail):
+            return {
+                "api_url": "http://fake", "api_token": None, "bank_id": "test-bank",
+                "content": content, "document_id": doc, "context": "claude-code",
+                "metadata": {}, "tags": [], "observation_scopes": None,
+                "reconcile_session_id": session,
+                "reconcile_last_uuid": last_uuid,
+                "reconcile_ordered_uuids": ordered,
+                "reconcile_is_tail": is_tail,
+            }
+
+        # The earlier remainder (mid-transcript last_uuid) is enqueued FIRST so
+        # it sorts ahead of the tail in the oldest-first drain order.
+        pending.enqueue(
+            _payload(older_doc, "older remainder turns", f"{session}-a1", False),
+            RuntimeError("reconcile deferred"),
+        )
+        import time as _t
+        _t.sleep(0.002)
+        pending.enqueue(
+            _payload(tail_doc, "tail turns", f"{session}-a2", True),
+            RuntimeError("reconcile deferred"),
+        )
+        self.assertEqual(len(self._pending_entries()), 2)
+
+        # Upstream: the tail commits, but the earlier remainder still fails, so
+        # it stays queued through the whole drain run.
+        posted = []
+
+        def fake_retain(self_c, bank_id=None, content=None,
+                        document_id="conversation", **kw):
+            posted.append(document_id)
+            if document_id == older_doc:
+                raise RuntimeError("earlier remainder still failing upstream")
+            return {"ok": True}
+
+        from drain_pending import drain
+        with mock.patch.object(HindsightClient, "retain", fake_retain):
+            drain(self._config())
+
+        # The tail POST succeeded and its entry was retired ...
+        self.assertIn(tail_doc, posted)
+        remaining = [e["document_id"] for _p, e in self._pending_entries()]
+        self.assertNotIn(tail_doc, remaining)
+        # ... but the watermark did NOT advance: an earlier, still-unconfirmed
+        # sibling of the same session is queued, and advancing past it would
+        # risk silent loss of the remainder (#4571 no-loss guard).
+        self.assertIsNone(watermark.load(session))
+        # The earlier remainder is still queued (its POST failed).
+        self.assertIn(older_doc, remaining)
+
+
 def _stdin(obj):
     import io
     return io.StringIO(json.dumps(obj))

package/vendor/hindsight-memory/settings.json

@@ -6,7 +6,7 @@
   "autoRecall": true,
   "autoRetain": true,
   "retainMode": "full-session",
-  "recallBudget": "low",
+  "recallBudget": "mid",
   "recallMaxTokens": 1024,
   "recallMaxMemories": 12,
   "recallTypes": ["world", "experience"],
@@ -26,7 +26,7 @@
   "retainToolCalls": true,
   "retainTags": ["{session_id}"],
   "retainMetadata": {},
-  "retainContext": "claude-code",
+  "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).",
   "hindsightApiToken": null,
   "apiPort": 9077,
   "daemonIdleTimeout": 0,

package/vendor/hindsight-memory/tests/test_config.py

@@ -42,8 +42,13 @@ class TestLoadConfig:
         cfg = load_config()
         assert cfg["autoRecall"] is True
         assert cfg["autoRetain"] is True
-        assert cfg["recallBudget"] == "low"
+        assert cfg["recallBudget"] == "mid"
         assert cfg["retainEveryNTurns"] == 10
+        # Switchroom — speaker-aware retain context template (resolved
+        # per-retain by build_retain_payload). Must carry the {agent} and
+        # {bank_id} slots so the consolidation LLM can attribute speakers.
+        assert "{agent}" in cfg["retainContext"]
+        assert "{bank_id}" in cfg["retainContext"]
 
     def test_settings_json_overrides_defaults(self, tmp_path, monkeypatch):
         monkeypatch.setenv("CLAUDE_PLUGIN_ROOT", str(tmp_path))
@@ -75,7 +80,7 @@ class TestLoadConfig:
         monkeypatch.setenv("CLAUDE_PLUGIN_ROOT", str(tmp_path))
         (tmp_path / "settings.json").write_text("not valid json{{")
         cfg = load_config()
-        assert cfg["recallBudget"] == "low"  # default still applies
+        assert cfg["recallBudget"] == "mid"  # default still applies
 
     def test_null_values_in_settings_json_not_applied(self, tmp_path, monkeypatch):
         monkeypatch.setenv("CLAUDE_PLUGIN_ROOT", str(tmp_path))
@@ -112,7 +117,7 @@ class TestLoadConfig:
         # HOME points to tmp_path where no .hindsight/claude-code.json exists
         monkeypatch.setenv("HOME", str(tmp_path))
         cfg = load_config()
-        assert cfg["recallBudget"] == "low"  # default
+        assert cfg["recallBudget"] == "mid"  # default
 
     def test_env_var_wins_over_user_config(self, tmp_path, monkeypatch):
         plugin_root = tmp_path / "plugin"

package/vendor/hindsight-memory/tests/test_hooks.py

@@ -833,6 +833,11 @@ class TestRetainHook:
             assert captured["body"].get("async") is False
 
     def test_retain_includes_context_label(self, monkeypatch, tmp_path):
+        # Switchroom — the default retainContext is now a speaker-aware
+        # template resolved per-retain: {agent} from SWITCHROOM_AGENT_NAME
+        # and {bank_id} from the target bank. Pin a known agent name so the
+        # resolved label is deterministic regardless of the ambient env.
+        monkeypatch.setenv("SWITCHROOM_AGENT_NAME", "testbot")
         messages = [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "world"}]
         transcript = make_transcript_file(tmp_path, messages)
         hook_input = make_hook_input(transcript_path=transcript)
@@ -846,7 +851,11 @@ class TestRetainHook:
         _run_hook("retain", hook_input, monkeypatch, tmp_path, urlopen_side_effect=capture)
 
         if "body" in captured:
-            assert captured["body"]["items"][0]["context"] == "claude-code"
+            context = captured["body"]["items"][0]["context"]
+            # Template placeholders must be resolved (no literal braces left)
+            # and the agent name must be filled in from the env.
+            assert "{" not in context and "}" not in context
+            assert "agent 'testbot'" in context
 
     def test_disabled_auto_retain_does_not_call_api(self, monkeypatch, tmp_path):
         (tmp_path / "plugin_root").mkdir(exist_ok=True)

package/vendor/hindsight-memory/tests/test_retain_context.py

@@ -0,0 +1,69 @@
+"""Tests for build_retain_payload's speaker-aware retainContext template.
+
+Switchroom — retainContext is no longer the opaque constant "claude-code".
+It is a template resolved per-retain by build_retain_payload's
+_resolve_template, filling {agent} from SWITCHROOM_AGENT_NAME and {bank_id}
+from the target bank so the consolidation LLM knows whose first-person
+experience each transcript line is.
+"""
+
+import pytest
+
+from retain import build_retain_payload
+
+MESSAGES = [
+    {"role": "user", "content": "human fact"},
+    {"role": "assistant", "content": "agent action"},
+]
+
+
+def _build(config, monkeypatch, agent="klanker", bank_id="klanker-main"):
+    if agent is None:
+        monkeypatch.delenv("SWITCHROOM_AGENT_NAME", raising=False)
+    else:
+        monkeypatch.setenv("SWITCHROOM_AGENT_NAME", agent)
+    result = build_retain_payload(
+        config,
+        session_id="sess-1",
+        messages_to_retain=MESSAGES,
+        all_messages=MESSAGES,
+        bank_id=bank_id,
+        api_url="http://localhost:9077",
+        api_token=None,
+    )
+    assert result is not None
+    return result["payload"]["context"]
+
+
+def test_context_template_resolves_agent_and_bank(monkeypatch):
+    context = _build(
+        {"retainContext": "agent '{agent}' ({bank_id})"},
+        monkeypatch,
+        agent="klanker",
+        bank_id="klanker-main",
+    )
+    assert context == "agent 'klanker' (klanker-main)"
+
+
+def test_context_template_agent_empty_outside_switchroom(monkeypatch):
+    context = _build(
+        {"retainContext": "agent '{agent}'"},
+        monkeypatch,
+        agent=None,
+    )
+    assert context == "agent ''"
+
+
+def test_context_default_is_speaker_aware_and_resolved(monkeypatch):
+    # No retainContext in config → build_retain_payload falls back to the
+    # "claude-code" literal, which carries no template vars and is returned
+    # verbatim. The speaker-aware default lives in settings.json / config.py
+    # DEFAULTS and is exercised by test_config; here we assert the fallback
+    # path stays byte-stable.
+    context = _build({}, monkeypatch)
+    assert context == "claude-code"
+
+
+def test_context_plain_string_passthrough(monkeypatch):
+    context = _build({"retainContext": "just plain text"}, monkeypatch)
+    assert context == "just plain text"