switchroom 0.19.24 → 0.19.25

package/profiles/_base/start.sh.hbs

@@ -737,19 +737,58 @@ export HINDSIGHT_RECALL_MAX_MEMORIES={{hindsightRecallMaxMemories}}
 {{#if (isNumber hindsightRecallCacheTtlSecs)}}
 export HINDSIGHT_RECALL_CACHE_TTL_SECS={{hindsightRecallCacheTtlSecs}}
 {{/if}}
-# Lexical-overlap relevance gate (#475). Drops memories whose containment
-# overlap (|Q n M| / |M|, see #3541) with the user's query is
-# below this threshold (range 0.0–1.0).
-# Plugin default is 0.0 (gate disabled); export only when the operator
-# overrode it via memory.recall.min_overlap in switchroom.yaml. Use 0.10:
-# it is a near-passthrough floor, not a precision control. Values at or
-# above 0.20 measurably starve recall — on production replay 0.20 leaves
-# ~41.9% of turns with NO memories at all, re-creating the bug #3541
-# fixed. Observe `overlap_dropped` via
-# `switchroom memory recall-log <agent>`.
-{{#if (isNumber hindsightRecallMinOverlap)}}
-export HINDSIGHT_RECALL_MIN_OVERLAP={{hindsightRecallMinOverlap}}
-{{/if}}
+# BM25 term budget for the recall query (#3757). The hook composes a query
+# from the last 2 turns and Hindsight OR-joins EVERY token into one
+# to_tsquery; Postgres native FTS cannot top-k from the GIN index, so it
+# ranks the entire matched set before the top-60 heapsort. Measured on the
+# live `overlord` bank (135,565 rows, 3 fact-type arms): 96 distinct terms
+# = 119,510 rows ranked = 14.0s, versus 24 terms = 48,433 rows = 2.7s.
+# memory.recall.query_max_tokens; 0 disables shaping (rollback lever).
+# Exported UNCONDITIONALLY with a concrete value — see the note on
+# HINDSIGHT_RECALL_REQUEST_TIMEOUT_SECONDS below for why an unexported or
+# empty knob is a silent-shadowing bug rather than a no-op.
+export HINDSIGHT_RECALL_QUERY_MAX_TOKENS={{hindsightRecallQueryMaxTokens}}
+# Bank-specific high-document-frequency terms to drop from the BM25 query
+# (#3757, memory.recall.query_stop_terms). Postgres' `english` config
+# already strips generic English stopwords; this is for words a generic
+# stoplist cannot know are useless in THIS bank — on `overlord`,
+# `switchroom` matched 27,075 rows (20%) and `agent` a similar share.
+# JSON array (the plugin also accepts a comma-separated string), single-
+# quoted so the JSON's double quotes reach the plugin intact. The schema
+# constrains each term to `[\w./-]+`, so it cannot contain a quote. Exported
+# unconditionally: with no operator override this is the literal `[]`, which
+# `_cast_env` parses to an empty list and assigns, so the env still wins over
+# a stale claude-code.json.
+export HINDSIGHT_RECALL_QUERY_STOP_TERMS='{{hindsightRecallQueryStopTermsJson}}'
+# Per-bank HTTP timeout for a single recall request (#3757). Was hardcoded
+# at 8s in the plugin, which fired on 96.8% of overlord's own-bank recalls
+# and returned the model nothing at all. Plugin default is now 12s; the
+# shared multi-bank deadline (recallParallelDeadlineSeconds, default 10s)
+# is normally the tighter bound, so this is the safety net, not the budget.
+# Exported UNCONDITIONALLY, always carrying a concrete value (#3774 defect
+# class). The plugin resolves DEFAULTS -> settings.json -> claude-code.json ->
+# env, so a knob left unexported — or exported empty, which `_cast_env` turns
+# into a skipped assignment — lets a stale hand-written claude-code.json shadow
+# the shipped default with every test still green.
+export HINDSIGHT_RECALL_REQUEST_TIMEOUT_SECONDS={{hindsightRecallRequestTimeoutSeconds}}
+# Per-bank slot FLOORS inside the recall count cap. The merged multi-bank set
+# is sorted globally by relevance then head-sliced, which is winner-take-all
+# across banks: when both banks return more candidates than the cap, one bank's
+# score distribution can fill every slot and the agent gets a dossier about its
+# operator and none of its own session memory. Floors, not quotas — recall.py
+# bounds the two floors to HALF the cap between them, so the rest is always won
+# on pure relevance. Switchroom ships 2 own / 1 additional against the deployed
+# cap of 6; 0/0 restores the pure head-slice.
+#
+# EXPORTED UNCONDITIONALLY (#3774), like the two #3757 knobs above. The resolved
+# effective value (memory.recall.own_bank_min_slots / .additional_bank_min_slots
+# from the cascade, else the shipped default) is always written, because
+# ~/.hindsight/claude-code.json survives an apply and loads AFTER the plugin's
+# settings.json — a conditional export would let a stale hand-edited value there
+# shadow what switchroom stamps, silently and permanently.
+# Observe `injected_own_bank_count` via `switchroom memory recall-log <agent>`.
+export HINDSIGHT_RECALL_OWN_BANK_MIN_SLOTS={{hindsightRecallOwnBankMinSlots}}
+export HINDSIGHT_RECALL_ADDITIONAL_BANK_MIN_SLOTS={{hindsightRecallAdditionalBankMinSlots}}
 # Recall fact types (memory.recall.types cascade). Switchroom default is
 # world,experience,observation (the synthesized `observation` tier is ON
 # by default, set in the plugin settings.json). Export only when the

package/skills/switchroom-health/SKILL.md

@@ -80,6 +80,23 @@ done
 
 # Check Hindsight MCP reachable
 switchroom memory search "test" --agent assistant 2>/dev/null && echo "OK: memory search works" || echo "WARN: memory search failed"
+
+# Reachable is NOT healthy. A bank that arrived already populated (restore,
+# cross-version upgrade, vector-extension switch) never got its per-bank vector
+# indexes, so recall falls back to a global index + post-filter and silently
+# UNDER-RETURNS — a search still "works", it just returns almost nothing.
+# This fleet ran that way for ~3 months. Check coverage, not just liveness.
+# Exit codes are a contract (src/memory/hindsight-repair.ts): 0 = coverage
+# confirmed complete, 3 = indexes MISSING, 4 = coverage could NOT be confirmed
+# (no summary line, or zero banks scanned — a typo'd --bank looks like this),
+# 1 = the check itself failed. 4 is not "fine": it means nothing was verified.
+switchroom memory repair --all --dry-run >/tmp/sr-cov.txt 2>&1
+case $? in
+  0) echo "OK: vector index coverage complete" ;;
+  3) echo "FAIL: vector index coverage MISSING — recall is under-returning; run 'switchroom memory repair --all'"; tail -2 /tmp/sr-cov.txt ;;
+  4) echo "WARN: coverage NOT verified — the scan confirmed nothing (check the --bank/--schema names, or the hindsight backend)"; tail -2 /tmp/sr-cov.txt ;;
+  *) echo "WARN: coverage check could not run (hindsight < 0.8.5, container down, or docker unavailable)"; tail -2 /tmp/sr-cov.txt ;;
+esac
 ```
 
 ## Step 3 — Interpret and report
@@ -108,6 +125,8 @@ For common failures, give the exact fix:
 | Fleet on the wrong account | `switchroom auth use <label>` (fleet-wide) or `switchroom auth agent override <agent> <label>` (one agent) |
 | Container unhealthy | `docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml restart switchroom-<name>` |
 | Missing .mcp.json | `switchroom apply` (full reconcile + rewrite compose; bring up via `docker compose ... up -d`) or `switchroom agent reconcile <name>` (targeted) |
+| Recall returns few/no results though hindsight is up (esp. after a restore or upgrade) | Missing per-bank vector index coverage. `switchroom memory repair --all --dry-run` to confirm, then `switchroom memory repair --all`. Idempotent, uses `CREATE INDEX CONCURRENTLY`, safe on a live fleet. Requires hindsight ≥ 0.8.5. |
+| `switchroom doctor` shows a red/amber `hindsight version` line | The running backend drifted from the MCP contract switchroom captured. Older → bump the pinned image (`switchroom memory --update`). Newer → re-capture `tests/fixtures/hindsight-tools-list.snapshot.json`; until then any tool added upstream is invisible to agents. |
 | Bot token unresolved | Check vault: `switchroom vault list` |
 | Memory unreachable | Check Hindsight MCP server is running |
 

package/skills/switchroom-status/SKILL.md

@@ -85,7 +85,7 @@ assistant — running (2h 14m)
   model: claude-sonnet-5  collection: general
 
 dev — running (45m)
-  model: claude-opus-4-8  collection: coding
+  model: claude-opus-5  collection: coding
 
 coach — stopped
   last run: 3 days ago

package/telegram-plugin/auth-snapshot-format.ts

@@ -21,6 +21,7 @@
 import type { QuotaResult, QuotaUtilization } from './quota-check.js';
 import { isProbeThin, refillNormalizedUtils } from '../src/auth/quota.js';
 import type { AccountState, LastQuotaSnapshot, ListStateData } from '../src/auth/broker/client.js';
+import { effectiveServingLabel } from '../src/auth/broker/client.js';
 import { maskEmail } from './demo-mask.js';
 import { escapeMarkdown, codeSpanSafe } from './card-format.js';
 
@@ -1152,12 +1153,16 @@ export function buildSnapshotsFromState(
   quotas: QuotaResult[],
 ): AccountSnapshot[] {
   const out: AccountSnapshot[] = [];
+  // `isActive` means SERVING, not pinned — see effectiveServingLabel. Reading
+  // `state.active` here marked the rolled-off pin as "(active)" on the /usage
+  // card after every soft-avoid roll.
+  const serving = effectiveServingLabel(state);
   for (let i = 0; i < state.accounts.length; i++) {
     const acc: AccountState = state.accounts[i]!;
     const q = quotas[i];
     out.push({
       label: acc.label,
-      isActive: acc.label === state.active,
+      isActive: acc.label === serving,
       quota: q && q.ok ? q.data : null,
       quotaError: q && !q.ok ? q.reason : undefined,
       expiresAtMs: acc.expiresAt,
@@ -1206,11 +1211,13 @@ export function reviveLastQuota(snap: LastQuotaSnapshot | null | undefined): Quo
 export function buildSnapshotsFromCachedState(
   state: ListStateData,
 ): AccountSnapshot[] {
+  // SERVING, not pinned — same contract as buildSnapshotsFromState.
+  const serving = effectiveServingLabel(state);
   return state.accounts.map((acc) => {
     const lq = acc.last_quota ?? null;
     return {
       label: acc.label,
-      isActive: acc.label === state.active,
+      isActive: acc.label === serving,
       quota: reviveLastQuota(lq),
       quotaError: lq ? undefined : 'no cached quota (no probe since broker start)',
       expiresAtMs: acc.expiresAt,