switchroom 0.21.14 → 0.21.16

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

@@ -178,6 +178,7 @@ class HindsightClient:
         tags_match: Optional[str] = None,
         tag_groups: Optional[object] = None,
         prefer_observations: Optional[bool] = None,
+        query_timestamp: Optional[str] = None,
         timeout: int = 10,
     ) -> dict:
         """Recall memories from a bank.
@@ -190,6 +191,17 @@ class HindsightClient:
         `prefer_observations=True` asks the engine to prefer deduped
         observation statements over the raw facts they supersede, backfilling
         the freed slots — denser coverage inside the same token/count budget.
+
+        ``query_timestamp`` is an ISO 8601 datetime naming when the query is
+        being asked, from the user's perspective. The engine uses it as the
+        anchor for resolving relative temporal expressions in the query ("last
+        week", "yesterday") and for recency scoring; absent, the server's own
+        current time is the anchor. Sent only when non-empty, so a ``None``
+        (the default) leaves the wire body byte-identical to a pre-field
+        client — the additive-field invariant switchroom P2 depends on. The
+        REST recall body validates this field's format (a malformed value
+        400s: "Invalid query_timestamp format. Expected ISO format"), so the
+        caller is responsible for passing a well-formed ISO string.
         """
         path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/memories/recall"
         body = {
@@ -208,6 +220,8 @@ class HindsightClient:
             body["tag_groups"] = tag_groups
         if prefer_observations is not None:
             body["prefer_observations"] = prefer_observations
+        if query_timestamp:
+            body["query_timestamp"] = query_timestamp
         return self._request("POST", path, body, timeout=timeout)
 
     def retain(

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

@@ -122,6 +122,14 @@ DEFAULTS = {
     # out per-agent via memory.directive_capture_nudge=false →
     # HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE (disables BOTH hooks).
     "directiveCaptureNudge": True,
+    # RFC phase4 P3 — operator-profile capture nudge (recall.py,
+    # UserPromptSubmit). Regex-detects a first-person durable self-statement by
+    # the operator and appends a terse advisory telling the model to persist it
+    # with an explicit retain tagged `profile:ken` into the agent's OWN bank.
+    # Pure detection — no model callsite, no silent hook-side write. Operators
+    # opt out per-agent via memory.profile_capture_nudge=false →
+    # HINDSIGHT_PROFILE_CAPTURE_NUDGE.
+    "profileCaptureNudge": 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;
@@ -426,6 +434,15 @@ ENV_OVERRIDES = {
     "HINDSIGHT_RETAIN_OVERLAP_TURNS": ("retainOverlapTurns", int),
     "HINDSIGHT_RETAIN_CONTEXT": ("retainContext", str),
     "HINDSIGHT_RETAIN_TAGS": ("retainTags", list),
+    # `retainToolCalls` (RFC memory-redesign P4): whether retain stores tool_use
+    # inputs + tool_result content. Had a DEFAULTS entry (True) but — like the
+    # cadence knobs before them — no env channel and no scaffold stamp, so an
+    # operator could not opt an agent out and a docker-exec'd retain/backfill
+    # could not be steered. Adding the env key mirrors the yaml surface
+    # (`memory.retain.tool_calls`) and closes the same drift class. `false`
+    # (via `false`/`0`/`no`) resolves to Python False and lands over the True
+    # default; unset keeps True, byte-identical.
+    "HINDSIGHT_RETAIN_TOOL_CALLS": ("retainToolCalls", bool),
     # Switchroom-local: per-row observation scope on retains. Set by start.sh
     # from agents.<name>.memory.observation_scopes (cascading through
     # defaults.memory.observation_scopes) ONLY when the operator set it; unset
@@ -488,6 +505,11 @@ ENV_OVERRIDES = {
     # the operator overrode it; the switchroom default is on (settings.json
     # pins true; recall.py falls back to True).
     "HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE": ("directiveCaptureNudge", bool),
+    # RFC phase4 P3: operator-profile capture nudge on/off. Set by start.sh from
+    # agents.<name>.memory.profile_capture_nudge only when the operator overrode
+    # it; the switchroom default is on (settings.json pins true; recall.py falls
+    # back to True).
+    "HINDSIGHT_PROFILE_CAPTURE_NUDGE": ("profileCaptureNudge", 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

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

@@ -47,8 +47,9 @@ from .state import list_state_names, read_state, remove_state, write_state
 # move the doctor thresholds with it.
 #
 # Banks with more active directives than this are pathological; we truncate
-# with an in-prompt footer, a `directives_omitted` field on the recall_log row,
-# and a stderr warning (see `format_active_directives_block`).
+# with a LOUD, operator-directed in-prompt overflow notice (memory-RFC P7 — the
+# in-turn channel), a `directives_omitted` field on the recall_log row, and a
+# stderr warning (see `format_active_directives_block`).
 MAX_DIRECTIVES = 30
 
 # Hard timeout for the list_directives call. The recall hook is on the
@@ -272,6 +273,10 @@ def format_active_directives_block(directives: list, max_directives: int = MAX_D
         1. [P10] <name>: <content>
         2. [P9] <name>: <content>
         ...
+
+        === DIRECTIVE OVERFLOW — ACTION REQUIRED ===
+        <N of TOTAL directives dropped; agent is told to surface it to the
+         operator this turn and merge/retire directives> (only when omitted > 0)
         (+N more, omitted)
         </active_directives>
     """
@@ -301,12 +306,45 @@ def format_active_directives_block(directives: list, max_directives: int = MAX_D
         lines.append(f"{i}. [P{priority}] {name}: {content}")
 
     if omitted > 0:
+        # LOUD in-prompt overflow notice (memory-RFC P7). The prior footer was a
+        # single quiet parenthetical — `(+N more, omitted)` — which the agent
+        # could read past without registering that explicit, operator-authored
+        # instructions had been silently DROPPED from this turn. The three other
+        # signals this module records are either not operator-visible (stderr —
+        # swallowed, see below) or not in-turn (the `directives_omitted`
+        # recall_log row and `switchroom doctor`, both read after the fact). The
+        # in-prompt block is the one channel that is BOTH in-turn and reaches an
+        # operator — indirectly, because the agent relays it in its reply. So we
+        # make the footer loud and explicitly action-directed: state the loss,
+        # name the count and cap, and instruct the agent to surface it to the
+        # operator THIS turn. This is the P7 "loud channel" and is deliberately
+        # NOT a MAX_DIRECTIVES change (raising the cap only moves the silent-drop
+        # point; visibility has to ship first).
+        #
+        # The literal `(+N more, omitted)` marker is retained verbatim so the
+        # existing recall_log/doctor cross-checks and the directive-dedup parser
+        # (`parse_active_directives_block`) keep working unchanged.
         lines.append("")
+        lines.append("=== DIRECTIVE OVERFLOW — ACTION REQUIRED ===")
+        lines.append(
+            f"{omitted} of {total} active directives were DROPPED from this turn's "
+            f"prompt: the bank exceeds MAX_DIRECTIVES={max_directives}, so the "
+            f"{omitted} LOWEST-priority directive(s) are NOT in effect this turn. "
+            "This is silent loss of explicit, operator-authored instructions."
+        )
+        lines.append(
+            "ACTION: tell the operator in your reply this turn that directive "
+            "overflow is dropping rules, then merge or retire duplicate/stale "
+            "directives (mental-model-curator skill) to get the bank back under "
+            "the cap. Do not let this pass unmentioned."
+        )
         lines.append(f"(+{omitted} more, omitted)")
-        # The in-prompt footer above only tells the AGENT. This stderr warn is
-        # the same channel every other operational failure in this module uses
-        # (see `_fetch_directives_with_status`), and it is a LAST-RESORT
-        # breadcrumb only — do NOT rely on it reaching an operator.
+        # The in-prompt notice above is the operator-visible in-turn channel
+        # (P7): the agent reads it every turn the overflow persists and is told
+        # to relay it. This stderr warn is the same channel every other
+        # operational failure in this module uses (see
+        # `_fetch_directives_with_status`), and it is a LAST-RESORT breadcrumb
+        # only — do NOT rely on it reaching an operator.
         #
         # Measured 2026-07-25: `docker logs --tail 20000` across all 12 running
         # agent containers returns ZERO `[Hindsight]` lines, and nothing under
@@ -315,7 +353,7 @@ def format_active_directives_block(directives: list, max_directives: int = MAX_D
         # appears to swallow hook stderr on a zero exit, so hook stderr is not
         # an operator-visible channel.
         #
-        # The channels that DO reach an operator:
+        # The other channels that reach an operator, but only AFTER the turn:
         #   * the `directives_omitted` field on the recall_log row
         #     (state/recall_log.jsonl — see `count_omitted_directives`), and
         #   * `switchroom doctor`'s WARN/FAIL on the bank's active directive

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

@@ -0,0 +1,236 @@
+"""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 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)

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

@@ -92,6 +92,33 @@ def _lock_path(session_id: str) -> str:
     return os.path.join(watermark_dir(), f"{_safe_session(session_id)}.lock")
 
 
+def tail_after(messages: list, last_uuid: Optional[str]) -> list:
+    """Return the transcript entries AFTER the committed watermark anchor.
+
+    Pure and IO-free — the single shared slice used by BOTH the boot reconciler
+    (``reconcile_tail``) and the incremental SessionEnd sweep (``retain``, the
+    switchroom memory-RFC P1 change). One implementation, so the reconcile /
+    watermark failure category cannot grow a second, divergent copy.
+
+    Two safety fallbacks, both returning the WHOLE transcript — a safe
+    re-upsert, never a skip, never an empty slice:
+
+    * ``last_uuid`` falsy (no committed watermark) — e.g. a short session that
+      never fired a per-window retain, so the force sweep must flush it whole.
+    * ``last_uuid`` absent from ``messages`` (compaction removed the anchor).
+
+    Callers in the retain seam depend on the whole-transcript fallback: an empty
+    or skipped slice there DELETES a turn rather than degrading it
+    (``retain.py`` §4.3 hazard). Never change a fallback here to return ``[]``.
+    """
+    if not last_uuid:
+        return list(messages)
+    for i, m in enumerate(messages):
+        if isinstance(m, dict) and m.get("uuid") == last_uuid:
+            return messages[i + 1:]
+    return list(messages)
+
+
 def load(session_id: str) -> Optional[dict]:
     """Return the stored watermark dict for ``session_id``, or ``None``."""
     p = _path(session_id)

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

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""M4 P-PRE — async Stop-hook prefetch producer.
+
+carve-M4.md: moves recall injection off the synchronous UserPromptSubmit
+path by speculatively retaining + recalling at the END of turn N (this
+script, registered as an async Stop hook), so turn N+1's UserPromptSubmit
+(`recall.py`) can join an already-warm buffer instead of paying the full
+recall latency synchronously.
+
+Entirely gated by `memoryPrefetchEnabled` (default OFF/falsy — Fix C, the
+red-team-mandated per-agent kill switch). When off this script is a no-op:
+it reads config, sees the flag off, and exits silently before touching
+`lib.retain`, `lib.recall_buffer`, or the network.
+
+Call order (test a-integration in `tests/test_prefetch_pipeline.py`):
+  1. delta retain (`retain.run_retain(hook_input, force=False, delta=True)`)
+     — persists this turn's NEW slice using the Fix-A content-derived
+     document_id, never truncating the session document.
+  2. speculative recall (best-effort query derived from the transcript's
+     last human turn — the strongest available proxy for what turn N+1
+     will ask about).
+  3. `recall_buffer.write_buffer` then `recall_buffer.write_sentinel`
+     (STRICTLY in that order — the sentinel-ordering contract `lib/
+     recall_buffer.py` and `tests/test_recall_buffer.py` prove).
+
+Silent on stdout always (an async Stop hook's stdout is not surfaced to the
+transcript); errors go to stderr and NEVER raise past `main()` — a broken
+prefetch must degrade to "recall.py's synchronous path runs as before",
+never break the turn or leave a torn buffer (a crash between steps 2 and 3a
+just means no sentinel is written this turn, which `read_if_fresh` already
+treats as "nothing fresh" — fail-closed by construction).
+
+Skips the same junk turns `recall.py` skips (`<task-notification>` prefix)
+— a synthetic follow-up turn is not a real conversation shift worth
+prefetching for.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from lib.bank import derive_bank_id
+from lib.client import HindsightClient
+from lib.config import debug_log, load_config
+from lib.content import _extract_text_content, strip_channel_envelope
+from lib.daemon import get_api_url
+from lib import recall_buffer
+import retain as retain_module
+
+
+def _last_human_prompt(transcript_path: str) -> str:
+    """Best-effort: the most recent human-authored user turn's text, used
+    as the speculative query for next turn's prefetch. Never raises —
+    returns "" on any read/parse failure (degrades to no query, which the
+    caller treats as "nothing to prefetch")."""
+    try:
+        messages = retain_module.read_transcript(transcript_path)
+    except Exception:
+        return ""
+    for msg in reversed(messages):
+        if msg.get("role") != "user":
+            continue
+        text = _extract_text_content(msg.get("content"), role="user")
+        text = strip_channel_envelope(text) if text else text
+        if text and text.strip():
+            return text.strip()
+    return ""
+
+
+def run_prefetch(hook_input: dict, config: dict) -> bool:
+    """Execute one prefetch cycle. Returns True iff a buffer+sentinel pair
+    was written. Never raises — every internal step is wrapped so a bug in
+    ANY sub-step degrades to "no buffer written this turn", never a crash
+    that could take the Stop hook (and thus the turn) down with it."""
+    session_id = hook_input.get("session_id") or "unknown"
+
+    prompt = (hook_input.get("prompt") or hook_input.get("user_prompt") or "").strip()
+    if prompt.startswith("<task-notification"):
+        debug_log(config, "Prefetch: task-notification turn, skipping")
+        return False
+
+    # Step 1 — delta retain (Fix A: content-derived document_id, never the
+    # bare {session_id} document; never truncates).
+    try:
+        retain_module.run_retain(hook_input, force=False, delta=True)
+    except Exception as exc:  # pragma: no cover - defensive
+        debug_log(config, f"Prefetch: delta retain failed, continuing without it: {exc}")
+
+    # Step 2 — speculative recall.
+    transcript_path = hook_input.get("transcript_path") or ""
+    query = _last_human_prompt(transcript_path)
+    if not query:
+        debug_log(config, "Prefetch: no usable query, nothing to prefetch")
+        return False
+
+    try:
+        bank_id = derive_bank_id(hook_input, config)
+        api_url = get_api_url(config)
+        client = HindsightClient(api_url)
+        response = client.recall(
+            bank_id,
+            query,
+            types=None,
+            timeout=config.get("memoryPrefetchTimeoutSeconds", 5),
+        )
+        results = (response or {}).get("results") or []
+    except Exception as exc:  # pragma: no cover - defensive
+        debug_log(config, f"Prefetch: recall fetch failed: {exc}")
+        return False
+
+    if not results:
+        debug_log(config, "Prefetch: no candidates, nothing to buffer")
+        return False
+
+    from lib.content import format_memories
+
+    memories_block = format_memories(results)
+    if not memories_block:
+        return False
+
+    # Step 3 — write payload THEN sentinel, strictly in that order.
+    try:
+        recall_buffer.write_buffer(session_id, memories_block, {"result_count": len(results)})
+        recall_buffer.write_sentinel(session_id)
+    except Exception as exc:  # pragma: no cover - defensive
+        debug_log(config, f"Prefetch: buffer write failed: {exc}")
+        return False
+
+    return True
+
+
+def main():
+    config = load_config()
+    if not config.get("memoryPrefetchEnabled", False):
+        # Fix C, producer side: the whole mechanism is dark by default.
+        return
+
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        print("[Hindsight] Prefetch: failed to read hook input", file=sys.stderr)
+        return
+
+    try:
+        run_prefetch(hook_input, config)
+    except Exception as exc:  # pragma: no cover - defensive, must never break the turn
+        print(f"[Hindsight] Prefetch: unexpected error: {exc}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:  # pragma: no cover - defensive
+        print(f"[Hindsight] Unexpected error in prefetch: {e}", file=sys.stderr)
+        sys.exit(0)