switchroom 0.19.24 → 0.19.26

package/profiles/_base/cron-session.sh.hbs

@@ -74,6 +74,12 @@ export CLAUDE_CONFIG_DIR="$CRON_CONFIG_DIR"
 # (honouring any value already in the env). See start.sh.hbs for rationale.
 export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH="${CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH:-2}"
 
+# Pin sub-agent fan-out width below the CLI's own default of 20 — the
+# deterministic half of the dev-protocol's "max 15 parallel sub-agents".
+# Normally inherited from start.sh's env; set here as a belt-and-braces default
+# (honouring any value already in the env). See start.sh.hbs for rationale.
+export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS="${CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS:-15}"
+
 # Defer the (now full) MCP schema set via tool-search so the cron session keeps
 # its low-context cost — the heavy servers load on demand; switchroom-telegram
 # + hindsight stay alwaysLoad. Normally inherited from start.sh's env; set here

package/profiles/_base/start.sh.hbs

@@ -685,10 +685,19 @@ unset CLAUDE_CODE_OAUTH_TOKEN
 # out its own sub-agents), so we restore the pre-2.1.217 behaviour. Depth 2
 # = main → sub-agent → grandchild, which covers the one extra level the
 # fleet actually uses; there is no evidence of deeper nesting, so we don't
-# raise it further. (The companion 2.1.217 change — CLAUDE_CODE_MAX_
-# CONCURRENT_SUBAGENTS defaulting to 20 — is already compatible: our fleet
-# self-caps at 15 parallel sub-agents, so the 20 default is left untouched.)
+# raise it further.
 export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH="${CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH:-2}"
+# Fan-out width. The CLI's own default is 20 (2.1.217's companion change);
+# switchroom deliberately pins it LOWER, at 15, because the dev-protocol
+# fragment every agent boots with ("max 15 parallel sub-agents",
+# profiles/_shared/dev-protocol.md.hbs) is prompt text — a model can ignore
+# it, and nothing else caps the width. This export is the deterministic
+# mechanism behind that sentence: past 15 the CLI refuses the launch instead
+# of relying on the agent to count. 15 rather than 20 keeps a fully fanned-out
+# worker inside the per-container CPU/RAM envelope and leaves headroom for the
+# nested level that SPAWN_DEPTH=2 above permits. Override-able for a one-off
+# wide job; raise both this and the fragment together or they disagree.
+export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS="${CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS:-15}"
 export TELEGRAM_STATE_DIR="{{agentDir}}/telegram"
 # SWITCHROOM_AGENT_NAME is the canonical "which agent am I" identifier the
 # telegram-plugin reads to detect self-restart commands. We can't rely on
@@ -737,19 +746,85 @@ 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}}
+# Recall latency envelope (memory.recall.parallel_deadline_seconds /
+# .request_timeout_seconds cascade). Exported UNCONDITIONALLY, unlike the
+# override-only knobs above, and that is deliberate.
+#
+# The plugin's config load order is: built-in defaults -> plugin settings.json
+# -> ~/.hindsight/claude-code.json -> environment. Switchroom stamps these two
+# into settings.json as well, but claude-code.json sits BETWEEN the two and
+# SURVIVES `switchroom apply`. A hand-written value left in that file (the
+# documented pre-promotion workaround — the live fleet had exactly this,
+# pinning recallParallelDeadlineSeconds to a stale 16) would therefore silently
+# defeat a settings.json-only stamp. Env is the top of the chain, so exporting
+# the resolved value unconditionally is what actually makes switchroom.yaml
+# authoritative. Both values come from the same resolver
+# (src/setup/hindsight-recall-tunables.ts) fed the same CASCADED agent config —
+# scaffold/reconcile thread their resolved `agentConfig` into
+# installHindsightPlugin instead of letting it re-derive — so the two channels
+# cannot diverge. Sharing a resolver was NOT enough on its own: the stamp used
+# to re-derive from `agents[name] ?? {}`, and `{}` carries no `extends`, so it
+# silently dropped the profile tier on one side only.
+# Pinned by tests/scaffold.recall-envelope-carrier.test.ts, which asserts on the
+# RENDERED start.sh — a typo'd handlebars variable renders empty rather than
+# failing, and an empty export hands authority straight back to claude-code.json.
+#
+# The third knob in this envelope — the UserPromptSubmit hook ceiling — has no
+# env channel at all (Claude Code does not expand env in hooks.json `timeout`),
+# so it is stamped into the deployed hooks/hooks.json instead.
+export HINDSIGHT_RECALL_PARALLEL_DEADLINE_SECONDS={{hindsightRecallParallelDeadlineSeconds}}
+# 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
@@ -1733,7 +1808,7 @@ esac
 # tells the operator once.
 #
 # NB: the CONFIGURED default resolution is untouched (#3186 constraint) —
-# the fleet `thinking_effort: low` pin (see #1978 /
+# the configured `thinking_effort` (see #1978 /
 # src/config/thinking-effort-risk.ts) resolves exactly as before.
 _EFFECTIVE_EFFORT={{#if thinkingEffort}}'{{thinkingEffort}}'{{else}}''{{/if}}
 if [ -f "{{agentDir}}/.session-effort" ]; then

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,