switchroom 0.19.16 → 0.19.18

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

@@ -23,10 +23,33 @@ 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.
-MAX_DIRECTIVES = 15
+# Sanity cap on how many directives we ever inject into the prompt.
+#
+# This number is a COST TRADEOFF, not an arbitrary limit, and the real cost is
+# larger than "one block": `recall.py` rebuilds the <active_directives> block
+# on EVERY UserPromptSubmit (the `format_active_directives_block` call there)
+# with no per-session dedupe and no "unchanged since last turn" suppression,
+# and `additionalContext` is APPENDED into the conversation. So the block is
+# re-paid every turn and accumulates — roughly (block size) x (turn count) over
+# a session, not once.
+#
+# Measured live 2026-07-25 (fleet REST `/directives`):
+#   overlord  12 active  ~9.8 KB   ~816 chars avg  (one 2,981-char outlier)
+#   klanker   17 active  ~9.9 KB   ~585 chars avg
+#   gymbro     9 active  ~9.3 KB  ~1038 chars avg
+# At the ~700-char fleet average, a bank sitting at this cap injects ~21 KB —
+# on the order of 5,000-6,000 tokens per injection, per turn, cumulative across
+# the session. 30 is chosen to clear the observed fleet maximum with headroom;
+# it is NOT a size at which a runaway bank becomes harmless. The actual defence
+# against pile-up is the doctor's WARN/FAIL on the active directive count
+# (src/cli/doctor-memory.ts), not this cap. Raising it further is a legitimate
+# call — make it deliberately, with the per-turn-times-turns cost in mind, and
+# 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`).
+MAX_DIRECTIVES = 30
 
 # Hard timeout for the list_directives call. The recall hook is on the
 # UserPromptSubmit critical path — we cannot block it for long.
@@ -208,6 +231,16 @@ def invalidate_directives_cache(bank_id: Optional[str] = None) -> None:
         remove_state(name)
 
 
