switchroom 0.16.47 → 0.17.1

package/vendor/hindsight-memory/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 ## [Unreleased]
 
+### Changed (switchroom divergence)
+
+- **retain.py: decouple chunked window-slicing from the `retainEveryNTurns > 1`
+  throttle** (switchroom Phase 6b). Previously the chunked sliding-window only
+  applied when `retainEveryNTurns > 1`; with `retainEveryNTurns=1` (switchroom
+  sets this in `scaffold.ts` for every-turn crash durability) chunked mode fell
+  through to full-session and re-consolidated the entire accumulated transcript
+  on every Stop fire. Window selection is now extracted into a pure
+  `select_retain_window()` helper and slices a window of
+  `max(retainEveryNTurns, 1) + retainOverlapTurns` turns whenever
+  `retainMode == "chunked"`, independent of the throttle. The throttle-skip
+  logic (`retain_every_n > 1` firing cadence) is unchanged, so `> 1` behaviour
+  and the full-session default are equivalent. This is a deliberate switchroom
+  divergence from pristine vendor and is a **candidate to upstream to
+  vectorize-io/hindsight** — decoupling *what* to retain from *whether* to fire
+  this turn is a general improvement, not switchroom-specific.
+
+- **content.py: `slice_last_turns_by_user_boundary()` counts genuine HUMAN
+  turns only** (switchroom Phase 6b, adversarial-review fix). Claude Code emits
+  tool results as `role="user"` messages whose content is a list of
+  `tool_result` blocks. The boundary counter treated every `role="user"`
+  message as a turn, so on a tool-heavy turn (≥N sequential tool rounds) a
+  fixed-size retain window filled with `tool_result` messages and pushed the
+  actual human message OUTSIDE the window — silently dropping the fact from
+  that fire and every later fire (whose window starts even further away), so it
+  was never retained; on restart the fact was gone. A message whose content is
+  entirely `tool_result` blocks is now skipped as a boundary
+  (`_is_tool_result_only_user_message`), so "window = N turns" means N *human*
+  turns regardless of tool volume. Affects both the retain window-slice and the
+  recall context-slice (both want N human turns). **Candidate to upstream** —
+  the same silent-loss bug exists in vendor's own `retainEveryNTurns > 1`
+  chunked path. NOTE: switchroom never ran chunked before Phase 6b, so this
+  changes no previously-exercised switchroom behaviour.
+
+- **retain.py: SessionEnd `force=True` widens chunked mode to a full-session
+  sweep** (switchroom Phase 6b, belt-and-braces). Per-turn fires still slice
+  the window; the single forced retain at SessionEnd
+  (`session_end.py` → `run_retain(force=True)`) now retains the whole session
+  in chunked mode, guaranteeing a graceful shutdown always flushes everything
+  even if per-turn windowing had an edge. Costs one full sweep per session (at
+  end), not per turn.
+
+### Ported from upstream (vectorize-io/hindsight, `hindsight-integrations/claude-code/`)
+
+- `c5a61db2b` — raise `_check_health` default timeout 2s→10s in
+  `scripts/lib/daemon.py` to stop the busy-daemon restart/kill loop
+  (applied clean; codex-integration hunk not applicable).
+- `3d6c2ba8b` — label "Current time" as UTC in the recall context block
+  (`lib/content.py:format_current_time`), so client LLMs in non-UTC
+  timezones don't misread the timestamp as local time.
+- `962140eef` — recall tag filters: `recallTags`, `recallTagsMatch`,
+  `recallTagGroups`, plus per-additional-bank overrides via
+  `recallAdditionalBankFilters`. Hand-ported into the switchroom recall.py
+  rewrite: filters compose with sender-bank routing (per-bank overrides
+  apply to sender banks too) and are part of the recall cache key
+  (`_tag_filter_sig`) so a filter change can't serve stale cached results.
+  Note: because the key now joins an extra part (empty string when filters
+  are unused), every cache key rotates ONCE across this upgrade boundary —
+  the first recall per session after upgrading is a cache miss. Within a
+  version, keys are unchanged as long as filters stay unused.
+- `55ef70679` — optional `requestTimeoutSeconds` /
+  `HINDSIGHT_REQUEST_TIMEOUT_SECONDS` global request-timeout override in
+  `HindsightClient` (adapted to our `_request`). Wired into retain.py only;
+  recall.py deliberately keeps its own 8s hook-budget timeout. Upstream's
+  mcp_server.py hunks skipped (not vendored).
+
 ### Added
 
 - `{user_id}` template variable for `retainTags` and `retainMetadata`, resolved

