switchroom 0.21.15 → 0.21.17

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

@@ -0,0 +1,329 @@
+"""M4 prefetch-buffer MUTATION INVALIDATION — red-team-M3 R2 (BLOCKER).
+
+The M4 prefetch buffer holds a RECALLED memories block captured at a prior
+turn's Stop hook and consumed at the next UserPromptSubmit. If a mutation —
+a rule/directive retire, or a retain that supersedes a fact — lands between
+producing that buffer and consuming it, the pre-mutation snapshot can
+resurrect the just-retired/just-changed content on a later turn. Worse,
+``prefetch.run_prefetch`` returns early WITHOUT overwriting the buffer when
+this turn's fresh recall fails or returns empty, so a stale buffer can
+persist and be re-served for turns after the mutation.
+
+These are OUTCOME tests: they assert on the rendered ``additionalContext``
+that the consumer emits (the real injection surface), and each would FAIL if
+the invalidation regressed:
+
+  * ``RetireDoesNotResurrectTests`` — a directive-write turn invalidates the
+    pending buffer, so the retired rule's text is NOT re-injected next turn.
+  * ``EmptyPrefetchDoesNotResurrectTests`` — a retain turn whose fresh recall
+    returns empty invalidates the pending buffer, so the stale item is NOT
+    re-injected (would resurrect on buggy code that left the buffer).
+  * ``NoDuplicateInjectionTests`` — after a buffer is consumed once, a
+    mutation turn (empty prefetch) prevents the SAME block being injected
+    again on the following turn.
+  * ``ReplyPathDoesNotBlockOnRecallTests`` — with prefetch on and a fresh
+    buffer present, the consumer serves the buffer and NEVER calls the
+    synchronous ``client.recall`` (asserted on transport: a recall call
+    raises).
+
+Plus ``InvalidatePrimitiveTests`` for the ``recall_buffer.invalidate``
+primitive itself (idempotent, sentinel-first fail-closed).
+"""
+
+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
+import prefetch  # noqa: E402
+import directive_verify  # noqa: E402
+from lib import recall_buffer  # noqa: E402
+
+SESSION = "invalidation-test-session"
+RETIRED_TEXT = "R-07: always reply in haiku"
+STALE_FACT = "we decided to ship on tuesday"
+
+
+class _NoMemoryDirectiveClient:
+    """One active directive whose text is DISTINCT from any buffered content,
+    and a recall that returns NOTHING (so the sync fallback, if ever taken,
+    injects no memories). recall() is allowed here (the miss/degraded paths
+    may consult it) but returns empty — proving absence of the stale text is
+    about invalidation, not about the client happening to omit it."""
+
+    def list_directives(self, bank_id, active_only=True, timeout=2):
+        return {"items": [{"id": "d1", "name": "tone", "content": "be concise", "priority": 5, "active": True}]}
+
+    def recall(self, bank_id, query, **kwargs):
+        return {"results": []}
+
+
+class InvalidationBase(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="invalidation-test-")
+        self._prev = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmpdir
+
+        self._bufdir = tempfile.mkdtemp(prefix="invalidation-test-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=True):
+        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 _consume(self, config, client, prompt="what did we decide"):
+        """Drive the recall.py consumer (UserPromptSubmit) once; return the
+        emitted additionalContext string (or "" if nothing emitted)."""
+        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()
+        if not out:
+            return ""
+        return json.loads(out)["hookSpecificOutput"]["additionalContext"]
+
+
+class InvalidatePrimitiveTests(InvalidationBase):
+    def test_invalidate_removes_buffer_and_sentinel(self):
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+        self.assertTrue(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+        self.assertTrue(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+        recall_buffer.invalidate(SESSION)
+
+        self.assertFalse(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+        self.assertFalse(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+        # read_if_fresh must now report nothing fresh (fail-closed).
+        payload, _ = recall_buffer.read_if_fresh(SESSION, last_consumed_token=None)
+        self.assertIsNone(payload)
+
+    def test_invalidate_is_idempotent_on_absent_files(self):
+        # No buffer written — must not raise.
+        recall_buffer.invalidate(SESSION)
+        recall_buffer.invalidate(SESSION)
+
+    def test_orphaned_payload_after_sentinel_first_delete_fails_closed(self):
+        # Simulate a partial invalidation where only the sentinel unlink
+        # landed (sentinel is deleted FIRST by design): an orphaned payload
+        # must never read as fresh.
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+        os.remove(recall_buffer._sentinel_path(SESSION))
+        payload, _ = recall_buffer.read_if_fresh(SESSION, last_consumed_token=None)
+        self.assertIsNone(payload)
+
+
+class RetireDoesNotResurrectTests(InvalidationBase):
+    """Assertion (1): a directive retire invalidates the pending buffer so the
+    retired item is NOT re-injected on the next turn."""
+
+    def _retire_turn_messages(self):
+        # A real turn transcript: the user retires a rule, the assistant issues
+        # a delete_directive tool_use. This is what directive_verify inspects.
+        return [
+            {"role": "user", "content": "Retire the haiku rule R-07, it no longer applies."},
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "tool_use", "id": "t1", "name": "delete_directive", "input": {"id": "d-r07"}}
+                ],
+            },
+        ]
+
+    def test_directive_write_turn_invalidates_buffer_and_blocks_resurrection(self):
+        config = self._config(prefetch_enabled=True)
+
+        # Turn N Stop: prefetch buffered the rule text while it was still active.
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+
+        # Turn N+1: the retire lands. directive_verify's Stop-hook invalidation
+        # detects the delete_directive write and drops the pending buffer.
+        directive_verify.invalidate_prefetch_buffer_on_directive_write(
+            self._retire_turn_messages(), config, SESSION
+        )
+        self.assertFalse(
+            os.path.isfile(recall_buffer._sentinel_path(SESSION)),
+            "directive-write turn must invalidate the pending prefetch buffer",
+        )
+
+        # Turn N+2 UserPromptSubmit: the consumer must NOT re-inject the retired
+        # rule text. (With no fresh buffer it takes the sync/degraded path, which
+        # here surfaces only the fresh directive block, not the retired text.)
+        ctx = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertNotIn(
+            "R-07", ctx,
+            "retired rule text must not resurrect from a pre-retire prefetch buffer",
+        )
+        self.assertNotIn("haiku", ctx)
+
+    def test_non_directive_turn_leaves_buffer_intact(self):
+        # Guard against over-invalidation: an ordinary turn (no directive write)
+        # must NOT drop the buffer, or every turn would lose the prefetch.
+        config = self._config(prefetch_enabled=True)
+        recall_buffer.write_buffer(SESSION, "- a normal prefetched memory", {})
+        recall_buffer.write_sentinel(SESSION)
+        directive_verify.invalidate_prefetch_buffer_on_directive_write(
+            [
+                {"role": "user", "content": "what's the weather"},
+                {"role": "assistant", "content": "Sunny."},
+            ],
+            config,
+            SESSION,
+        )
+        self.assertTrue(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+    def test_flag_off_is_a_noop(self):
+        # Kill switch: with prefetch off, the directive-write invalidation must
+        # not touch the buffer module at all.
+        config = self._config(prefetch_enabled=False)
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+        with patch("directive_verify.recall_buffer.invalidate",
+                   side_effect=AssertionError("must not invalidate when prefetch is off")):
+            directive_verify.invalidate_prefetch_buffer_on_directive_write(
+                self._retire_turn_messages(), config, SESSION
+            )
+        self.assertTrue(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+
+class EmptyPrefetchDoesNotResurrectTests(InvalidationBase):
+    """Assertion (1) via the RETAIN mutation path: a retain turn whose fresh
+    recall returns empty must invalidate the pending buffer so the stale item
+    is NOT re-served. This FAILS on buggy code that returns early leaving the
+    old buffer in place."""
+
+    def test_retain_turn_with_empty_recall_invalidates_stale_buffer(self):
+        config = self._config(prefetch_enabled=True)
+
+        # Turn N Stop: a stale fact was buffered.
+        recall_buffer.write_buffer(SESSION, STALE_FACT, {})
+        recall_buffer.write_sentinel(SESSION)
+
+        # Turn N+1 Stop: prefetch runs (a retain mutation), but this turn's
+        # fresh recall returns NOTHING. run_prefetch must have already
+        # invalidated the old buffer up front — so no stale buffer survives.
+        empty_client = mock.Mock()
+        empty_client.recall.return_value = {"results": []}
+        hook_input = {
+            "prompt": "and another thing",
+            "session_id": SESSION,
+            "transcript_path": "",  # _last_human_prompt degrades to "" -> we inject a query below
+            "cwd": "/tmp",
+        }
+        with patch("prefetch.retain_module.run_retain", return_value={"status": "ok"}), \
+                patch("prefetch.HindsightClient", return_value=empty_client), \
+                patch("prefetch.get_api_url", return_value="http://fake"), \
+                patch("prefetch._last_human_prompt", return_value="and another thing"):
+            wrote = prefetch.run_prefetch(hook_input, config)
+
+        self.assertFalse(wrote, "empty recall must not write a fresh buffer")
+        self.assertFalse(
+            os.path.isfile(recall_buffer._sentinel_path(SESSION)),
+            "a mutation (retain) turn must invalidate the stale buffer even when the fresh recall is empty",
+        )
+
+        # Turn N+2 UserPromptSubmit: the stale fact must NOT re-inject.
+        ctx = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertNotIn(
+            STALE_FACT, ctx,
+            "stale buffered fact must not resurrect after a mutation turn with an empty recall",
+        )
+
+
+class NoDuplicateInjectionTests(InvalidationBase):
+    """Assertion (2): the same buffered block is not injected twice. After a
+    turn consumes a buffer, a mutation turn (empty prefetch) prevents the SAME
+    block from being re-served on the following turn."""
+
+    def test_consumed_buffer_not_reinjected_after_mutation_turn(self):
+        config = self._config(prefetch_enabled=True)
+        marker = "- unique-fact-abc123 decided at standup"
+
+        recall_buffer.write_buffer(SESSION, marker, {})
+        recall_buffer.write_sentinel(SESSION)
+
+        # Turn N+1: consumer injects the buffered block once.
+        first = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertIn("unique-fact-abc123", first)
+
+        # Turn N+1 Stop: a mutation turn whose recall returns empty -> the old
+        # buffer is invalidated, nothing fresh written.
+        empty_client = mock.Mock()
+        empty_client.recall.return_value = {"results": []}
+        hook_input = {"prompt": "next", "session_id": SESSION, "transcript_path": "", "cwd": "/tmp"}
+        with patch("prefetch.retain_module.run_retain", return_value={"status": "ok"}), \
+                patch("prefetch.HindsightClient", return_value=empty_client), \
+                patch("prefetch.get_api_url", return_value="http://fake"), \
+                patch("prefetch._last_human_prompt", return_value="next"):
+            prefetch.run_prefetch(hook_input, config)
+
+        # Turn N+2: the same block must NOT be injected a second time.
+        second = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertNotIn(
+            "unique-fact-abc123", second,
+            "a consumed buffer must not be re-injected after a mutation invalidated it",
+        )
+
+
+class ReplyPathDoesNotBlockOnRecallTests(InvalidationBase):
+    """Assertion (3): with prefetch on and a fresh buffer present, the reply
+    path (UserPromptSubmit consumer) joins the buffer and NEVER blocks on a
+    synchronous recall. Asserted on transport: client.recall raises if called."""
+
+    def test_fresh_buffer_served_without_calling_recall(self):
+        config = self._config(prefetch_enabled=True)
+        recall_buffer.write_buffer(SESSION, "- a prefetched memory xyz", {})
+        recall_buffer.write_sentinel(SESSION)
+
+        class _ExplodingRecallClient:
+            def list_directives(self, bank_id, active_only=True, timeout=2):
+                return {"items": []}
+
+            def recall(self, bank_id, query, **kwargs):
+                raise AssertionError("reply path must not block on synchronous recall when a fresh buffer exists")
+
+        ctx = self._consume(config, _ExplodingRecallClient())
+        self.assertIn("a prefetched memory xyz", ctx)
+
+
+if __name__ == "__main__":
+    unittest.main()

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()