switchroom 0.19.2 → 0.19.4

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

@@ -0,0 +1,200 @@
+"""Switchroom hindsight-leverage PR2 (workstream A2) — coverage for the
+``recallContextTurns`` default flip 1 → 2 and its latency bound.
+
+Two things are asserted here:
+
+1. **The default is now 2** (config.py + settings.json), so a bare follow-up
+   user message composes with its antecedent human turn — WITHOUT anyone
+   setting ``recallContextTurns`` explicitly.
+2. **The multi-turn composition is budget- and latency-bounded:**
+   - ``truncate_recall_query`` keeps the composed 2-turn query within
+     ``recallMaxQueryChars`` even when the antecedent turn is huge — the latest
+     turn is always preserved, oldest context is dropped first.
+   - ``read_transcript_messages(..., tail_bytes=N)`` parses only the trailing
+     N bytes of a large transcript, so the per-recall read stays O(tail_bytes)
+     regardless of how large the session ``.jsonl`` has grown. The last human
+     turns (which is all the slice needs) still land.
+
+Stdlib-only; runs under ``python3 -m unittest discover tests/``.
+"""
+
+import json
+import os
+import sys
+import tempfile
+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 DEFAULTS  # noqa: E402
+from lib.content import compose_recall_query, truncate_recall_query  # noqa: E402
+from recall import read_transcript_messages  # noqa: E402
+
+
+class ContextTurnsDefaultIsTwo(unittest.TestCase):
+    """The A2 flip: bare follow-ups embed with their antecedent by default."""
+
+    def test_config_default_is_two(self):
+        self.assertEqual(DEFAULTS.get("recallContextTurns"), 2)
+
+    def test_settings_json_default_is_two(self):
+        settings_path = os.path.join(
+            os.path.dirname(SCRIPTS_DIR), "settings.json"
+        )
+        with open(settings_path, encoding="utf-8") as f:
+            settings = json.load(f)
+        self.assertEqual(settings.get("recallContextTurns"), 2)
+
+    def test_settings_and_config_defaults_agree(self):
+        settings_path = os.path.join(
+            os.path.dirname(SCRIPTS_DIR), "settings.json"
+        )
+        with open(settings_path, encoding="utf-8") as f:
+            settings = json.load(f)
+        for key in ("recallContextTurns", "recallTranscriptTailBytes"):
+            self.assertEqual(
+                settings.get(key),
+                DEFAULTS.get(key),
+                f"settings.json and config.py disagree on {key}",
+            )
+
+    def test_bare_followup_composes_with_antecedent_at_default_turns(self):
+        # Simulate what recall.py does with the *default* turn count: a bare
+        # pronoun follow-up must carry its antecedent human turn into the query.
+        turns = DEFAULTS["recallContextTurns"]
+        messages = [
+            {"role": "user", "content": "how is the ORCHID_PRIMARY database configured"},
+            {"role": "assistant", "content": "it runs Postgres 16 with PITR"},
+        ]
+        composed = compose_recall_query("and the port?", messages, turns)
+        self.assertIn("Prior context:", composed)
+        self.assertIn("ORCHID_PRIMARY", composed)
+        self.assertTrue(composed.rstrip().endswith("and the port?"))
+
+
+class ComposedQueryStaysWithinBudget(unittest.TestCase):
+    """The composition can never blow the recall query char budget."""
+
+    def test_huge_antecedent_truncated_to_budget_keeping_latest(self):
+        max_chars = 800
+        huge_antecedent = "x" * 5000  # far larger than the whole budget
+        messages = [
+            {"role": "user", "content": huge_antecedent},
+            {"role": "assistant", "content": "y" * 5000},
+        ]
+        latest = "and what about staging?"
+        composed = compose_recall_query(latest, messages, 2)
+        # Pre-truncation the composed query is over budget (the antecedent is 5k).
+        self.assertGreater(len(composed), max_chars)
+        truncated = truncate_recall_query(composed, latest, max_chars)
+        # Bounded — never exceeds the budget.
+        self.assertLessEqual(len(truncated), max_chars)
+        # The latest turn is always preserved verbatim (never sacrificed to
+        # make room for context).
+        self.assertTrue(truncated.rstrip().endswith(latest))
+
+    def test_modest_context_fits_and_is_preserved(self):
+        max_chars = 800
+        messages = [
+            {"role": "user", "content": "the deploy target is ap-southeast-2"},
+            {"role": "assistant", "content": "noted, Sydney region"},
+        ]
+        latest = "and the fallback region?"
+        composed = compose_recall_query(latest, messages, 2)
+        truncated = truncate_recall_query(composed, latest, max_chars)
+        self.assertLessEqual(len(truncated), max_chars)
+        # Small enough to keep the context line intact.
+        self.assertIn("ap-southeast-2", truncated)
+        self.assertTrue(truncated.rstrip().endswith(latest))
+
+
+class TranscriptTailReadIsBounded(unittest.TestCase):
+    """The per-recall transcript read is byte-tail-bounded (latency bound)."""
+
+    def _write_transcript(self, path, filler_rows, tail_rows):
+        with open(path, "w", encoding="utf-8") as f:
+            for r in filler_rows + tail_rows:
+                f.write(json.dumps(r) + "\n")
+
+    def test_tail_bytes_reads_only_the_trailing_lines(self):
+        tmpdir = tempfile.mkdtemp(prefix="recall-tail-")
+        try:
+            path = os.path.join(tmpdir, "t.jsonl")
+            # A large body of old turns (well over any small tail bound) …
+            filler = [
+                {"type": "user", "message": {"role": "user",
+                 "content": "OLD_TURN_" + str(i) + " " + ("f" * 500)}}
+                for i in range(200)
+            ]
+            # … then the two recent turns we actually want to slice.
+            tail = [
+                {"type": "user", "message": {"role": "user",
+                 "content": "RECENT_FACT the api key is FALCON_9_KEY"}},
+                {"type": "assistant", "message": {"role": "assistant",
+                 "content": "RECENT_ANSWER got it"}},
+            ]
+            self._write_transcript(path, filler, tail)
+
+            # Small tail bound — must NOT parse the old filler, but MUST reach
+            # the recent turns at the end.
+            msgs = read_transcript_messages(path, tail_bytes=4096)
+            joined = json.dumps(msgs)
+            self.assertIn("RECENT_FACT", joined)
+            self.assertIn("RECENT_ANSWER", joined)
+            self.assertNotIn("OLD_TURN_0", joined)
+            # Bounded read yields far fewer than the 202 total rows.
+            self.assertLess(len(msgs), 200)
+        finally:
+            import shutil
+            shutil.rmtree(tmpdir, ignore_errors=True)
+
+    def test_tail_bytes_zero_reads_whole_file(self):
+        tmpdir = tempfile.mkdtemp(prefix="recall-tail-")
+        try:
+            path = os.path.join(tmpdir, "t.jsonl")
+            rows = [
+                {"type": "user", "message": {"role": "user", "content": "FIRST"}},
+                {"type": "assistant", "message": {"role": "assistant", "content": "mid"}},
+                {"type": "user", "message": {"role": "user", "content": "LAST"}},
+            ]
+            self._write_transcript(path, [], rows)
+            msgs = read_transcript_messages(path, tail_bytes=0)
+            joined = json.dumps(msgs)
+            self.assertIn("FIRST", joined)
+            self.assertIn("LAST", joined)
+            self.assertEqual(len(msgs), 3)
+        finally:
+            import shutil
+            shutil.rmtree(tmpdir, ignore_errors=True)
+
+    def test_small_file_under_bound_reads_fully(self):
+        # When the file is smaller than the tail bound, nothing is dropped —
+        # the partial-first-line trim only applies when we actually seek.
+        tmpdir = tempfile.mkdtemp(prefix="recall-tail-")
+        try:
+            path = os.path.join(tmpdir, "t.jsonl")
+            rows = [
+                {"type": "user", "message": {"role": "user", "content": "ALPHA"}},
+                {"type": "user", "message": {"role": "user", "content": "OMEGA"}},
+            ]
+            self._write_transcript(path, [], rows)
+            msgs = read_transcript_messages(path, tail_bytes=262144)
+            joined = json.dumps(msgs)
+            self.assertIn("ALPHA", joined)
+            self.assertIn("OMEGA", joined)
+            self.assertEqual(len(msgs), 2)
+        finally:
+            import shutil
+            shutil.rmtree(tmpdir, ignore_errors=True)
+
+    def test_missing_transcript_returns_empty(self):
+        self.assertEqual(read_transcript_messages("", tail_bytes=4096), [])
+        self.assertEqual(
+            read_transcript_messages("/nonexistent/nope.jsonl", tail_bytes=4096), []
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,477 @@
+"""Switchroom hindsight-leverage PR 1 (workstream A1 + A3 stage-1 telemetry).
+
+Two single-concern guarantees:
+
+  1. Query hygiene — the ``<channel …>`` transport envelope is stripped from
+     the recall query on BOTH the single-turn and the multi-turn (composed)
+     paths, so ~100-200 chars of chat_id/ts/user XML noise never reach the
+     embedding or consume the recallMaxQueryChars cap. The stripped query is
+     the one recorded in ``recall_log.jsonl`` (acceptance: no ``<channel``
+     substring in the logged query). The multi-turn fixture is a regression
+     guard for the future ``recallContextTurns`` default flip (A2): it locks
+     in that the composed query — both its "Prior context:" lines and its
+     trailing latest-query segment — is envelope-free.
+
+  2. Telemetry — every non-cache recall log carries per-bank latency +
+     timeout flags, directives-fetch latency, total critical-path wall time,
+     and a derived ``deadline_hit`` (any bank hit its hard per-request
+     timeout). This is the A3 stage-1 baseline instrumentation, landed ahead
+     of the parallelism change so a fresh pre-A3 breach baseline can accrue.
+
+Stdlib-only (unittest + mock); runs under ``python3 -m unittest discover
+tests/``. Mirrors the harness in ``test_recall_integration.py``.
+"""
+
+import io
+import json
+import os
+import socket
+import sys
+import tempfile
+import shutil
+import unittest
+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.content import compose_recall_query, strip_channel_envelope  # noqa: E402
+
+
+def _memory(text, mem_type="fact", mentioned_at="2026-01-01", mem_id=None):
+    out = {"text": text, "type": mem_type, "mentioned_at": mentioned_at}
+    if mem_id is not None:
+        out["id"] = mem_id
+    return out
+
+
+class _RecordingClient:
+    """Fake HindsightClient that records the exact `query` passed to recall().
+
+    Per-bank behaviour (results / exception) is configurable so a bank can be
+    made to raise a timeout for the telemetry tests.
+    """
+
+    def __init__(self, memories=None, directives=None, bank_behaviour=None):
+        self._memories = memories if memories is not None else []
+        self._directives = directives if directives is not None else []
+        # Maps bank_id -> Exception to raise (e.g. a timeout).
+        self._bank_behaviour = bank_behaviour or {}
+        self.queries = []  # every query string passed, in call order
+
+    def list_directives(self, bank_id, active_only=True, timeout=2):
+        return {"items": list(self._directives)}
+
+    def recall(self, bank_id, query, **kwargs):
+        self.queries.append(query)
+        exc = self._bank_behaviour.get(bank_id)
+        if exc is not None:
+            raise exc
+        return {"results": list(self._memories)}
+
+
+def _run_main_with(client, prompt, config_extra=None):
+    """Invoke recall.main with a fake client; capture stdout JSON."""
+    hook_input = {
+        "prompt": prompt,
+        "session_id": "test-session",
+        "transcript_path": "",
+        "cwd": "/tmp",
+    }
+    config = {
+        "autoRecall": True,
+        "bankId": "test-bank",
+        "recallMaxTokens": 1024,
+        "recallBudget": "mid",
+        "recallContextTurns": 1,
+        "recallMaxQueryChars": 800,
+        "recallPromptPreamble": "",
+    }
+    if config_extra:
+        config.update(config_extra)
+
+    stdout = io.StringIO()
+    stderr = io.StringIO()
+    with patch.object(recall, "load_config", return_value=config), patch.object(
+        recall, "get_api_url", return_value="http://localhost:18888"
+    ), patch.object(recall, "HindsightClient", return_value=client), patch.object(
+        recall, "ensure_bank_mission", return_value=None
+    ), patch.object(recall, "write_state", return_value=None), patch(
+        "sys.stdin", new=io.StringIO(json.dumps(hook_input))
+    ), patch("sys.stdout", new=stdout), patch("sys.stderr", new=stderr):
+        recall.main()
+
+    raw = stdout.getvalue()
+    if not raw.strip():
+        return None, raw
+    parsed = json.loads(raw)
+    return parsed["hookSpecificOutput"]["additionalContext"], raw
+
+
+WRAPPED = (
+    '<channel source="switchroom-telegram" chat_id="1000000001" '
+    'message_id="42" user="testuser" ts="2026-07-20T10:00:00Z">'
+    "what did we decide about the auth flow</channel>"
+)
+BARE = "what did we decide about the auth flow"
+
+
+class SingleTurnEnvelopeStrip(unittest.TestCase):
+    """The single-turn recall query must be the envelope-free inner text —
+    identical to what a bare (unwrapped) prompt produces."""
+
+    def test_wrapped_and_bare_produce_identical_query(self):
+        wrapped_client = _RecordingClient(memories=[_memory("m")])
+        bare_client = _RecordingClient(memories=[_memory("m")])
+        _run_main_with(wrapped_client, prompt=WRAPPED)
+        _run_main_with(bare_client, prompt=BARE)
+        self.assertEqual(len(wrapped_client.queries), 1)
+        self.assertEqual(len(bare_client.queries), 1)
+        self.assertEqual(wrapped_client.queries[0], bare_client.queries[0])
+        self.assertEqual(wrapped_client.queries[0], BARE)
+
+    def test_no_channel_substring_or_attrs_in_query(self):
+        client = _RecordingClient(memories=[_memory("m")])
+        _run_main_with(client, prompt=WRAPPED)
+        q = client.queries[0]
+        self.assertNotIn("<channel", q)
+        self.assertNotIn("chat_id", q)
+        self.assertNotIn("1000000001", q)
+        self.assertNotIn("ts=", q)
+
+
+class MultiTurnComposedEnvelopeStrip(unittest.TestCase):
+    """Regression guard for the future recallContextTurns default flip (A2):
+    the composed multi-turn query must be envelope-free in BOTH the trailing
+    latest-query segment and the "Prior context:" lines."""
+
+    def test_composed_query_helper_strips_wrapped_latest(self):
+        # compose_recall_query is called directly here (the helper must be
+        # safe for any future caller, per A1). A wrapped latest query and a
+        # wrapped prior user turn must both be stripped.
+        messages = [
+            {"role": "user", "content": '<channel source="telegram" chat_id="9">'
+                                         "we were discussing the auth flow</channel>"},
+            {"role": "assistant", "content": "right, the OAuth refresh path"},
+        ]
+        composed = compose_recall_query(WRAPPED, messages, recall_context_turns=2)
+        self.assertNotIn("<channel", composed)
+        self.assertNotIn("chat_id", composed)
+        self.assertIn("Prior context:", composed)
+        # Trailing latest-query segment is the bare text.
+        self.assertTrue(composed.rstrip().endswith(BARE))
+        # Prior user turn text survives, stripped.
+        self.assertIn("we were discussing the auth flow", composed)
+
+    def test_composed_query_via_main_has_no_channel(self):
+        # End-to-end through main() with recallContextTurns=2 and a transcript
+        # on disk whose latest user turn is wrapped.
+        tmpdir = tempfile.mkdtemp(prefix="recall-transcript-")
+        try:
+            transcript = os.path.join(tmpdir, "t.jsonl")
+            rows = [
+                {"type": "user", "message": {"role": "user",
+                 "content": "earlier i mentioned the ORCHID database"}},
+                {"type": "assistant", "message": {"role": "assistant",
+                 "content": "noted, ORCHID_PRIMARY"}},
+                {"type": "user", "message": {"role": "user", "content": WRAPPED}},
+            ]
+            with open(transcript, "w", encoding="utf-8") as f:
+                for r in rows:
+                    f.write(json.dumps(r) + "\n")
+
+            client = _RecordingClient(memories=[_memory("m")])
+            hook_input = {
+                "prompt": WRAPPED,
+                "session_id": "test-session",
+                "transcript_path": transcript,
+                "cwd": "/tmp",
+            }
+            config = {
+                "autoRecall": True,
+                "bankId": "test-bank",
+                "recallMaxTokens": 1024,
+                "recallBudget": "mid",
+                "recallContextTurns": 2,
+                "recallMaxQueryChars": 800,
+                "recallPromptPreamble": "",
+            }
+            stdout, stderr = io.StringIO(), io.StringIO()
+            with patch.object(recall, "load_config", return_value=config), patch.object(
+                recall, "get_api_url", return_value="http://localhost:18888"
+            ), patch.object(recall, "HindsightClient", return_value=client), patch.object(
+                recall, "ensure_bank_mission", return_value=None
+            ), patch.object(recall, "write_state", return_value=None), patch(
+                "sys.stdin", new=io.StringIO(json.dumps(hook_input))
+            ), patch("sys.stdout", new=stdout), patch("sys.stderr", new=stderr):
+                recall.main()
+
+            self.assertEqual(len(client.queries), 1)
+            q = client.queries[0]
+            self.assertNotIn("<channel", q)
+            self.assertNotIn("chat_id", q)
+            self.assertIn("Prior context:", q)
+            self.assertTrue(q.rstrip().endswith(BARE))
+        finally:
+            shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+class _LogTestBase(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="recall-log-test-")
+        self._prev = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmpdir
+
+    def tearDown(self):
+        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 _read_log(self):
+        path = os.path.join(self._tmpdir, "state", "recall_log.jsonl")
+        if not os.path.isfile(path):
+            return []
+        with open(path, encoding="utf-8") as f:
+            return [json.loads(line) for line in f if line.strip()]
+
+
+class StrippedQueryInLog(_LogTestBase):
+    def test_logged_query_has_no_channel_envelope(self):
+        client = _RecordingClient(memories=[_memory("m", mem_id="m1")])
+        _run_main_with(client, prompt=WRAPPED)
+        entries = self._read_log()
+        self.assertEqual(len(entries), 1)
+        e = entries[0]
+        self.assertIn("query", e)
+        self.assertEqual(e["query"], BARE)
+        self.assertNotIn("<channel", e["query"])
+        self.assertNotIn("chat_id", e["query"])
+
+
+class RecallTelemetryFields(_LogTestBase):
+    def test_telemetry_fields_present_on_success(self):
+        client = _RecordingClient(memories=[_memory("m", mem_id="m1")])
+        _run_main_with(client, prompt=BARE)
+        e = self._read_log()[0]
+        self.assertIn("total_elapsed_ms", e)
+        self.assertIsInstance(e["total_elapsed_ms"], int)
+        self.assertGreaterEqual(e["total_elapsed_ms"], 0)
+        self.assertIn("directives_elapsed_ms", e)
+        self.assertIsInstance(e["directives_elapsed_ms"], int)
+        self.assertIn("deadline_hit", e)
+        self.assertFalse(e["deadline_hit"])
+        # One bank timing record for the own bank, no timeout.
+        self.assertIn("bank_timings", e)
+        self.assertEqual(len(e["bank_timings"]), 1)
+        bt = e["bank_timings"][0]
+        self.assertEqual(bt["bank_id"], "test-bank")
+        self.assertFalse(bt["timed_out"])
+        self.assertIsInstance(bt["elapsed_ms"], int)
+
+    def test_additional_bank_gets_its_own_timing_record(self):
+        client = _RecordingClient(memories=[_memory("m", mem_id="m1")])
+        _run_main_with(
+            client,
+            prompt=BARE,
+            config_extra={"recallAdditionalBanks": ["shared-bank"]},
+        )
+        e = self._read_log()[0]
+        banks = [bt["bank_id"] for bt in e["bank_timings"]]
+        self.assertEqual(banks, ["test-bank", "shared-bank"])
+
+    def test_deadline_hit_true_when_a_bank_times_out(self):
+        # Own bank succeeds; the additional bank raises a socket timeout.
+        client = _RecordingClient(
+            memories=[_memory("m", mem_id="m1")],
+            bank_behaviour={"shared-bank": socket.timeout("timed out")},
+        )
+        _run_main_with(
+            client,
+            prompt=BARE,
+            config_extra={"recallAdditionalBanks": ["shared-bank"]},
+        )
+        e = self._read_log()[0]
+        self.assertTrue(e["deadline_hit"])
+        timings = {bt["bank_id"]: bt for bt in e["bank_timings"]}
+        self.assertFalse(timings["test-bank"]["timed_out"])
+        self.assertTrue(timings["shared-bank"]["timed_out"])
+
+    def test_non_timeout_error_is_not_deadline_hit(self):
+        # A 5xx / connection error is an error but NOT a deadline hit.
+        client = _RecordingClient(
+            memories=[_memory("m", mem_id="m1")],
+            bank_behaviour={"shared-bank": RuntimeError("HTTP 503 from server")},
+        )
+        _run_main_with(
+            client,
+            prompt=BARE,
+            config_extra={"recallAdditionalBanks": ["shared-bank"]},
+        )
+        e = self._read_log()[0]
+        self.assertFalse(e["deadline_hit"])
+        timings = {bt["bank_id"]: bt for bt in e["bank_timings"]}
+        self.assertFalse(timings["shared-bank"]["timed_out"])
+
+
+class TotalFailureStillLogs(_LogTestBase):
+    """Review finding 1 — a turn where every bank times out AND directives
+    are empty produces no injected block, yet the telemetry row (the exact
+    breach event the baseline counts) must still be written."""
+
+    def test_own_bank_timeout_no_directives_still_writes_row(self):
+        client = _RecordingClient(
+            memories=[],
+            directives=[],
+            bank_behaviour={"test-bank": socket.timeout("timed out")},
+        )
+        ctx, raw = _run_main_with(client, prompt=BARE)
+        # No block injected (no directives, no memories).
+        self.assertIsNone(ctx)
+        self.assertEqual(raw.strip(), "")
+        # …but the telemetry row exists and records the deadline hit.
+        entries = self._read_log()
+        self.assertEqual(len(entries), 1)
+        e = entries[0]
+        self.assertFalse(e["cache_hit"])
+        self.assertTrue(e["deadline_hit"])
+        self.assertEqual(e["result_count"], 0)
+        self.assertEqual(len(e["bank_timings"]), 1)
+        self.assertTrue(e["bank_timings"][0]["timed_out"])
+        self.assertIsInstance(e["total_elapsed_ms"], int)
+
+    def test_query_field_is_bounded_excerpt(self):
+        # Review finding 5 — the stored query is a bounded excerpt (≤200)
+        # even when the real query is long; query_chars keeps the full length.
+        long_tail = "auth flow " * 200  # ~2000 chars, well over the 800 cap
+        client = _RecordingClient(memories=[_memory("m", mem_id="m1")])
+        _run_main_with(client, prompt="decide " + long_tail)
+        e = self._read_log()[0]
+        self.assertLessEqual(len(e["query"]), 200)
+        # Full (post-truncation) length is still recorded separately.
+        self.assertGreater(e["query_chars"], 200)
+
+
+class CacheHitRowSchema(_LogTestBase):
+    """Review finding 3 — a cache-hit row carries the telemetry keys as
+    None/[] (no banks ran), never `deadline_hit: False`."""
+
+    def test_cache_hit_row_has_none_telemetry(self):
+        client = _RecordingClient(memories=[_memory("unused")])
+        with patch.object(recall, "_cache_ttl_secs", return_value=300), patch.object(
+            recall, "_cache_lookup", return_value="cached context block"
+        ):
+            _run_main_with(client, prompt=BARE)
+        # The cache hit returns before any client.recall call.
+        self.assertEqual(client.queries, [])
+        entries = self._read_log()
+        self.assertEqual(len(entries), 1)
+        e = entries[0]
+        self.assertTrue(e["cache_hit"])
+        self.assertIsNone(e["deadline_hit"])
+        self.assertEqual(e["bank_timings"], [])
+        self.assertIsNone(e["total_elapsed_ms"])
+        self.assertIsNone(e["directives_elapsed_ms"])
+        self.assertIsNone(e["query"])
+        # PR8 (#3369) — the bank_errored field is present on cache-hit rows
+        # for a uniform schema, and is None (NOT False) since no banks ran, so
+        # a reader can do row["bank_errored"] without a KeyError and the row is
+        # never miscounted as an observed no-error recall.
+        self.assertIn("bank_errored", e)
+        self.assertIsNone(e["bank_errored"])
+
+
+class MultiEnvelopeStrip(unittest.TestCase):
+    """Review finding 6 — strip_channel_envelope now sits on the live query
+    path, so a coalesced multi-envelope prompt must keep every inner text,
+    not just the first."""
+
+    def test_single_envelope_unchanged(self):
+        self.assertEqual(
+            strip_channel_envelope('<channel source="telegram">hello there</channel>'),
+            "hello there",
+        )
+
+    def test_bare_text_unchanged(self):
+        self.assertEqual(strip_channel_envelope("no envelope here"), "no envelope here")
+
+    def test_two_envelopes_are_coalesced(self):
+        content = (
+            '<channel source="telegram" chat_id="1">first message</channel>'
+            '<channel source="telegram" chat_id="1">second message</channel>'
+        )
+        out = strip_channel_envelope(content)
+        self.assertIn("first message", out)
+        self.assertIn("second message", out)
+        self.assertNotIn("<channel", out)
+        self.assertNotIn("chat_id", out)
+
+    def test_three_envelopes_with_interleaved_whitespace(self):
+        content = (
+            '<channel source="telegram">alpha</channel>\n'
+            '<channel source="telegram">beta</channel>\n'
+            '<channel source="telegram">gamma</channel>'
+        )
+        out = strip_channel_envelope(content)
+        for tok in ("alpha", "beta", "gamma"):
+            self.assertIn(tok, out)
+        self.assertNotIn("<channel", out)
+
+
+class TimeoutClassifier(unittest.TestCase):
+    """Unit coverage for _is_timeout_error's classification."""
+
+    def test_socket_timeout(self):
+        self.assertTrue(recall._is_timeout_error(socket.timeout("timed out")))
+
+    def test_builtin_timeout_error(self):
+        self.assertTrue(recall._is_timeout_error(TimeoutError("timed out")))
+
+    def test_urlerror_wrapping_timeout(self):
+        import urllib.error
+        self.assertTrue(
+            recall._is_timeout_error(urllib.error.URLError(socket.timeout("timed out")))
+        )
+
+    def test_runtime_error_with_timeout_message(self):
+        self.assertTrue(recall._is_timeout_error(RuntimeError("request timed out after 8s")))
+
+    def test_plain_http_error_is_not_timeout(self):
+        self.assertFalse(recall._is_timeout_error(RuntimeError("HTTP 503 from server")))
+
+    def test_connection_refused_is_not_timeout(self):
+        self.assertFalse(recall._is_timeout_error(ConnectionRefusedError("refused")))
+
+    def test_http_504_wrapper_with_timed_out_body_is_not_timeout(self):
+        # Review finding 4 — lib.client wraps HTTP errors as
+        # `RuntimeError("HTTP <code> from <url>: <body>")`. A 502/504 body
+        # containing an upstream proxy's "timed out" text is a SERVER status,
+        # not a client-side read deadline.
+        self.assertFalse(
+            recall._is_timeout_error(
+                RuntimeError("HTTP 504 from http://h/recall: upstream request timed out")
+            )
+        )
+
+    def test_direct_httperror_is_not_timeout(self):
+        import urllib.error
+        exc = urllib.error.HTTPError(
+            url="http://h/recall", code=504, msg="Gateway Timeout", hdrs=None, fp=None
+        )
+        self.assertFalse(recall._is_timeout_error(exc))
+
+    def test_runtimeerror_causing_httperror_is_not_timeout(self):
+        import urllib.error
+        http = urllib.error.HTTPError(
+            url="http://h/recall", code=502, msg="Bad Gateway", hdrs=None, fp=None
+        )
+        wrapper = RuntimeError("wrapped: connection timed out")
+        wrapper.__cause__ = http
+        self.assertFalse(recall._is_timeout_error(wrapper))
+
+
+if __name__ == "__main__":
+    unittest.main()