package/vendor/hindsight-memory/README.md

@@ -186,6 +186,11 @@ Auto-recall runs on every user prompt. It queries Hindsight for relevant memorie
 | `recallContextTurns` | `HINDSIGHT_RECALL_CONTEXT_TURNS` | `1` | How many prior conversation turns to include when composing the recall query. `1` = only the latest user message; higher values give more context but may dilute the query. |
 | `recallMaxQueryChars` | `HINDSIGHT_RECALL_MAX_QUERY_CHARS` | `800` | Maximum character length of the query sent to Hindsight. Longer queries are truncated. |
 | `recallRoles` | — | `["user", "assistant"]` | Which message roles to include when building the recall query from prior turns. |
+| `recallTags` | `HINDSIGHT_RECALL_TAGS` | `[]` | Optional tags to pass to the recall API, such as `["memory_type:rule"]`. The env var accepts JSON or a comma-separated list. |
+| `recallTagsMatch` | `HINDSIGHT_RECALL_TAGS_MATCH` | `"any"` | Tag matching mode used with `recallTags` or `recallTagGroups`: `"any"`, `"all"`, `"any_strict"`, or `"all_strict"`. |
+| `recallTagGroups` | `HINDSIGHT_RECALL_TAG_GROUPS` | `null` | Optional compound tag filter passed through to the recall API. The env var must be JSON. |
+| `recallAdditionalBankFilters` | `HINDSIGHT_RECALL_ADDITIONAL_BANK_FILTERS` | `{}` | Optional per-bank tag filter overrides for banks listed in `recallAdditionalBanks`, keyed by bank ID. Each value may set `recallTags`, `recallTagsMatch`, and `recallTagGroups`. The env var must be JSON. |
+| `requestTimeoutSeconds` | `HINDSIGHT_REQUEST_TIMEOUT_SECONDS` | unset | Optional global HTTP request timeout override (seconds) for retain and API calls. The recall hook keeps its own 8s hook-budget timeout regardless. |
 | `recallPromptPreamble` | — | built-in string | Text placed above the recalled memories in the injected context block. Customize this to change how Claude interprets the memories. |
 
 ---

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

@@ -44,9 +44,29 @@ def _validate_api_url(url: str) -> str:
 class HindsightClient:
     """HTTP client for the Hindsight API."""
 
-    def __init__(self, api_url: str, api_token: Optional[str] = None):
+    def __init__(
+        self,
+        api_url: str,
+        api_token: Optional[str] = None,
+        request_timeout_override: Optional[int] = None,
+    ):
         self.api_url = _validate_api_url(api_url)
         self.api_token = api_token
