switchroom 0.19.25 → 0.19.27

package/telegram-plugin/uat/assertions.ts

@@ -23,8 +23,15 @@ import type { Driver, ObservedMessage, ObservedReaction } from "./driver.js";
  *
  * Single source of truth; the worker-feed scenario asserts against this,
  * and recall/reply scenarios exclude it via {@link isWorkerFeedMessage}.
+ *
+ * `Workers?` is load-bearing, not cosmetic: the COMBINED (2+ worker) card's
+ * glance line reads `🛠 WORKERS · N running · …`, and `Worker\b` cannot match
+ * inside `WORKERS` (no word boundary between `r` and `S`). Without the optional
+ * `s` the whole 2+ worker surface was invisible to this predicate, so a
+ * recall/reply scenario running with two live workers could latch onto the
+ * combined card as the agent's answer. Found during the #3842 card audit.
  */
-export const WORKER_FEED_RE = /🛠[️]?\s*Worker\b|finished\s*·\s*(?:completed|failed)/i;
+export const WORKER_FEED_RE = /🛠[️]?\s*Workers?\b|finished\s*·\s*(?:completed|failed)/i;
 
 /**
  * True when `m` is a worker-activity-feed message rather than the agent's
@@ -72,6 +79,29 @@ const ACTIVITY_BODY_LINE_RE = /^[→✓↳]/u;
  * Elapsed is `formatFeedElapsed`: `<N>s` under a minute, else `<M>m<SS>s`.
  */
 const LIVENESS_HEADER_L1_RE = /^(?:🤖|🛠[️]?|⚙[️]?)\s+\S/u;
