switchroom 0.19.1 → 0.19.3

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

@@ -71,8 +71,28 @@ DEFAULTS = {
     # per-agent via memory.directive_capture_verify=false →
     # HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY.
     "directiveCaptureVerify": True,
-    "recallContextTurns": 1,
+    # 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
+    # directive writes invalidate the cache immediately via directive_verify.py.
+    # 0 disables the cache (live fetch every turn — the A4 rollback lever).
+    "directivesCacheTtlSeconds": 120,
+    # Switchroom hindsight-leverage A2 (PR2): default 2 so a bare follow-up
+    # user message ("and the port?", "what about staging?") embeds together
+    # with its antecedent turn, instead of recalling on the pronoun alone.
+    # Bounded by recallMaxQueryChars (truncate_recall_query preserves the
+    # latest turn and drops oldest context first) so the composition can never
+    # blow the recall query budget; the transcript read is byte-tail-bounded
+    # by recallTranscriptTailBytes so the added per-turn read stays O(1).
+    "recallContextTurns": 2,
     "recallMaxQueryChars": 800,
+    # Switchroom hindsight-leverage A2 (PR2) — latency bound for the multi-turn
+    # composition. With recallContextTurns>1 now the default, EVERY recall reads
+    # the transcript to slice the last N human turns. A long session's .jsonl can
+    # grow to many MB, so read only the last N bytes (complete trailing lines);
+    # the last 2-3 human turns always live at the tail. 0 disables the bound
+    # (read the whole file — the pre-A2 behaviour / rollback lever).
+    "recallTranscriptTailBytes": 262144,
     "recallRoles": ["user", "assistant"],
     # Upstream 962140eef — optional recall tag filters passed through to the
     # recall API, plus per-additional-bank overrides keyed by bank ID.
@@ -80,6 +100,19 @@ DEFAULTS = {
     "recallTagsMatch": "any",
     "recallTagGroups": None,
     "recallAdditionalBankFilters": {},
+    # Switchroom (hindsight-leverage PR5) — per-tag recall score weights. A map
+    # of ``{tag: multiplier}`` applied to each result's ``scores.final`` just
+    # before the final relevance sort/cap in recall.py. A weight < 1.0 DEMOTES
+    # (down-ranks) memories carrying that tag without DROPPING them — distinct
+    # from the hard demote-tag drop filter (`_is_demoted_memory`), which removes
+    # a memory from recall entirely. This is the "reduced weight" the drop
+    # filter cannot express: a demoted memory still surfaces when it is the only
+    # relevant hit, just below equal-scoring untagged memories. Default {} =
+    # no-op (identity weighting). Switchroom's scaffold seeds
+    # ``{"sidechain": 0.8}`` so delegated sub-agent process-memories rank just
+    # under first-party session memories. Env: HINDSIGHT_RECALL_TAG_WEIGHTS
+    # (JSON object).
+    "recallTagWeights": {},
     "recallPromptPreamble": (
         "Relevant memories from past conversations (prioritize recent when "
         "conflicting). Only use memories that are directly useful to continue "
@@ -95,6 +128,56 @@ DEFAULTS = {
     "retainContext": "claude-code",
     "retainTags": [],
     "retainMetadata": {},
+    # Switchroom hindsight-leverage E2 / PR9 (#398) — lesson & anti-pattern
+    # tagging at retain time. When on (default), build_retain_payload scans the
+    # formatted transcript slice for explicit lesson / anti-pattern markers and
+    # attaches the matching tag(s) to the retain. This is the retain-side half of
+    # #398: a transcript that captures a failure mode ("anti-pattern:", "what not
+    # to do") or a self-recognised lesson ("lesson learned", "note to self:") is
+    # tagged so the recall-side score-penalty weight map (recallTagWeights, PR5)
+    # can DEMOTE it below clean first-party session memories — without ever hard-
+    # dropping it. NON-GOAL (epic-recorded): historical corpus is NOT re-tagged;
+    # this fires on NEW retains only. Detection is deterministic substring match
+    # (case-insensitive), never model-dependent. Disable via
+    # HINDSIGHT_LESSON_TAGGING=false (rollback lever).
+    "lessonTagging": True,
+    # Marker map {tag: [substrings]}. A slice whose lower-cased text contains ANY
+    # of a tag's substrings gets that tag. Deliberately explicit prefixes to keep
+    # false positives low — a passing mention of the word "lesson" should not tag
+    # a whole transcript; an explicit "lesson learned" / "anti-pattern:" should.
+    # Operators can extend/replace via HINDSIGHT_LESSON_TAG_MARKERS (JSON object).
+    "lessonTagMarkers": {
+        "lesson": [
+            "lesson learned",
+            "lessons learned",
+            "lesson:",
+            "note to self:",
+            "for next time:",
+            "takeaway:",
+            "key takeaway",
+        ],
+        "anti-pattern": [
+            "anti-pattern:",
+            "anti pattern:",
+            "antipattern:",
+            "what not to do",
+            "do not do this again",
+            "don't do this again",
+            "failure mode:",
+        ],
+    },
+    # Switchroom hindsight-leverage E2 / PR9 (#398) — recall-side demotion weights
+    # for the lesson/anti-pattern tags above. Merged UNDER recallTagWeights at
+    # recall time (an explicit recallTagWeights entry for the same tag WINS), so
+    # lesson/anti-pattern transcripts are down-ranked out of the box while the
+    # PR5 sidechain seed and any operator override still compose cleanly. A raw
+    # transcript that merely discusses a failure mode should rank below a clean
+    # session memory of equal engine score, yet still surface when it is the only
+    # relevant hit (re-rank, never drop). Set HINDSIGHT_LESSON_DEMOTION=false to
+    # disable the built-in weights (rollback lever); override individual weights
+    # via recallTagWeights / HINDSIGHT_RECALL_TAG_WEIGHTS.
+    "lessonDemotion": True,
+    "lessonDemotionWeights": {"lesson": 0.85, "anti-pattern": 0.5},
     # Switchroom #3244 — boot reconciliation of un-committed transcript tails.
     # On by default; the load-bearing recovery for work an abrupt session death
     # (SIGKILL/OOM/watchdog) skipped. Disable per-agent via
@@ -102,6 +185,46 @@ DEFAULTS = {
     # HINDSIGHT_RECONCILE_{LOOKBACK_H,MAX_TURNS,BUDGET_S} bounds (read directly).
     "reconcileOnStart": True,
     "recallAdditionalBanks": [],
+    # Switchroom hindsight-leverage A3 — parallelise multi-bank recall.
+    # When on (default), the directives fetch and every bank recall run
+    # concurrently in daemon threads under ONE shared deadline
+    # (recallParallelDeadlineSeconds), so total critical-path latency is the
+    # SLOWEST slot instead of their SUM. Set false
+    # (HINDSIGHT_RECALL_PARALLEL=false) to restore the pre-A3 serial path —
+    # the rollback lever if the parallel path ever misbehaves.
+    "recallParallel": True,
+    # Shared deadline (seconds) for the whole parallel recall section. Sized
+    # at the UserPromptSubmit hook ceiling (12s, hooks.json) MINUS 2s headroom
+    # for block formatting + cache write + stdout flush, so a straggler bank
+    # can never push the hook past its ceiling. Slots still unfinished when the
+    # deadline elapses are abandoned (daemon threads) and marked timed_out.
+    "recallParallelDeadlineSeconds": 10,
+    # Switchroom hindsight-leverage E1 / PR8 (#3369) — bounded transcript-grep
+    # fallback. Boot reconciliation (reconcile_tail.py) closes the crash-loss
+    # window at the NEXT SessionStart, but between an abrupt kill and that boot,
+    # live recall returns nothing for the lost turns because the fact layer was
+    # never told about them. When on (default) AND every bank returned zero
+    # results AND no bank/directives slot hit its deadline (deadline_hit False —
+    # so a timed-out bank can't masquerade as a genuinely empty fact layer, the
+    # #3369 sequencing constraint that depends on A3's shared-deadline telemetry),
+    # recall greps the CURRENT session's transcript tail for turns that mention
+    # the query's terms and injects them as a clearly-labelled, lower-confidence
+    # fallback block. Everything is bounded: the tail read (…MaxBytes), the number
+    # of matched turns (…MaxTurns), the emitted characters (…MaxChars), and the
+    # grep wall-time (…DeadlineMs). Set false (HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK
+    # =false) to disable — the rollback lever.
+    "recallTranscriptFallback": True,
+    # Tail bytes read from the session transcript for the grep. 256 KiB covers
+    # many turns of recent conversation while keeping the read well inside the
+    # hook budget; only the LAST max_bytes are read (partial first line dropped).
+    "recallTranscriptFallbackMaxBytes": 262144,
+    # Hard ceiling on matched turns injected into the fallback block.
+    "recallTranscriptFallbackMaxTurns": 6,
+    # Hard ceiling on the fallback block's excerpt characters.
+    "recallTranscriptFallbackMaxChars": 2000,
+    # Wall-clock bound (ms) on the grep itself — abandons scanning older turns
+    # once exceeded so the fallback can never eat the recall critical path.
+    "recallTranscriptFallbackDeadlineMs": 1500,
     # Connection
     "hindsightApiUrl": None,
     "hindsightApiToken": None,
@@ -140,6 +263,12 @@ ENV_OVERRIDES = {
     "HINDSIGHT_AUTO_RECALL": ("autoRecall", bool),
     "HINDSIGHT_AUTO_RETAIN": ("autoRetain", bool),
     "HINDSIGHT_RETAIN_MODE": ("retainMode", str),
+    # Switchroom hindsight-leverage E2 / PR9 (#398) — lesson/anti-pattern tagging
+    # + recall demotion toggles and overrides.
+    "HINDSIGHT_LESSON_TAGGING": ("lessonTagging", bool),
+    "HINDSIGHT_LESSON_TAG_MARKERS": ("lessonTagMarkers", dict),
+    "HINDSIGHT_LESSON_DEMOTION": ("lessonDemotion", bool),
+    "HINDSIGHT_LESSON_DEMOTION_WEIGHTS": ("lessonDemotionWeights", dict),
     # Switchroom #3244 — boot reconciliation on/off (default on).
     "HINDSIGHT_RECONCILE_ON_START": ("reconcileOnStart", bool),
     "HINDSIGHT_RECALL_BUDGET": ("recallBudget", str),
@@ -171,13 +300,33 @@ ENV_OVERRIDES = {
     # agents.<name>.memory.directive_capture_verify only when the operator
     # overrode it; the switchroom default is on.
     "HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY": ("directiveCaptureVerify", bool),
+    # Switchroom hindsight-leverage A4 — directives-list cache TTL (seconds).
+    # 0 disables the cache (rollback lever).
+    "HINDSIGHT_DIRECTIVES_CACHE_TTL_SECONDS": ("directivesCacheTtlSeconds", int),
+    # Switchroom hindsight-leverage A3 — parallel multi-bank recall toggle +
+    # shared deadline. HINDSIGHT_RECALL_PARALLEL=false is the serial rollback
+    # lever; the deadline is the ceiling-minus-2s hard budget (see DEFAULTS).
+    "HINDSIGHT_RECALL_PARALLEL": ("recallParallel", bool),
+    "HINDSIGHT_RECALL_PARALLEL_DEADLINE_SECONDS": ("recallParallelDeadlineSeconds", int),
+    # Switchroom hindsight-leverage E1 / PR8 (#3369) — transcript-grep fallback
+    # toggle + bounds. HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK=false is the rollback
+    # lever; the others tune the byte / turn / char / time bounds.
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK": ("recallTranscriptFallback", bool),
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK_MAX_BYTES": ("recallTranscriptFallbackMaxBytes", int),
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK_MAX_TURNS": ("recallTranscriptFallbackMaxTurns", int),
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK_MAX_CHARS": ("recallTranscriptFallbackMaxChars", int),
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK_DEADLINE_MS": ("recallTranscriptFallbackDeadlineMs", int),
     "HINDSIGHT_RECALL_MAX_QUERY_CHARS": ("recallMaxQueryChars", int),
     "HINDSIGHT_RECALL_CONTEXT_TURNS": ("recallContextTurns", int),
+    # Switchroom hindsight-leverage A2 — byte-tail bound for the multi-turn
+    # transcript read (0 = read whole file / rollback lever).
+    "HINDSIGHT_RECALL_TRANSCRIPT_TAIL_BYTES": ("recallTranscriptTailBytes", int),
     # Upstream 962140eef — recall tag filters. The tags env var accepts JSON
     # or a comma-separated list; the others must be JSON.
     "HINDSIGHT_RECALL_TAGS": ("recallTags", list),
     "HINDSIGHT_RECALL_TAGS_MATCH": ("recallTagsMatch", str),
     "HINDSIGHT_RECALL_TAG_GROUPS": ("recallTagGroups", dict),
+    "HINDSIGHT_RECALL_TAG_WEIGHTS": ("recallTagWeights", dict),
     "HINDSIGHT_RECALL_ADDITIONAL_BANK_FILTERS": ("recallAdditionalBankFilters", dict),
     "HINDSIGHT_API_PORT": ("apiPort", int),
     "HINDSIGHT_DAEMON_IDLE_TIMEOUT": ("daemonIdleTimeout", int),

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

@@ -33,11 +33,17 @@ def strip_channel_envelope(content: str) -> str:
     This is the Claude Code equivalent of Openclaw's stripMetadataEnvelopes().
     Extracts the inner text, preserving the actual user message while removing
     transport metadata that Hindsight doesn't need.
+
+    A single prompt may carry MORE THAN ONE envelope (e.g. a coalesced
+    burst where several inbound messages were concatenated). Since this now
+    sits on the live recall-query path (hindsight-leverage PR 1, review
+    finding 6), coalesce EVERY envelope's inner text rather than keeping only
+    the first and silently dropping everything after the first ``</channel>``.
     """
-    # Match <channel ...>content</channel> — extract inner text
-    match = re.search(r"<channel\b[^>]*>([\s\S]*?)</channel>", content)
-    if match:
-        return match.group(1).strip()
+    # Match every <channel ...>content</channel> — extract & join inner texts.
+    matches = re.findall(r"<channel\b[^>]*>([\s\S]*?)</channel>", content)
+    if matches:
+        return "\n".join(m.strip() for m in matches if m.strip()).strip()
     return content
 
 
@@ -79,7 +85,14 @@ def compose_recall_query(
 
         <latest query>
     """
-    latest = latest_query.strip()
+    # Switchroom A1 (hindsight-leverage PR 1) — strip the <channel> envelope
+    # from the latest query INSIDE the helper as well, so any caller (present
+    # or future) gets an envelope-free composed query. The recall.py caller
+    # already strips before calling, but keeping the strip here is defence in
+    # depth: it guarantees the trailing latest-query segment appended below
+    # (and returned on the turns<=1 short-circuit) never carries the raw
+    # chat_id/ts/user XML noise into the embedding or the char cap.
+    latest = strip_channel_envelope(latest_query).strip()
     if recall_context_turns <= 1 or not isinstance(messages, list) or not messages:
         return latest
 
@@ -236,6 +249,43 @@ def slice_last_turns_by_user_boundary(messages: list, turns: int) -> list:
     return messages[start_index:]
 
 
+# ---------------------------------------------------------------------------
+# Sidechain (sub-agent transcript) detection
+# ---------------------------------------------------------------------------
+
+
+def transcript_first_line_is_sidechain(path: str) -> bool:
+    """True when the first JSON line of ``path`` carries ``isSidechain: true``.
+
+    Switchroom hindsight-leverage PR5. Claude Code writes sub-agent (Task-tool)
+    transcripts as separate ``.jsonl`` files under
+    ``<project>/<session>/subagents/agent-<agent_id>.jsonl`` whose every line
+    carries ``isSidechain: true``. This shared predicate lets BOTH the
+    SubagentStop retain (which resolves + retains these deliberately, tagged
+    ``sidechain`` + volume-gated) AND the boot reconciler / any transcript
+    sweeper (which must NOT treat a sidechain as a pseudo-session and re-retain
+    it untagged, at full recall weight, bypassing the volume gate) recognise a
+    sidechain file from its first line alone — a cheap single-line read. Any
+    read/parse error is treated as "not a sidechain" (fail-open: a
+    genuinely-unreadable file is skipped elsewhere by its empty transcript).
+    """
+    import json
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    return json.loads(line).get("isSidechain") is True
+                except json.JSONDecodeError:
+                    return False
+    except OSError:
+        return False
+    return False
+
+
 # ---------------------------------------------------------------------------
 # Memory formatting (recall results → context string)
 # ---------------------------------------------------------------------------

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

@@ -18,8 +18,11 @@ recall path; a directive-fetch failure must not kill the recall block.
 
 import re
 import sys
+import time
 from typing import Optional
 
+from .state import list_state_names, read_state, remove_state, write_state
+
 # Sanity cap on how many directives we ever inject into the prompt. Banks
 # with more active directives than this are pathological; truncate with a
 # footer so the agent knows there are more.
@@ -29,25 +32,56 @@ MAX_DIRECTIVES = 15
 # UserPromptSubmit critical path — we cannot block it for long.
 DIRECTIVES_TIMEOUT_SECONDS = 2
 
+# --- Directives-list cache (switchroom hindsight-leverage A4) -----------------
+#
+# `list_directives` runs on the recall (UserPromptSubmit) critical path every
+# non-skipped turn — a fresh 2s-timeout HTTP round-trip whose result changes
+# only when a directive is created/updated/deleted (rare). We cache the fetched
+# list in the plugin state dir with a short TTL so the common no-write turn
+# skips the round-trip, while bounding staleness:
+#   * In-session writes: directive_verify.py (Stop hook) deletes the cache when
+#     the just-ended turn contains a create/update/delete_directive tool_use, so
+#     the very next recall re-fetches — the new state is visible in turn N+1.
+#   * Cross-process writes (another session, operator CLI) have no invalidation
+#     channel and rely on TTL alone → at most TTL seconds stale.
+#
+# Invalidation blind spots (both fall back to TTL, ≤ TTL stale — acceptable):
+#   * Sub-agent / sidechain directive writes: the create_directive tool_use is
+#     in the SIDECHAIN transcript, not the parent's, so the parent's Stop hook
+#     (which reads the parent transcript) never sees it. PR 5 (SubagentStop)
+#     is where sidechain awareness lands.
+#   * Bash / operator-CLI directive writes (`switchroom` or a curl) produce no
+#     tool_use in any transcript, so there is nothing for the Stop hook to
+#     detect.
+#
+# Rollback: set the TTL to 0 (HINDSIGHT_DIRECTIVES_CACHE_TTL_SECONDS=0) to
+# disable the cache entirely — every turn fetches live, as before A4.
+DIRECTIVES_CACHE_TTL_SECONDS = 120
 
-def fetch_active_directives(client, bank_id: str, timeout: int = DIRECTIVES_TIMEOUT_SECONDS) -> list:
-    """Fetch active directives for a bank, sorted by priority (highest first).
+# All directive cache files share this basename prefix so they can be
+# enumerated for bulk (bank-agnostic) invalidation.
+_CACHE_PREFIX = "directives_cache."
 
-    Args:
-        client: A HindsightClient instance with a list_directives method.
-        bank_id: The bank to fetch directives from.
-        timeout: HTTP timeout in seconds.
 
-    Returns:
-        A list of directive dicts (each with id, name, content, priority,
-        tags, ...), sorted by priority descending. On any failure returns
-        an empty list and logs a single warn line to stderr — never raises.
+def _cache_name(bank_id: str) -> str:
+    """State-file name for a bank's cached directive list."""
+    return f"{_CACHE_PREFIX}{bank_id}.json"
+
+
+def _fetch_directives_with_status(client, bank_id: str, timeout: int) -> tuple:
+    """Fetch + normalize active directives, reporting fetch success.
+
+    Returns ``(ok, directives)``. ``ok`` is False only on a genuine fetch
+    FAILURE (HTTP error, non-dict response) — a bank that simply has no
+    directives returns ``(True, [])``. Callers use ``ok`` to avoid caching a
+    transient failure's empty result (which would mask real directives for a
+    whole TTL window). Never raises; logs a single warn line on failure.
     """
     try:
         response = client.list_directives(bank_id=bank_id, active_only=True, timeout=timeout)
     except Exception as e:
         print(f"[Hindsight] list_directives failed for bank '{bank_id}': {e}", file=sys.stderr)
-        return []
+        return False, []
 
     if not isinstance(response, dict):
         print(
@@ -55,20 +89,123 @@ def fetch_active_directives(client, bank_id: str, timeout: int = DIRECTIVES_TIME
             f"{type(response).__name__}",
             file=sys.stderr,
         )
-        return []
+        return False, []
 
     items = response.get("items")
     if not isinstance(items, list):
         # Empty / malformed response — quiet success, no warn (banks with
-        # no directives are normal).
-        return []
+        # no directives are normal). Cacheable.
+        return True, []
 
     # Filter to dicts only, then sort by priority descending. Treat missing
     # priority as 0 so malformed entries sink to the bottom rather than
     # crashing.
     valid = [d for d in items if isinstance(d, dict)]
     valid.sort(key=lambda d: d.get("priority", 0), reverse=True)
-    return valid
+    return True, valid
+
+
+def fetch_active_directives(client, bank_id: str, timeout: int = DIRECTIVES_TIMEOUT_SECONDS) -> list:
+    """Fetch active directives for a bank, sorted by priority (highest first).
+
+    Args:
+        client: A HindsightClient instance with a list_directives method.
+        bank_id: The bank to fetch directives from.
+        timeout: HTTP timeout in seconds.
+
+    Returns:
+        A list of directive dicts (each with id, name, content, priority,
+        tags, ...), sorted by priority descending. On any failure returns
+        an empty list and logs a single warn line to stderr — never raises.
+    """
+    _ok, directives = _fetch_directives_with_status(client, bank_id, timeout)
+    return directives
+
+
+def _read_cache(bank_id: str) -> Optional[dict]:
+    """Read + validate a bank's cache envelope. Returns None on miss/corruption.
+
+    A corrupted or wrong-shaped cache (bad JSON handled by read_state; here we
+    additionally reject a non-dict envelope, a non-numeric timestamp, or a
+    non-list directive payload) is treated as a MISS so the caller falls back to
+    a live fetch rather than injecting garbage.
+
+    Also rejects an envelope whose stored ``bank_id`` does not match the
+    requested one: ``_safe_filename`` can collapse two distinct bank ids onto a
+    single cache file, and serving bank A's directives for bank B would leak
+    rules across banks. The embedded ``bank_id`` is the authoritative key.
+    """
+    raw = read_state(_cache_name(bank_id), None)
+    if not isinstance(raw, dict):
+        return None
+    if raw.get("bank_id") != bank_id:
+        return None
+    ts = raw.get("ts")
+    directives = raw.get("directives")
+    if not isinstance(ts, (int, float)) or isinstance(ts, bool):
+        return None
+    if not isinstance(directives, list):
+        return None
+    return raw
+
+
+def fetch_active_directives_cached(
+    client,
+    bank_id: str,
+    ttl_seconds: int = DIRECTIVES_CACHE_TTL_SECONDS,
+    timeout: int = DIRECTIVES_TIMEOUT_SECONDS,
+    now: Optional[float] = None,
+) -> list:
+    """Cached wrapper around :func:`fetch_active_directives`.
+
+    On a fresh cache hit (age < ``ttl_seconds``) returns the cached list WITHOUT
+    an HTTP call. On a miss / expiry / corrupted cache, fetches live and, when
+    the fetch SUCCEEDED, writes the cache. A failed fetch is never cached, so a
+    transient error can't mask real directives for a TTL window.
+
+    ``ttl_seconds <= 0`` disables the cache (always live-fetch, never write) —
+    the A4 rollback lever.
+
+    Args:
+        now: Injectable current epoch seconds, for deterministic tests.
+    """
+    if now is None:
+        now = time.time()
+
+    caching = isinstance(ttl_seconds, (int, float)) and ttl_seconds > 0
+
+    if caching:
+        cached = _read_cache(bank_id)
+        if cached is not None:
+            age = now - cached["ts"]
+            # A negative age means the stored timestamp is in the FUTURE
+            # (wall-clock step-back / a doctored envelope) — treat it as
+            # expired rather than "fresh forever", so a clock correction can't
+            # pin a stale cache.
+            if 0 <= age < ttl_seconds:
+                return cached["directives"]
+
+    ok, directives = _fetch_directives_with_status(client, bank_id, timeout)
+
+    if caching and ok:
+        write_state(_cache_name(bank_id), {"ts": now, "bank_id": bank_id, "directives": directives})
+
+    return directives
+
+
+def invalidate_directives_cache(bank_id: Optional[str] = None) -> None:
+    """Delete the directives cache so the next recall re-fetches live.
+
+    With ``bank_id`` set, removes just that bank's cache file. With no argument
+    (the Stop-hook invalidation path, which does not resolve the bank), removes
+    EVERY directive cache file — directive writes are rare, so a bank-agnostic
+    sweep is cheap and robust. Best-effort; never raises.
+    """
+    if bank_id is not None:
+        remove_state(_cache_name(bank_id))
+        return
+    for name in list_state_names(_CACHE_PREFIX):
+        remove_state(name)
 
 
 def format_active_directives_block(directives: list, max_directives: int = MAX_DIRECTIVES) -> Optional[str]:

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

@@ -0,0 +1,142 @@
+"""Deadline-bounded parallel fan-out for the recall critical path.
+
+Switchroom hindsight-leverage A3 (parallel multi-bank recall). The recall
+hook (``recall.py``) queries the agent's own bank, every additional bank
+(profile / shared / sender), and the active-directives list. Serially, the
+critical-path latency is the SUM of those round-trips — a heavy agent with two
+extra banks plus directives can serialise four 2-8s calls and breach the 12s
+UserPromptSubmit hook ceiling, which drops recall entirely for that turn.
+
+This runs each labelled task in its OWN daemon thread and waits only until a
+single SHARED deadline (the hook ceiling minus a headroom margin). Key
+properties, all enforced by mechanism rather than convention:
+
+  * **Daemon threads.** Every worker is a daemon, so a thread still blocked on
+    a socket read when the deadline elapses can NEVER keep the interpreter (and
+    therefore the hook) alive past the ceiling — the process exits and the
+    kernel reaps the socket. ``recall.py``'s ``__main__`` additionally calls
+    ``os._exit(0)`` after flushing stdout as a belt-and-suspenders against any
+    non-daemon thread a client library might spawn.
+
+  * **One shared deadline.** Total wait is bounded by ``deadline_seconds`` from
+    the moment ``run_parallel`` is entered — not per-task — so N slow banks
+    cost the deadline ONCE, not N times.
+
+  * **Completion is observed, not assumed.** Each slot records whether its
+    thread finished before we stopped waiting (``completed``), its return value
+    or exception, and its wall-clock ``elapsed_ms``. A slot still running at the
+    deadline is ``completed=False`` with ``elapsed_ms`` pinned to the deadline —
+    the caller maps that to ``timed_out`` for telemetry.
+
+Stdlib-only (threading + time); no third-party deps, importable under the
+plugin's ``python3 -m unittest`` harness.
+"""
+
+import threading
+import time
+
+
+class SlotResult:
+    """Outcome of one labelled task run under the shared deadline.
+
+    Attributes:
+        label:      the task's key in the ``tasks`` mapping.
+        value:      the callable's return value, or None if it raised / did not
+                    finish before the deadline.
+        error:      the exception the callable raised, or None. A slot that hit
+                    the deadline mid-flight has ``error=None`` and
+                    ``completed=False`` (it never got to raise or return).
+        completed:  True iff the worker thread finished (returned or raised)
+                    before ``run_parallel`` stopped waiting on it. False means
+                    the shared deadline elapsed first.
+        elapsed_ms: wall-clock ms the slot took. For a completed slot this is
+                    its real duration; for a deadline-abandoned slot it is the
+                    time from fan-out start to the deadline.
+    """
+
+    __slots__ = ("label", "value", "error", "completed", "elapsed_ms")
+
+    def __init__(self, label):
+        self.label = label
+        self.value = None
+        self.error = None
+        self.completed = False
+        self.elapsed_ms = None
+
+
+def _runner(slot, fn, start):
+    """Worker body: run the task, capturing value/exception and duration.
+
+    Catches ``BaseException`` deliberately for slot isolation: a slot runs in
+    its own daemon thread, and a task failure of ANY kind — including
+    non-``Exception`` subclasses like ``KeyboardInterrupt`` /
+    ``SystemExit`` — must be captured into ``slot.error`` rather than escaping
+    the thread. An escaped exception would let the slot die silently and the
+    deadline join would then see no value AND no recorded error. (``socket.timeout``
+    is itself just an ``OSError`` subclass, i.e. an ordinary ``Exception``; the
+    broad catch is about never letting any slot failure leak out of the thread.)
+    """
+    try:
+        slot.value = fn()
+    except BaseException as e:  # noqa: BLE001 - deliberate: isolate the slot
+        slot.error = e
+    finally:
+        slot.elapsed_ms = int((time.monotonic() - start) * 1000)
+
+
+def run_parallel(tasks, deadline_seconds):
+    """Run ``{label: callable}`` concurrently under one shared deadline.
+
+    Args:
+        tasks: mapping of label -> zero-arg callable. Each is invoked once in
+            its own daemon thread. Insertion order is preserved in the returned
+            mapping (Python dicts are ordered) so the caller can emit per-slot
+            telemetry deterministically regardless of completion order.
+        deadline_seconds: total wall-clock budget for ALL tasks combined,
+            measured from entry. Non-positive values run every task with a
+            zero join (each slot is recorded as not-completed unless it was
+            already instantaneous) — a degenerate "give up immediately" mode.
+
+    Returns:
+        ``dict[label] -> SlotResult`` in the same order as ``tasks``. Never
+        raises for a task failure — a raising task surfaces via
+        ``SlotResult.error``.
+    """
+    start = time.monotonic()
+    pairs = []  # (SlotResult, Thread) in task order
+    for label, fn in tasks.items():
+        slot = SlotResult(label)
+        thread = threading.Thread(
+            target=_runner,
+            args=(slot, fn, start),
+            daemon=True,
+            name=f"recall-slot-{label}",
+        )
+        pairs.append((slot, thread))
+
+    for _slot, thread in pairs:
+        thread.start()
+
+    # Join each thread, but never wait past the SHARED deadline. Because the
+    # remaining budget is recomputed from ``start`` on every iteration, the
+    # total time spent here is bounded by ``deadline_seconds`` even with many
+    # slow slots — a fast early slot leaves more budget for later ones, and
+    # once the budget is exhausted every subsequent join is a non-blocking
+    # ``is_alive`` check.
+    for _slot, thread in pairs:
+        remaining = deadline_seconds - (time.monotonic() - start)
+        if remaining > 0:
+            thread.join(remaining)
+
+    # Classify each slot as completed (thread finished) or deadline-abandoned.
+    now = time.monotonic()
+    results = {}
+    for slot, thread in pairs:
+        if thread.is_alive():
+            slot.completed = False
+            if slot.elapsed_ms is None:
+                slot.elapsed_ms = int((now - start) * 1000)
+        else:
+            slot.completed = True
+        results[slot.label] = slot
+    return results

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

@@ -82,6 +82,37 @@ def write_state(name: str, data):
             pass
 
 
+def remove_state(name: str) -> None:
+    """Delete a state file if it exists. Best-effort; never raises.
+
+    Name is sanitized through the same path-traversal guard as read/write, so
+    callers cannot escape the state directory.
+    """
+    try:
+        path = _state_file(name)
+    except ValueError:
+        return
+    try:
+        os.remove(path)
+    except OSError:
+        pass
+
+
+def list_state_names(prefix: str = "") -> list:
+    """List state-file basenames in the state dir, optionally by prefix.
+
+    Returns [] on any error. Used to enumerate a family of cache files (e.g.
+    per-bank directive caches) for bulk invalidation.
+    """
+    try:
+        names = os.listdir(_state_dir())
+    except OSError:
+        return []
+    if prefix:
+        return [n for n in names if n.startswith(prefix)]
+    return names
+
+
 def get_turn_count(session_id: str) -> int:
     """Get the current turn count for a session."""
     turns = read_state("turns.json", {})