+def count_omitted_directives(directives: list, max_directives: int = MAX_DIRECTIVES) -> int:
+    """How many directives `format_active_directives_block` would DROP.
+
+    Pure counterpart of the truncation branch below, so `recall.py` can put the
+    number on the recall_log row without re-deriving the cap. 0 when nothing is
+    dropped.
+    """
+    return max(0, len(directives) - max_directives)
+
+
 def format_active_directives_block(directives: list, max_directives: int = MAX_DIRECTIVES) -> Optional[str]:
     """Format directives into the <active_directives> block string.
 
@@ -252,6 +285,31 @@ def format_active_directives_block(directives: list, max_directives: int = MAX_D
     if omitted > 0:
         lines.append("")
         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.
+        #
+        # Measured 2026-07-25: `docker logs --tail 20000` across all 12 running
+        # agent containers returns ZERO `[Hindsight]` lines, and nothing under
+        # ~/.switchroom/logs/ contains them either, despite months of runtime
+        # and several long-standing stderr paths in recall.py. Claude Code
+        # 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 `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
+        #     count (src/cli/doctor-memory.ts `classifyDirectiveCount`), which
+        #     reads the count from the same REST surface this module fetches.
+        print(
+            f"[Hindsight] directive truncation: {total} active directives exceeds "
+            f"MAX_DIRECTIVES={max_directives} — {omitted} lowest-priority "
+            f"directive(s) were DROPPED from this turn's prompt. Merge or retire "
+            f"directives (mental-model-curator) or raise MAX_DIRECTIVES.",
+            file=sys.stderr,
+        )
 
     lines.append("</active_directives>")
     return "\n".join(lines)

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

@@ -65,6 +65,7 @@ from lib.content import (
 from lib.daemon import get_api_url
 from lib.directives import (
     DIRECTIVES_CACHE_TTL_SECONDS,
+    count_omitted_directives,
     fetch_active_directives_cached,
     format_active_directives_block,
 )
@@ -405,11 +406,124 @@ def _is_demoted_memory(memory) -> bool:
 # regardless of which bank they came from. This gate is a *complementary*,
 # opt-in absolute precision floor: `scores.final` is a relative rank that
 # still orders weakly-matching memories rather than excluding them, so on a
-# low-relevance prompt the top-N could still be low-signal. The Jaccard
+# low-relevance prompt the top-N could still be low-signal. The lexical
 # overlap between the user's query terms and each memory's text terms is a
-# query-independent absolute measure that drops memories below a
+# rank-independent absolute measure that drops memories below a
 # configurable threshold outright — something the relative sort does not do.
 #
+# --- switchroom #3541: the metric is CONTAINMENT, not Jaccard ---
+#
+# This gate originally scored with Jaccard similarity,
+# `|Q ∩ M| / |Q ∪ M|`. That is the wrong metric here, because the two
+# sides have wildly asymmetric lengths: the recall query is the whole
+# prior-context preamble (production p50 778 chars) while a memory is a
+# single fact (tens of tokens). The union term is dominated by |Q|, so the
+# SAME memory with the SAME real overlap scores lower purely because the
+# prompt was longer. Query length, not relevance, decided the outcome.
+#
+# Measured on production recall telemetry (1548 rows, 646 of which put
+# candidates through the gate, ts >= 2026-07-18, all fleet agents'
+# `recall_log.jsonl`), at the fleet default threshold of 0.10:
+#
+#   query_chars    rows   candidates   survived   survival%   zero-result%
+#      0- 200        30        1364          99       7.3%          23.3%
+#    200- 400       110        4199         238       5.7%          17.3%
+#    400- 600       143        5305         293       5.5%          72.7%
+#    600- 750       213        7288          67       0.9%          93.0%
+#    750-1000       150        4968          70       1.4%          90.0%
+#
+# 22447 of 23124 candidate memories (97.1%) were discarded, and the
+# discard rate rose monotonically with prompt length — the signature of
+# the union-term artifact, not of a relevance judgement. Where the gate
+# actually got to run, it was decisive: of the 526 turns that had at least
+# one bank return successfully, 440 (83.7%) still delivered zero memories.
+#
+# How much of the empty-recall problem is this? Roughly a third — NOT all
+# of it. Partitioning the zero-result recalls by why they were empty:
+#
+#   >=1 bank returned OK, and overlap_dropped > 0   448  (~32%)  <- this gate
+#   ALL banks timed out or errored                  565  (~41%)  <- the deadline
+#   >=1 bank returned OK, nothing dropped             7
+#
+# So the 8s outer deadline accounts for MORE empty recalls than the gate
+# does, and it is still live after this change: `deadline_hit` is set on
+# 991 of 18656 logged recalls and the p50 `total_elapsed_ms` on the
+# deadline-hitting rows sits at the 8s ceiling. Fixing the metric does not
+# close #3541's latency half — see the reranker analysis in that issue.
+# This change fixes the gate; it does not fix the timeout.
+#
+# The correct metric for asymmetric-length comparison is containment:
+# `|Q ∩ M| / |M|` — "what fraction of THIS MEMORY's terms are present in
+# the prompt", invariant to how much unrelated preamble the prompt
+# carries. (Not `min(|Q|, |M|)`; see `containment_overlap` for why the
+# textbook overlap coefficient's short-prompt regime flip is undesirable
+# here.)
+#
+# --- what the 0.10 threshold does, and does not, buy ---
+#
+# Be honest about the retained default: at 0.10, containment is close to a
+# PASSTHROUGH. Because the denominator is the memory's own token count, a
+# memory of <= 10 content tokens clears 0.10 on a SINGLE shared word. Only
+# longer memories are meaningfully filtered (a 40-token memory still needs
+# 4 shared terms). Measured on the production-shaped prompt used in the
+# regression tests, a wholly off-topic memory that merely reuses words
+# from the prior-context preamble scores 0.857 — HIGHER than the genuinely
+# relevant memory at 0.571.
+#
+# That inversion is the reason the threshold is NOT being raised to
+# compensate. Raising it would drop the relevant memory before the
+# off-topic one, because on a preamble-heavy prompt containment is not
+# monotone in relevance. Lexical overlap cannot make that distinction at
+# any threshold; the engine's reranker can, and does.
+#
+# The threshold was nevertheless re-derived from data rather than inherited
+# from the Jaccard era. 31 real production queries (reconstructed from
+# transcripts with the hook's own compose+truncate, validated by matching
+# 320 of them verbatim against logged recall rows) were replayed against
+# the live engine; the 202 returned candidates were rescored offline:
+#
+#   containment    survival%   zero-result%   mean kept/query
+#      0.05           99.5%          0.0%           6.5
+#      0.10           86.1%          6.5%           5.6   <- shipped
+#      0.20           65.8%         41.9%           4.3
+#      0.30           58.4%         41.9%           3.8
+#      0.40           52.5%         54.8%           3.4
+#
+# (Jaccard @0.10 on the same candidates: 70.3% survival, 32.3%
+# zero-result — i.e. the fix cuts empty recalls from ~1 turn in 3 to
+# ~1 in 15 on this sample.)
+#
+# 0.30 and 0.40 leave 42-55% of turns with NO memories at all — they
+# re-create the exact failure #3541 is about, for a precision gain the
+# inversion above says is illusory. 0.10 is the shipped value.
+#
+# Sample caveat, stated plainly: these are single-bank (overlord) replays
+# and the engine returned ~6.5 already-top-ranked candidates per query,
+# not the ~35-candidate pools seen in the fleet logs. The ABSOLUTE
+# survival percentages are therefore optimistic versus production; the
+# RANKING of the thresholds, and the zero-result cliff above 0.10, are the
+# load-bearing results.
+#
+# So the honest statement of the design after #3541 is: the effective
+# precision control is the engine rerank plus the `recallMaxMemories`
+# head-slice, and this gate is a cheap floor that removes only candidates
+# with (near-)zero lexical relationship to the prompt. It is no longer
+# doing the job the #475 note above describes — "on a low-relevance prompt
+# the top-N could still be low-signal" is a real concern that this gate
+# does not actually address. Doing so needs a relevance-score floor
+# (`scores.final`), not a lexical one; that is deliberately out of scope
+# here and wants its own measured change.
+#
+# This is safe to run permissively: the gate is a FLOOR, not a ranker.
+# `_sort_by_final_score` orders the survivors by the engine's reranked
+# relevance score immediately afterwards, and only then does
+# `recallMaxMemories` head-slice. So admitting more candidates cannot
+# lower the quality of what is injected — it can only give the
+# score-sort a non-empty set to choose the top-N from. And because
+# `|Q ∩ M| / |M| >= |Q ∩ M| / |Q ∪ M|` always, at a fixed threshold this
+# metric admits a superset of what the deployed Jaccard gate admits: no
+# memory that survives in production today can be dropped by this change.
+#
 # Threshold default is 0.0 (disabled) so the gate is opt-in initially.
 # Operators tune via `memory.recall.min_overlap` in switchroom.yaml or
 # `HINDSIGHT_RECALL_MIN_OVERLAP=0.15` env. Telemetry surfaces the dropped
@@ -465,22 +579,60 @@ def _overlap_tokens(text) -> set:
     return out
 
 
-def jaccard_overlap(query: str, memory_text: str) -> float:
-    """Jaccard similarity between two texts, after stop-word + punctuation
-    stripping. Returns a float in [0.0, 1.0]. Empty/degenerate inputs
-    return 0.0 — it's safer to drop than retain when we can't compute.
+def containment_overlap(query: str, memory_text: str) -> float:
+    """Containment of the MEMORY in the query, after stop-word + punctuation
+    stripping: ``|Q ∩ M| / |M|``.
+
+    Returns a float in [0.0, 1.0]. Empty/degenerate inputs return 0.0 —
+    it's safer to drop than retain when we can't compute.
+
+    Unlike Jaccard (`|Q ∩ M| / |Q ∪ M|`, used until switchroom #3541) this
+    is INVARIANT TO QUERY LENGTH. The recall query is a long prior-context
+    preamble and a memory is a short fact; dividing by the union made the
+    score collapse as the prompt grew, so the gate discarded 97.1% of
+    already-reranked candidates and did so monotonically in prompt length.
+    Dividing by the memory asks the question the gate actually means: what
+    fraction of this memory's terms appear in the prompt. See the design
+    note above `_OVERLAP_STOPWORDS` for the production measurement.
+
+    That invariance is specifically against growth of NON-OVERLAPPING
+    preamble in the query — the failure mode #3541 hit — and is not
+    unqualified: a short query still scores low against a long memory
+    (whenever `|Q| < threshold * |M|` the memory is dropped however
+    relevant it is), and where `Q ⊆ M` the metric degenerates to exactly
+    Jaccard. So `|M|` is a trade against `min(|Q|, |M|)`, not a strict
+    improvement over it; the paragraph below is the argument for which
+    side of that trade is safer here.
+
+    Why ``|M|`` and not ``min(|Q|, |M|)`` (the textbook overlap coefficient):
+    the two agree only where the memory is the shorter side, and that is NOT
+    a safe assumption here. Replaying real production queries against the
+    live engine, `|Q| < |M|` held for 87 of 202 candidate pairs — 43%.
+    Memories are routinely LONGER than the prompt that retrieves them.
+    Wherever that happens `min()` selects the QUERY and the metric silently
+    becomes the converse measure: what fraction of the *prompt* appears in
+    the memory. That regime flip re-introduces exactly the query-length
+    dependence #3541 is about — a one-word prompt scores 1.0 against any
+    memory containing that word. Dividing by `|M|` unconditionally has no
+    such discontinuity.
+
+    Safety, relative to what production runs today: for any Q and M,
+
+        |Q ∩ M| / |Q ∪ M|  <=  |Q ∩ M| / |M|  <=  |Q ∩ M| / min(|Q|, |M|)
+
+    because `|Q ∪ M| >= |M| >= min(|Q|, |M|)`. So at a fixed threshold this
+    metric admits a SUPERSET of what the deployed Jaccard gate admits: no
+    memory that survives the gate today can be dropped by this change.
     """
     a = _overlap_tokens(query)
     b = _overlap_tokens(memory_text)
     if not a or not b:
         return 0.0
