switchroom 0.19.23 → 0.19.25

package/examples/switchroom.yaml

@@ -249,7 +249,7 @@ agents:
   #   topic_emoji: "💻"
   #   bot_token: "vault:telegram-dev-bot-token"     # its own bot
   #   extends: coder                      # inherits from inline profile above
-  #   model: claude-opus-4-8              # override defaults.model for this agent
+  #   model: opus                         # override defaults.model for this agent
   #   memory:
   #     collection: coding
   #   cli_args: ["--effort", "high"]      # escape hatch: extra exec claude flags

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.19.23",
+  "version": "0.19.25",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

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/profiles/_shared/dev-protocol.md.hbs

@@ -1,15 +1,14 @@
 ## Development Protocol
 
-Judgement criteria for substantive coding, infra, or debugging work. The long-form playbook — task classification, design-report shape, adversarial-review dispatch, re-review verdict format — is the bundled `dev-protocol` skill; load it before starting.
+Judgement criteria for substantive coding, infra, or debugging work.
 
 This governs HOW delegated work is done, and is **not a license to do it inline**: dispatch first (see Delegation), then these bind the worker.
 
 - **Orient before you build — validate, don't assume.** Root-cause in real source — the repo's files at HEAD, not `dist/`, caches, or generated output. If the evidence contradicts your theory, the plan, or the task description, report the contradiction rather than force-fitting it. Cite `file:line`, commits, PRs.
 - **Infer before you ask.** Most questions are answerable from the code and history. If genuinely unsure, ask ONE question at a time, during planning; act autonomously during execution — make the reasonable call and note the assumption.
 - **Design report before implementation, when the change is large.** Architecturally significant, cross-cutting, or ambiguous-approach work earns an evidence-grounded design report and a red-team pass before code, and ships as focused single-concern PRs.
-- **Branch off fresh main. Scoped tests + lint locally; CI is the full-suite authority. Merge only on CI green.**
+- **Run `git fetch origin` first, then branch off `origin/main`.** Never branch off the working copy as-is: you do not start in the repo you are coding in, and the checkout on disk may be many commits stale. Scoped tests + lint locally; CI is the full-suite authority.
 - **Adversarial review of the diff.** Read every change as an adversary would: what breaks, what's untested, what's inconsistent.
-- **Blockers and mediums block the merge; lows don't** — fix a low inline if it's a one-liner, else file a follow-up issue and merge. Filing is mandatory.
-- **Re-review only a behavioural fix** — a docs/comment/log/test-only commit doesn't earn one. Prefix a fix commit `review-fix:`; two rounds is the cap, and CI enforces it.
+- **Blockers and majors block the merge; lows don't** — file a low as a follow-up issue rather than fixing it now. Filing is mandatory. Fix what blocks, then merge on CI green. Do not count review rounds and do not run a mandatory re-review pass: verifying your own fix is part of making it, not a separate step.
 - **Durable fixes over hack patches. Deterministic mechanisms over model-dependent behaviour** — if code can enforce a guarantee, don't leave it to prompt discipline. **Tests assert outcomes, not just code paths:** one that wouldn't fail on the bug it guards is not a test.
 - **Communicate as you go.** Consolidated messages — one substantive update beats five fragments; never go dark; no foreground watch over 30 seconds (background it); max 15 parallel sub-agents.

package/skills/dev-protocol/SKILL.md

@@ -80,29 +80,36 @@ fixing lows produces a new diff, and a new diff earned another re-review. It
 produced PRs going four rounds where the last round's only finding was an
 inaccurate doc comment. So:
 