+        self.request_timeout_override = request_timeout_override
+
+    def _resolve_timeout(self, timeout: int) -> int:
+        """Return the override if configured, otherwise the caller's timeout.
+
+        Upstream 55ef70679. NOTE: recall.py deliberately does not pass the
+        override — its 8s timeout is a hook-budget invariant.
+
+        The override is clamped to >= 1: a zero/negative env value would
+        otherwise reach urlopen as a nonsensical timeout (0 fails every
+        request immediately), turning a config typo into a dead client.
+        """
+        if self.request_timeout_override is None:
+            return timeout
+        return max(1, self.request_timeout_override)
 
     def _headers(self) -> dict:
         headers = {
@@ -58,6 +78,7 @@ class HindsightClient:
         return headers
 
     def _request(self, method: str, path: str, body: Optional[dict] = None, timeout: int = DEFAULT_TIMEOUT) -> dict:
+        timeout = self._resolve_timeout(timeout)
         url = f"{self.api_url}{path}"
         data = json.dumps(body).encode() if body else None
         req = urllib.request.Request(url, data=data, headers=self._headers(), method=method)
@@ -100,6 +121,9 @@ class HindsightClient:
         max_tokens: int = 1024,
         budget: str = "mid",
         types: Optional[list] = None,
+        tags: Optional[list] = None,
+        tags_match: Optional[str] = None,
+        tag_groups: Optional[object] = None,
         timeout: int = 10,
     ) -> dict:
         """Recall memories from a bank.
@@ -115,6 +139,12 @@ class HindsightClient:
             body["budget"] = budget
         if types:
             body["types"] = types
+        if tags:
+            body["tags"] = tags
+        if tags_match:
+            body["tags_match"] = tags_match
+        if tag_groups:
+            body["tag_groups"] = tag_groups
         return self._request("POST", path, body, timeout=timeout)
 
     def retain(

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

@@ -40,6 +40,12 @@ DEFAULTS = {
     "recallContextTurns": 1,
     "recallMaxQueryChars": 800,
     "recallRoles": ["user", "assistant"],
+    # Upstream 962140eef — optional recall tag filters passed through to the
+    # recall API, plus per-additional-bank overrides keyed by bank ID.
+    "recallTags": [],
+    "recallTagsMatch": "any",
+    "recallTagGroups": None,
+    "recallAdditionalBankFilters": {},
     "recallPromptPreamble": (
         "Relevant memories from past conversations (prioritize recent when "
         "conflicting). Only use memories that are directly useful to continue "
@@ -63,6 +69,12 @@ DEFAULTS = {
     "daemonIdleTimeout": 0,
     "embedVersion": "latest",
     "embedPackagePath": None,
+    # Upstream 55ef70679 — optional global HTTP request timeout override
+    # (seconds). None = keep each call's own default. NOTE: switchroom's
+    # recall.py deliberately does NOT wire this override into its client —
+    # recall carries its own 8s hook-budget timeout (see recall.py). This
+    # mainly benefits retain's 15s timeout on slow/loaded servers.
+    "requestTimeoutSeconds": None,
     # Bank
     "bankId": None,
     "bankIdPrefix": "",
@@ -109,8 +121,16 @@ ENV_OVERRIDES = {
     "HINDSIGHT_RECALL_SKIP_TRIVIAL": ("recallSkipTrivial", bool),
     "HINDSIGHT_RECALL_MAX_QUERY_CHARS": ("recallMaxQueryChars", int),
     "HINDSIGHT_RECALL_CONTEXT_TURNS": ("recallContextTurns", int),
+    # Upstream 962140eef — recall tag filters. The tags env var accepts JSON
+    # or a comma-separated list; the others must be JSON.
+    "HINDSIGHT_RECALL_TAGS": ("recallTags", list),
+    "HINDSIGHT_RECALL_TAGS_MATCH": ("recallTagsMatch", str),
+    "HINDSIGHT_RECALL_TAG_GROUPS": ("recallTagGroups", dict),
+    "HINDSIGHT_RECALL_ADDITIONAL_BANK_FILTERS": ("recallAdditionalBankFilters", dict),
     "HINDSIGHT_API_PORT": ("apiPort", int),
     "HINDSIGHT_DAEMON_IDLE_TIMEOUT": ("daemonIdleTimeout", int),
+    # Upstream 55ef70679 — global request timeout override.
+    "HINDSIGHT_REQUEST_TIMEOUT_SECONDS": ("requestTimeoutSeconds", int),
     "HINDSIGHT_EMBED_VERSION": ("embedVersion", str),
     "HINDSIGHT_EMBED_PACKAGE_PATH": ("embedPackagePath", str),
     "HINDSIGHT_DYNAMIC_BANK_ID": ("dynamicBankId", bool),
@@ -131,8 +151,27 @@ def _cast_env(value: str, typ):
         if typ is float:
             return float(value)
         if typ is list:
-            # Comma-separated → list of trimmed, non-empty strings.
-            return [t.strip() for t in value.split(",") if t.strip()]
+            # JSON list first (upstream 962140eef). A value that parses as
+            # JSON but is NOT a list (e.g. `42`, `"x"`, `{}`) is a config
+            # mistake, not a comma-separated string — return None so the
+            # default is kept (matches upstream; fail-open). Only values
+            # that don't parse as JSON at all take the comma-split path.
+            try:
+                parsed = json.loads(value)
+            except ValueError:
+                if value.lstrip().startswith(("[", "{")):
+                    # Looks like intended JSON but doesn't parse —
+                    # malformed config, not a comma list. Keep default.
+                    return None
+                # Comma-separated → list of trimmed, non-empty strings.
+                return [t.strip() for t in value.split(",") if t.strip()]
+            return parsed if isinstance(parsed, list) else None
+        if typ is dict:
+            # JSON only (dict or list accepted — tag_groups may be a list).
+            parsed = json.loads(value)
+            if isinstance(parsed, (dict, list)):
+                return parsed
+            return None
         return value
     except (ValueError, AttributeError):
         return None

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

@@ -167,13 +167,48 @@ def truncate_recall_query(query: str, latest_query: str, max_chars: int) -> str:
 # ---------------------------------------------------------------------------
 
 
+def _is_tool_result_only_user_message(message: dict) -> bool:
+    """True when a ``role="user"`` message carries ONLY tool_result blocks.
+
+    SWITCHROOM DIVERGENCE (candidate to upstream to vectorize-io/hindsight):
+    Claude Code emits tool results as ``role="user"`` messages whose content
+    is a list of ``{"type": "tool_result", ...}`` blocks — they are NOT
+    human turns. A genuine human turn has text (a string, or a content list
+    with at least one non-tool_result block, e.g. ``{"type": "text"}`` or an
+    image). Treating tool_result messages as turn boundaries lets a tool-heavy
+    turn (≥N sequential tool rounds) fill a fixed-size retain window with
+    tool_result messages and push the actual human message OUTSIDE the window
+    — silently dropping the fact from that fire, and from every later fire
+    (whose window starts even further from the human message). On restart the
+    fact is gone. This helper lets the boundary counter skip those messages so
+    "window = N turns" means N *human* turns regardless of tool volume.
+    """
+    if message.get("role") != "user":
+        return False
+    content = message.get("content")
+    if isinstance(content, list):
+        blocks = [b for b in content if isinstance(b, dict)]
+        # A non-empty content list that is ENTIRELY tool_result blocks.
+        if blocks and all(b.get("type") == "tool_result" for b in blocks):
+            return True
+    return False
+
+
 def slice_last_turns_by_user_boundary(messages: list, turns: int) -> list:
     """Slice messages to the last N turns, where a turn starts at a user message.
 
     Port of: sliceLastTurnsByUserBoundary() in index.js
 
