switchroom 0.21.16 → 0.21.17

package/vendor/hindsight-memory/scripts/lib/recall_buffer.py

@@ -210,6 +210,35 @@ def read_if_fresh(session_id: str, last_consumed_token: Optional[int]) -> tuple:
     return {"context": payload.get("context", ""), "telemetry": payload.get("telemetry", {})}, token
 
 
+def invalidate(session_id: str) -> None:
+    """Drop any pending prefetch buffer + sentinel for ``session_id``.
+
+    Called at MUTATION sites — a rule/directive retire (``directive_verify``)
+    or a retain (``prefetch.run_prefetch`` before it re-recalls) — so a buffer
+    captured BEFORE the mutation can never be consumed AFTER it. This closes
+    the resurrection class the M3 red-team (R2, BLOCKER) flagged at the
+    M3/M4 intersection: a rule retired mid-session must not re-inject from a
+    buffer prefetched while the rule was still active. It is the read-after-
+    write ordering the producer already builds for the happy path, extended
+    to the mutation path — NOT a reliance on the buffer's TTL (timing, not
+    correctness).
+
+    The SENTINEL is removed FIRST so a partial invalidation still fails
+    closed: ``read_if_fresh`` checks the sentinel before the payload, so once
+    the sentinel is gone the reader returns ``None`` regardless of whether the
+    payload unlink also succeeded — an orphaned payload is never served as
+    fresh. Best-effort and idempotent: a missing file is a no-op, and the
+    function NEVER raises (a failed unlink must not break the turn).
+    """
+    for path in (_sentinel_path(session_id), _buffer_path(session_id)):
+        try:
+            os.remove(path)
+        except FileNotFoundError:
+            pass
+        except OSError:
+            pass
+
+
 def poll_for_sentinel(session_id: str, last_consumed_token: Optional[int], cap_ms: int) -> bool:
     """Clock-bounded poll for a fresh sentinel. Never busy-spins.
 

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

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""SessionStart hook: Memory v2 M5 — orientation-at-boot (Surface B).
+
+carve-M5.md §3. Injects the agent's cron-refreshed ``orientation`` mental
+model into context at SessionStart AND re-seats it after every compaction —
+"reflect once, serve from cache" (E-79), deterministically, zero tool call.
+
+DARK BY DEFAULT (red-team kill switch). Entirely gated by
+``memoryOrientationEnabled`` (default False — carve §4, same discipline as
+M4's ``memoryPrefetchEnabled``). When off this hook is a hard no-op: it reads
+config, sees the flag off, and exits BEFORE any bank resolve or network call.
+The flag is per-agent — a stripped/absent value fails to OFF (fail-safe), so
+an un-flipped agent boots exactly as pre-M5.
+
+MATCHER-LESS (load-bearing, carve §1/§3). Registered with NO matcher, so it
+fires on every SessionStart source — startup, resume, clear, fork AND compact.
+The compact firing is the free deterministic post-compaction re-seat that
+answers E-88 ("nothing re-seats orientation today"): the hook re-reads the
+model from the engine each time, so a mid-session refresh is picked up at the
+next compaction with no session restart. Do NOT add a matcher.
+
+FAIL-SAFE INVARIANTS (all asserted in tests/test_orientation_hook.py):
+  - Boot is NEVER blocked on the orientation read. Every failure path
+    (server down, no model, read error, read timeout, degraded/undated
+    model) degrades to a VISIBLE one-line cold notice + a refresh request,
+    and exits 0. Never a silently memoryless boot, never a stale briefing
+    presented as fresh.
+  - A stale (1.5×–3× cadence) model is injected WITH a visible prefix; a
+    degraded (>3×) or undated model is NOT injected — the cold notice is
+    emitted instead. Thresholds are per-tier (carve §5), not a fixed 36h.
+
+STDOUT CONTRACT. A SessionStart hook's stdout IS added to the model's context
+(unlike PreCompact); we emit ``{"hookSpecificOutput":{"hookEventName":
+"SessionStart","additionalContext": "…"}}``. Exit code is 0 ALWAYS — a
+non-zero exit BLOCKS the turn in Claude Code, and orientation must degrade to
+a notice, never a hard stop (same doctrine as rules-sentinel-hook.sh).
+"""
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from lib import orientation as orient
+from lib.bank import derive_bank_id
+from lib.client import HindsightClient
+from lib.config import debug_log, load_config
+from lib.daemon import get_api_url
+
+#: Generous read-timeout for the model GET (carve §3). overlord's own-bank read
+#: is ~270ms and klanker's ~4ms (m0/m5-0 probes), but the latency asymmetry is
+#: unexplained and possibly bank-size-correlated, so leave headroom — and on a
+#: timeout degrade to the cold notice, never a hung boot.
+ORIENTATION_READ_TIMEOUT_S = 3
+
+
+def _emit(additional_context: str) -> None:
+    """Print the SessionStart additionalContext envelope to stdout."""
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "SessionStart",
+                    "additionalContext": additional_context,
+                }
+            }
+        )
+    )
+
+
+def enqueue_refresh(config: dict, bank_id: str, model_name: str) -> None:
+    """Signal that ``bank_id``'s orientation model needs a background refresh.
+
+    The cold/degraded path requests a refresh so a boot that found no usable
+    briefing does not stay briefing-less indefinitely (carve §3-4). This is the
+    SEAM the M5-C out-of-session tiered scheduler consumes; the scheduler is
+    cadence-driven regardless, so this is a best-effort nudge, never a blocking
+    dependency. Kept as a thin, override-able function so the cold-path tests
+    can assert the OUTCOME ("a refresh was requested") without a live scheduler.
+
+    Best-effort and total: any failure is swallowed — a boot must never fail
+    because a refresh request could not be recorded.
+    """
+    debug_log(
+        config,
+        f"orientation cold/degraded on bank '{bank_id}' model "
+        f"'{model_name}' — refresh requested",
+    )
+    try:
+        state_dir = os.environ.get("HINDSIGHT_STATE_DIR") or os.path.join(
+            os.path.expanduser("~"), ".hindsight"
+        )
+        os.makedirs(state_dir, exist_ok=True)
+        marker = os.path.join(state_dir, "orientation-refresh-pending.jsonl")
+        with open(marker, "a") as f:
+            f.write(json.dumps({"bank_id": bank_id, "model": model_name}) + "\n")
+    except Exception as e:  # noqa: BLE001 — best-effort, never breaks boot
+        debug_log(config, f"orientation refresh-request write failed (ignored): {e}")
+
+
+def _match_model(models: dict, name: str) -> dict | None:
+    """Find the mental model whose ``name`` matches the configured orientation name."""
+    items = models.get("items") if isinstance(models, dict) else None
+    if not isinstance(items, list):
+        return None
+    for item in items:
+        if isinstance(item, dict) and item.get("name") == name:
+            return item
+    return None
+
+
+def run(hook_input: dict, config: dict) -> None:
+    """Core hook logic. Emits at most one additionalContext block; never raises."""
+    if not config.get("memoryOrientationEnabled", False):
+        debug_log(config, "memoryOrientationEnabled off — orientation no-op")
+        return
+
+    model_name = config.get("memoryOrientationModel", "orientation")
+    cadence_hours = int(config.get("memoryOrientationCadenceHours", 48) or 48)
+    bank_id = derive_bank_id(hook_input, config)
+
+    def _dbg(*a):
+        debug_log(config, *a)
+
+    # Resolve the engine REST URL WITHOUT starting the daemon (too slow for
+    # SessionStart). If the server is unreachable, degrade to the cold notice —
+    # we cannot read the model, and boot must not block.
+    try:
+        api_url = get_api_url(config, debug_fn=_dbg, allow_daemon_start=False)
+        client = HindsightClient(api_url, config.get("hindsightApiToken"))
+    except (RuntimeError, ValueError) as e:
+        debug_log(config, f"orientation: Hindsight unreachable ({e}) — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    # Resolve the orientation model by NAME → id, then read its content +
+    # freshness watermark. Any read error/timeout is a cold notice, not a hang.
+    try:
+        models = client.list_mental_models(bank_id, timeout=ORIENTATION_READ_TIMEOUT_S)
+        match = _match_model(models, model_name)
+    except Exception as e:  # noqa: BLE001 — degrade to cold, never block boot
+        debug_log(config, f"orientation: list models failed ({e}) — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    if not match or not match.get("id"):
+        debug_log(config, f"orientation: no model named '{model_name}' — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    try:
+        full = client.get_mental_model(
+            bank_id, match["id"], detail="full", timeout=ORIENTATION_READ_TIMEOUT_S
+        )
+    except Exception as e:  # noqa: BLE001 — includes urllib timeout
+        debug_log(config, f"orientation: model read failed ({e}) — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    content = (full or {}).get("content") or ""
+    last_refreshed_at = (full or {}).get("last_refreshed_at")
+    state, hours_ago = orient.classify_staleness(last_refreshed_at, cadence_hours)
+
+    if not content.strip() or state in ("degraded", "unknown"):
+        # Empty payload, or refreshed > 3× cadence ago / undated: never present
+        # stale-as-fresh. Cold notice + refresh request (carve §5).
+        debug_log(config, f"orientation: state={state}, empty={not content.strip()} — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    debug_log(config, f"orientation: injecting (state={state}, {hours_ago}h ago)")
+    _emit(orient.render_orientation(content, state, hours_ago))
+
+
+def main():
+    config = load_config()
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        hook_input = {}
+    run(hook_input, config)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:  # noqa: BLE001 — a hook that exits non-zero blocks the turn
+        print(f"[Hindsight] Orientation SessionStart error: {e}", file=sys.stderr)
+    sys.exit(0)

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

@@ -80,6 +80,16 @@ def run_prefetch(hook_input: dict, config: dict) -> bool:
         debug_log(config, "Prefetch: task-notification turn, skipping")
         return False
 
+    # Step 0 — MUTATION INVALIDATION (red-team-M3 R2, BLOCKER). This turn is
+    # about to retain (step 1) — a memory mutation. Drop any buffer left from a
+    # prior turn BEFORE recalling, so that if this turn's fresh recall fails or
+    # returns empty (steps 2-3 below bail without overwriting), the consumer
+    # cannot resurrect the pre-mutation snapshot: with no sentinel it falls to
+    # the explicitly stale-marked LAST_RECALL_STATE / degraded notice instead of
+    # serving a stale buffer as fresh. A successful recall repopulates the buffer
+    # with the post-mutation snapshot at step 3. Never raises.
+    recall_buffer.invalidate(session_id)
+
     # Step 1 — delta retain (Fix A: content-derived document_id, never the
     # bare {session_id} document; never truncates).
     try:

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