switchroom 0.21.19 → 0.21.20

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.21.19", COMMIT_SHA = "7e7061ba", COMMIT_DATE = "2026-08-18T15:36:04Z";
+var VERSION = "0.21.20", COMMIT_SHA = "fa05da22", COMMIT_DATE = "2026-08-18T20:00:16Z";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -30555,16 +30555,25 @@ function resolveHindsightVendorResolution() {
     execPath: process.execPath
   });
 }
+function removeVendoredHindsightPlugin(agentDir) {
+  const destPath = join15(agentDir, ".claude", "plugins", "hindsight-memory");
+  if (existsSync20(destPath)) {
+    rmSync7(destPath, { recursive: true, force: true });
+  }
+}
 function installHindsightPlugin(agentName, agentDir, switchroomConfig, resolvedAgentConfig) {
   if (!switchroomConfig)
     return null;
   const memory = switchroomConfig.memory;
-  if (!isHindsightEnabled(switchroomConfig))
+  if (!isHindsightEnabled(switchroomConfig)) {
+    removeVendoredHindsightPlugin(agentDir);
     return null;
+  }
   if (!memory)
     return null;
   const agentMemory = switchroomConfig.agents[agentName]?.memory;
   if (resolveHindsightAutoRecall(switchroomConfig, agentName, resolvedAgentConfig) === false) {
+    removeVendoredHindsightPlugin(agentDir);
     return null;
   }
   const vendorResolution = resolveHindsightVendorResolution();
@@ -63817,6 +63826,92 @@ function detectPrefetchAsyncTimeoutDrift(name, agentConfig, agentDir, config) {
     }
   ];
 }