-    Walks backward counting user messages as turn boundaries. Returns
-    messages from the Nth user boundary to the end.
+    Walks backward counting GENUINE HUMAN user messages as turn boundaries.
+    Returns messages from the Nth human boundary to the end.
+
+    SWITCHROOM DIVERGENCE (candidate to upstream): tool_result messages carry
+    ``role="user"`` in the Claude Code transcript but are not human turns; they
+    are skipped as boundaries (see ``_is_tool_result_only_user_message``). This
+    keeps the fixed-size retain window anchored to human turns so a tool-heavy
+    turn can never push the human's fact outside the window (silent memory loss).
+    Affects both the retain window-slice and the recall context slice — both
+    want "N human turns", not "N transcript user-messages".
     """
     if not isinstance(messages, list) or not messages or turns <= 0:
         return []
@@ -182,7 +217,8 @@ def slice_last_turns_by_user_boundary(messages: list, turns: int) -> list:
     start_index = -1
 
     for i in range(len(messages) - 1, -1, -1):
-        if messages[i].get("role") == "user":
+        msg = messages[i]
+        if msg.get("role") == "user" and not _is_tool_result_only_user_message(msg):
             user_turns_seen += 1
             if user_turns_seen >= turns:
                 start_index = i
@@ -221,10 +257,13 @@ def format_memories(results: list) -> str:
 def format_current_time() -> str:
     """Format current UTC time for recall context.
 