+
+/**
+ * Leading indent chrome a card line can carry: a `U+2800` run, applied by
+ * `WORKER_STEP_INDENT` to the step lines under each worker header on the
+ * combined (2+ worker) card so one worker's steps are visibly separated from
+ * the next worker's.
+ *
+ * Every line-shape matcher below must normalise it away first: Telegram
+ * delivers it verbatim and `String.trim()` does NOT remove it — U+2800 is
+ * category So, not whitespace (that property is exactly why it survives
+ * Telegram's own left-trim; see WORKER_STEP_INDENT). Without this, a worker
+ * card's body lines stop matching `ACTIVITY_BODY_LINE_RE`.
+ *
+ * #3842 removed the whole-card `└─ ` header prefix and the whole-card indent
+ * that #3820/#3821 put on worker cards, so this no longer has to strip a `└─ `.
+ * The step indent is the only nesting a card emits now.
+ */
+const CARD_INDENT_PREFIX_RE = /^\u2800+/u;
+
+/** A card line with its leading step-indent chrome removed, trimmed. */
+export function stripCardNesting(line: string): string {
+  return line.replace(CARD_INDENT_PREFIX_RE, "").trim();
+}
 const LIVENESS_ELAPSED = String.raw`(?:\d+m)?\d+s`;
 const LIVENESS_HEADER_L2_RE = new RegExp(
   `^(?:${LIVENESS_ELAPSED}\\s*·\\s*\\d+\\s+tools?` +
@@ -94,7 +124,7 @@ const LIVENESS_HEADER_L2_RE = new RegExp(
 export function isLivenessCardMessage(m: ObservedMessage): boolean {
   const lines = m.text
     .split("\n")
-    .map((l) => l.trim())
+    .map((l) => stripCardNesting(l))
     .filter((l) => l.length > 0);
   if (lines.length < 2) return false;
   if (!LIVENESS_HEADER_L1_RE.test(lines[0])) return false;
@@ -124,7 +154,7 @@ export function isLivenessCardMessage(m: ObservedMessage): boolean {
 export function isActivityFeedMessage(m: ObservedMessage): boolean {
   const lines = m.text
     .split("\n")
-    .map((l) => l.trim())
+    .map((l) => stripCardNesting(l))
     .filter((l) => l.length > 0);
   if (lines.length === 0) return false;
   if (lines.every((l) => ACTIVITY_FEED_LINE_RE.test(l))) return true;

package/telegram-plugin/uat/feed-matcher.test.ts

@@ -4,6 +4,7 @@ import {
   isFrameworkFallbackText,
   isLivenessCardMessage,
   isWorkerFeedMessage,
+  stripCardNesting,
   WORKER_FEED_RE,
 } from "./assertions.js";
 
@@ -50,6 +51,41 @@ describe("isWorkerFeedMessage", () => {
   it("exposes the regex for scenarios that assert on the feed directly", () => {
     expect(WORKER_FEED_RE.test("🛠 Worker · x")).toBe(true);
   });
+
+  it("matches the FLUSH worker card as Telegram delivers it (#3842)", () => {
+    // #3842 removed the whole-card `└─ ` prefix and whole-card indent that
+    // #3820/#3821 put on worker cards, so the single-worker card arrives flush.
+    const flush = "🛠 WORKER · crawling changelog\n55s · 9 tools · opus 5";
+    expect(isWorkerFeedMessage(feed(flush))).toBe(true);
+  });
+});
+
+describe("#3842 the surviving step indent is transparent to the matchers", () => {
+  it("classifies a flush agent-shaped worker card as the liveness card, not an answer", () => {
+    const flush =
+      "🛠 WORKER · crawl\n12s · 3 tools\n✓ Reading CLAUDE.md\n→ Searching memory";
+    expect(isLivenessCardMessage(feed(flush))).toBe(true);
+    expect(isActivityFeedMessage(feed(flush))).toBe(true);
+  });
+
+  it("classifies a combined card whose step lines carry WORKER_STEP_INDENT", () => {
+    // The one indent that survives #3842: step lines under a worker row header
+    // on the 2+ worker card. `String.trim()` does NOT remove U+2800 (category
+    // So, not whitespace), so the matchers must normalise it explicitly or a
+    // recall/reply scenario latches onto the combined card as an answer.
+    const combined =
+      "🛠 WORKERS · 2 running · oldest 55s · 13 tools\n" +
+      "1. crawl · 55s · 9 tools\n⠀⠀⠀✓ Reading CLAUDE.md\n⠀⠀⠀→ Searching memory";
+    expect(isWorkerFeedMessage(feed(combined))).toBe(true);
+  });
+
+  it("strips the step indent and leaves ordinary prose alone", () => {
+    expect(stripCardNesting("⠀⠀⠀→ Searching memory")).toBe("→ Searching memory");
+    expect(stripCardNesting("🛠 WORKER · crawl")).toBe("🛠 WORKER · crawl");
+    expect(stripCardNesting("on it, pulling the logs now")).toBe(
+      "on it, pulling the logs now",
+    );
+  });
 });
 
 describe("isActivityFeedMessage", () => {

package/telegram-plugin/uat/scenarios/jtbd-liveness-narration-channel.test.ts

@@ -11,7 +11,11 @@
 
 import { describe, expect, it } from "vitest";
 import { spinUp } from "../harness.js";
-import { isActivityFeedMessage, isFrameworkFallbackText } from "../assertions.js";
+import {
+  isActivityFeedMessage,
+  isFrameworkFallbackText,
+  stripCardNesting,
+} from "../assertions.js";
 import type { ObservedMessage } from "../driver.js";
 
 const AGENT = "test-harness";
@@ -30,7 +34,10 @@ const NARRATED_WORK_PROMPT =
 function narratedBodyLines(text: string): string[] {
   return text
     .split("\n")
-    .map((l) => l.trim())
+    // strip the #3820 subordinate-card nesting (`└─ ` / U+2800 indent) first —
+    // `trim()` removes neither, and a worker card's header/body lines would
+    // otherwise read as model narration
+    .map((l) => stripCardNesting(l))
     .filter((l) => l.length > 0)
     .map((l) => l.replace(/^[→✓↳]+\s*/u, "").trim())
     .filter(

package/telegram-plugin/uat/scenarios/jtbd-liveness-narration-dm.test.ts

@@ -17,7 +17,11 @@
 
 import { describe, expect, it } from "vitest";
 import { spinUp } from "../harness.js";
-import { isActivityFeedMessage, isFrameworkFallbackText } from "../assertions.js";
+import {
+  isActivityFeedMessage,
+  isFrameworkFallbackText,
+  stripCardNesting,
+} from "../assertions.js";
 import type { ObservedMessage } from "../driver.js";
 
 /**
@@ -30,7 +34,10 @@ import type { ObservedMessage } from "../driver.js";
 function narratedBodyLines(text: string): string[] {
   return text
     .split("\n")
-    .map((l) => l.trim())
+    // strip the #3820 subordinate-card nesting (`└─ ` / U+2800 indent) first —
+    // `trim()` removes neither, and a worker card's header/body lines would
+    // otherwise read as model narration
+    .map((l) => stripCardNesting(l))
     .filter((l) => l.length > 0)
     // strip glyphs so a `→ Working…` placeholder compares as `Working…`
     .map((l) => l.replace(/^[→✓↳]+\s*/u, "").trim())

package/telegram-plugin/worker-activity-feed.ts

@@ -53,9 +53,9 @@ import {
   cleanWorkerResultParagraph,
   stripMarkdown,
   truncate,
-  COLLAPSE_SAFE_SEPARATOR,
 } from './card-format.js'
 import { WORKER_HISTORY_MAX } from './status-no-truncate.js'
+import { renderCardTitleLine } from './card-layout.js'
 import {
   renderStatusCard,
   formatStepSuffix,
@@ -126,6 +126,49 @@ export interface WorkerActivityView {
   model?: string
 }
 
+/**
+ * Out-of-band metadata about ONE feed edit, handed to the transport adapter
+ * alongside the Bot API arguments (switchroom#3848).
+ *
+ * Deliberately a SEPARATE parameter rather than a field on `opts`: `opts` is
+ * forwarded verbatim to `editMessageText` and therefore onto the wire, and
+ * `outbound-class.ts` exists precisely so a priority signal never has to be
+ * smuggled into an outbound Bot API payload.
+ */
+export interface WorkerFeedEditMeta {
+  /**
+   * True when this edit paints the card's FINAL state — the last worker's
+   * terminal recap, or the "superseded" note on a rotated-out message. False
+   * for every intermediate / liveness repaint.
+   */
+  terminal: boolean
+}
+
+/**
+ * The send-gate priority class a worker-feed edit must carry.
+ *
+ * Intermediate repaints are `cosmetic`: dropping one costs nothing, because
+ * the next render carries full state, and holding them to the fuse's tight
+ * cosmetic ceilings (4/message/60s, 6/chat/60s) is what stops the feed
+ * earning a per-chat flood ban (#3847).
+ *
+ * A TERMINAL frame is `useful` (#3848). It is the last frame the operator
+ * ever reads for that card and nothing newer is coming to repaint it, so
+ * classing it cosmetic made the one frame carrying the finished state
+ * compete in — and get shed from — the same starved budget as a heartbeat.
+ * `useful` rather than `critical` matches the activity-summary finalize in
+ * `gateway/narrative-lane.ts`: it may be DEFERRED under pressure, but it is
+ * not shed, and it does not spend the per-chat reply reservation that keeps
+ * the operator's real answer unstarvable.
+ *
+ * Exported so the mapping is unit-testable; `gateway.ts` only calls it.
+ */
+export function workerFeedEditPriorityClass(
+  meta?: WorkerFeedEditMeta,
+): 'useful' | 'cosmetic' {
+  return meta?.terminal === true ? 'useful' : 'cosmetic'
+}
+
 export interface BotApiForWorkerFeed {
   sendMessage(
     chatId: string,
@@ -137,6 +180,12 @@ export interface BotApiForWorkerFeed {
     messageId: number,
     text: string,
     opts?: Record<string, unknown>,
+    /**
+     * Out-of-band edit metadata (NOT part of the Bot API payload). The
+     * gateway adapter maps `terminal` to the send-gate priority class via
+     * {@link workerFeedEditPriorityClass}.
+     */
+    meta?: WorkerFeedEditMeta,
   ): Promise<unknown>
 }
 
@@ -164,22 +213,32 @@ export function repeatCountOf(line: string): number {
 
 /**
  * Thin adapter over the unified `renderStatusCard` primitive (emoji 🛠, label
- * 'Worker'): builds the header, passes raw narrative steps (the primitive runs
- * stripMarkdown → collapse ws → clip → escape per line), and on finish passes
- * the cleaned result paragraph as the `result` block.
+ * 'WORKER'): builds the header, passes raw narrative steps
+ * (the primitive runs stripMarkdown → collapse ws → clip → escape per line),
+ * and on finish passes the cleaned result paragraph as the `result` block.
  *
  * Layout (running):
- *   🛠 <b>Worker</b> · <i>{description}</i>
- *   <i>{elapsed} · {n} tools</i>
- *   <s><i>✓ {earlier step}</i></s>
- *   <b>→ {newest step}</b>
+ *   🛠 **WORKER** · _{description}_
+ *   _{elapsed} · {n} tools_
+ *   ~~_✓ {earlier step}_~~
+ *   **→ {newest step}**
  *
  * Layout (finished): the feed renders all-done, then a rule + cleaned result:
- *   🛠 <b>Worker</b> · <i>{description}</i>
- *   <i>done · {n} tools · {elapsed}</i>
- *   <s><i>✓ {step}</i></s>
+ *   🛠 **WORKER** · _{description}_
+ *   _done · {n} tools · {elapsed}_
+ *   ~~_✓ {step}_~~
  *   ─────
- *   ✅ <i>{cleaned result paragraph}</i>
+ *   ✅ _{cleaned result paragraph}_
+ *
+ * FLUSH (#3842): this card sits at the left margin. #3820/#3821 indented the
+ * whole block and prefixed line 1 with `└─ ` to mark it subordinate to the 🤖
+ * agent card; that was reverted because it burned a level of horizontal phone
+ * width and because this card does not always sit below the agent card, so a
+ * card-level subordination marker asserts a relationship that is not always
+ * true. The remaining type cue is line 1: the 🛠 emoji plus the caps `WORKER`
+ * label against the agent card's 🤖 `Agent`. Keep that pair — with identical
+ * step text and stats the two cards' BODY lines can now coincide byte for
+ * byte, so line 1 is doing all of the distinguishing work.
  */
 export function renderWorkerActivity(v: WorkerActivityView, liveSuffix = ''): string {
   const desc = truncate(stripMarkdown(v.description).trim() || 'background task', DESC_MAX)
@@ -201,7 +260,9 @@ export function renderWorkerActivity(v: WorkerActivityView, liveSuffix = ''): st
 
   const header: Parameters<typeof renderStatusCard>[0]['header'] = {
     emoji: '🛠',
-    label: 'Worker',
+    // Caps (#3820, issue option 4): `WORKER` against the agent card's `Agent`
+    // is a high-contrast type label, not a same-shaped word one letter apart.
+    label: 'WORKER',
     description: desc,
     elapsedMs: v.elapsedMs,
     toolCount: v.toolCount,
@@ -225,9 +286,6 @@ export function renderWorkerActivity(v: WorkerActivityView, liveSuffix = ''): st
     if (text.length > 0) result = { emoji: v.state === 'done' ? '✅' : '⚠️', text }
   }
 
-  // `renderStatusCard` always returns content when a header is supplied. When
-  // running with no steps it shows just the header — append a "starting…" line
-  // for parity with the prior behaviour.
   const card = renderStatusCard({
     header,
     steps,
@@ -237,19 +295,18 @@ export function renderWorkerActivity(v: WorkerActivityView, liveSuffix = ''): st
     // Lone-worker card: window to the w=1 point of Ken's curve (6) so it shows
     // the full recent trail, not the 5-line agent-card default (#3349).
     historyWindow: workerHistoryDepth(1),
+    // A just-dispatched worker has no narrative yet. The placeholder is a normal
+    // BODY line of the shared spec now (#3846): it used to be concatenated onto
+    // this function's return value, which put a user-visible card line outside
+    // the primitive that owns hard-break stacking, the collapse-safe separator
+    // and the char budget, and made the seam the one boundary that could mash in
+    // Telegram's pinned bar. Only while RUNNING — a finished worker with no
+    // steps must not read as "starting…".
+    emptyPlaceholder: finished ? undefined : '_starting…_',
   })
   if (card == null) {
     // Unreachable (header always present) — defensive.
-    return `🛠 **Worker** · _starting…_`
-  }
-  if (!finished && steps.length === 0) {
-    // Header-only running render → append the starting placeholder with a GFM
-    // hard break (`  \n`) so it stacks under the header instead of collapsing
-    // onto the header line in the rich-message renderer (matches stackCardLines).
-    // The collapse separator is carried here too (#3666) — this card is pinned,
-    // and a hand-rolled seam would be the one boundary that still mashed in
-    // Telegram's pinned bar.
-    return `${card}${COLLAPSE_SAFE_SEPARATOR}  \n_starting…_`
+    return renderCardTitleLine('🛠', 'WORKER', 'starting…')
   }
   return card
 }
@@ -596,9 +653,21 @@ const COOLDOWN_JITTER_MS = 500
  * rows and reads like a stuck worker. A single best-effort edit collapses it to
  * an honest "moved" note — issued once per rotation (≥ cap interval), never per
  * tick, so it adds no edit churn / pin storm. Plain voice, no em dash.
+ *
+ * Exported so the card-preview harness (`scripts/card-previews.ts`) renders the
+ * real string rather than a copy that can drift from it.
+ *
+ * DELIBERATELY still a constant, not a card render (#3846). It shows no live
+ * state — no elapsed, no tool count, no steps — so there is nothing for a
+ * renderer to compose and no rolling window or char budget to enforce; routing
+ * it through `renderStatusCard` would mean inventing a state to render. What it
+ * DOES share with every other card is its type chrome, so line 1 comes from the
+ * one title composer (`renderCardTitleLine`): if the 🛠 / **WORKER** convention
+ * ever changes, this notice moves with it instead of being the one stale card.
  */
-const WORKER_CARD_SUPERSEDED_BODY =
-  '🛠 **Worker** · _continued_\n\n_Live progress moved to a fresh card to stay pinned._'
+export const WORKER_CARD_SUPERSEDED_BODY =
+  `${renderCardTitleLine('🛠', 'WORKER', 'continued')}\n\n` +
+  '_Live progress moved to a fresh card to stay pinned._'
 
 function extractRetryAfterSecs(err: unknown): number | null {
   if (err == null || typeof err !== 'object') return null
@@ -1176,7 +1245,11 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
     }
 
     try {
-      const res = await opts.bot.editMessageText(g.chatId, g.messageId, body, sendOptsFor(g))
+      // #3848: tell the transport whether this is the card's LAST frame. A
+      // terminal recap must not be shed with the heartbeat repaints.
+      const res = await opts.bot.editMessageText(
+        g.chatId, g.messageId, body, sendOptsFor(g), { terminal: isTerminal },
+      )
       // Shed honesty (#3084): a cosmetic edit the gate shed resolves the
       // distinguishable SEND_GATE_SHED sentinel (NOT a bare `undefined`, which
       // the gate reserves for a benign no-op drop whose payload IS on screen).
@@ -1465,8 +1538,14 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
         // doesn't sit frozen showing live-styled rows (mistakable for a stuck
         // worker). ONE best-effort edit per rotation (≥ cap interval), fired
         // off-chain and swallowing errors — never per-tick, never a burst.
+        // #3848: terminal — this is the retired message's LAST frame, and it
+        // fires at most once per `groupMessageLifetimeCapMs`, so promoting it
+        // out of the cosmetic budget costs nothing and stops the retired card
+        // being left frozen showing live-styled rows.
         void opts.bot
-          .editMessageText(g.chatId, retiredId, WORKER_CARD_SUPERSEDED_BODY, sendOptsFor(g))
+          .editMessageText(
+            g.chatId, retiredId, WORKER_CARD_SUPERSEDED_BODY, sendOptsFor(g), { terminal: true },
+          )
           .catch(() => {})
       }
 

package/vendor/hindsight-memory/CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md — vendor/hindsight-memory
+
+**This directory is a VENDORED SNAPSHOT of the hindsight-memory plugin. It is
+not the specification, and it is not what runs.** Treat it as evidence about
+one commit of the implementation, nothing more.
+
+The load-bearing copy of this rule is the repo-root `CLAUDE.md`
+("Third-party docs — the official site is the spec"); nothing auto-loads a
+subdirectory `CLAUDE.md`, so this file only reaches an agent that opens it.
+
+## Where the truth is
+
+1. **Official docs site** — <https://hindsight.vectorize.io/>. Curation and
+   the memory-unit endpoints: `/developer/api/memories`. Also
+   `/developer/api/retain`, `/developer/api/recall`,
+   `/developer/observations`, `/developer/configuration`, index at
+   `/api-reference`. (`/developer/` itself has no index page — it 404s.)
+2. **context7** — prefer `/websites/hindsight_vectorize_io` (the docs site)
+   over `/vectorize-io/hindsight` (the OSS repo).
+3. **This tree** — last, and only for "what does the code here actually do".
+
+Not finding something here is not evidence it doesn't exist. Search the docs
+before you tell anyone a knob, endpoint or config path is unsupported.
+
+## Trap: `settings.json` here is NOT what switchroom installs
+
+`installHindsightPlugin` (`src/agents/scaffold.ts`) copies this tree into each
+agent's `.claude/plugins/hindsight-memory/` and then **stamps switchroom's own
+overrides over `settings.json`** — additional banks, the retain cadence knobs,
+and the recall types. Concretely, this file has
+`"recallTypes": ["world", "experience"]` while switchroom writes
+`["world", "experience", "observation"]` (`scaffold.ts:3449` as of writing;
+line anchors drift — grep `settings.recallTypes`).
+
+So reading the vendored `settings.json` to learn live behaviour is actively
+misleading. Read the override site in `scaffold.ts`, or the deployed
+`~/.switchroom/agents/<name>/.claude/plugins/hindsight-memory/settings.json`.
+
+## Editing
+
+Don't hand-edit vendored upstream files without a reason (repo-root
+`CLAUDE.md` § Secrets & safety rails). This file and switchroom's local
+patches are the exceptions; changes here ship to every agent on the next
+`apply`/reconcile, and the Python under `scripts/` is gated by the required
+`python-ok` check (`python3 -m unittest discover` in `scripts`).

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

@@ -46,6 +46,20 @@ DEFAULTS = {
     # cap of 6 its fleet actually deploys.
     "recallOwnBankMinSlots": 0,
     "recallAdditionalBankMinSlots": 0,
+    # Switchroom #3837: absolute floor on a result's engine relevance score
+    # (`scores.final`) for it to be injected. 0.0 (default) DISABLES the floor
+    # — nothing is dropped and the injected set is byte-identical to the
+    # pre-#3837 behaviour. `recallMinScoreScope` decides which turns a
+    # non-zero floor binds on: "degraded" (default) = only turns where the
+    # agent's OWN bank timed out or was unreachable, which is the population
+    # where a below-floor score actually predicts noise (98.4% of degraded
+    # rows have a best injected score under 0.01, against 28.4% of healthy
+    # ones); "all" = every turn, which #3761's replay says empties ~28% of
+    # HEALTHY recalls at 0.01 and is not recommended as a fleet default. See
+    # the design note above `_filter_by_min_score` in recall.py. Env:
+    # HINDSIGHT_RECALL_MIN_SCORE / HINDSIGHT_RECALL_MIN_SCORE_SCOPE.
+    "recallMinScore": 0.0,
+    "recallMinScoreScope": "degraded",
     "recallTypes": ["world", "experience"],
     # Switchroom-local: when True (default; Ken-approved ON) recall biases
     # toward synthesized `observation`-tier facts. Escape hatch: pin off via
@@ -324,6 +338,12 @@ ENV_OVERRIDES = {
     # .additional_bank_min_slots (cascading through defaults). 0 = off.
     "HINDSIGHT_RECALL_OWN_BANK_MIN_SLOTS": ("recallOwnBankMinSlots", int),
     "HINDSIGHT_RECALL_ADDITIONAL_BANK_MIN_SLOTS": ("recallAdditionalBankMinSlots", int),
+    # Switchroom #3837: absolute `scores.final` floor + the population it binds
+    # on. Set by start.sh from agents.<name>.memory.recall.min_score /
+    # .min_score_scope (cascading through defaults), exported only when the
+    # operator opted in. 0.0 = off (the default, and the shipped behaviour).
+    "HINDSIGHT_RECALL_MIN_SCORE": ("recallMinScore", float),
+    "HINDSIGHT_RECALL_MIN_SCORE_SCOPE": ("recallMinScoreScope", str),
     # Switchroom-local: recall fact types (comma-separated). Set by start.sh
     # from agents.<name>.memory.recall.types only when the operator overrode
     # the switchroom default (world,experience,observation) — i.e. the
@@ -333,6 +353,19 @@ ENV_OVERRIDES = {
     # from agents.<name>.memory.recall.skip_trivial only on override; the
     # switchroom default is on (recall.py falls back to True).
     "HINDSIGHT_RECALL_SKIP_TRIVIAL": ("recallSkipTrivial", bool),
+    # Switchroom #3841: the last three recall settings that had a config key but
+    # no env channel at all, so switchroom.yaml could not reach them and a
+    # hand-edit of the installed plugin did not survive `switchroom apply`. Set
+    # by start.sh from agents.<name>.memory.recall.prefer_observations / .roles /
+    # .prompt_preamble (cascading through defaults), always exported at their
+    # existing effective values, so an operator who sets none of them sees no
+    # change. The other #3841 knobs (budget, max_tokens, context_turns,
+    # max_query_chars, transcript_tail_bytes, tags, tags_match, tag_groups,
+    # tag_weights, additional_bank_filters, transcript_fallback, parallel)
+    # already had entries in this table and only needed the yaml surface.
+    "HINDSIGHT_RECALL_PREFER_OBSERVATIONS": ("recallPreferObservations", bool),
+    "HINDSIGHT_RECALL_ROLES": ("recallRoles", list),
+    "HINDSIGHT_RECALL_PROMPT_PREAMBLE": ("recallPromptPreamble", str),
     # Switchroom #2848 Stage B: directive-capture nudge on/off. Set by
     # start.sh from agents.<name>.memory.directive_capture_nudge only when
     # the operator overrode it; the switchroom default is on (settings.json