switchroom 0.21.14 → 0.21.16

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

@@ -0,0 +1,335 @@
+"""RFC phase4 P3 — unit + end-to-end tests for the operator-profile capture nudge.
+
+Ken's first stated want is "save memories about him". Auto-retain stores
+transcript facts, but nothing gives a DETERMINISTIC signal that a durable
+*profile fact* about the operator himself just went by — so profile capture is
+left to model discretion (the same per-agent lottery Stage A measured for
+directives). P3 mirrors the shipped directive-capture nudge (recall.py #2848):
+a POSITIVE regex detects a first-person durable self-statement, a NEGATIVE
+regex scrubs the two false-positive shapes (questions, attributions to others)
+BEFORE the positive match, and on a hit the UserPromptSubmit hook appends a
+terse advisory telling the model to persist it with an explicit retain tagged
+`profile:ken` into the agent's OWN bank. Pure regex — no model callsite.
+
+These tests pin (all OUTCOME assertions):
+  * True positives — the RFC's listed profile shapes fire.
+  * True negatives — questions and third-/second-party attributions do NOT
+    fire (the negative-lookaround guard scrubs them first).
+  * The advisory carries the `profile:ken` tag instruction and targets the
+    agent's OWN bank (not a shared / cross-agent person bank).
+  * End-to-end through recall.main(): the advisory reaches the emitted
+    additionalContext, the recall_log row carries `profile_nudge: true`, and
+    the config knob OFF (`profileCaptureNudge: false`) suppresses both.
+
+Stdlib-only; runs under `python3 -m unittest discover tests/`. The end-to-end
+harness mirrors test_recall_envelope_strip_telemetry.py.
+"""
+
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+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 recall import (  # noqa: E402
+    _PROFILE_CAPTURE_NUDGE,
+    _combine_context,
+    _is_trivial_stateless,
+    looks_like_profile_statement,
+)
+
+
+# First-person durable self-statements that MUST fire the nudge. Drawn from the
+# RFC P3 shapes ("I prefer …", "my … is …", "I always …", "remind me that I …")
+# plus the conservative identity/situation set.
+PROFILE_STATEMENTS = [
+    # --- stated preferences ---
+    "I prefer dark roast coffee",
+    "I'd prefer British spelling in my docs",
+    "my preference is tabs over spaces",
+    # --- durable self-facts: "my <ATTRIBUTE> is/are …" (tight allow-list) ---
+    "my timezone is Australia/Melbourne",
+    "my email is ken@example.com",
+    "my sister is Lisa",
+    "my kids are at school during the day",
+    "my name's Ken",  # contraction form
+    # --- identity / situation ---
+    "I live in Melbourne",
+    "I work at Anthropic",
+    "I'm allergic to peanuts",
+    "I'm based in Australia",
+    # --- durable identity: diet / abstention / "I'm a <noun>" ---
+    "I'm a vegetarian",
+    "I don't eat meat",
+    "call me Ken",
+    # --- tastes (durable like/dislike framing) ---
+    "I hate em-dashes",
+    # --- durable habits ---
+    "I always take my coffee black",
+    "I usually work late on Thursdays",
+    "I never eat red meat",
+    # --- explicit memory framing about the operator himself ---
+    "remind me that I have a standing 9am standup",
+    "remember that I hate em-dashes",
+]
+
+# Questions and attributions that MUST NOT fire — the negative-lookaround guard
+# scrubs these BEFORE the positive match. A false positive here is nudge noise.
+NON_PROFILE = [
+    # --- questions about the operator (not statements of a durable fact) ---
+    "do I prefer tea or coffee?",
+    "what's my timezone?",
+    "where is my email address stored?",
+    "how do I fix this bug",
+    "should I always run the tests first?",
+    "what do I usually do here",
+    "remind me what my calendar looks like",
+    # --- attributions to a third / second party ---
+    "you said I prefer tea",
+    "she claims my code is broken",
+    "he thinks I always overcomplicate things",
+    "they told me my access was revoked",
+    # --- neither: no first-person durable self-fact ---
+    "the project timezone is UTC",
+    "please run the tests",
+    "what time is it",
+    # --- discourse-marker "my <X> is" — not a durable profile fact. The
+    #     positive arm uses a TIGHT identity allow-list, so a free noun never
+    #     reaches the matcher; these confirm that. ---
+    "my guess is the cache is stale",
+    "my point is that we should ship it",
+    "my concern is the timeout",
+    # --- transient dev state "my <transient> is/are …". These are the exact
+    #     over-fires the free-`\w+` arm produced; the allow-list must NOT fire
+    #     on them (RFC favour-false-negatives constraint on this agent). ---
+    "my container is down",
+    "my build is failing",
+    "my code is broken",
+    "my PR is ready",
+    "my worktree is dirty",
+    "my server is down",
+    "my deploy is stuck",
+    "my tests are green",
+    "my branch is merged",
+    # --- pleasantry embedding a bare always/never after "I" ---
+    "I always appreciate your help",
+    "I never enjoy waiting, but thanks",
+    # --- "I'm a <hedge>" is a transient mood, not an "I'm a <noun>" identity ---
+    "I'm a bit tired",
+    "I'm a little confused about the config",
+    "I'm a big fan of shipping fast",
+    # --- "call me <phrasing>" as a request, not a name form ---
+    "call me back later",
+    "call me when the build finishes",
+    # --- the <channel …> envelope wrapper on its own must never trigger ---
+    '<channel user="ken" chat_id="123">',
+]
+
+
+class TestProfileDetection(unittest.TestCase):
+    def test_profile_statements_fire_the_nudge(self):
+        for p in PROFILE_STATEMENTS:
+            with self.subTest(prompt=p):
+                self.assertTrue(
+                    looks_like_profile_statement(p),
+                    f"expected profile detection for {p!r}",
+                )
+
+    def test_questions_and_attributions_do_not_fire(self):
+        for p in NON_PROFILE:
+            with self.subTest(prompt=p):
+                self.assertFalse(
+                    looks_like_profile_statement(p),
+                    f"FALSE POSITIVE: profile nudge would fire for {p!r}",
+                )
+
+    def test_empty_and_non_string_are_false(self):
+        for bad in ("", "   ", None, 123, [], {}):
+            with self.subTest(value=bad):
+                self.assertFalse(looks_like_profile_statement(bad))
+
+    def test_attribution_scrub_does_not_mask_a_real_self_fact(self):
+        # A message that opens with an attributed clause AND then states the
+        # operator's own durable fact must still fire — the negative guard
+        # scrubs only the attributed span (through end-of-sentence).
+        self.assertTrue(
+            looks_like_profile_statement(
+                "she thinks I'm wrong. my timezone is Melbourne"
+            )
+        )
+
+    def test_attribution_scrub_stops_at_a_comma(self):
+        # The attributed span must stop at a comma, not run to end-of-sentence:
+        # a real self-fact trailing the attributed clause in the SAME sentence
+        # must still reach the positive matcher (MINOR: greedy [^.?!]* → [^.?!,]*).
+        self.assertTrue(
+            looks_like_profile_statement(
+                "she said the deploy failed, my timezone is Melbourne"
+            )
+        )
+
+
+class TestProfileNudgeString(unittest.TestCase):
+    def test_nudge_carries_the_profile_ken_tag_instruction(self):
+        self.assertIn("profile:ken", _PROFILE_CAPTURE_NUDGE)
+        self.assertIn("retain", _PROFILE_CAPTURE_NUDGE)
+        self.assertIn("profile_capture_check", _PROFILE_CAPTURE_NUDGE)
+
+    def test_nudge_targets_the_agents_own_bank_not_a_shared_one(self):
+        # Constraint 2 forbids a cross-agent person bank — the advisory must
+        # route to the agent's OWN bank and say so explicitly.
+        self.assertIn("OWN bank", _PROFILE_CAPTURE_NUDGE)
+        self.assertIn("shared", _PROFILE_CAPTURE_NUDGE)
+
+    def test_combine_appends_nudge_after_recall_block(self):
+        base = "<hindsight_memories>\n…\n</hindsight_memories>"
+        out = _combine_context(base, _PROFILE_CAPTURE_NUDGE)
+        self.assertTrue(out.startswith(base))
+        self.assertTrue(out.endswith(_PROFILE_CAPTURE_NUDGE))
+
+
+class TestTrivialSkipUnaffected(unittest.TestCase):
+    """A profile statement carries personal/stateful signal and must never be
+    trivial-stateless-skipped; greetings still are."""
+
+    def test_profile_statements_are_never_trivial_skipped(self):
+        for p in PROFILE_STATEMENTS:
+            with self.subTest(prompt=p):
+                self.assertFalse(
+                    _is_trivial_stateless("", p),
+                    f"profile statement {p!r} was trivial-skipped",
+                )
+
+
+# --- End-to-end harness (mirrors test_recall_envelope_strip_telemetry.py) ---
+
+
+class _RecordingClient:
+    def __init__(self, memories=None, directives=None):
+        self._memories = memories if memories is not None else []
+        self._directives = directives if directives is not None else []
+        self.queries = []
+
+    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)
+        return {"results": list(self._memories)}
+
+
+def _run_main_with(client, prompt, config_extra=None):
+    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
+
+
+# A profile-only prompt: matches the profile regex but NOT the directive regex,
+# so these end-to-end assertions isolate the profile nudge cleanly.
+PROFILE_PROMPT = "my timezone is Australia/Melbourne"
+
+
+class _LogTestBase(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="profile-nudge-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 ProfileNudgeEndToEnd(_LogTestBase):
+    def test_advisory_reaches_context_and_row_records_it(self):
+        client = _RecordingClient(memories=[{"text": "m", "type": "fact",
+                                             "mentioned_at": "2026-01-01", "id": "m1"}])
+        ctx, _raw = _run_main_with(client, prompt=PROFILE_PROMPT)
+        # The profile advisory is injected into the turn context, tagged and
+        # own-bank-scoped.
+        self.assertIsNotNone(ctx)
+        self.assertIn("profile:ken", ctx)
+        self.assertIn("OWN bank", ctx)
+        # The recall_log row carries the firing-rate boolean.
+        entries = self._read_log()
+        self.assertEqual(len(entries), 1)
+        self.assertTrue(entries[0]["profile_nudge"])
+
+    def test_knob_off_suppresses_nudge_and_row_is_false(self):
+        client = _RecordingClient(memories=[{"text": "m", "type": "fact",
+                                             "mentioned_at": "2026-01-01", "id": "m1"}])
+        ctx, _raw = _run_main_with(
+            client, prompt=PROFILE_PROMPT,
+            config_extra={"profileCaptureNudge": False},
+        )
+        # Nudge suppressed: the advisory is absent from context (memories may
+        # still be injected, but never the profile block).
+        if ctx is not None:
+            self.assertNotIn("profile:ken", ctx)
+            self.assertNotIn("profile_capture_check", ctx)
+        entries = self._read_log()
+        self.assertEqual(len(entries), 1)
+        self.assertFalse(entries[0]["profile_nudge"])
+
+    def test_non_profile_prompt_does_not_fire(self):
+        client = _RecordingClient(memories=[{"text": "m", "type": "fact",
+                                             "mentioned_at": "2026-01-01", "id": "m1"}])
+        ctx, _raw = _run_main_with(client, prompt="please run the tests")
+        if ctx is not None:
+            self.assertNotIn("profile:ken", ctx)
+        entries = self._read_log()
+        self.assertEqual(len(entries), 1)
+        self.assertFalse(entries[0]["profile_nudge"])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,143 @@
+"""M4 P0 — buffer + sentinel primitive, OUTCOME tests (RED test a).
+
+The sentinel/poll race is the whole safety story for M4's prefetch producer
+(carve §4 note 1, red-team-verified sound). This module is the FOUNDATION
+every other M4 packet depends on: P-REC's join logic and P-PRE's producer
+both build on the read-after-write guarantee proven here.
+
+Contract under test:
+  (i)   ``buffer.done`` is written strictly AFTER the buffer payload
+        (mtime/content ordering — proven via a monotonic token, not wall
+        clock, since two writes can land in the same clock tick).
+  (ii)  ``read_if_fresh(last_consumed_token)`` returns ``(None, token)``
+        when the sentinel is absent, or not newer than ``last_consumed``.
+  (iii) A torn write (payload present, sentinel absent) reads as ``None``
+        — fail-closed, never a stale/malformed payload leaking through.
+  (iv)  ``poll_for_sentinel`` is clock-bounded: never exceeds its cap, no
+        busy-spin (sleeps sum to <= cap, with generous tolerance).
+
+Stdlib-only (``python3 -m unittest discover tests/``).
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+import time
+import unittest
+from unittest import mock
+
+SCRIPTS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, SCRIPTS_DIR)
+
+from lib import recall_buffer  # noqa: E402
+
+
+class RecallBufferBase(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="hs-m4-buffer-")
+        self.env = mock.patch.dict(
+            os.environ, {"HINDSIGHT_PREFETCH_BUFFER_DIR": self.tmp}, clear=False
+        )
+        self.env.start()
+
+    def tearDown(self):
+        self.env.stop()
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+
+class TestSentinelOrdering(RecallBufferBase):
+    def test_sentinel_written_strictly_after_payload(self):
+        session = "sess-order"
+        write_order = []
+        real_replace = os.replace
+
+        def _spy_replace(src, dst):
+            write_order.append(os.path.basename(dst))
+            return real_replace(src, dst)
+
+        with mock.patch("os.replace", side_effect=_spy_replace):
+            recall_buffer.write_buffer(session, "<hindsight_memories>x</hindsight_memories>", {"k": "v"})
+            recall_buffer.write_sentinel(session)
+
+        buffer_writes = [w for w in write_order if "buffer.json" in w]
+        sentinel_writes = [w for w in write_order if "buffer.done" in w]
+        self.assertEqual(len(buffer_writes), 1)
+        self.assertEqual(len(sentinel_writes), 1)
+        self.assertLess(
+            write_order.index(buffer_writes[0]),
+            write_order.index(sentinel_writes[0]),
+            "sentinel must be written strictly AFTER the buffer payload",
+        )
+
+    def test_read_if_fresh_returns_none_when_sentinel_absent(self):
+        session = "sess-nosentinel"
+        recall_buffer.write_buffer(session, "content", {})
+        ctx, token = recall_buffer.read_if_fresh(session, last_consumed_token=None)
+        self.assertIsNone(ctx)
+
+    def test_read_if_fresh_returns_none_when_sentinel_not_newer(self):
+        session = "sess-stale"
+        recall_buffer.write_buffer(session, "content", {})
+        token = recall_buffer.write_sentinel(session)
+        # Already consumed this exact token -> not fresh.
+        ctx, new_token = recall_buffer.read_if_fresh(session, last_consumed_token=token)
+        self.assertIsNone(ctx)
+        self.assertEqual(new_token, token)
+
+    def test_read_if_fresh_returns_payload_when_sentinel_is_newer(self):
+        session = "sess-fresh"
+        recall_buffer.write_buffer(session, "<hindsight_memories>fact</hindsight_memories>", {"telemetry": 1})
+        token = recall_buffer.write_sentinel(session)
+        ctx, new_token = recall_buffer.read_if_fresh(session, last_consumed_token=None)
+        self.assertIsNotNone(ctx)
+        self.assertIn("fact", ctx["context"])
+        self.assertEqual(ctx["telemetry"], {"telemetry": 1})
+        self.assertEqual(new_token, token)
+
+    def test_torn_write_payload_present_sentinel_absent_reads_as_none(self):
+        # Simulate a crash between write_buffer() and write_sentinel(): the
+        # payload landed, the sentinel never did. Must fail-closed to None,
+        # NEVER read the torn/possibly-incomplete payload as fresh.
+        session = "sess-torn"
+        recall_buffer.write_buffer(session, "<hindsight_memories>partial</hindsight_memories>", {})
+        # No write_sentinel() call — this IS the torn state.
+        ctx, token = recall_buffer.read_if_fresh(session, last_consumed_token=None)
+        self.assertIsNone(ctx, "torn write (payload without sentinel) must read as None, fail-closed")
+
+
+class TestPollCap(RecallBufferBase):
+    def test_poll_returns_true_when_sentinel_appears(self):
+        session = "sess-poll-hit"
+        recall_buffer.write_buffer(session, "content", {})
+        recall_buffer.write_sentinel(session)
+        found = recall_buffer.poll_for_sentinel(session, last_consumed_token=None, cap_ms=500)
+        self.assertTrue(found)
+
+    def test_poll_never_exceeds_cap(self):
+        # No sentinel ever appears — poll must give up within cap_ms
+        # (generous tolerance for test-host scheduling jitter).
+        session = "sess-poll-miss"
+        cap_ms = 200
+        start = time.monotonic()
+        found = recall_buffer.poll_for_sentinel(session, last_consumed_token=None, cap_ms=cap_ms)
+        elapsed_ms = (time.monotonic() - start) * 1000
+        self.assertFalse(found)
+        self.assertLess(elapsed_ms, cap_ms + 150, "poll exceeded its cap by more than tolerance")
+
+    def test_poll_does_not_busy_spin(self):
+        # A busy-spin would burn far more than a handful of read attempts in
+        # the cap window; assert sleep is actually happening by checking the
+        # elapsed time is close to (not far below) the cap when nothing
+        # ever shows up.
+        session = "sess-poll-nospin"
+        cap_ms = 150
+        start = time.monotonic()
+        recall_buffer.poll_for_sentinel(session, last_consumed_token=None, cap_ms=cap_ms)
+        elapsed_ms = (time.monotonic() - start) * 1000
+        self.assertGreaterEqual(elapsed_ms, cap_ms * 0.5, "poll returned suspiciously fast — looks like it skipped sleeping")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,193 @@
+"""M4 P-REC test (b) + red-team Fix B / Fix C — prefetch buffer join.
+
+Asserts on RENDERED transport (`additionalContext`), never on an internal
+flag alone, per the red-team's explicit strengthening. Covers:
+
+  * Fix C (kill switch): `memoryPrefetchEnabled` OFF (the default) leaves
+    the mechanism completely inert — synchronous recall runs exactly as
+    before, `lib.recall_buffer` is never touched.
+  * Fresh-hit: a producer-written buffer is joined and rendered as-is.
+  * Fix B (BINDING): the stale-buffer fallback (no fresh sentinel, but a
+    prior `LAST_RECALL_STATE` exists) renders memories WITHOUT any
+    directives block, even when a directive is active for the bank —
+    directives stay on the synchronous fetch path, never the stale cache.
+  * Cold-start short circuit: no sentinel has EVER existed for the session
+    -> no poll wait, falls through to the degraded notice / sync path
+    without blocking for the poll cap.
+"""
+
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+import time
+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
+from lib.state import write_state  # noqa: E402
+
+SESSION = "test-session"
+
+
+class _DirectiveClient:
+    """Answers with ONE active directive and no memories (recall not
+    expected to be called on the fresh-hit/stale-fallback fast paths, but
+    directive fetch IS expected — always synchronous per M3)."""
+
+    def list_directives(self, bank_id, active_only=True, timeout=2):
+        return {"items": [{"id": "d1", "name": "haiku-rule", "content": "always reply in haiku", "priority": 5, "active": True}]}
+
+    def recall(self, bank_id, query, **kwargs):
+        raise AssertionError("buffer-join fast path must not call recall() directly")
+
+
+class BufferJoinBase(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="recall-bufjoin-test-")
+        self._prev = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmpdir
+
+        self._bufdir = tempfile.mkdtemp(prefix="recall-bufjoin-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, prefetch_enabled):
+        return {
+            "autoRecall": True,
+            "bankId": "test-bank",
+            "recallMaxTokens": 4096,
+            "recallBudget": "mid",
+            "recallContextTurns": 1,
+            "recallMaxQueryChars": 800,
+            "recallPromptPreamble": "",
+            "recallParallelDeadlineSeconds": 5,
+            "directivesCacheTtlSeconds": 0,
+            "memoryPrefetchEnabled": prefetch_enabled,
+            "memoryPrefetchPollCapMs": 100,
+        }
+
+    def _run(self, config, client, prompt="what did we decide about deploys"):
+        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()
+        return stdout.getvalue()
+
+
+class FreshHitTests(BufferJoinBase):
+    def test_fresh_buffer_hit_is_rendered_with_directives_layered_on(self):
+        recall_buffer.write_buffer(SESSION, "- a prefetched memory", {})
+        recall_buffer.write_sentinel(SESSION)
+
+        out = self._run(self._config(prefetch_enabled=True), _DirectiveClient())
+        self.assertTrue(out)
+        ctx = json.loads(out)["hookSpecificOutput"]["additionalContext"]
+        self.assertIn("a prefetched memory", ctx)
+        self.assertIn("always reply in haiku", ctx)
+
+
+class StaleFallbackFixBTests(BufferJoinBase):
+    def test_stale_fallback_renders_memories_without_any_directives_block(self):
+        # No fresh sentinel this turn (buffer is cold), but a prior turn's
+        # cache DOES exist and DOES include memories_context (directive-free
+        # per Fix B) plus a bundled directive in `context` that must NOT
+        # leak through the stale path.
+        write_state(
+            recall.LAST_RECALL_STATE,
+            {
+                "context": "## Active Directives\n- always reply in haiku\n\n- a stale cached memory",
+                "memories_context": "- a stale cached memory",
+                "saved_at": "2026-01-01T00:00:00Z",
+                "bank_id": "test-bank",
+                "result_count": 1,
+                "directive_count": 1,
+            },
+        )
+        out = self._run(self._config(prefetch_enabled=True), _DirectiveClient())
+        self.assertTrue(out)
+        ctx = json.loads(out)["hookSpecificOutput"]["additionalContext"]
+        self.assertIn("a stale cached memory", ctx)
+        self.assertIn("stale", ctx.lower())
+        # Fix B, BINDING: the fresh directive fetch (synchronous, M3 rule)
+        # IS allowed to appear — what must NEVER appear is the STALE
+        # directives text sourced from the cached `context` field. Prove
+        # this by using a client whose directive text differs from what a
+        # stale-context leak would have produced, and confirming there is
+        # exactly one occurrence (the fresh fetch), not a duplicate/leaked
+        # second copy from the cache.
+        self.assertEqual(ctx.count("always reply in haiku"), 1)
+
+    def test_stale_fallback_directive_free_field_never_leaks_bare_context_directives(self):
+        # A cache row is deliberately malformed/legacy-shaped (missing the
+        # M4 `memories_context` field entirely, i.e. pre-M4 cache on disk).
+        # The fallback must degrade to "nothing stale to show", NEVER fall
+        # back to the directive-contaminated `context` field.
+        write_state(
+            recall.LAST_RECALL_STATE,
+            {
+                "context": "## Active Directives\n- always reply in haiku\n\n- a stale cached memory",
+                "saved_at": "2026-01-01T00:00:00Z",
+                "bank_id": "test-bank",
+                "result_count": 1,
+                "directive_count": 1,
+            },
+        )
+        client = _DirectiveClient()
+        out = self._run(self._config(prefetch_enabled=True), client)
+        self.assertTrue(out)
+        ctx = json.loads(out)["hookSpecificOutput"]["additionalContext"]
+        self.assertNotIn("a stale cached memory", ctx, "must not fall back to the directive-contaminated context field")
+
+
+class ColdStartShortCircuitTests(BufferJoinBase):
+    def test_no_sentinel_ever_written_skips_the_poll_wait(self):
+        config = self._config(prefetch_enabled=True)
+        config["memoryPrefetchPollCapMs"] = 5000  # would dominate the test if NOT short-circuited
+        start = time.monotonic()
+        out = self._run(config, _DirectiveClient())
+        elapsed_ms = (time.monotonic() - start) * 1000
+        self.assertTrue(out)
+        self.assertLess(elapsed_ms, 1000, "cold-start (no sentinel ever) must not wait out the poll cap")
+
+
+class KillSwitchOffTests(BufferJoinBase):
+    def test_flag_off_never_touches_the_buffer_module(self):
+        recall_buffer.write_buffer(SESSION, "- a prefetched memory", {})
+        recall_buffer.write_sentinel(SESSION)
+
+        with patch("recall.recall_buffer.read_if_fresh", side_effect=AssertionError("must not be called when flag is off")):
+            client = _DirectiveClient()
+            client.recall = lambda *a, **kw: {"results": []}  # sync path IS allowed to call recall
+            out = self._run(self._config(prefetch_enabled=False), client)
+        self.assertTrue(out)
+        ctx = json.loads(out)["hookSpecificOutput"]["additionalContext"]
+        # Byte-identical-behaviour proof: the buffer's content must NOT
+        # appear (it was never consulted) even though it exists on disk.
+        self.assertNotIn("a prefetched memory", ctx)
+
+
+if __name__ == "__main__":
+    unittest.main()