+    The "UTC" suffix is explicit so client LLMs do not misread the
+    value as local time when reasoning about wall-clock context.
+
     Port of: formatCurrentTimeForRecall() in index.js
     """
     now = datetime.now(timezone.utc)
-    return now.strftime("%Y-%m-%d %H:%M")
+    return now.strftime("%Y-%m-%d %H:%M UTC")
 
 
 # ---------------------------------------------------------------------------

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

@@ -71,8 +71,17 @@ def _is_embed_available(config: dict) -> bool:
     return shutil.which("uvx") is not None or shutil.which("hindsight-embed") is not None
 
 
-def _check_health(base_url: str, timeout: int = 2) -> bool:
-    """Quick health check against a Hindsight server."""
+def _check_health(base_url: str, timeout: int = 10) -> bool:
+    """Quick health check against a Hindsight server.
+
+    Default timeout is 10s (matching the recall hook budget): under load an
+    alive-but-busy daemon mid fact-extraction may not answer /health within a
+    couple of seconds. A too-short timeout yields a false negative, so
+    get_api_url() falls through to _ensure_daemon_running() ->
+    `hindsight-embed daemon start`, whose _clear_port() then SIGTERMs the
+    live daemon -- a restart/kill loop. A 10s budget lets a busy daemon
+    respond before it is declared dead.
+    """
     try:
         url = f"{base_url.rstrip('/')}/health"
         req = urllib.request.Request(url, method="GET", headers={"User-Agent": USER_AGENT})

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

@@ -229,6 +229,33 @@ def _resolve_sender_bank(
     return additional_banks
 
 
+def _tag_filter_sig(
+    recall_tags,
+    tags_match,
+    tag_groups,
+    additional_bank_filters,
+) -> str:
+    """Stable fingerprint of the recall tag-filter configuration
+    (upstream 962140eef) for cache keying. Tag filters change what the
+    recall API returns for an identical query, so they MUST be part of
+    the cache key — otherwise a config change (or per-bank filter edit)
+    within the TTL window would serve stale, differently-filtered
+    results. Empty/default filters collapse to "" so pre-existing cache
+    behaviour (and keys) are unchanged when the feature is unused."""
+    if not (recall_tags or tag_groups or additional_bank_filters):
+        return ""
+    try:
+        return json.dumps(
+            [recall_tags, tags_match, tag_groups, additional_bank_filters],
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+    except (TypeError, ValueError):
+        # Unserializable config — fall back to repr; stable within a
+        # process and still distinguishes filtered from unfiltered.
+        return repr([recall_tags, tags_match, tag_groups, additional_bank_filters])
+
+
 def _cache_key(
     session_id: str,
     prompt: str,
@@ -236,6 +263,7 @@ def _cache_key(
     extra_banks: list,
     active_thread_id: str | None = None,
     active_sender: str | None = None,
+    tag_filter_sig: str = "",
 ) -> str:
     """Stable hash for cache keying. Session_id is included so a new
     session always misses, regardless of the TTL setting. Extra banks
@@ -259,6 +287,9 @@ def _cache_key(
         ",".join(sorted(extra_banks or [])),
         active_thread_id or "",
         active_sender or "",
+        # Upstream 962140eef port: tag filters shape the result set, so
+        # they are part of the key (see _tag_filter_sig). "" when unused.
+        tag_filter_sig or "",
     ]
     payload = "\x1f".join(parts)
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()
@@ -703,11 +734,32 @@ def main():
         additional_banks,
     )
 
+    # Upstream 962140eef — optional recall tag filters. Resolved BEFORE the
+    # cache check so the tag-filter fingerprint is part of the cache key
+    # (filters change the result set for an identical query). Per-bank
+    # overrides in recallAdditionalBankFilters apply to any additional bank —
+    # including sender banks appended by _resolve_sender_bank above.
+    recall_tags = config.get("recallTags") or None
+    tag_groups = config.get("recallTagGroups") or None
+    tags_match = config.get("recallTagsMatch") if recall_tags or tag_groups else None
+    additional_bank_filters = config.get("recallAdditionalBankFilters") or {}
+    if not isinstance(additional_bank_filters, dict):
+        additional_bank_filters = {}
+    tag_filter_sig = _tag_filter_sig(recall_tags, tags_match, tag_groups, additional_bank_filters)
+
     # Switchroom #424 phase 4.1 — cache check BEFORE any HTTP traffic.
     # Whole-session-scoped, opt-in via HINDSIGHT_RECALL_CACHE_TTL_SECS.
     cache_ttl = _cache_ttl_secs()
     cache_key = (
-        _cache_key(session_id, prompt, bank_id, additional_banks, active_thread_id, active_sender)
+        _cache_key(
+            session_id,
+            prompt,
+            bank_id,
+            additional_banks,
+            active_thread_id,
+            active_sender,
+            tag_filter_sig,
+        )
         if cache_ttl > 0
         else ""
     )
