switchroom 0.21.16 → 0.21.18

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

@@ -157,6 +157,110 @@ def _topic_filter_mode() -> str:
     return "soft-preamble"
 
 
+# ── Memory v2 M3 (Surface-A) — directive-injection flip guard ───────────────
+#
+# Once an agent has migrated its standing directives into the CLAUDE.md rules
+# block (Memory v2 M1) AND flipped `injectDirectives` OFF, this hook stops
+# injecting the `<active_directives>` block on every turn: the rules block
+# already carries the same guarantees inline, so re-injecting the directives is
+# ~pure token waste (the whole point of M3 — ~49M directive-tokens/30d saved
+# fleet-wide once the heavy agents follow ziggy).
+#
+# `injectDirectives` defaults TRUE (lib/config.py DEFAULTS); an agent is only
+# flipped when switchroom.yaml sets `memory.inject_directives: false`, which
+# plumbs to `HINDSIGHT_INJECT_DIRECTIVES=false` (lib/config.py ENV_OVERRIDES).
+#
+# The flip is DELIBERATELY guarded on physical evidence, not the flag alone:
+# suppression fires IFF the flag is off AND a non-empty rules block is actually
+# present in CLAUDE.md. If the flag is off but no rules block exists (mis-
+# sequenced flip, or M1 not yet run for this agent), we FAIL SAFE — keep
+# injecting directives and surface a one-line degraded-canary notice — rather
+# than strip every guardrail the agent has. A mis-sequenced flip is therefore
+# loud and non-destructive, never silently memory-less. Suppress-only: this
+# NEVER deletes a directive, it only stops re-injecting it. Format-locked to
+# src/memory/rules-block.ts (a golden-fixture test guards against TS drift).
+# See carve-M3.md §2/§4.
+RULES_BLOCK_BEGIN_MARKER = "<!-- switchroom:rules:begin -->"
+RULES_BLOCK_END_MARKER = "<!-- switchroom:rules:end -->"
+
+# A rendered rule line looks like `- **R-01** (source: X, added Y): text`. The
+# literal `(none)` placeholder an empty block renders must NOT count as a rule
+# (that is exactly the empty-block case we fail-safe on). Anchored, no
+# unbounded alternation.
+_RULES_BLOCK_RULE_LINE_RE = re.compile(r"^- \*\*R-", re.MULTILINE)
+
+# config.py DEFAULTS key + settings.json field name for the flip flag.
+INJECT_DIRECTIVES_CONFIG_KEY = "injectDirectives"
+
+_DIRECTIVE_FLIP_DEGRADED_NOTICE = (
+    "⚠️ memory config: injectDirectives is OFF for this agent but no CLAUDE.md "
+    "rules block was found — still injecting <active_directives> this turn to "
+    "avoid a guardrail-less turn. Run the M1 rules-block migration (or "
+    "re-enable injectDirectives) to clear this notice."
+)
+
+
+def _recall_project_dir(hook_input: dict) -> str | None:
+    """Resolve the agent's project directory (where CLAUDE.md lives).
+
+    Prefers `CLAUDE_PROJECT_DIR` (set by Claude Code for hook subprocesses);
+    falls back to the hook payload's `cwd`. Returns None when neither is a
+    usable directory, so callers treat "can't locate the project dir" the same
+    as "no rules block" — fail-safe, keep injecting.
+    """
+    for candidate in (os.environ.get("CLAUDE_PROJECT_DIR"), hook_input.get("cwd")):
+        if candidate and os.path.isdir(candidate):
+            return candidate
+    return None
+
+
+def rules_block_present(project_dir: str | None) -> bool:
+    """True iff CLAUDE.md in `project_dir` carries a NON-EMPTY rules block.
+
+    Non-empty means: the `switchroom:rules:begin/end` markers are both present
+    AND at least one rendered rule line (`- **R-…`) sits between them. The
+    `(none)` placeholder an empty block renders does NOT count. Any IO error →
+    False (fail-safe: absence of proof of a rules block keeps injection on).
+    """
+    if not project_dir:
+        return False
+    path = os.path.join(project_dir, "CLAUDE.md")
+    try:
+        with open(path, encoding="utf-8") as fh:
+            text = fh.read()
+    except OSError:
+        return False
+    begin = text.find(RULES_BLOCK_BEGIN_MARKER)
+    if begin == -1:
+        return False
+    end = text.find(RULES_BLOCK_END_MARKER, begin)
+    if end == -1:
+        return False
+    inner = text[begin + len(RULES_BLOCK_BEGIN_MARKER):end]
+    return _RULES_BLOCK_RULE_LINE_RE.search(inner) is not None
+
+
+def directive_injection_decision(config: dict, hook_input: dict) -> tuple[bool, str | None]:
+    """Decide whether to inject the `<active_directives>` block this turn.
+
+    Returns `(inject, degraded_notice)`:
+      * flag ON (default)                    → (True, None)   inject normally
+      * flag OFF and rules block present     → (False, None)  SUPPRESS (M3 flip)
+      * flag OFF but NO rules block present  → (True, notice) FAIL SAFE: still
+        inject AND surface a one-line degraded-canary notice, so a mis-
+        sequenced flip is loud instead of silently guardrail-less.
+
+    Central to all three recall emit surfaces (main path, prefetch fast path,
+    task-notification directives-only path) so a flipped agent cannot leak
+    directives on a cache hit. Suppress-only — never deletes a directive.
+    """
+    if config.get(INJECT_DIRECTIVES_CONFIG_KEY, True):
+        return True, None
+    if rules_block_present(_recall_project_dir(hook_input)):
+        return False, None
+    return True, _DIRECTIVE_FLIP_DEGRADED_NOTICE
+
+
 def _filter_by_active_topic(results: list, active_thread_id: str | None) -> tuple[list, int]:
     """When hard-filter mode is on AND we know the active thread, drop
     any memory whose stored metadata.thread_id is set to a different
@@ -471,9 +575,17 @@ def _handle_prefetch_buffer(config: dict, hook_input: dict, prompt: str) -> bool
         debug_log(config, f"Prefetch buffer: directive fetch failed: {exc}")
         directives_block = None
 
+    # Memory v2 M3 (Surface-A) — apply the directive-injection flip decision on
+    # the fast path too, so a flipped agent does not leak `<active_directives>`
+    # on a prefetch/cache hit. Suppress iff flag off AND rules block present;
+    # else keep injecting (and carry the degraded-canary notice, if any).
+    _inject_directives, _dir_notice = directive_injection_decision(config, hook_input)
+    if not _inject_directives:
+        directives_block = None
+
     if payload is not None:
         memories_block = payload.get("context") or ""
-        parts = [b for b in (directives_block, memories_block) if b]
+        parts = [b for b in (_dir_notice, directives_block, memories_block) if b]
         if not parts:
             return False
         _emit_cached_context("\n\n".join(parts))
@@ -486,13 +598,13 @@ def _handle_prefetch_buffer(config: dict, hook_input: dict, prompt: str) -> bool
     last = read_state(LAST_RECALL_STATE) or {}
     stale_memories = last.get("memories_context") or ""
     stale_block = stale_recall_notice(stale_memories)
-    parts = [b for b in (directives_block, stale_block) if b]
+    parts = [b for b in (_dir_notice, directives_block, stale_block) if b]
     if parts:
         _emit_cached_context("\n\n".join(parts))
         return True
 
-    if directives_block:
-        _emit_cached_context(directives_block)
+    if directives_block or _dir_notice:
+        _emit_cached_context("\n\n".join([b for b in (_dir_notice, directives_block) if b]))
         return True
 
     # Nothing fresh, nothing stale, nothing cached — say so explicitly
@@ -534,8 +646,15 @@ def _emit_directives_only(config: dict, hook_input: dict) -> None:
         debug_log(config, f"Task-notification skip: directive fetch failed: {exc}")
         return
 
-    if directives_block:
-        _emit_cached_context(directives_block)
+    # Memory v2 M3 (Surface-A) — apply the flip decision here too, so a flipped
+    # agent's directives-only fast path (task-notification junk gate) also
+    # suppresses `<active_directives>` once the rules block carries them.
+    _inject_directives, _dir_notice = directive_injection_decision(config, hook_input)
+    if not _inject_directives:
+        directives_block = None
+
+    if directives_block or _dir_notice:
+        _emit_cached_context("\n\n".join([b for b in (_dir_notice, directives_block) if b]))
 
 
 def _is_demoted_memory(memory) -> bool:
@@ -2829,6 +2948,16 @@ def main():
     bank_errored = any(bt.get("errored") for bt in bank_timings)
 
     directives_block = format_active_directives_block(directives) if directives else None
+
+    # Memory v2 M3 (Surface-A) — directive-injection flip decision. Suppress the
+    # `<active_directives>` block iff this agent is flipped (injectDirectives
+    # OFF) AND a non-empty CLAUDE.md rules block physically carries the same
+    # guarantees; else keep injecting and carry a degraded-canary notice. This
+    # is the primary (synchronous) surface; the two fast paths above mirror it.
+    _inject_directives, directive_flip_notice = directive_injection_decision(config, hook_input)
+    if not _inject_directives:
+        directives_block = None
+
     if directives_block:
         debug_log(config, f"Injecting {len(directives)} active directives")
 
@@ -3267,12 +3396,13 @@ def main():
     # is precisely the turn on which the agent must not assume it remembers.
     # #3837: so is a set the score floor withheld entirely.
     if not directives_block and not memories_block and not transcript_fallback_block:
-        if degraded_block or withheld_block or nudge_block or profile_nudge_block:
+        if degraded_block or withheld_block or nudge_block or profile_nudge_block or directive_flip_notice:
             _emit_cached_context(
                 "\n\n".join(
                     [
                         b
                         for b in (
+                            directive_flip_notice,
                             degraded_block,
                             withheld_block,
                             nudge_block,
@@ -3346,14 +3476,17 @@ def main():
         "hookSpecificOutput": {
             "hookEventName": "UserPromptSubmit",
             "additionalContext": _combine_context(
+                directive_flip_notice,
                 _combine_context(
                     _combine_context(
-                        _combine_context(degraded_block, withheld_block),
-                        context_message,
+                        _combine_context(
+                            _combine_context(degraded_block, withheld_block),
+                            context_message,
+                        ),
+                        nudge_block,
                     ),
-                    nudge_block,
+                    profile_nudge_block,
                 ),
-                profile_nudge_block,
             ),
         }
     }

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

@@ -73,7 +73,16 @@ def build_hooks(plugin_root: str) -> dict:
                         "timeout": 5,
                     }
                 ]
-            }
+            },
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f'python3 "{plugin_root}/scripts/orientation.py"',
+                        "timeout": 8,
+                    }
+                ]
+            },
         ],
         "SessionEnd": [
             {

package/vendor/hindsight-memory/scripts/tests/fixtures/rules-block.golden.md

@@ -0,0 +1,9 @@
+<!-- switchroom:rules:begin -->
+Standing rules — sanctioned via the `memory rule` tool. Do not hand-edit;
+edits made outside the tool break the tamper sentinel below.
+
+- **R-01** (source: reflect-directive, added 2026-08-17T00:00:00.000Z): Always end replies to the user with a one-line summary.
+- **R-02** (source: reflect-directive, added 2026-08-17T00:00:00.000Z): Never send email without explicit user approval.
+
+<!-- switchroom:rules:sentinel sha256=533c23603bb3b72930c8c79b4f4970481b0ce7caf13c3e2bb63953b652b8a0ae rules=2 -->
+<!-- switchroom:rules:end -->

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

@@ -0,0 +1,283 @@
+"""Memory v2 M5 — Surface B: orientation-at-boot (hook wiring).
+
+End-to-end tests for orientation.py's run() — the SessionStart hook entry.
+Every assertion is an OUTCOME (what reached stdout / whether a refresh was
+requested / that boot was never blocked), not a call-path spy, so reverting the
+fix it guards turns the test RED (carve-M5 §8 tautology-guard discipline).
+
+Coverage:
+  T2  DARK by default: memoryOrientationEnabled off is a HARD no-op — no
+      stdout, no bank resolve, no network call (the red-team kill switch).
+  T2  Every failure path (server unreachable, no model, read error, empty
+      payload, degraded/undated model) degrades to a VISIBLE cold notice AND
+      enqueues a refresh AND never raises — boot is never blocked.
+  T3  A stale (1.5x-3x) model is injected WITH a visible prefix; a fresh model
+      is injected plainly; a degraded (>3x) model is NOT injected.
+  T4  Matcher-less re-fire: a "compact" SessionStart produces the SAME output
+      as "startup" (the free post-compaction re-seat — E-88).
+  main() always exits 0 (a non-zero SessionStart hook BLOCKS the turn).
+
+Stdlib-only.
+"""
+
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from datetime import datetime, timedelta, timezone
+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)
+
+import orientation  # noqa: E402
+
+
+def _iso_hours_ago(hours):
+    return (datetime.now(timezone.utc) - timedelta(hours=hours)).isoformat()
+
+
+class _FakeClient:
+    """Stand-in for HindsightClient. Records the OUTCOME the hook depends on:
+    which bank was read, and returns scripted list/get responses (or raises)."""
+
+    def __init__(self, models=None, model_full=None, list_raises=None, get_raises=None):
+        self._models = models if models is not None else {"items": []}
+        self._full = model_full
+        self._list_raises = list_raises
+        self._get_raises = get_raises
+        self.listed_bank = None
+        self.got = None
+
+    def list_mental_models(self, bank_id, timeout=5):
+        self.listed_bank = bank_id
+        if self._list_raises:
+            raise self._list_raises
+        return self._models
+
+    def get_mental_model(self, bank_id, model_id, detail="full", timeout=5):
+        self.got = (bank_id, model_id)
+        if self._get_raises:
+            raise self._get_raises
+        return self._full
+
+
+def _run(config, hook_input=None, client=None, api_raises=None):
+    """Drive orientation.run() with patched I/O; return (stdout_str, client)."""
+    hook_input = hook_input or {"source": "startup"}
+    buf = io.StringIO()
+    with mock.patch.object(orientation, "derive_bank_id", return_value="klanker"), \
+         mock.patch.object(orientation, "HindsightClient", return_value=client):
+        if api_raises is not None:
+            api_ctx = mock.patch.object(orientation, "get_api_url", side_effect=api_raises)
+        else:
+            api_ctx = mock.patch.object(
+                orientation, "get_api_url", return_value="http://127.0.0.1:18888"
+            )
+        with api_ctx, redirect_stdout(buf):
+            orientation.run(hook_input, config)
+    return buf.getvalue(), client
+
+
+def _emitted_context(stdout_str):
+    """Parse the additionalContext out of the hook's stdout envelope, or None."""
+    stdout_str = stdout_str.strip()
+    if not stdout_str:
+        return None
+    payload = json.loads(stdout_str)
+    return payload["hookSpecificOutput"]["additionalContext"]
+
+
+class _RefreshSpyMixin:
+    """Point HINDSIGHT_STATE_DIR at a tmpdir so enqueue_refresh's JSONL marker is
+    inspectable — the OUTCOME 'a refresh was requested' without a live scheduler."""
+
+    def setUp(self):
+        self._tmp = tempfile.mkdtemp()
+        self._env = mock.patch.dict(os.environ, {"HINDSIGHT_STATE_DIR": self._tmp})
+        self._env.start()
+
+    def tearDown(self):
+        self._env.stop()
+        import shutil
+        shutil.rmtree(self._tmp, ignore_errors=True)
+
+    def _refresh_requested(self):
+        marker = os.path.join(self._tmp, "orientation-refresh-pending.jsonl")
+        if not os.path.exists(marker):
+            return False
+        with open(marker) as f:
+            return any(line.strip() for line in f)
+
+
+ENABLED = {"memoryOrientationEnabled": True, "memoryOrientationCadenceHours": 48}
+
+
+class TestDarkByDefault(_RefreshSpyMixin, unittest.TestCase):
+    """T2 — the kill switch. Off (the default) is a hard, silent no-op."""
+
+    def test_disabled_emits_nothing_and_never_touches_client(self):
+        client = _FakeClient()
+        # A client whose methods would blow up if called — proves no I/O happens.
+        client.list_mental_models = mock.Mock(side_effect=AssertionError("must not read"))
+        stdout, _ = _run({"memoryOrientationEnabled": False}, client=client)
+        self.assertEqual(stdout.strip(), "")
+        self.assertFalse(self._refresh_requested())
+
+    def test_absent_flag_defaults_to_off(self):
+        # A stripped/absent value must fail to OFF (fail-safe).
+        client = _FakeClient()
+        client.list_mental_models = mock.Mock(side_effect=AssertionError("must not read"))
+        stdout, _ = _run({}, client=client)
+        self.assertEqual(stdout.strip(), "")
+
+
+class TestColdPaths(_RefreshSpyMixin, unittest.TestCase):
+    """T2 — every failure degrades to a visible cold notice + refresh, never a block."""
+
+    def _assert_cold(self, stdout):
+        ctx = _emitted_context(stdout)
+        self.assertIsNotNone(ctx)
+        self.assertIn("not yet built or refreshed", ctx)
+        self.assertTrue(self._refresh_requested())
+
+    def test_server_unreachable(self):
+        stdout, _ = _run(ENABLED, client=None, api_raises=RuntimeError("no daemon"))
+        self._assert_cold(stdout)
+
+    def test_no_model_named_orientation(self):
+        client = _FakeClient(models={"items": [{"id": "x", "name": "something-else"}]})
+        stdout, _ = _run(ENABLED, client=client)
+        self._assert_cold(stdout)
+
+    def test_list_models_raises(self):
+        client = _FakeClient(list_raises=TimeoutError("read timed out"))
+        stdout, _ = _run(ENABLED, client=client)
+        self._assert_cold(stdout)
+
+    def test_model_read_raises(self):
+        client = _FakeClient(
+            models={"items": [{"id": "m1", "name": "orientation"}]},
+            get_raises=TimeoutError("read timed out"),
+        )
+        stdout, _ = _run(ENABLED, client=client)
+        self._assert_cold(stdout)
+
+    def test_empty_content(self):
+        client = _FakeClient(
+            models={"items": [{"id": "m1", "name": "orientation"}]},
+            model_full={"content": "   ", "last_refreshed_at": _iso_hours_ago(1)},
+        )
+        stdout, _ = _run(ENABLED, client=client)
+        self._assert_cold(stdout)
+
+    def test_degraded_model_not_injected(self):
+        # Refreshed 200h ago at cadence 48 -> >3x -> degraded -> cold, never
+        # presented stale-as-fresh.
+        client = _FakeClient(
+            models={"items": [{"id": "m1", "name": "orientation"}]},
+            model_full={"content": "# Real\nbody", "last_refreshed_at": _iso_hours_ago(200)},
+        )
+        stdout, _ = _run(ENABLED, client=client)
+        self._assert_cold(stdout)
+
+    def test_undated_model_not_injected(self):
+        client = _FakeClient(
+            models={"items": [{"id": "m1", "name": "orientation"}]},
+            model_full={"content": "# Real\nbody", "last_refreshed_at": None},
+        )
+        stdout, _ = _run(ENABLED, client=client)
+        self._assert_cold(stdout)
+
+
+class TestInjectPaths(_RefreshSpyMixin, unittest.TestCase):
+    """T3 — usable models are injected; fresh plainly, stale with a prefix."""
+
+    def test_fresh_model_injected_plainly(self):
+        client = _FakeClient(
+            models={"items": [{"id": "m1", "name": "orientation"}]},
+            model_full={"content": "# Brief\nthe orientation body",
+                        "last_refreshed_at": _iso_hours_ago(2)},
+        )
+        stdout, _ = _run(ENABLED, client=client)
+        ctx = _emitted_context(stdout)
+        self.assertIn("the orientation body", ctx)
+        self.assertNotIn("may be stale", ctx)
+        # A usable inject does NOT request a refresh.
+        self.assertFalse(self._refresh_requested())
+        # It read the agent's OWN bank.
+        self.assertEqual(client.listed_bank, "klanker")
+
+    def test_stale_model_injected_with_prefix(self):
+        # 100h ago at cadence 48 -> 1.5x(72) < 100 < 3x(144) -> stale.
+        client = _FakeClient(
+            models={"items": [{"id": "m1", "name": "orientation"}]},
+            model_full={"content": "# Brief\nthe orientation body",
+                        "last_refreshed_at": _iso_hours_ago(100)},
+        )
+        stdout, _ = _run(ENABLED, client=client)
+        ctx = _emitted_context(stdout)
+        self.assertIn("the orientation body", ctx)
+        self.assertIn("may be stale", ctx)
+
+
+class TestCompactionReSeat(_RefreshSpyMixin, unittest.TestCase):
+    """T4 — matcher-less: a compaction SessionStart re-seats identically to startup."""
+
+    def _model(self):
+        return {"items": [{"id": "m1", "name": "orientation"}]}, {
+            "content": "# Brief\nbody text", "last_refreshed_at": _iso_hours_ago(2)
+        }
+
+    def test_compact_source_matches_startup_source(self):
+        models, full = self._model()
+        out_start, _ = _run(ENABLED, hook_input={"source": "startup"},
+                            client=_FakeClient(models=models, model_full=full))
+        out_compact, _ = _run(ENABLED, hook_input={"source": "compact"},
+                             client=_FakeClient(models=models, model_full=full))
+        self.assertEqual(_emitted_context(out_start), _emitted_context(out_compact))
+        self.assertIn("body text", _emitted_context(out_compact))
+
+
+class TestNeverBlocksBoot(unittest.TestCase):
+    """The script must exit 0 on every path — a non-zero SessionStart hook BLOCKS
+    the turn in Claude Code. Driven as a real subprocess (the actual __main__
+    guard), because that guard is exactly what turns an internal raise into a
+    clean exit; an in-process patch of sys.exit could never catch a regression
+    where the guard itself is removed."""
+
+    def _run_script(self, env_extra, stdin_text="{}"):
+        import subprocess
+        env = dict(os.environ)
+        env.update(env_extra)
+        script = os.path.join(SCRIPTS_DIR, "orientation.py")
+        proc = subprocess.run(
+            [sys.executable, script],
+            input=stdin_text, capture_output=True, text=True, env=env, timeout=20,
+        )
+        return proc
+
+    def test_disabled_exits_zero_silent(self):
+        proc = self._run_script({"HINDSIGHT_ORIENTATION_ENABLED": "false"})
+        self.assertEqual(proc.returncode, 0)
+        self.assertEqual(proc.stdout.strip(), "")
+
+    def test_enabled_but_server_unreachable_exits_zero_with_cold_notice(self):
+        # Point at a closed port: the read fails, but boot must NOT block — exit
+        # 0 and a visible cold notice on stdout, never a hang or non-zero.
+        with tempfile.TemporaryDirectory() as tmp:
+            proc = self._run_script({
+                "HINDSIGHT_ORIENTATION_ENABLED": "true",
+                "HINDSIGHT_API_URL": "http://127.0.0.1:9",  # discard port, refused
+                "HINDSIGHT_STATE_DIR": tmp,
+            })
+            self.assertEqual(proc.returncode, 0, proc.stderr)
+            self.assertIn("not yet built or refreshed", proc.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()