switchroom 0.21.15 → 0.21.17

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

@@ -519,3 +519,38 @@ class HindsightClient:
         if retain_mission:
             updates["retain_mission"] = retain_mission
         return self._request("PATCH", path, {"updates": updates}, timeout=timeout)
+
+    def list_mental_models(self, bank_id: str, timeout: int = 5) -> dict:
+        """List the mental models for a bank (Memory v2 M5 — orientation-at-boot).
+
+        The orientation SessionStart hook knows the orientation model by NAME
+        (the configured `memoryOrientationModel`), not by its `mm-…` id, so it
+        lists the bank's models and matches on name → id before reading content
+        (carve-M5 §0d/§3). Read-only GET on the ungated engine REST surface;
+        m5-0-probe measured the own-bank read at ~4ms on klanker.
+
+        REST: ``GET /v1/default/banks/{bank_id}/mental-models``. Returns the raw
+        response dict, expected to carry an ``items`` list where each item has at
+        least ``id`` and ``name``.
+        """
+        path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/mental-models"
+        return self._request("GET", path, timeout=timeout)
+
+    def get_mental_model(
+        self, bank_id: str, model_id: str, detail: str = "full", timeout: int = 5
+    ) -> dict:
+        """Read one mental model's content + freshness watermark (M5).
+
+        REST: ``GET /v1/default/banks/{bank_id}/mental-models/{model_id}?detail=full``
+        (m5-0-probe Q3/Q4 proved this returns ``content`` + the
+        ``last_refreshed_at`` watermark the staleness guard keys on, ~4ms warm).
+        Read-only; ungated. The caller wraps this in a generous read-timeout and
+        degrades to the cold notice on any error — a slow/failed read must never
+        block boot (carve §3 fail-safe).
+        """
+        bank = urllib.parse.quote(bank_id, safe="")
+        model = urllib.parse.quote(model_id, safe="")
+        path = f"/v1/default/banks/{bank}/mental-models/{model}"
+        if detail:
+            path = f"{path}?{urllib.parse.urlencode({'detail': detail})}"
+        return self._request("GET", path, timeout=timeout)

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