+function hashPluginScriptsTree(scriptsRoot) {
+  if (!existsSync69(scriptsRoot))
+    return null;
+  const out = new Map;
+  const skipDir = (n) => n === "__pycache__";
+  const skipFile = (n) => n.endsWith(".pyc") || n.includes(".bak");
+  const walk = (dir, rel) => {
+    let entries;
+    try {
+      entries = readdirSync27(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      const childRel = rel === "" ? ent.name : `${rel}/${ent.name}`;
+      const childAbs = join66(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (skipDir(ent.name))
+          continue;
+        walk(childAbs, childRel);
+      } else if (ent.isFile()) {
+        if (skipFile(ent.name))
+          continue;
+        try {
+          out.set(childRel, createHash13("sha256").update(readFileSync62(childAbs)).digest("hex"));
+        } catch {
+          out.set(childRel, "unreadable");
+        }
+      }
+    }
+  };
+  walk(scriptsRoot, "");
+  return out;
+}
+function detectHindsightPluginTreeDrift(name, agentDir) {
+  const pluginDir = join66(agentDir, ".claude", "plugins", "hindsight-memory");
+  if (!existsSync69(pluginDir))
+    return [];
+  const releaseResolution = resolveHindsightVendorResolution();
+  if (releaseResolution.path === null) {
+    return [];
+  }
+  const releaseScripts = join66(releaseResolution.path, "scripts");
+  const deployedScripts = join66(pluginDir, "scripts");
+  const releaseHashes = hashPluginScriptsTree(releaseScripts);
+  if (releaseHashes === null || releaseHashes.size === 0) {
+    return [];
+  }
+  const deployedHashes = hashPluginScriptsTree(deployedScripts) ?? new Map;
+  const missing = [];
+  const changed = [];
+  const extra = [];
+  for (const [rel, hash2] of releaseHashes) {
+    const got = deployedHashes.get(rel);
+    if (got === undefined)
+      missing.push(rel);
+    else if (got !== hash2)
+      changed.push(rel);
+  }
+  for (const rel of deployedHashes.keys()) {
+    if (!releaseHashes.has(rel))
+      extra.push(rel);
+  }
+  if (missing.length === 0 && changed.length === 0 && extra.length === 0) {
+    return [];
+  }
+  const parts = [];
+  const summarise = (label, items) => {
+    if (items.length === 0)
+      return;
+    const shown = items.slice(0, 6).sort();
+    const more = items.length > shown.length ? ` (+${items.length - shown.length} more)` : "";
+    parts.push(`${label}: ${shown.join(", ")}${more}`);
+  };
+  summarise("missing", missing);
+  summarise("changed", changed);
+  summarise("stale-extra", extra);
+  return [
+    {
+      surface: "memory-plugin-build",
+      agent: name,
+      detail: `vendored hindsight-memory plugin scripts/ tree does NOT match the ` + `release build (manifest version is not a reliable signal \u2014 it can ` + `sit unchanged across builds): ${parts.join("; ")}`,
+      fix: "Re-vendor the plugin: `switchroom apply` re-copies the release " + "`scripts/` tree into this agent (or removes it entirely when the " + "agent has memory turned off), then restart the agent " + "(`switchroom agent restart " + name + "`). A tree that keeps drifting after apply means the agent's memory " + "config and its on-disk plugin disagree \u2014 check memory.backend / " + "memory.auto_recall for this agent."
+    }
+  ];
+}
 function writeDriftReport(agentDir, findings) {
   try {
     const report = {
@@ -63841,6 +63936,7 @@ function detectAgentDrift(name, agentConfigRaw, agentsDir, config, configPath, o
   findings.push(...detectSkillsDrift(name, agentDir));
   findings.push(...detectHindsightRecallTunableDrift(name, agentConfig, agentDir, config));
   findings.push(...detectPrefetchAsyncTimeoutDrift(name, agentConfig, agentDir, config));
+  findings.push(...detectHindsightPluginTreeDrift(name, agentDir));
   if (!opts.skipContainerProbes) {
     findings.push(...detectHookScriptDrift(name, {
       binDir: opts.binDir,

package/dist/host-control/main.js

@@ -21598,7 +21598,7 @@ function allocateAgentUid(name) {
 }
 
 // src/build-info.ts
-var VERSION = "0.21.19";
+var VERSION = "0.21.20";
 
 // src/setup/hindsight-recall-passthrough.ts
 var HINDSIGHT_RECALL_TAG_WEIGHT_SEED = Object.freeze({ sidechain: 0.8 });

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.21.19",
+  "version": "0.21.20",
   "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

@@ -105918,10 +105918,10 @@ function startOutboxSweep(deps) {
 }
 
 // ../src/build-info.ts
-var VERSION2 = "0.21.19";
-var COMMIT_SHA = "7e7061ba";
-var COMMIT_DATE = "2026-08-18T15:36:04Z";
-var LATEST_PR = 4777;
+var VERSION2 = "0.21.20";
+var COMMIT_SHA = "fa05da22";
+var COMMIT_DATE = "2026-08-18T20:00:16Z";
+var LATEST_PR = 4782;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts

package/vendor/hindsight-memory/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hindsight-memory",
   "description": "Automatic long-term memory for Claude Code via Hindsight. Recalls relevant memories before each prompt and retains conversation transcripts after each response.",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": {"name": "Hindsight Team", "url": "https://vectorize.io/hindsight"},
   "license": "MIT",
   "keywords": ["memory", "hindsight", "recall", "retain"]

package/vendor/hindsight-memory/CHANGELOG.md

@@ -1,7 +1,27 @@
 # Changelog
 
+> **Versioning scheme (switchroom, #4779).** The manifest `version` in
+> `.claude-plugin/plugin.json` MUST be bumped on every substantive change to
+> this vendored tree — new/removed `scripts/`, changed hook wiring, or any
+> behaviour an agent would observe. It sat frozen at `0.4.0` across the entire
+> M4/M5 async-recall-prefetch rewrite, so a version-string check could not tell
+> a June pre-M4 tree from the shipped build and `test-harness` silently ran the
+> stale one. The version is only a COARSE signal, though — the authoritative
+> drift guard is the `scripts/`-tree hash in
+> `detectHindsightPluginTreeDrift` (`src/agents/drift.ts`), surfaced by
+> `switchroom doctor` and the gateway boot-card. Bump the version AND rely on
+> the hash; never the version alone.
+
 ## [Unreleased]
 
+### Changed (switchroom divergence)
+
+- **Manifest version bumped `0.4.0` → `0.5.0`** to reflect the M4/M5
+  async-recall-prefetch tree (adds `scripts/prefetch.py`,
+  `scripts/lib/recall_buffer.py`, `scripts/orientation.py`, and the
+  `memoryPrefetch*` settings). Per the scheme note above this is the first
+  bump of the discipline that stops build drift from going invisible (#4779).
+
 ### Added (switchroom divergence)
 
 - **Per-row `observation_scopes` on every retain.** Hindsight accepts and

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

@@ -93,13 +93,27 @@ def _sentinel_path(session_id: str) -> str:
     return os.path.join(buffer_dir(), f"{_safe_session(session_id)}.buffer.done")
 
 
-def write_buffer(session_id: str, context: str, telemetry: Optional[dict] = None) -> None:
+def write_buffer(
+    session_id: str,
+    context: str,
+    telemetry: Optional[dict] = None,
+    query: Optional[str] = None,
+) -> None:
     """Write the prefetched recall payload for ``session_id``.
 
     Atomic (temp file + ``os.replace`` within the same directory). Does NOT
     write the sentinel — the caller MUST call ``write_sentinel`` after this,
     and only once the payload write has returned, to preserve the
     read-after-write ordering guarantee.
+
+    ``query`` (#4778) is the speculative query the producer used to build this
+    buffer. It is stored verbatim so the consumer can gate the join on topical
+    similarity between it and turn N+1's ACTUAL prompt — the buffer is keyed by
+    ``session_id`` alone and, without this, a fresh buffer built for the prior
+    turn is served on a topic pivot regardless of relevance. A ``None``/absent
+    query is stored as ``""``, which the consumer treats as "cannot establish a
+    topic match" and falls through to synchronous recall (fail-safe; also the
+    backward-compat behaviour for buffers written before this field existed).
     """
     d = _ensure_dir()
     final = _buffer_path(session_id)
@@ -108,6 +122,7 @@ def write_buffer(session_id: str, context: str, telemetry: Optional[dict] = None
         "schema": SCHEMA,
         "session_id": session_id,
         "context": context,
+        "query": query or "",
         "telemetry": telemetry or {},
         "written_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
     }
@@ -187,7 +202,11 @@ def sentinel_exists(session_id: str) -> bool:
 def read_if_fresh(session_id: str, last_consumed_token: Optional[int]) -> tuple:
     """Return ``(payload_dict | None, current_token)``.
 
-    ``payload_dict`` (when present) is ``{"context": str, "telemetry": dict}``.
+    ``payload_dict`` (when present) is
+    ``{"context": str, "query": str, "telemetry": dict}``. ``query`` (#4778) is
+    the speculative query the buffer was built for — the consumer uses it to
+    gate the join on topical similarity to turn N+1's prompt. It is ``""`` for a
+    legacy buffer written before the field existed.
 
     Returns ``(None, token_or_last_consumed)`` when:
       * no sentinel exists yet (nothing has been produced this session), or
@@ -207,7 +226,11 @@ def read_if_fresh(session_id: str, last_consumed_token: Optional[int]) -> tuple:
         # Torn write: sentinel landed but payload didn't (or is corrupt).
         # Fail-closed — never serve this as fresh.
         return None, token
-    return {"context": payload.get("context", ""), "telemetry": payload.get("telemetry", {})}, token
+    return {
+        "context": payload.get("context", ""),
+        "query": payload.get("query", ""),
+        "telemetry": payload.get("telemetry", {}),
+    }, token
 
 
 def invalidate(session_id: str) -> None:

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

@@ -159,7 +159,13 @@ def run_prefetch(hook_input: dict, config: dict) -> bool:
 
     # Step 3 — write payload THEN sentinel, strictly in that order.
     try:
-        recall_buffer.write_buffer(session_id, memories_block, {"result_count": len(results)})
+        # #4778 — persist the speculative `query` alongside the buffer so the
+        # consumer can gate the turn-N+1 join on topical similarity, not just
+        # session freshness. Without it a fresh buffer built for THIS turn's
+        # prompt is served on next turn's prompt even after a topic pivot.
+        recall_buffer.write_buffer(
+            session_id, memories_block, {"result_count": len(results)}, query=query
+        )
         recall_buffer.write_sentinel(session_id)
     except Exception as exc:  # pragma: no cover - defensive
         debug_log(config, f"Prefetch: buffer write failed: {exc}")

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

@@ -664,6 +664,21 @@ def _handle_prefetch_buffer(config: dict, hook_input: dict, prompt: str) -> bool
 
     payload, _token = recall_buffer.read_if_fresh(session_id, last_consumed_token=last_consumed)
 
+    # #4778 — TOPIC-RELEVANCE GUARD. `read_if_fresh` only proves the buffer is
+    # FRESH (a strictly-newer sentinel this session), never that it is ON TOPIC:
+    # the producer built it from turn N's last human prompt, so on a topic PIVOT
+    # a perfectly-fresh buffer holds the WRONG-topic memories. Gate the join on
+    # topical similarity between the buffered query and turn N+1's ACTUAL prompt
+    # BEFORE the directive fetch below; a mismatch marks the token consumed (so
+    # it is never reconsidered) and falls through to SYNCHRONOUS recall — which
+    # fetches correct, current-topic memories AND re-injects directives itself.
+    # This is layered ON TOP of the F3 freshness machinery, not a replacement.
+    if payload is not None and not _prefetch_topic_matches(prompt, payload.get("query", ""), config):
+        if _token is not None:
+            _write_consumed_token(session_id, _token)
+        debug_log(config, "Prefetch buffer: topic mismatch vs current prompt, falling through to synchronous recall")
+        return False
+
     # Directives stay on the synchronous, always-fresh path (M3 rule) even
     # in the fast path — fetched here directly, never from the buffer.
     directives_block = None
@@ -888,6 +903,78 @@ def _overlap_tokens(text) -> set:
     return out
 
 
+_PREFETCH_TOPIC_OVERLAP_DEFAULT = 0.3
+
+# #4778 review MAJOR — short-prompt Jaccard floor. Jaccard is probabilistic, not
+# absolute, on SHORT prompts: two ~2-content-token turns that share ONE incidental
+# token while EACH carries a divergent token give 1/3 = 0.333 >= 0.30 and wrongly
+# clear the ratio bar ("call mom" buffer served on a "call ended" turn — the pivot
+# signature). When either token set is small (fewer than ``MIN_SMALL_SET_TOKENS``)
+# such a partial overlap must supply at least ``_PREFETCH_MIN_SMALL_SET_INTERSECTION``
+# shared tokens, not just clear the ratio.
+#
+# The floor fires ONLY on that divergent-on-both-sides shape. It deliberately
+# EXEMPTS full containment (``intersection == min(|A|, |B|)`` — the smaller set is
+# wholly shared: identical or subset/narrowing queries like "decide" vs "decide",
+# or "restart klanker" vs "restart the klanker agent"), which is a legitimate
+# topical match regardless of brevity and must still be served. Long prompts (both
+# sides at or above ``MIN_SMALL_SET_TOKENS``) skip the floor entirely and use the
+# Jaccard ratio exactly as before. The floor only ever ANDs a stricter condition
+# onto the ratio — it can reject, never serve.
+MIN_SMALL_SET_TOKENS = 3
+_PREFETCH_MIN_SMALL_SET_INTERSECTION = 2
+
+
+def _prefetch_topic_matches(prompt, buffered_query, config) -> bool:
+    """#4778 — True iff turn N+1's ``prompt`` is topically close enough to the
+    ``buffered_query`` the M4 producer used to build the warm buffer.
+
+    Jaccard overlap (``|A∩B| / |A∪B|``) on ``_overlap_tokens`` — the same
+    stop-word-stripped, digit-preserving, dependency-free tokenizer the
+    transcript-fallback keyword match uses (unicode-safe via ``str.isalnum``,
+    characterised in ``tests/test_overlap_tokens.py``) — against
+    ``memoryPrefetchMinTopicOverlap`` (default 0.3). Jaccard, not the overlap
+    coefficient: both score 0 on a true pivot (disjoint content tokens), so the
+    correctness guarantee is identical, but Jaccard cannot be driven to 1.0 by a
+    single incidental shared token in a short prompt — it biases the residual
+    error toward a harmless false-MISS (sync recall, slower) rather than a
+    false-HIT (wrong-topic memories, the bug).
+
+    Fail-safe: an empty token set on EITHER side — a contentless prompt, or a
+    legacy/torn buffer whose ``query`` is ``""`` — returns False, so the caller
+    falls through to synchronous recall. A miss only ever costs latency; it can
+    never serve wrong-topic memories. Both sides are stripped of the ``<channel>``
+    envelope first, matching the producer's own query derivation.
+    """
+    now_tokens = _overlap_tokens(strip_channel_envelope(prompt or ""))
+    buf_tokens = _overlap_tokens(strip_channel_envelope(buffered_query or ""))
+    if not now_tokens or not buf_tokens:
+        return False
+    intersection = len(now_tokens & buf_tokens)
+    if intersection == 0:
+        return False
+    # Short-prompt floor (#4778 review MAJOR): when either side is small, a single
+    # incidental shared token must not clear the guard on the Jaccard ratio alone.
+    # Exempt full containment (intersection == smaller set) — identical/subset
+    # queries are a legitimate topical match, never the divergent-on-both-sides
+    # pivot this floor targets. ANDed with the ratio check below: stricter, never
+    # looser, and long prompts (both sides >= MIN_SMALL_SET_TOKENS) are untouched.
+    min_set = min(len(now_tokens), len(buf_tokens))
+    if min_set < MIN_SMALL_SET_TOKENS \
+            and intersection < min_set \
+            and intersection < _PREFETCH_MIN_SMALL_SET_INTERSECTION:
+        return False
+    union = len(now_tokens | buf_tokens)
+    threshold = config.get("memoryPrefetchMinTopicOverlap", _PREFETCH_TOPIC_OVERLAP_DEFAULT)
+    try:
+        threshold = float(threshold)
+    except (TypeError, ValueError):
+        threshold = _PREFETCH_TOPIC_OVERLAP_DEFAULT
+    if not (0.0 <= threshold <= 1.0):
+        threshold = _PREFETCH_TOPIC_OVERLAP_DEFAULT
+    return (intersection / union) >= threshold
+
+
 def _result_final_score(m) -> float:
     """Return a result's engine relevance score (`scores.final`).
 

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

@@ -278,7 +278,9 @@ class NoDuplicateInjectionTests(InvalidationBase):
         config = self._config(prefetch_enabled=True)
         marker = "- unique-fact-abc123 decided at standup"
 
-        recall_buffer.write_buffer(SESSION, marker, {})
+        # #4778 — on-topic with the `_consume` prompt ("what did we decide") so
+        # the topic guard passes and this stays a genuine warm-buffer hit.
+        recall_buffer.write_buffer(SESSION, marker, {}, query="what did we decide")
         recall_buffer.write_sentinel(SESSION)
 
         # Turn N+1: consumer injects the buffered block once.
@@ -311,7 +313,10 @@ class ReplyPathDoesNotBlockOnRecallTests(InvalidationBase):
 
     def test_fresh_buffer_served_without_calling_recall(self):
         config = self._config(prefetch_enabled=True)
-        recall_buffer.write_buffer(SESSION, "- a prefetched memory xyz", {})
+        # #4778 — on-topic with the `_consume` prompt so the topic guard passes;
+        # the point of THIS test is that a matched fresh buffer never blocks on a
+        # synchronous recall, so the query must clear the guard.
+        recall_buffer.write_buffer(SESSION, "- a prefetched memory xyz", {}, query="what did we decide")
         recall_buffer.write_sentinel(SESSION)
 
         class _ExplodingRecallClient:

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

@@ -147,7 +147,7 @@ class CallOrderTests(PrefetchPipelineBase):
             order.append("retain")
             return {"status": "ok"}
 
-        def _spy_write_buffer(session_id, context, telemetry=None):
+        def _spy_write_buffer(session_id, context, telemetry=None, query=None):
             order.append("buffer")
 
         def _spy_write_sentinel(session_id):

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

@@ -0,0 +1,279 @@
+"""M4 #4778 — prefetch buffer TOPIC-RELEVANCE guard.
+
+The F3 freshness machinery proves a joined buffer is FRESH (a strictly-newer
+sentinel this session); it does NOT prove the buffer is ON TOPIC. The producer
+builds the buffer from turn N's last human prompt, so on a topic PIVOT a
+perfectly-fresh buffer holds the WRONG-topic memories. These are OUTCOME tests
+on the rendered ``additionalContext`` (the real injection surface):
+
+  * RED/GREEN: a pivot query must NOT be served the prior-topic buffer — it must
+    fall through to SYNCHRONOUS recall (correct, current-topic memories). On the
+    pre-guard code the prior-topic block is injected at warm-buffer latency; with
+    the guard the pivot turn shows the synchronous result instead.
+  * An on-topic follow-up is STILL a warm hit (the guard is not so tight it kills
+    the latency win).
+  * A legacy buffer with no stored query fails safe to synchronous recall.
+
+Mirrors the harness in ``tests/test_recall_buffer_join.py`` (drives ``recall.main``
+end-to-end, asserts on transport). Stdlib-only.
+"""
+
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+from unittest import mock
+from unittest.mock import patch
+
+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)
+
+import recall  # noqa: E402
+from lib import recall_buffer  # noqa: E402
+
+SESSION = "topic-guard-session"
+
+# The producer built the warm buffer for turn N's prompt about a DB failover
+# rollback; its recalled block is the us-east-1 standby plan.
+PRODUCER_QUERY = "what's the rollback plan for the us-east-1 primary failover"
+BUFFERED_BLOCK = "- Rollback plan: keep the us-east-1 primary in read-only standby"
+
+# Turn N+1 PIVOTS sharply to an unrelated topic (the issue's reproduction shape).
+PIVOT_PROMPT = "what's the weather forecast for Melbourne this weekend"
+SYNC_RECALL_TEXT = "sync recalled: Melbourne weekend outlook is sunny"
+
+# An on-topic FOLLOW-UP that reuses the salient nouns of the producer query.
+ONTOPIC_PROMPT = "and is the us-east-1 primary still the rollback target"
+
+# --- #4778 review MAJOR: SHORT-PROMPT Jaccard floor -------------------------
+# Jaccard is probabilistic on short prompts. The producer built a buffer for a
+# 2-content-token "call mom" turn; its block is a mom-topic reminder. Turn N+1 is
+# "call ended" — a SHARP pivot that shares only the incidental "call". Raw
+# Jaccard = |{call}| / |{call, mom, ended}| = 1/3 = 0.333 >= 0.30, so the
+# pre-floor guard WRONGLY serves the mom buffer. The small-set intersection floor
+# (either side < 3 tokens => demand >= 2 shared tokens) rejects it.
+SHORT_PRODUCER_QUERY = "call mom"
+SHORT_BUFFERED_BLOCK = "- Reminder: call mom about her dentist appointment"
+SHORT_PIVOT_PROMPT = "call ended"
+SHORT_BUFFER_MARKER = "dentist"
+
+# Positive control: two SHORT prompts that LEGITIMATELY share >= 2 content tokens
+# still join the warm buffer. Buffer query has 3 content tokens (restart, klanker,
+# agent — "the" is a stop word); the follow-up "restart klanker" is 2 tokens, so
+# the small-set floor applies, but the intersection {restart, klanker} = 2 clears
+# it and Jaccard = 2/3 = 0.667 clears the ratio. Served, no synchronous recall.
+SHORT_ONTOPIC_PRODUCER_QUERY = "restart the klanker agent"
+SHORT_ONTOPIC_BLOCK = "- Runbook: restart klanker with docker restart switchroom-klanker"
+SHORT_ONTOPIC_PROMPT = "restart klanker"
+SHORT_ONTOPIC_MARKER = "docker"
+
+
+class _SyncClient:
+    """Directive-free client whose synchronous recall returns a marker distinct
+    from the buffered block, so a served warm buffer and a served sync result are
+    unambiguously distinguishable in the rendered output."""
+
+    def list_directives(self, bank_id, active_only=True, timeout=2):
+        return {"items": []}
+
+    def recall(self, bank_id, query, **kwargs):
+        return {"results": [{
+            "text": SYNC_RECALL_TEXT, "type": "fact",
+            "mentioned_at": "2026-01-01", "id": "s1", "scores": {"final": 0.9},
+        }]}
+
+
+class TopicGuardBase(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="topic-guard-test-")
+        self._prev = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmpdir
+
+        self._bufdir = tempfile.mkdtemp(prefix="topic-guard-buf-")
+        self.env = mock.patch.dict(
+            os.environ, {"HINDSIGHT_PREFETCH_BUFFER_DIR": self._bufdir}, clear=False
+        )
+        self.env.start()
+
+    def tearDown(self):
+        self.env.stop()
+        shutil.rmtree(self._bufdir, ignore_errors=True)
+        shutil.rmtree(self._tmpdir, ignore_errors=True)
+        if self._prev is None:
+            os.environ.pop("CLAUDE_PLUGIN_DATA", None)
+        else:
+            os.environ["CLAUDE_PLUGIN_DATA"] = self._prev
+
+    def _config(self):
+        return {
+            "autoRecall": True,
+            "bankId": "test-bank",
+            "recallMaxTokens": 4096,
+            "recallBudget": "mid",
+            "recallContextTurns": 1,
+            "recallMaxQueryChars": 800,
+            "recallPromptPreamble": "",
+            "recallParallelDeadlineSeconds": 5,
+            "directivesCacheTtlSeconds": 0,
+            "memoryPrefetchEnabled": True,
+            "memoryPrefetchPollCapMs": 100,
+        }
+
+    def _run(self, config, client, prompt):
+        hook_input = {"prompt": prompt, "session_id": SESSION, "transcript_path": "", "cwd": "/tmp"}
+        stdout = io.StringIO()
+        with patch("recall.load_config", return_value=config), \
+                patch("recall.get_api_url", return_value="http://fake"), \
+                patch("recall.HindsightClient", return_value=client), \
+                patch("recall.ensure_bank_mission"), \
+                patch("sys.stdin", io.StringIO(json.dumps(hook_input))), \
+                patch("sys.stdout", stdout):
+            recall.main()
+        out = stdout.getvalue()
+        return json.loads(out)["hookSpecificOutput"]["additionalContext"] if out else ""
+
+
+class PivotFallsThroughTests(TopicGuardBase):
+    def test_pivot_query_is_not_served_the_prior_topic_buffer(self):
+        # RED on pre-guard code: `read_if_fresh` returns the fresh buffer and the
+        # consumer injects the rollback block for a WEATHER prompt at ~1ms. GREEN
+        # with the guard: the topic mismatch falls through to synchronous recall.
+        recall_buffer.write_buffer(SESSION, BUFFERED_BLOCK, {}, query=PRODUCER_QUERY)
+        recall_buffer.write_sentinel(SESSION)
+
+        ctx = self._run(self._config(), _SyncClient(), PIVOT_PROMPT)
+
+        self.assertNotIn(
+            "us-east-1", ctx,
+            "a topic pivot must NOT be served the prior turn's wrong-topic buffer",
+        )
+        self.assertIn(
+            SYNC_RECALL_TEXT, ctx,
+            "a topic pivot must fall through to synchronous recall for correct memories",
+        )
+
+
+class OnTopicStillHitsTests(TopicGuardBase):
+    def test_ontopic_followup_still_gets_the_warm_buffer(self):
+        # The guard must not be so tight it kills the latency win: a follow-up
+        # reusing the salient nouns still clears the Jaccard threshold and joins
+        # the warm buffer WITHOUT a synchronous recall.
+        class _ExplodingRecallClient:
+            def list_directives(self, bank_id, active_only=True, timeout=2):
+                return {"items": []}
+
+            def recall(self, bank_id, query, **kwargs):
+                raise AssertionError("on-topic warm hit must not fall through to synchronous recall")
+
+        recall_buffer.write_buffer(SESSION, BUFFERED_BLOCK, {}, query=PRODUCER_QUERY)
+        recall_buffer.write_sentinel(SESSION)
+
+        ctx = self._run(self._config(), _ExplodingRecallClient(), ONTOPIC_PROMPT)
+        self.assertIn(
+            "us-east-1", ctx,
+            "an on-topic follow-up must still join the warm prefetch buffer",
+        )
+
+
+class LegacyBufferFailsSafeTests(TopicGuardBase):
+    def test_buffer_without_stored_query_falls_through_to_sync_recall(self):
+        # Backward-compat: a buffer written before the `query` field existed has
+        # query="" -> the guard cannot establish a topic match -> fail-safe to
+        # synchronous recall, never a blind wrong-topic serve.
+        recall_buffer.write_buffer(SESSION, BUFFERED_BLOCK, {})  # no query
+        recall_buffer.write_sentinel(SESSION)
+
+        ctx = self._run(self._config(), _SyncClient(), PIVOT_PROMPT)
+        self.assertNotIn("us-east-1", ctx)
+        self.assertIn(SYNC_RECALL_TEXT, ctx)
+
+
+class ShortPromptFloorTests(TopicGuardBase):
+    def test_short_pivot_sharing_one_incidental_token_is_not_served(self):
+        # RED without the small-set floor: "call mom" buffer + "call ended" turn
+        # gives raw Jaccard 1/3 = 0.333 >= 0.30, so the mom-topic block is served
+        # on an unrelated turn. GREEN with the floor: either side has < 3 tokens
+        # and the intersection is only {call} = 1 < 2, so the guard rejects and
+        # the turn falls through to synchronous recall.
+        recall_buffer.write_buffer(SESSION, SHORT_BUFFERED_BLOCK, {}, query=SHORT_PRODUCER_QUERY)
+        recall_buffer.write_sentinel(SESSION)
+
+        ctx = self._run(self._config(), _SyncClient(), SHORT_PIVOT_PROMPT)
+
+        self.assertNotIn(
+            SHORT_BUFFER_MARKER, ctx,
+            "a short-prompt pivot sharing one incidental token must NOT be served the buffer",
+        )
+        self.assertIn(
+            SYNC_RECALL_TEXT, ctx,
+            "a short-prompt pivot must fall through to synchronous recall",
+        )
+
+    def test_short_ontopic_sharing_two_tokens_still_gets_the_warm_buffer(self):
+        # Positive control: the floor must not kill a legitimate short warm hit.
+        # "restart klanker" (2 tokens) vs "restart the klanker agent" shares
+        # {restart, klanker} = 2, clearing both the small-set floor and the ratio;
+        # served WITHOUT any synchronous recall.
+        class _ExplodingRecallClient:
+            def list_directives(self, bank_id, active_only=True, timeout=2):
+                return {"items": []}
+
+            def recall(self, bank_id, query, **kwargs):
+                raise AssertionError("short on-topic warm hit must not fall through to sync recall")
+
+        recall_buffer.write_buffer(SESSION, SHORT_ONTOPIC_BLOCK, {}, query=SHORT_ONTOPIC_PRODUCER_QUERY)
+        recall_buffer.write_sentinel(SESSION)
+
+        ctx = self._run(self._config(), _ExplodingRecallClient(), SHORT_ONTOPIC_PROMPT)
+        self.assertIn(
+            SHORT_ONTOPIC_MARKER, ctx,
+            "a short on-topic follow-up sharing >= 2 tokens must still join the warm buffer",
+        )
+
+    def test_short_floor_unit_boundaries(self):
+        cfg = self._config()
+        # Short pivot, one incidental shared token -> floor rejects despite ratio.
+        self.assertFalse(recall._prefetch_topic_matches(SHORT_PIVOT_PROMPT, SHORT_PRODUCER_QUERY, cfg))
+        # Short on-topic, two shared tokens -> floor and ratio both clear.
+        self.assertTrue(
+            recall._prefetch_topic_matches(SHORT_ONTOPIC_PROMPT, SHORT_ONTOPIC_PRODUCER_QUERY, cfg)
+        )
+        # The reviewer's borderline case: "kill process 4080" / "process 4080 logs"
+        # shares two tokens (both sides 3 tokens) -> served, unaffected by floor.
+        self.assertTrue(
+            recall._prefetch_topic_matches("kill process 4080", "process 4080 logs", cfg)
+        )
+        # Full-containment exemption: an identical single-content-token query
+        # ("what did we decide" -> {decide} both sides) is wholly shared, not a
+        # divergent pivot -> the floor must NOT reject it. Guards the regression
+        # the naive floor caused in test_prefetch_invalidation's short queries.
+        self.assertTrue(recall._prefetch_topic_matches("what did we decide", "what did we decide", cfg))
+        # Subset/narrowing short query is likewise exempt from the floor.
+        self.assertTrue(recall._prefetch_topic_matches("call mom please", "call mom", cfg))
+
+
+class TopicMatchUnitTests(TopicGuardBase):
+    def test_jaccard_threshold_boundaries(self):
+        cfg = self._config()
+        # Disjoint content tokens -> pivot -> no match.
+        self.assertFalse(recall._prefetch_topic_matches(PIVOT_PROMPT, PRODUCER_QUERY, cfg))
+        # Identical query -> match.
+        self.assertTrue(recall._prefetch_topic_matches(PRODUCER_QUERY, PRODUCER_QUERY, cfg))
+        # On-topic follow-up sharing salient nouns -> match.
+        self.assertTrue(recall._prefetch_topic_matches(ONTOPIC_PROMPT, PRODUCER_QUERY, cfg))
+        # Empty buffered query (legacy) -> fail-safe miss.
+        self.assertFalse(recall._prefetch_topic_matches(PRODUCER_QUERY, "", cfg))
+        # Empty current prompt -> fail-safe miss.
+        self.assertFalse(recall._prefetch_topic_matches("", PRODUCER_QUERY, cfg))
+        # Garbage threshold coerces to the 0.3 default rather than raising.
+        bad = dict(cfg)
+        bad["memoryPrefetchMinTopicOverlap"] = "not-a-number"
+        self.assertTrue(recall._prefetch_topic_matches(PRODUCER_QUERY, PRODUCER_QUERY, bad))
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -99,7 +99,10 @@ class BufferJoinBase(unittest.TestCase):
 
 class FreshHitTests(BufferJoinBase):
     def test_fresh_buffer_hit_is_rendered_with_directives_layered_on(self):
-        recall_buffer.write_buffer(SESSION, "- a prefetched memory", {})
+        # #4778 — the buffered query must be on-topic with the consumer prompt
+        # (default "what did we decide about deploys") for the join to fire;
+        # here it is identical, so the topic guard passes and the warm hit lands.
+        recall_buffer.write_buffer(SESSION, "- a prefetched memory", {}, query="what did we decide about deploys")
         recall_buffer.write_sentinel(SESSION)
 
         out = self._run(self._config(prefetch_enabled=True), _DirectiveClient())
@@ -194,7 +197,7 @@ class StaleBufferTokenTests(BufferJoinBase):
     turns N+1..N+k when no strictly-newer sentinel has been produced."""
 
     def test_consumed_buffer_is_not_reserved_as_fresh_next_turn(self):
-        recall_buffer.write_buffer(SESSION, "- a prefetched memory", {})
+        recall_buffer.write_buffer(SESSION, "- a prefetched memory", {}, query="what did we decide about deploys")
         recall_buffer.write_sentinel(SESSION)
         cfg = self._config(prefetch_enabled=True)
 
@@ -219,7 +222,7 @@ class StaleBufferTokenTests(BufferJoinBase):
         # Positive control: once the producer writes a STRICTLY-NEWER sentinel,
         # the fresh path serves again — the token gate rejects only re-reads of
         # an ALREADY-consumed sentinel, never a genuinely new one.
-        recall_buffer.write_buffer(SESSION, "- memory one", {})
+        recall_buffer.write_buffer(SESSION, "- memory one", {}, query="what did we decide about deploys")
         recall_buffer.write_sentinel(SESSION)
         cfg = self._config(prefetch_enabled=True)
 
@@ -227,7 +230,7 @@ class StaleBufferTokenTests(BufferJoinBase):
         self.assertIn("memory one", json.loads(out1)["hookSpecificOutput"]["additionalContext"])
 
         # New turn's producer output.
-        recall_buffer.write_buffer(SESSION, "- memory two", {})
+        recall_buffer.write_buffer(SESSION, "- memory two", {}, query="what did we decide about deploys")
         recall_buffer.write_sentinel(SESSION)
         out2 = self._run(cfg, _DirectiveClient())
         ctx2 = json.loads(out2)["hookSpecificOutput"]["additionalContext"]