-    inter = len(a & b)
-    union = len(a | b)
-    return inter / union if union else 0.0
+    return len(a & b) / len(b)
 
 
 def _filter_by_overlap(results, query: str, threshold: float):
-    """Drop memories whose Jaccard overlap with the query is below the
+    """Drop memories whose containment overlap with the query is below the
     threshold. Threshold <= 0 short-circuits to passthrough (no
     iteration cost).
 
@@ -492,7 +644,7 @@ def _filter_by_overlap(results, query: str, threshold: float):
     dropped = 0
     for m in results:
         text = m.get("text", "") if isinstance(m, dict) else ""
-        if jaccard_overlap(query, text) >= threshold:
+        if containment_overlap(query, text) >= threshold:
             kept.append(m)
         else:
             dropped += 1
@@ -517,6 +669,74 @@ def _result_final_score(m) -> float:
     return float("-inf")
 
 
+def _injected_score_stats(results) -> dict:
+    """Relevance-score aggregates for the INJECTED set (post-head-slice).
+
+    Switchroom #3541 review finding — recall-quality telemetry.
+    `recall_log.jsonl` records volume and plumbing only (`overlap_dropped`,
+    `capped`, `pre_cap_count`, `memory_ids`, `deadline_hit`). With the
+    overlap gate deliberately near-passthrough at 0.10, 100% of precision now
+    rests on the engine's `scores.final` plus the `recallMaxMemories`
+    head-slice — and no field observes that. Post-rollout, `overlap_dropped`
+    collapsing to 0 while `result_count` rises to the cap reads as
+    unambiguous success on every existing dashboard whether the reranker is
+    good OR whether every agent is being fed 8 mediocre memories per turn.
+    These three fields are what distinguishes those two worlds.
+
+    Returns ``{"injected_score_min", "injected_score_median",
+    "injected_score_max"}``. Values are floats rounded to 4dp, or None when
+    the set is empty or no result carried a usable score (results missing
+    `scores.final` are excluded rather than counted as a sentinel, so a
+    single malformed entry cannot drag the aggregate).
+
+    Aggregates ONLY — no query text and no memory text is recorded here.
+
+    READING THESE ACROSS THE CE-DAMPING ROLLOUT (#3579). `scores.final` is the
+    engine's `combined_score`, and #3579 changes how that number is composed:
+    ``CE * boost`` becomes ``CE * boost**k`` with k ≈ 0.0395 at the engine's
+    default alphas. So these three fields SHIFT ON DEPLOY as a scale artifact,
+    not as a quality change. Measured against the pinned upstream image on a
+    saturated 100-result band (CE 0.9800-0.9999), the injected top-8 moved from
+    min/median/max 1.0822/1.0843/1.1136 (spread 0.0314) to 0.9977/0.9979/0.9981
+    (spread 0.0004): the level drops ~8% and the spread collapses ~78x as
+    combined_score converges onto the raw cross-encoder score. Two consequences:
+
+      * Any threshold or dashboard band calibrated on pre-#3579 data is invalid
+        afterwards, and a before/after comparison across the deploy boundary
+        measures the rescale, not recall quality. Re-baseline after rollout.
+      * These aggregates are PERMUTATION-INVARIANT over the injected set, so
+        they cannot see a pure re-ordering of the head-slice - which is exactly
+        what #3579 does. They move only when the head-slice MEMBERSHIP changes
+        (in the measured band it changed completely: 0 of 8 ids in common).
+        Membership churn is therefore the signal to watch, not the level.
+
+    Setting `HINDSIGHT_CE_DECISIVE_RELATIVE_GAP` at or above ~0.651 clamps k to
+    1.0 and restores the pre-#3579 scale exactly, which is also how to get a
+    like-for-like reading back.
+    """
+    empty = {
+        "injected_score_min": None,
+        "injected_score_median": None,
+        "injected_score_max": None,
+    }
+    try:
+        scores = [s for s in (_result_final_score(m) for m in results or []) if s != float("-inf")]
+        if not scores:
+            return empty
+        scores.sort()
+        n = len(scores)
+        mid = n // 2
+        median = scores[mid] if n % 2 else (scores[mid - 1] + scores[mid]) / 2.0
+        return {
+            "injected_score_min": round(scores[0], 4),
+            "injected_score_median": round(median, 4),
+            "injected_score_max": round(scores[-1], 4),
+        }
+    except Exception:
+        # Telemetry must never take recall down.
+        return empty
+
+
 def _sort_by_final_score(results):
     """Sort merged multi-bank results by `scores.final` descending, in place.
 
@@ -1279,8 +1499,16 @@ def main():
                 "query": None,  # no recall query composed on a cache hit
                 "result_count": None,  # not known on cache hit
                 "directive_count": None,
+                # No directives block is built on a cache hit.
+                "directives_omitted": None,
                 "demoted_count": 0,
                 "capped": False,
+                # #3541 quality telemetry — present for a uniformly queryable
+                # schema. A cache hit replays a formatted context block, not a
+                # result set, so no per-memory scores exist to aggregate.
+                "injected_score_min": None,
+                "injected_score_median": None,
+                "injected_score_max": None,
                 "cache_hit": True,
                 # A3 stage-1 telemetry keys kept present for a uniformly
                 # queryable schema; a cache hit issues no bank HTTP, so there
@@ -1631,9 +1859,12 @@ def main():
             )
 
     # Switchroom #475 — lexical-overlap relevance gate. Drops memories
-    # whose Jaccard overlap with the query is below
+    # whose containment overlap with the query is below
     # `recallMinOverlap` (default 0.0 = disabled). Runs after the
     # demote filter so the threshold sees the operator-curated set.
+    # #3541: the metric is containment, NOT Jaccard — see the design
+    # note above `_OVERLAP_STOPWORDS`. Jaccard made the gate a function
+    # of prompt length and it discarded 97.1% of reranked candidates.
     overlap_threshold = config.get("recallMinOverlap", 0.0)
     if isinstance(overlap_threshold, (int, float)) and overlap_threshold > 0:
         pre_overlap_count = len(results)
@@ -1812,6 +2043,14 @@ def main():
         "query": query[:200],
         "result_count": len(results),
         "directive_count": len(directives),
+        # Switchroom 2026-07-25 review finding 2 — how many active directives
+        # MAX_DIRECTIVES dropped from this turn's <active_directives> block.
+        # The stderr warning in lib/directives.py is NOT operator-visible
+        # (Claude Code swallows hook stderr on a zero exit — verified fleet-wide),
+        # so this row is the durable, queryable record that real hard rules
+        # never reached the agent. >0 here means the bank is over cap and the
+        # doctor's directive-count check will be FAILing too.
+        "directives_omitted": count_omitted_directives(directives),
         "demoted_count": demoted_count,
         "overlap_dropped": overlap_dropped,
         "capped": capped,
@@ -1820,6 +2059,12 @@ def main():
             m.get("id") for m in results
             if isinstance(m, dict) and m.get("id")
         ],
+        # Switchroom #3541 — recall QUALITY telemetry, alongside the volume
+        # fields above. min/median/max of `scores.final` over the injected
+        # (post-head-slice) set. See `_injected_score_stats` for why volume
+        # alone can't distinguish "reranker is working" from "8 mediocre
+        # memories per turn" now that the overlap gate is near-passthrough.
+        **_injected_score_stats(results),
         "cache_hit": False,
         # Switchroom A3 stage-1 telemetry (hindsight-leverage PR 1) — per-bank
         # latency + timeout breakdown, directives-fetch latency, total

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

@@ -117,8 +117,9 @@ def select_retain_window(
     SWITCHROOM DIVERGENCE (Phase 6b — candidate to upstream to
     vectorize-io/hindsight): the chunked sliding-window is decoupled from
     the ``retainEveryNTurns > 1`` throttle. Upstream only sliced a window
-    when ``retain_every_n > 1``; with ``retainEveryNTurns=1`` (switchroom's
-    every-turn crash-durability setting, applied in scaffold.ts) chunked
+    when ``retain_every_n > 1``; at ``retainEveryNTurns=1`` (switchroom's
+    historical every-turn crash-durability setting; the current scaffold.ts
+    default is 3) chunked
     mode fell through to full-session and re-consolidated the ENTIRE
     accumulated transcript on every Stop fire — an unbounded, per-turn cost.
 
@@ -127,9 +128,11 @@ def select_retain_window(
     (still owned by run_retain, unchanged); this function only decides *what*
     to retain once a fire happens. A chunked window of
     ``max(retain_every_n, 1) + overlap_turns`` turns is correct for any
-    ``retain_every_n >= 1``. With ``retain_every_n=1, overlap=2`` the window
-    is the 3 most-recent HUMAN turns (tool_result messages don't count as
-    turns — see slice_last_turns_by_user_boundary).
+    ``retain_every_n >= 1``. At the current switchroom defaults
+    (``retain_every_n=3, overlap=1``) the window is the 4 most-recent HUMAN
+    turns; at ``retain_every_n=1, overlap=2`` it is the 3 most-recent
+    (tool_result messages don't count as turns — see
+    slice_last_turns_by_user_boundary).
 
     ``force=True`` (SessionEnd final retain) widens chunked mode to a
     full-session sweep — belt-and-braces so a graceful shutdown always flushes
@@ -429,7 +432,10 @@ def run_retain(hook_input: dict, force: bool = False) -> dict:
     debug_log(config, f"Read {len(all_messages)} messages from transcript")
 
     # Retention mode: full session (vendor default) or chunked. Switchroom
-    # runs chunked at retainEveryNTurns=1 (see select_retain_window / scaffold.ts).
+    # overrides to chunked in scaffold.ts, at the cascaded
+    # memory.retain.every_n_turns (default 3) / .overlap_turns (default 1) —
+    # a fire every 3rd turn over a ~4-turn window. See select_retain_window
+    # and scaffold.ts (HINDSIGHT_DEFAULT_RETAIN_*).
     retain_mode = config.get("retainMode", "full-session")
     retain_every_n = max(1, config.get("retainEveryNTurns", 1))
     retain_full_window = False

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

@@ -24,6 +24,7 @@ from lib.directives import (  # noqa: E402
     DIRECTIVES_CACHE_TTL_SECONDS,
     MAX_DIRECTIVES,
     _cache_name,
+    count_omitted_directives,
     fetch_active_directives,
     fetch_active_directives_cached,
     format_active_directives_block,
@@ -181,20 +182,89 @@ class FormatActiveDirectivesBlockTests(unittest.TestCase):
         self.assertIn("Line one.\nLine two.\nLine three.", out)
 
     def test_truncates_at_cap_with_footer(self):
-        # 20 synthetic directives — should truncate to MAX_DIRECTIVES with
-        # a "(+N more, omitted)" footer.
+        # MAX_DIRECTIVES + 5 synthetic directives — should truncate to
+        # MAX_DIRECTIVES with a "(+N more, omitted)" footer.
+        total = MAX_DIRECTIVES + 5
         directives = [
-            _directive(f"d{i}", f"content {i}", priority=20 - i) for i in range(20)
+            _directive(f"d{i}", f"content {i}", priority=total - i) for i in range(total)
         ]
         out = format_active_directives_block(directives)
-        # Cap should be 15 by default.
-        self.assertEqual(MAX_DIRECTIVES, 15)
-        self.assertIn("1. [P20] d0", out)
+        self.assertIn(f"1. [P{total}] d0", out)
         self.assertIn(f"{MAX_DIRECTIVES}. [P", out)
-        # 16th item should NOT appear.
+        # The first item past the cap must NOT appear.
         self.assertNotIn(f"{MAX_DIRECTIVES + 1}. [P", out)
         # Footer with the right omitted count.
-        self.assertIn(f"(+{20 - MAX_DIRECTIVES} more, omitted)", out)
+        self.assertIn("(+5 more, omitted)", out)
+
+    def test_cap_is_30_and_clears_the_observed_fleet_maximum(self):
+        """The cap must clear the busiest real bank (24 active directives).
+
+        Regression: at MAX_DIRECTIVES=15 a 24-directive bank had 9 of its
+        rules dropped from every turn's prompt. This asserts the OUTCOME —
+        all 24 directives are rendered, and no truncation footer/warning is
+        produced — not merely that the constant changed.
+        """
+        self.assertEqual(MAX_DIRECTIVES, 30)
+        directives = [
+            _directive(f"d{i}", f"content {i}", priority=24 - i) for i in range(24)
+        ]
+        with patch("sys.stderr", new=StringIO()) as fake_err:
+            out = format_active_directives_block(directives)
+        for i in range(24):
+            self.assertIn(f"d{i}: content {i}", out)
+        self.assertIn("24. [P", out)
+        self.assertNotIn("more, omitted", out)
+        self.assertEqual(fake_err.getvalue(), "")
+
+    def test_truncation_emits_a_stderr_breadcrumb_naming_the_dropped_count(self):
+        """Truncation writes a `[Hindsight]` line to stderr naming total, cap
+        and dropped count, alongside the in-prompt "(+N more, omitted)" footer.
+
+        Scope note (2026-07-25 review finding 2): this asserts ONLY that the
+        line is written to stderr. It does NOT — and cannot — show that an
+        operator ever sees it; hook stderr is swallowed by Claude Code on a
+        zero exit (zero `[Hindsight]` lines across all 12 live containers).
+        The operator-visible signals are the `directives_omitted` recall_log
+        field and `switchroom doctor`'s directive-count row, tested elsewhere.
+        """
+        total = MAX_DIRECTIVES + 4
+        directives = [
+            _directive(f"d{i}", f"c{i}", priority=total - i) for i in range(total)
+        ]
+        with patch("sys.stderr", new=StringIO()) as fake_err:
+            out = format_active_directives_block(directives)
+        err = fake_err.getvalue()
+        self.assertNotEqual(err, "", "truncation must write a stderr breadcrumb")
+        self.assertIn("[Hindsight]", err)
+        self.assertIn(str(total), err)
+        self.assertIn(f"MAX_DIRECTIVES={MAX_DIRECTIVES}", err)
+        self.assertIn("4", err)  # the dropped count
+        # The in-prompt footer is still emitted (agent-facing signal).
+        self.assertIn("(+4 more, omitted)", out)
+
+    def test_count_omitted_directives_matches_the_rendered_footer(self):
+        """The recall_log's `directives_omitted` number must equal what the
+        block actually dropped — it is the operator-visible record of it."""
+        total = MAX_DIRECTIVES + 4
+        directives = [
+            _directive(f"d{i}", f"c{i}", priority=total - i) for i in range(total)
+        ]
+        with patch("sys.stderr", new=StringIO()):
+            out = format_active_directives_block(directives)
+        self.assertEqual(count_omitted_directives(directives), 4)
+        self.assertIn("(+4 more, omitted)", out)
+        # Under cap → nothing omitted, and no footer to disagree with.
+        under = directives[:2]
+        self.assertEqual(count_omitted_directives(under), 0)
+        self.assertNotIn("more, omitted", format_active_directives_block(under))
+        # Honours a custom cap the same way the formatter does.
+        self.assertEqual(count_omitted_directives(directives, max_directives=5), total - 5)
+
+    def test_no_warning_when_nothing_is_truncated(self):
+        directives = [_directive("only", "single", priority=5)]
+        with patch("sys.stderr", new=StringIO()) as fake_err:
+            format_active_directives_block(directives)
+        self.assertEqual(fake_err.getvalue(), "")
 
     def test_no_footer_when_under_cap(self):
         directives = [_directive("only", "single", priority=5)]
@@ -208,7 +278,8 @@ class FormatActiveDirectivesBlockTests(unittest.TestCase):
 
     def test_custom_cap_respected(self):
         directives = [_directive(f"d{i}", f"c{i}", priority=10) for i in range(5)]
-        out = format_active_directives_block(directives, max_directives=2)
+        with patch("sys.stderr", new=StringIO()):
+            out = format_active_directives_block(directives, max_directives=2)
         self.assertIn("1. [P10] d0", out)
         self.assertIn("2. [P10] d1", out)
         self.assertNotIn("3. [P10] d2", out)