@@ -130,6 +130,20 @@ DEFAULTS = {
     # opt out per-agent via memory.profile_capture_nudge=false →
     # HINDSIGHT_PROFILE_CAPTURE_NUDGE.
     "profileCaptureNudge": True,
+    # Switchroom Memory v2 M3 Surface-A — directive-injection switch. When True
+    # (default), recall.py injects the `<active_directives>` block on every
+    # UserPromptSubmit at all three emit sites (main + prefetch/cache fast
+    # paths). When False (a flipped M3 canary), that injection is SUPPRESSED —
+    # the agent's standing rules come from the live rules block instead, which
+    # is the change that collapses the always-on directive-token spend (E-41).
+    # Suppression is fail-safe and re-checked every turn: it fires ONLY when a
+    # non-empty rules block is physically present in CLAUDE.md; a False flag
+    # with an empty/absent block keeps injecting AND emits a degraded-canary
+    # notice, so a zero-standing-rules turn is unreachable. Operators flip a
+    # canary per-agent via memory.inject_directives=false →
+    # HINDSIGHT_INJECT_DIRECTIVES; the ordered flip (rules_block live → migrate
+    # → this flag off) is enforced by `switchroom memory flip`.
+    "injectDirectives": True,
     # Switchroom #2873/#2903 Fix 6.2 — the BLOCKING half (Stage C
     # directive_verify.py Stop hook) split out from the advisory nudge. When
     # True (default) the verifier may block the stop once to re-prompt capture;
@@ -140,6 +154,23 @@ DEFAULTS = {
     # per-agent via memory.directive_capture_verify=false →
     # HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY.
     "directiveCaptureVerify": True,
+    # Memory v2 M5 — orientation-at-boot (Surface B). All four fail-safe by
+    # default so a stripped/absent key (the Zod-strip footgun, carve §1) boots
+    # exactly as pre-M5. `memoryOrientationEnabled` is the per-agent kill switch,
+    # default OFF (dark build — the orientation SessionStart hook no-ops before
+    # any bank resolve or network call when off). `memoryOrientationModel` is the
+    # mental-model NAME the hook resolves to an id (the agent's OWN bank).
+    # `memoryOrientationCadenceHours` is the per-agent refresh cadence tier
+    # (klanker/overlord 24, everyone else 48) the staleness guard's per-tier
+    # thresholds (1.5×/3×) key on. `memoryOrientationReinjectTurns` is the
+    # epic's optional per-turn re-inject knob, default 0 = SessionStart+compaction
+    # only (the cheap path; N>0 is the ~55M/30d-at-every-turn expensive variant,
+    # which is why it defaults off). Delivered per-agent via the scaffold
+    # settings.json stamp and overridable via the HINDSIGHT_ORIENTATION_* env.
+    "memoryOrientationEnabled": False,
+    "memoryOrientationModel": "orientation",
+    "memoryOrientationCadenceHours": 48,
+    "memoryOrientationReinjectTurns": 0,
     # Switchroom hindsight-leverage A4 — TTL (seconds) for the directives-list
     # cache on the recall critical path (see lib/directives.py). The list is
     # re-fetched at most once per TTL window for no-write turns; in-session
@@ -510,11 +541,27 @@ ENV_OVERRIDES = {
     # it; the switchroom default is on (settings.json pins true; recall.py falls
     # back to True).
     "HINDSIGHT_PROFILE_CAPTURE_NUDGE": ("profileCaptureNudge", bool),
+    # Switchroom Memory v2 M3 Surface-A: directive-injection switch on/off. Set
+    # by start.sh from agents.<name>.memory.inject_directives only when the
+    # operator overrode it; the switchroom default is on (settings.json pins
+    # true; recall.py falls back to True). False SUPPRESSES the
+    # <active_directives> injection for a flipped canary, fail-safe on a live
+    # rules block (see recall.py directive_injection_decision).
+    "HINDSIGHT_INJECT_DIRECTIVES": ("injectDirectives", bool),
     # Switchroom #2873/#2903 Fix 6.2: the Stage C block on/off, independent of
     # the Stage B nudge. Set by start.sh from
     # agents.<name>.memory.directive_capture_verify only when the operator
     # overrode it; the switchroom default is on.
     "HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY": ("directiveCaptureVerify", bool),
+    # Memory v2 M5 — orientation-at-boot. Env override channel for the four
+    # orientation knobs (settings.json carries the per-agent value; env wins for
+    # a docker-exec'd hook or an agent `env:` map). `memoryOrientationEnabled`
+    # is the per-agent kill switch (default off); the model NAME, cadence tier,
+    # and reinject count follow. See DEFAULTS above and carve-M5 §4.
+    "HINDSIGHT_ORIENTATION_ENABLED": ("memoryOrientationEnabled", bool),
+    "HINDSIGHT_ORIENTATION_MODEL": ("memoryOrientationModel", str),
+    "HINDSIGHT_ORIENTATION_CADENCE_HOURS": ("memoryOrientationCadenceHours", int),
+    "HINDSIGHT_ORIENTATION_REINJECT_TURNS": ("memoryOrientationReinjectTurns", int),
     # Switchroom hindsight-leverage A4 — directives-list cache TTL (seconds).
     # 0 disables the cache (rollback lever).
     "HINDSIGHT_DIRECTIVES_CACHE_TTL_SECONDS": ("directivesCacheTtlSeconds", int),

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

@@ -0,0 +1,248 @@
+"""Memory v2 M5 — Surface B: orientation-at-boot (pure logic).
+
+carve-M5.md §3/§5/§0c. This module holds the network-free, deterministically
+testable half of the orientation SessionStart hook: staleness classification
+(per-tier thresholds, NOT a fixed 36h), rule-aware truncation to the content
+token budget, and the `additionalContext` rendering. The hook entry
+(`orientation.py`) does the I/O — resolve own bank, list mental models, match
+the orientation model by name, GET its content — and calls into here so the
+budget/staleness/render logic can be unit-tested without a live engine.
+
+Why the split mirrors the fleet's other deterministic memory surfaces
+(recall.py's nudge regexes, prefetch.py's buffer contract): the value is a
+DETERMINISTIC mechanism, not model discretion, so every branch that decides
+"inject / prefix-as-stale / degrade-to-cold / truncate" must be pinned by a
+test that fails on the bug it guards (carve §8 tautology-guard discipline).
+
+TOKEN BUDGET (carve §0c). The epic caps the injected briefing at 2048 tokens,
+but M0 measured real mental models at ~1,766–1,962 tokens of CONTENT alone —
+so a naive "cap at 2048" overflows the moment a stale prefix or framing is
+prepended. The real number to design to is a CONTENT budget below the cap,
+leaving headroom for the prefix + framing. Truncation is rule-aware: whole
+markdown sections are kept, trailing sections dropped, and a visible marker is
+emitted so the loss is never silent.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+
+#: Hard ceiling on the total injected `additionalContext` (epic line 143).
+ORIENTATION_TOTAL_TOKEN_CAP = 2048
+#: Budget for the model CONTENT alone, below the cap so the stale prefix +
+#: framing tags fit inside 2048 (carve §0c: ~1,800, reserving ~250).
+ORIENTATION_CONTENT_TOKEN_BUDGET = 1800
+#: Chars-per-token estimate M0 used to convert measured char sizes to tokens
+#: (7,063 chars ≈ 1,766 tokens). Deterministic proxy — no tokenizer dependency
+#: on the boot critical path.
+CHARS_PER_TOKEN = 4
+
+#: Emitted (once) when trailing sections were dropped to fit the budget, so the
+#: loss is visible to the model rather than a silent mid-sentence byte-cut.
+TRUNCATION_MARKER = "(orientation truncated to fit context budget)"
+
+# Framing tags. Kept intentionally tiny — they count against the 2048 cap.
+_OPEN_TAG = "<orientation source=\"memory\">"
+_CLOSE_TAG = "</orientation>"
+
+
+def estimate_tokens(text: str) -> int:
+    """Deterministic token estimate (ceil of chars / CHARS_PER_TOKEN).
+
+    A proxy, not a real tokenizer — but the SAME proxy M0 measured content
+    sizes with, so the budget math is internally consistent, and it needs no
+    model/tokenizer on the boot path. Empty string is 0 tokens.
+    """
+    if not text:
+        return 0
+    return math.ceil(len(text) / CHARS_PER_TOKEN)
+
+
+def classify_staleness(
+    last_refreshed_at: str | None,
+    cadence_hours: int,
+    now: datetime | None = None,
+) -> tuple[str, float | None]:
+    """Classify an orientation model's freshness against its agent's TIER.
+
+    Returns ``(state, hours_ago)`` where state is one of:
+      - ``"fresh"``    — refreshed < 1.5× cadence ago: inject plainly.
+      - ``"stale"``    — 1.5×–3× cadence ago: inject WITH a visible prefix.
+      - ``"degraded"`` — > 3× cadence ago: do NOT inject stale-as-fresh; the
+                          hook emits the cold notice + enqueues a refresh.
+      - ``"unknown"``  — no/unparseable ``last_refreshed_at``: treat as cold
+                          (fail closed — never present an un-dated model as
+                          fresh). ``hours_ago`` is None.
+
+    The thresholds are PER-TIER (carve §5): a fixed 36h would mislabel every
+    48h-cadence agent as stale a full day early. 1.5× / 3× of the resolved
+    cadence is the tier-correct boundary — 36h/72h at cadence 24, 72h/144h at
+    cadence 48. Keyed on ``last_refreshed_at`` (the freshness watermark the
+    persisting refresh advances — m5-0-probe Q3), NOT ``updated_at`` (returned
+    null on the single-model read) and NOT the engine's own ``is_stale`` (its
+    threshold is engine-defined, not the agent's tier).
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+    if not last_refreshed_at:
+        return ("unknown", None)
+    ts = _parse_iso(last_refreshed_at)
+    if ts is None:
+        return ("unknown", None)
+    # A naive timestamp is assumed UTC (the engine stores tz-aware UTC; this is
+    # belt-and-braces so an aware/naive mismatch can never raise on subtract).
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    hours_ago = (now - ts).total_seconds() / 3600.0
+    # Guard a clock-skew future timestamp: treat as fresh, never negative-stale.
+    if hours_ago < 0:
+        hours_ago = 0.0
+    stale_at = 1.5 * cadence_hours
+    degrade_at = 3.0 * cadence_hours
+    if hours_ago < stale_at:
+        return ("fresh", hours_ago)
+    if hours_ago < degrade_at:
+        return ("stale", hours_ago)
+    return ("degraded", hours_ago)
+
+
+def _parse_iso(value: str) -> datetime | None:
+    """Parse an engine ISO-8601 timestamp, tolerating a trailing ``Z``."""
+    try:
+        # datetime.fromisoformat handles "+00:00" and fractional seconds; map a
+        # trailing Z (some engine surfaces emit it) to the offset form first.
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (ValueError, AttributeError):
+        return None
+
+
+def truncate_to_budget(content: str, token_budget: int) -> tuple[str, bool]:
+    """Rule-aware truncation to ``token_budget`` tokens.
+
+    Returns ``(text, truncated)``. Prefers WHOLE markdown sections (a section
+    starts at a line beginning with ``#``): accumulates sections while they fit,
+    drops trailing sections that don't, and signals ``truncated=True`` so the
+    caller can append :data:`TRUNCATION_MARKER`. If the very first section
+    already exceeds the budget, hard-cuts at a whitespace boundary (never
+    mid-word) rather than emitting nothing.
+
+    Never returns more than the budget; an empty/whitespace input returns
+    ``("", False)``.
+    """
+    content = (content or "").strip()
+    if not content:
+        return ("", False)
+    if estimate_tokens(content) <= token_budget:
+        return (content, False)
+
+    sections = _split_sections(content)
+    kept: list[str] = []
+    used = 0
+    for sec in sections:
+        sec_tokens = estimate_tokens(sec)
+        # +1 token slack for the join newline between kept sections.
+        if kept and used + sec_tokens + 1 > token_budget:
+            break
+        if not kept and sec_tokens > token_budget:
+            # First section alone overflows — hard-cut on a word boundary.
+            return (_hard_cut(sec, token_budget), True)
+        kept.append(sec)
+        used += sec_tokens + (1 if len(kept) > 1 else 0)
+
+    if not kept:
+        return (_hard_cut(sections[0], token_budget), True)
+    return ("\n".join(kept).strip(), True)
+
+
+def _split_sections(content: str) -> list[str]:
+    """Split markdown into whole sections at lines beginning with ``#``.
+
+    Leading preamble before the first header is its own section. A document
+    with no headers is a single section (the hard-cut path handles overflow).
+    """
+    lines = content.split("\n")
+    sections: list[str] = []
+    cur: list[str] = []
+    for line in lines:
+        if line.startswith("#") and cur:
+            sections.append("\n".join(cur))
+            cur = [line]
+        else:
+            cur.append(line)
+    if cur:
+        sections.append("\n".join(cur))
+    return sections
+
+
+def _hard_cut(text: str, token_budget: int) -> str:
+    """Cut ``text`` to fit ``token_budget`` at a whitespace boundary."""
+    char_budget = max(0, token_budget * CHARS_PER_TOKEN)
+    if len(text) <= char_budget:
+        return text.strip()
+    cut = text[:char_budget]
+    # Back up to the last whitespace so we never slice a word in half.
+    ws = cut.rfind(" ")
+    nl = cut.rfind("\n")
+    boundary = max(ws, nl)
+    if boundary > 0:
+        cut = cut[:boundary]
+    return cut.strip()
+
+
+def stale_prefix(hours_ago: float | None) -> str:
+    """One-line visible staleness prefix (carve §5). Never presents stale as fresh."""
+    if hours_ago is None:
+        return "(orientation staleness unknown — may be stale)"
+    return f"(orientation last refreshed {int(round(hours_ago))}h ago — may be stale)"
+
+
+def cold_notice() -> str:
+    """One-line cold notice (carve §3-4): no usable model, boot un-blocked.
+
+    Visible by design — a missing/degraded briefing degrades to a NOTICE the
+    model can see, never a silently memoryless boot.
+    """
+    return (
+        f"{_OPEN_TAG}\n"
+        "orientation model not yet built or refreshed — booting without a "
+        "briefing (a background refresh has been requested)\n"
+        f"{_CLOSE_TAG}"
+    )
+
+
+def render_orientation(
+    content: str,
+    staleness: str,
+    hours_ago: float | None,
+) -> str:
+    """Render the injected `additionalContext` for a usable model.
+
+    Applies the stale prefix when warranted, truncates the CONTENT to
+    :data:`ORIENTATION_CONTENT_TOKEN_BUDGET` (rule-aware), wraps in the tiny
+    framing tags, and guarantees the WHOLE rendered block (prefix + framing +
+    content) stays within :data:`ORIENTATION_TOTAL_TOKEN_CAP` — if the prefix
+    pushes it over, the content budget is trimmed further so the cap holds.
+
+    Callers pass only ``fresh`` or ``stale`` here; ``degraded``/``unknown`` go
+    to :func:`cold_notice` in the hook (never rendered as fresh).
+    """
+    prefix = stale_prefix(hours_ago) if staleness == "stale" else ""
+    # Reserve budget for the framing tags + prefix so the TOTAL stays under the
+    # hard cap, not just the content.
+    framing_tokens = estimate_tokens(_OPEN_TAG) + estimate_tokens(_CLOSE_TAG) + 2
+    prefix_tokens = estimate_tokens(prefix) + (1 if prefix else 0)
+    content_budget = min(
+        ORIENTATION_CONTENT_TOKEN_BUDGET,
+        ORIENTATION_TOTAL_TOKEN_CAP - framing_tokens - prefix_tokens,
+    )
+    body, truncated = truncate_to_budget(content, content_budget)
+    if truncated:
+        body = f"{body}\n\n{TRUNCATION_MARKER}"
+
+    parts = [_OPEN_TAG]
+    if prefix:
+        parts.append(prefix)
+    parts.append(body)
+    parts.append(_CLOSE_TAG)
+    return "\n".join(parts)

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

@@ -0,0 +1,265 @@
+"""M4 P0 — prefetch buffer + sentinel primitive.
+
+The end-of-turn-N Stop hook (``prefetch.py``) writes a prefetched recall
+block into a per-session buffer file, then writes a ``buffer.done`` sentinel
+LAST. The start-of-turn-N+1 UserPromptSubmit hook (``recall.py``) polls for a
+FRESH sentinel (bounded by ``poll_for_sentinel``'s ``cap_ms``) and, on a hit,
+consumes the buffered block instead of running recall synchronously.
+
+Read-after-write safety (the whole ballgame — carve §4 note 1):
+
+  * The payload is written via temp-file + atomic ``os.replace`` (POSIX
+    atomic within the same directory).
+  * The sentinel is written LAST, also via temp-file + ``os.fsync`` +
+    atomic ``os.replace``, and carries a MONOTONIC token (a `time.time_ns()`
+    counter, not wall-clock-comparable across machines but perfectly
+    ordered within one) — never content or mtime comparison, since two
+    writes CAN land in the same filesystem mtime tick.
+  * ``read_if_fresh`` treats "sentinel absent" OR "sentinel token not newer
+    than ``last_consumed_token``" as a miss (``None``). A torn write
+    (payload present, sentinel absent — e.g. the producer crashed between
+    the two writes) is INDISTINGUISHABLE from "no fresh buffer yet" by
+    construction, so it fails closed to ``None`` rather than serving a
+    possibly-incomplete/stale payload.
+
+State dir: ``$HOME/.hindsight/prefetch-buffer/`` (override via
+``HINDSIGHT_PREFETCH_BUFFER_DIR`` for tests), mirroring the
+``lib/watermark.py`` convention (a distinct dir, not a shared one, so a
+polling reader and a writing producer never contend for the same files as
+unrelated retain-watermark state).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+from typing import Optional
+
+if sys.platform != "win32":
+    import fcntl
+else:  # pragma: no cover - switchroom agents are Linux only
+    fcntl = None
+
+SCHEMA = 1
+
+# Default poll behaviour (Hermes's 3s join, hand-rolled — P-REC/P-PRE tune
+# the actual cap via config; this is the primitive's own conservative floor
+# if a caller passes a cap smaller than one sleep tick).
+_MIN_SLEEP_S = 0.02
+_MAX_SLEEP_S = 0.1
+
+
+def buffer_dir() -> str:
+    """Return the prefetch-buffer directory.
+
+    Override with ``HINDSIGHT_PREFETCH_BUFFER_DIR`` (tests). Default:
+    ``$HOME/.hindsight/prefetch-buffer/``.
+    """
+    override = os.environ.get("HINDSIGHT_PREFETCH_BUFFER_DIR")
+    if override:
+        return override
+    return os.path.join(os.path.expanduser("~"), ".hindsight", "prefetch-buffer")
+
+
+def _ensure_dir() -> str:
+    d = buffer_dir()
+    if not os.path.isdir(d):
+        os.makedirs(d, mode=0o700, exist_ok=True)
+    else:
+        try:
+            mode = os.stat(d).st_mode & 0o777
+            if mode != 0o700:
+                os.chmod(d, 0o700)
+        except OSError:
+            pass
+    return d
+
+
+def _safe_session(session_id: str) -> str:
+    """Sanitise a session id for use as a filename (no path traversal)."""
+    keep = [c if (c.isalnum() or c in "-_.") else "_" for c in (session_id or "unknown")]
+    name = "".join(keep)[:200]
+    return name.replace("..", "_") or "unknown"
+
+
+def _buffer_path(session_id: str) -> str:
+    return os.path.join(buffer_dir(), f"{_safe_session(session_id)}.buffer.json")
+
+
+def _sentinel_path(session_id: str) -> str:
+    return os.path.join(buffer_dir(), f"{_safe_session(session_id)}.buffer.done")
+
+
+def write_buffer(session_id: str, context: str, telemetry: Optional[dict] = None) -> None:
+    """Write the prefetched recall payload for ``session_id``.
+
+    Atomic (temp file + ``os.replace`` within the same directory). Does NOT
+    write the sentinel — the caller MUST call ``write_sentinel`` after this,
+    and only once the payload write has returned, to preserve the
+    read-after-write ordering guarantee.
+    """
+    d = _ensure_dir()
+    final = _buffer_path(session_id)
+    tmp = final + f".tmp.{os.getpid()}"
+    entry = {
+        "schema": SCHEMA,
+        "session_id": session_id,
+        "context": context,
+        "telemetry": telemetry or {},
+        "written_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(entry, f, ensure_ascii=False)
+        f.flush()
+        os.fsync(f.fileno())
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, final)
+
+
+def write_sentinel(session_id: str) -> int:
+    """Write the ``buffer.done`` sentinel for ``session_id``, LAST.
+
+    Returns the monotonic token written (an ever-increasing integer derived
+    from ``time.time_ns()``, disambiguated against the previous token on
+    this session so two writes within the same nanosecond still order).
+    fsync'd before the atomic rename so a reader that observes the renamed
+    file is guaranteed to observe durable content.
+    """
+    d = _ensure_dir()
+    final = _sentinel_path(session_id)
+    token = time.time_ns()
+    # Guarantee strict monotonicity even under nanosecond-resolution ties or
+    # clock weirdness: never emit a token <= the previously written one.
+    prev = _read_sentinel_token(session_id)
+    if prev is not None and token <= prev:
+        token = prev + 1
+    tmp = final + f".tmp.{os.getpid()}"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump({"schema": SCHEMA, "token": token}, f)
+        f.flush()
+        os.fsync(f.fileno())
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, final)
+    return token
+
+
+def _read_sentinel_token(session_id: str) -> Optional[int]:
+    path = _sentinel_path(session_id)
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        token = data.get("token")
+        return int(token) if token is not None else None
+    except (OSError, json.JSONDecodeError, ValueError, TypeError):
+        return None
+
+
+def _read_buffer_payload(session_id: str) -> Optional[dict]:
+    path = _buffer_path(session_id)
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def sentinel_exists(session_id: str) -> bool:
+    """Return True iff a ``buffer.done`` sentinel has EVER been written for
+    ``session_id`` (regardless of freshness).
+
+    Cold-start guard (red-team MAJOR finding): a reader must be able to tell
+    "no producer has ever run for this session" from "a producer ran but
+    hasn't finished this turn's slice yet" WITHOUT paying the full poll cap
+    — the former should skip polling entirely (every session-open turn
+    would otherwise eat the full poll cap, the opposite of M4's latency
+    goal), the latter is exactly what polling is for.
+    """
+    return os.path.isfile(_sentinel_path(session_id))
+
+
+def read_if_fresh(session_id: str, last_consumed_token: Optional[int]) -> tuple:
+    """Return ``(payload_dict | None, current_token)``.
+
+    ``payload_dict`` (when present) is ``{"context": str, "telemetry": dict}``.
+
+    Returns ``(None, token_or_last_consumed)`` when:
+      * no sentinel exists yet (nothing has been produced this session), or
+      * the sentinel's token is not strictly newer than ``last_consumed_token``
+        (already consumed — stale from the reader's perspective), or
+      * the buffer payload itself is missing/corrupt (a torn write, or a
+        sentinel written with no payload at all) — fail-closed, never serve
+        a partial/absent payload as fresh.
+    """
+    token = _read_sentinel_token(session_id)
+    if token is None:
+        return None, last_consumed_token
+    if last_consumed_token is not None and token <= last_consumed_token:
+        return None, token
+    payload = _read_buffer_payload(session_id)
+    if payload is None:
+        # Torn write: sentinel landed but payload didn't (or is corrupt).
+        # Fail-closed — never serve this as fresh.
+        return None, token
+    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.
+
+    Returns True as soon as ``read_if_fresh`` would return a payload; False
+    once the cumulative sleep time reaches ``cap_ms``. Short sleeps (20-100ms,
+    backing off) sum to at most ``cap_ms`` — never a hard-loop re-stat.
+    """
+    if cap_ms <= 0:
+        ctx, _ = read_if_fresh(session_id, last_consumed_token)
+        return ctx is not None
+
+    deadline = time.monotonic() + (cap_ms / 1000.0)
+    sleep_s = _MIN_SLEEP_S
+    while True:
+        ctx, _ = read_if_fresh(session_id, last_consumed_token)
+        if ctx is not None:
+            return True
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            return False
+        this_sleep = min(sleep_s, remaining, _MAX_SLEEP_S)
+        if this_sleep > 0:
+            time.sleep(this_sleep)
+        sleep_s = min(sleep_s * 1.5, _MAX_SLEEP_S)