-- **Blockers and mediums block the merge.** Fix them.
-- **Lows do NOT block.** Fix a low inline only if it's a genuine one-liner;
-  otherwise **file a follow-up issue and merge**. Filing is mandatory — an
-  unfiled low is a dropped bug, and there is no human team to catch it later.
-- **A re-review is earned only by a behavioural fix.** A docs-, comment-,
-  log-, or test-only fix commit does not earn another pass.
-- **Two rounds is the cap.** Prefix every commit answering a review round
-  `review-fix:` — `scripts/check-review-rounds.mjs` counts them and the
-  `review-rounds` check fails past two, unless a `review-cap-override` label
-  is on the PR.
+- **Blockers and majors block the merge.** Fix them.
+- **Lows do NOT block.** File a low as a follow-up issue rather than fixing it
+  now. Filing is mandatory — an unfiled low is a dropped bug, and there is no
+  human team to catch it later.
+- **Fix what blocks, then merge on CI green.**
+- **Do not count review rounds, and do not run a mandatory re-review pass.**
+  Verifying your own fix is part of making it, not a separate step. Counting
+  rounds was itself a loop driver: it made the review process the subject of
+  the work instead of the change.
 
 If a finding is genuinely invalid, rebut it with evidence in writing; silence
 is not a rebuttal.
 
-When you do re-review, the verdict states per original finding: the finding
-ID, what changed (`file:line` of the fix), whether it fully resolves the
-finding (`RESOLVED` / `PARTIAL` / `REBUTTED` with evidence), and whether the
-fix introduced anything new. A bare "fixed" is not a verdict.
-
 ## 5. Non-obvious pipeline rules
 
 - **CI is the full-suite authority.** Local scoped tests are a fast filter,
   never the merge evidence. Never claim done off a local run alone.
+- **`main` is behind a merge queue: `gh pr merge` ENQUEUES, it does not
+  merge.** The command exits 0 and the PR stays `OPEN`. The queue then re-runs
+  all seven required contexts on its own `gh-readonly-queue/main/pr-<n>-<sha>`
+  ref before landing anything, so "green on the PR" is necessary but not
+  sufficient. Never report a PR merged off that exit code — poll until its
+  state is `MERGED` and the commit is an ancestor of `origin/main`. Two flags
+  to know: `--delete-branch` is **rejected outright** while the queue is on
+  (delete the branch after it lands), and `--subject` is ignored, since the
+  queue composes the merge commit from the PR title plus `(#<pr>)` — so the PR
+  title is the commit title, write it accordingly. An entry stuck in
+  `AWAITING_CHECKS` means a required workflow is not listening for
+  `merge_group`; `.github/MERGE-QUEUE.md` owns that failure mode and the
+  invariants that prevent it.
 - **A test that wouldn't fail on the bug it guards is not a test.** Assert the
   observable outcome, not that the code path executed.
 - **Prefer a deterministic mechanism over prompt discipline.** If a check, a

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-release/SKILL.md

@@ -100,7 +100,8 @@ The tag push triggers `docker-images` and `release`. `release` internally waits
 
 ### Gate B — the release pipeline (`release.yml`)
 - `gh run list --workflow=release.yml --limit 1` — wait for `completed` / `success`. Expect ~25-30 minutes: four native build legs plus the wait on `docker-images`.
-- Its jobs, in order: `guard` (release exists + held out of `latest`) → `build` ×4 → `bundle` → `publish` (attach) → `images-gate` (wait on docker-images) → `npm` → `finalize` (un-draft). A red job anywhere leaves the release a **draft** and npm **unpublished** — which is the correct, recoverable state.
+- Its jobs, in order: `guard` (release exists + held out of `latest`) → `build` ×4 → `bundle` → `publish` (attach) → `images-gate` (wait on docker-images) → `npm` → `finalize` (un-draft) → `images-latest` (promote `:vX.Y.Z` → `:latest`). A red job anywhere leaves the release a **draft** and npm **unpublished** — which is the correct, recoverable state.
+- `images-latest` is why a tag push no longer moves the `:latest` image tag by itself (#3685). If that last job is the one that failed, every other leg shipped and only the image tag lags: re-run it with `gh workflow run promote.yml -f from=vX.Y.Z -f to=latest`. Don't roll the fleet off `:latest` until it is green — `docker manifest inspect ghcr.io/switchroom/switchroom-agent:latest` should report the same digest as `:vX.Y.Z`.
 - Verify the release page actually has assets **and is no longer a draft**:
   ```bash
   gh release view vX.Y.Z -R switchroom/switchroom --json isDraft,assets \

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,