@@ -787,6 +839,11 @@ def main():
             max_tokens=config.get("recallMaxTokens", 1024),
             budget=config.get("recallBudget", "mid"),
             types=config.get("recallTypes"),
+            # Upstream 962140eef — optional tag filters (resolved above the
+            # cache check; part of the cache key).
+            tags=recall_tags,
+            tags_match=tags_match,
+            tag_groups=tag_groups,
             # 8s in-script timeout leaves 4s headroom inside the 12s
             # UserPromptSubmit hook ceiling (see hooks.json:20) for cache
             # write + block formatting. Tightened from 10s in switchroom
@@ -809,6 +866,19 @@ def main():
     # cache key reflects every bank queried; reuse that local instead of
     # re-reading config.
     for extra_bank_id in additional_banks:
+        # Upstream 962140eef — per-bank tag-filter overrides; fall back to
+        # the global filters when the bank has no entry. Applies uniformly
+        # to config-listed banks and sender banks appended by
+        # _resolve_sender_bank (both flow through `additional_banks`).
+        extra_filter = additional_bank_filters.get(extra_bank_id, {})
+        if not isinstance(extra_filter, dict):
+            extra_filter = {}
+        extra_tags = extra_filter.get("recallTags", recall_tags) or None
+        extra_tag_groups = extra_filter.get("recallTagGroups", tag_groups) or None
+        extra_tags_match = extra_filter.get(
+            "recallTagsMatch",
+            tags_match if extra_tags or extra_tag_groups else None,
+        )
         try:
             extra_response = client.recall(
                 bank_id=extra_bank_id,
@@ -816,6 +886,9 @@ def main():
                 max_tokens=config.get("recallMaxTokens", 1024),
                 budget=config.get("recallBudget", "mid"),
                 types=config.get("recallTypes"),
+                tags=extra_tags,
+                tags_match=extra_tags_match,
+                tag_groups=extra_tag_groups,
                 # 8s in-script timeout leaves 4s headroom inside the 12s
                 # UserPromptSubmit hook ceiling (see hooks.json:20) for cache
                 # write + block formatting. Tightened from 10s in switchroom

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

@@ -69,6 +69,60 @@ def read_transcript(transcript_path: str) -> list:
     return messages
 
 
+def select_retain_window(
+    retain_mode: str,
+    retain_every_n: int,
+    overlap_turns: int,
+    all_messages: list,
+    force: bool = False,
+) -> tuple:
+    """Decide which messages to retain and whether to send as a full window.
+
+    Returns ``(messages_to_retain, retain_full_window)``.
+
+    SWITCHROOM DIVERGENCE (Phase 6b — candidate to upstream to
+    vectorize-io/hindsight): the chunked sliding-window is decoupled from
+    the ``retainEveryNTurns > 1`` throttle. Upstream only sliced a window
+    when ``retain_every_n > 1``; with ``retainEveryNTurns=1`` (switchroom's
+    every-turn crash-durability setting, applied in scaffold.ts) chunked
+    mode fell through to full-session and re-consolidated the ENTIRE
+    accumulated transcript on every Stop fire — an unbounded, per-turn cost.
+
+    Decoupling is safe because window selection and the throttle answer two
+    independent questions: the throttle decides *whether* to fire this turn
+    (still owned by run_retain, unchanged); this function only decides *what*
+    to retain once a fire happens. A chunked window of
+    ``max(retain_every_n, 1) + overlap_turns`` turns is correct for any
+    ``retain_every_n >= 1``. With ``retain_every_n=1, overlap=2`` the window
+    is the 3 most-recent HUMAN turns (tool_result messages don't count as
+    turns — see slice_last_turns_by_user_boundary).
+
+    ``force=True`` (SessionEnd final retain) widens chunked mode to a
+    full-session sweep — belt-and-braces so a graceful shutdown always flushes
+    the whole session even if per-turn windowing had an edge. This costs a
+    full sweep only ONCE per session (at end), not per turn.
+
+    Durability invariant (jtbd-memory-survives-restart UAT): the window
+    always extends to the END of the transcript (``slice_last_turns_by_user_boundary``
+    returns ``messages[start:]``), so the turn that just completed — the one
+    whose Stop hook is firing — is ALWAYS included. Every turn fires (no
+    throttle at n=1), so every turn's content is retained on its own fire.
+    Boundaries are counted on human messages only, so a tool-heavy turn can't
+    push the human's fact outside the window. No fact can fall outside every
+    window.
+    """
+    if retain_mode == "chunked" and not force:
+        # Sliding window: N turns + configured overlap. max(retain_every_n, 1)
+        # keeps the window valid at n=1 (the decoupling); for n>1 this equals
+        # the previous `retain_every_n + overlap_turns` (behaviour unchanged).
+        window_turns = max(retain_every_n, 1) + overlap_turns
+        messages_to_retain = slice_last_turns_by_user_boundary(all_messages, window_turns)
+        return messages_to_retain, True
+    # Full session: vendor full-session mode, OR a forced (SessionEnd) chunked
+    # sweep. Retain all messages, always as a full window.
+    return list(all_messages), True
+
+
 def run_retain(hook_input: dict, force: bool = False) -> dict:
     """Run the auto-retain flow.
 
@@ -104,7 +158,8 @@ def run_retain(hook_input: dict, force: bool = False) -> dict:
 
     debug_log(config, f"Read {len(all_messages)} messages from transcript")
 
-    # Retention mode: full session (default) or chunked (legacy)
+    # Retention mode: full session (vendor default) or chunked. Switchroom
+    # runs chunked at retainEveryNTurns=1 (see select_retain_window / scaffold.ts).
     retain_mode = config.get("retainMode", "full-session")
     retain_every_n = max(1, config.get("retainEveryNTurns", 1))
     retain_full_window = False
@@ -118,19 +173,25 @@ def run_retain(hook_input: dict, force: bool = False) -> dict:
             debug_log(config, f"Turn {turn_count}/{retain_every_n}, skipping retain (next at turn {next_at})")
             return {"status": "skipped", "reason": "throttled"}
 
-    if retain_mode == "chunked" and retain_every_n > 1:
-        # Sliding window: N turns + configured overlap
-        overlap_turns = config.get("retainOverlapTurns", 0)
-        window_turns = retain_every_n + overlap_turns
-        messages_to_retain = slice_last_turns_by_user_boundary(all_messages, window_turns)
-        retain_full_window = True
+    # Window selection is decoupled from the throttle above — see
+    # select_retain_window() for the switchroom-divergence rationale
+    # (Phase 6b: chunked window-slicing now works at retainEveryNTurns=1).
+    overlap_turns = config.get("retainOverlapTurns", 0)
+    messages_to_retain, retain_full_window = select_retain_window(
+        retain_mode, retain_every_n, overlap_turns, all_messages, force=force
+    )
+    if retain_mode == "chunked" and not force:
+        window_turns = max(retain_every_n, 1) + overlap_turns
         debug_log(
             config,
-            f"Chunked retain firing (window: {window_turns} turns, {len(messages_to_retain)} messages)",
+            f"Chunked retain firing (window: {window_turns} human turns, {len(messages_to_retain)} messages)",
+        )
+    elif retain_mode == "chunked" and force:
+        debug_log(
+            config,
+            f"Chunked retain, forced full-session sweep (SessionEnd): {len(all_messages)} messages",
         )
     else:
-        # Full session mode: retain all messages, always as full window
-        retain_full_window = True
         debug_log(config, f"Full session retain: {len(all_messages)} messages")
 
     # Format transcript
@@ -156,7 +217,14 @@ def run_retain(hook_input: dict, force: bool = False) -> dict:
 
     api_token = config.get("hindsightApiToken")
     try:
-        client = HindsightClient(api_url, api_token)
+        # Upstream 55ef70679 — honor the optional requestTimeoutSeconds
+        # override (retain runs outside the recall hook budget, so a longer
+        # timeout is safe here; recall.py deliberately omits this).
+        client = HindsightClient(
+            api_url,
+            api_token,
+            request_timeout_override=config.get("requestTimeoutSeconds"),
+        )
     except ValueError as e:
         print(f"[Hindsight] Invalid API URL: {e}", file=sys.stderr)
         return {"status": "failed", "error": e, "payload": None}