switchroom 0.21.15 → 0.21.16

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

@@ -0,0 +1,247 @@
+"""M4 P-PRE — prefetch.py producer pipeline.
+
+Tests:
+  (a-integration) call order: delta retain runs BEFORE the speculative
+    recall, which runs BEFORE the buffer/sentinel write — proven via a
+    shared event-order list, not mocked call assertions alone.
+  (c, red-team STRENGTHENED) a fact retained at turn N-2 is STILL
+    recallable after further retains at N-1/N — guards against the
+    truncation bug (Fix A), not merely "present in the latest delta".
+  Fix C (producer side): `memoryPrefetchEnabled` off is a hard no-op —
+    no retain, no recall, no buffer file written.
+  Junk gate: a `<task-notification>` turn is skipped (no retain, no
+    recall, no buffer write) same as recall.py's consumer-side gate.
+"""
+
+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 prefetch  # noqa: E402
+from lib import recall_buffer  # noqa: E402
+
+SESSION = "prefetch-test-session"
+
+
+def _write_transcript(path, turns):
+    """turns: list of (role, text) tuples, in order."""
+    with open(path, "w", encoding="utf-8") as f:
+        for i, (role, text) in enumerate(turns):
+            entry = {
+                "type": role,
+                "uuid": f"u{i}",
+                "message": {"role": role, "content": text},
+            }
+            f.write(json.dumps(entry) + "\n")
+
+
+class _Daemon:
+    """A tiny in-memory fake standing in for the whole retain+recall
+    round trip, so the truncation-regression test (c) is a REAL round
+    trip through retain.run_retain + a recall against retained content,
+    not two independently-mocked legs."""
+
+    def __init__(self):
+        self.documents = {}  # document_id -> text
+
+    def retain(self, bank_id, content, document_id=None, **kwargs):
+        self.documents[document_id or bank_id] = content
+        return {"status": "ok", "document_id": document_id or bank_id}
+
+    def recall(self, bank_id, query, **kwargs):
+        # Naive substring match across all retained documents — enough to
+        # prove presence/absence, not a real ranking engine.
+        hits = []
+        for i, (doc_id, text) in enumerate(self.documents.items()):
+            hits.append({
+                "text": text, "type": "fact", "mentioned_at": "2026-01-01",
+                "id": f"r{i}", "scores": {"final": 1.0 - i * 0.01},
+            })
+        return {"results": hits}
+
+    def list_directives(self, bank_id, active_only=True, timeout=2):
+        return {"items": []}
+
+
+class PrefetchPipelineBase(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="prefetch-test-")
+        self.plugin_root = os.path.join(self._tmpdir, "plugin_root")
+        self.data = os.path.join(self._tmpdir, "data")
+        self.home = os.path.join(self._tmpdir, "home")
+        for d in (self.plugin_root, self.data, self.home):
+            os.makedirs(d)
+        self._write_settings(prefetch_enabled=True)
+
+        self._bufdir = tempfile.mkdtemp(prefix="prefetch-test-buf-")
+        self.env = mock.patch.dict(os.environ, {
+            "CLAUDE_PLUGIN_ROOT": self.plugin_root,
+            "CLAUDE_PLUGIN_DATA": self.data,
+            "HOME": self.home,
+            "HINDSIGHT_PREFETCH_BUFFER_DIR": self._bufdir,
+            "HINDSIGHT_PENDING_DIR": os.path.join(self.home, ".hindsight", "pending-retains"),
+            "HINDSIGHT_RETAINED_DIR": os.path.join(self.home, ".hindsight", "retained"),
+            "HINDSIGHT_INFLIGHT_LOCK": os.path.join(self.home, ".hindsight", "retain-inflight.lock"),
+            "HINDSIGHT_TRANSCRIPTS_DIR": os.path.join(self._tmpdir, "transcripts"),
+        }, clear=False)
+        self.env.start()
+        for k in list(os.environ):
+            if k.startswith("HINDSIGHT_") and k not in (
+                "HINDSIGHT_PREFETCH_BUFFER_DIR", "HINDSIGHT_PENDING_DIR",
+                "HINDSIGHT_RETAINED_DIR", "HINDSIGHT_INFLIGHT_LOCK", "HINDSIGHT_TRANSCRIPTS_DIR",
+            ):
+                os.environ.pop(k, None)
+
+        self.transcript_path = os.path.join(self._tmpdir, "transcript.jsonl")
+        self.daemon = _Daemon()
+
+    def _write_settings(self, prefetch_enabled=True):
+        settings = {
+            "autoRetain": True,
+            "bankId": "test-bank",
+            "retainMode": "chunked",
+            "retainEveryNTurns": 1,
+            "retainOverlapTurns": 0,
+            "memoryPrefetchEnabled": prefetch_enabled,
+        }
+        with open(os.path.join(self.plugin_root, "settings.json"), "w") as f:
+            json.dump(settings, f)
+
+    def tearDown(self):
+        self.env.stop()
+        shutil.rmtree(self._bufdir, ignore_errors=True)
+        shutil.rmtree(self._tmpdir, ignore_errors=True)
+
+    def _config(self, prefetch_enabled=True):
+        return {
+            "bankId": "test-bank",
+            "memoryPrefetchEnabled": prefetch_enabled,
+            "retainMode": "chunked",
+            "retainEveryNTurns": 1,
+        }
+
+    def _hook_input(self, prompt="what's the deploy status"):
+        return {
+            "prompt": prompt,
+            "session_id": SESSION,
+            "transcript_path": self.transcript_path,
+            "cwd": "/tmp",
+        }
+
+
+class CallOrderTests(PrefetchPipelineBase):
+    def test_retain_then_recall_then_sentinel_in_that_order(self):
+        _write_transcript(self.transcript_path, [("user", "we decided to ship on friday")])
+        order = []
+
+        def _spy_run_retain(hook_input, force=False, delta=False):
+            order.append("retain")
+            return {"status": "ok"}
+
+        def _spy_write_buffer(session_id, context, telemetry=None):
+            order.append("buffer")
+
+        def _spy_write_sentinel(session_id):
+            order.append("sentinel")
+            return 1
+
+        client = mock.Mock()
+        client.recall.side_effect = lambda *a, **kw: (order.append("recall") or {"results": [
+            {"text": "we decided to ship on friday", "type": "fact", "mentioned_at": "2026-01-01",
+             "id": "r1", "scores": {"final": 0.9}},
+        ]})
+
+        with patch("prefetch.retain_module.run_retain", side_effect=_spy_run_retain), \
+                patch("prefetch.HindsightClient", return_value=client), \
+                patch("prefetch.get_api_url", return_value="http://fake"), \
+                patch("prefetch.recall_buffer.write_buffer", side_effect=_spy_write_buffer), \
+                patch("prefetch.recall_buffer.write_sentinel", side_effect=_spy_write_sentinel):
+            wrote = prefetch.run_prefetch(self._hook_input(), self._config())
+
+        self.assertTrue(wrote)
+        self.assertEqual(order, ["retain", "recall", "buffer", "sentinel"])
+
+
+class TruncationRegressionTests(PrefetchPipelineBase):
+    def test_fact_retained_two_turns_ago_still_recallable_after_further_retains(self):
+        # This is the STRONGER, red-team-mandated version of test (c): not
+        # "the latest delta contains the newest fact" but "an OLDER fact
+        # retained at turn N-2 survives further retains at N-1 and N" — the
+        # exact shape of bug Fix A closes (a naive tail-slice retain would
+        # have overwritten/truncated the older fact's document).
+        client = self.daemon
+
+        # Drive the REAL retain.run_retain (prefetch.retain_module IS the
+        # `retain` module object, unpatched here) against the daemon fake —
+        # a genuine round trip through the actual delta-retain logic, not a
+        # mocked short-circuit. Only the network-facing leaves (the client
+        # + api url) are faked, on both retain's and prefetch's own module
+        # references (they resolve to the same underlying calls).
+        with patch("retain.HindsightClient", return_value=client), \
+                patch("retain.get_api_url", return_value="http://fake"), \
+                patch("prefetch.HindsightClient", return_value=client), \
+                patch("prefetch.get_api_url", return_value="http://fake"):
+            # Turn N-2
+            _write_transcript(self.transcript_path, [("user", "fact alpha from turn N-2")])
+            prefetch.run_prefetch(self._hook_input("fact alpha from turn N-2"), self._config())
+            # Turn N-1
+            _write_transcript(self.transcript_path, [
+                ("user", "fact alpha from turn N-2"),
+                ("assistant", "ack"),
+                ("user", "fact beta from turn N-1"),
+            ])
+            prefetch.run_prefetch(self._hook_input("fact beta from turn N-1"), self._config())
+            # Turn N
+            _write_transcript(self.transcript_path, [
+                ("user", "fact alpha from turn N-2"),
+                ("assistant", "ack"),
+                ("user", "fact beta from turn N-1"),
+                ("assistant", "ack"),
+                ("user", "fact gamma from turn N"),
+            ])
+            prefetch.run_prefetch(self._hook_input("fact gamma from turn N"), self._config())
+
+        all_retained_content = " ".join(client.documents.values())
+        self.assertIn("fact alpha from turn N-2", all_retained_content,
+                       "an older delta must not be truncated/overwritten by a later delta retain")
+        self.assertIn("fact beta from turn N-1", all_retained_content)
+        self.assertIn("fact gamma from turn N", all_retained_content)
+
+
+class KillSwitchOffTests(PrefetchPipelineBase):
+    def test_flag_off_is_a_hard_no_op(self):
+        _write_transcript(self.transcript_path, [("user", "anything")])
+        # The flag GATE lives in main(), before hook_input is even read —
+        # prove the whole mechanism is a no-op at that entrypoint.
+        import io
+        with patch("prefetch.retain_module.run_retain", side_effect=AssertionError("must not retain when flag is off")), \
+                patch("prefetch.HindsightClient", side_effect=AssertionError("must not touch client when flag is off")), \
+                patch("prefetch.load_config", return_value=self._config(prefetch_enabled=False)), \
+                patch("sys.stdin", io.StringIO(json.dumps(self._hook_input()))):
+            prefetch.main()
+        self.assertFalse(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+        self.assertFalse(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+
+class JunkGateTests(PrefetchPipelineBase):
+    def test_task_notification_turn_is_skipped(self):
+        _write_transcript(self.transcript_path, [("user", "irrelevant")])
+        with patch("prefetch.retain_module.run_retain", side_effect=AssertionError("must not retain a task-notification turn")):
+            wrote = prefetch.run_prefetch(
+                self._hook_input("<task-notification>done</task-notification>"), self._config()
+            )
+        self.assertFalse(wrote)
+        self.assertFalse(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+
+
+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()