switchroom 0.17.10 → 0.18.6

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

@@ -220,6 +220,28 @@ interface WorkerHandle {
   chain: Promise<void>
   /** Last view rendered into the message (drives the heartbeat re-render). */
   lastView: WorkerActivityView | null
+  /**
+   * A terminal (`finish`) view whose edit could not land yet — most often
+   * because a 429 cooldown was in effect when `doFinish` ran. The heartbeat
+   * re-drives `doFinish` with this view once the cooldown expires so a
+   * transport hiccup can't leave the card stuck on its last running render
+   * ("worker done, card says running"). Cleared on a successful terminal
+   * edit, on a permanent failure (message gone), or when the handle is
+   * deleted. Null when no finalize is pending.
+   */
+  pendingFinish: WorkerActivityView | null
+  /**
+   * Latched in `doFinish` before the terminal edit. A late watcher
+   * `onProgress` tick that arrives after `finish()` queued its chain (but
+   * before the `.finally(handles.delete)` microtask drains) must NOT
+   * resurrect the handle and paint a fresh `running` message on an
+   * already-finalized worker. The heartbeat's orphan-paint guard
+   * (`if (!handles.has(h.agentId)) continue`) only covers the heartbeat
+   * tick — this flag covers the `update` entry point. Set synchronously
+   * inside `doFinish` (runs on the chain), checked synchronously in
+   * `update` before handle creation.
+   */
+  finished: boolean
   /**
    * Wall-clock ms the worker was dispatched, derived from `now - view.elapsedMs`
    * on the first update. The heartbeat computes a live elapsed from this so the
@@ -246,6 +268,47 @@ function extractRetryAfterSecs(err: unknown): number | null {
   return null
 }
 
+/**
+ * Classify a card-edit transport error. Card edits are a best-effort
+ * liveness surface — a recoverable hiccup must never freeze the card, and
+ * a permanent failure must never log a scary warning for something with
+ * nothing to update.
+ *
+ *   'not_modified' — content identical to what's already shown. The card
+ *     already reads correctly; treat as SUCCESS (no retry, no warning).
+ *   'rate_limited' — 429 with retry_after. Back off; the heartbeat re-drives
+ *     the edit after cooldown (running renders + deferred terminal edits).
+ *   'gone'         — message/chat deleted or edit window expired. Nothing to
+ *     update; drop the handle silently (no warning — there is no card).
+ *   'transient'    — anything else (network blip, 5xx). Retry on the next
+ *     heartbeat tick; don't spam stderr.
+ */
+type EditOutcome = 'not_modified' | 'rate_limited' | 'gone' | 'transient'
+function classifyEditError(err: unknown): EditOutcome {
+  const retryAfter = extractRetryAfterSecs(err)
+  if (retryAfter != null) return 'rate_limited'
+  const desc =
+    err instanceof Error ? err.message : err != null && typeof err === 'object' && 'description' in err
+      ? String((err as { description?: unknown }).description)
+      : String(err)
+  const low = desc.toLowerCase()
+  // "message is not modified" / "message was not modified" — Telegram's
+  // identical-content signal. The card already shows the right thing.
+  if (low.includes('not modified')) return 'not_modified'
+  // Message or chat no longer exists, or the edit window (48h) has closed.
+  // "message to edit not found" / "message to delete not found" / "chat not
+  // found" / "message can't be edited". Nothing to update.
+  if (
+    low.includes('not found') ||
+    low.includes("can't be edited") ||
+    low.includes('cannot be edited') ||
+    low.includes('not enough rights')
+  ) {
+    return 'gone'
+  }
+  return 'transient'
+}
+
 /**
  * Manager owning one live message per background worker. Keyed by jsonl
  * agent id. The gateway calls `update` on each watcher activity cue and
@@ -294,6 +357,28 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
     })
   const clearIntervalFn = opts.clearInterval ?? ((handle: unknown) => clearInterval(handle as ReturnType<typeof setInterval>))
   const handles = new Map<string, WorkerHandle>()
+  /**
+   * Agent ids that have been finalized (`doFinish` latched). Survives handle
+   * deletion so a LATE watcher `onProgress` tick — which can arrive after
+   * `finish()`'s chain has fully settled and the handle was deleted — cannot
+   * resurrect a fresh handle and paint a running card on a worker that is
+   * already done. The per-handle `finished` flag only covers the narrow
+   * window between latch and delete; this set is the durable gate. A late
+   * tick arrives within seconds of finish (watcher poll cadence), so the set
+   * only needs to cover recent finalizations — capped at FINALIZED_CAP and
+   * trimmed FIFO to stay bounded across a long gateway lifetime.
+   */
+  const finalized = new Set<string>()
+  const FINALIZED_CAP = 256
+  function markFinalized(agentId: string): void {
+    if (finalized.has(agentId)) return
+    finalized.add(agentId)
+    if (finalized.size > FINALIZED_CAP) {
+      // Map-free FIFO trim: Set iterates in insertion order; drop the oldest.
+      const oldest = finalized.values().next().value
+      if (oldest != null) finalized.delete(oldest)
+    }
+  }
   let heartbeatTimer: unknown = null
 
   function sendOptsFor(h: WorkerHandle): Record<string, unknown> {
@@ -384,39 +469,99 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
           `thread=${h.threadId ?? '-'} msgId=${h.messageId} bytes=${body.length}`,
       )
     } catch (err) {
-      noteRateLimited(h, err, 'edit')
-      // Stale message_id (manually deleted / edit window gone). Re-post
-      // on the next tick rather than now, so we don't double-down inside
-      // a cooldown.
-      log(`worker-feed: edit failed, will re-post: ${(err as Error).message}`)
-      h.messageId = null
-      h.lastBody = null
+      const outcome = classifyEditError(err)
+      if (outcome === 'rate_limited') {
+        noteRateLimited(h, err, 'edit')
+        return
+      }
+      if (outcome === 'not_modified') {
+        // Card already shows this body — record it as landed and move on.
+        h.lastBody = body
+        h.lastEditAt = nowFn()
+        return
+      }
+      if (outcome === 'gone') {
+        // Message/chat deleted or edit window closed — there is no card to
+        // update. Drop the handle silently; a fresh first-paint on the next
+        // running tick re-establishes one if the worker is still active. No
+        // warning: "no card" is not a liveness-logic error.
+        h.messageId = null
+        h.lastBody = null
+        return
+      }
+      // 'transient' — network blip / 5xx. Leave the handle intact; the
+      // heartbeat re-attempts on its next tick. Log at debug, not stderr-warn:
+      // a transport hiccup on a best-effort card is not "shit code", it's a
+      // retryable blip the framework rides out deterministically.
+      log(`worker-feed: edit transient error agent=${h.agentId}: ${(err as Error).message}`)
     }
   }
 
   async function doFinish(h: WorkerHandle, view: WorkerActivityView): Promise<void> {
+    // Latch FIRST, before any early return. A `running`-cue tick arriving
+    // after `finish()` queued this chain (but before its `.finally(delete)`
+    // drains) would otherwise resurrect a handle via `update()` and paint a
+    // fresh running message on a finalized worker. Setting this synchronously
+    // on the chain — ahead of the cooldown/no-message guards — makes the
+    // gate in `update()` authoritative regardless of which guard path runs.
+    // The durable `finalized` set survives the subsequent handle deletion so
+    // a tick arriving AFTER the full settle still can't resurrect.
+    h.finished = true
+    markFinalized(h.agentId)
     // No message ever posted → nothing to finalize. The worker's result
     // reaches the user via the handback reply; a bare "done" recap with
     // no preceding activity would be noise.
-    if (h.messageId == null) return
+    if (h.messageId == null) {
+      h.pendingFinish = null
+      return
+    }
     if (nowFn() < h.cooldownUntil) {
-      // Honour the flood-wait; a terminal edit isn't worth a ban. The
-      // message is left at its last running render — stale but harmless.
+      // Honour the flood-wait; a terminal edit isn't worth a ban. But
+      // unlike the prior "stale but harmless" surrender, STAGE the terminal
+      // view so the heartbeat re-drives the finalize edit the instant the
+      // cooldown expires — a transport hiccup can no longer leave a
+      // finished worker's card stuck on its last running render.
+      h.pendingFinish = view
       return
     }
     const body = renderWorkerActivity({ ...view, narrativeLines: h.narrative })
-    if (body === h.lastBody) return
+    if (body === h.lastBody) {
+      h.pendingFinish = null
+      return
+    }
     try {
       await opts.bot.editMessageText(h.chatId, h.messageId, body, sendOptsFor(h))
       h.lastBody = body
       h.lastEditAt = nowFn()
+      h.pendingFinish = null
       log(
         `worker-feed: finish agent=${h.agentId} chat=${h.chatId} ` +
           `thread=${h.threadId ?? '-'} msgId=${h.messageId} state=${view.state} bytes=${body.length}`,
       )
     } catch (err) {
-      noteRateLimited(h, err, 'finish')
-      log(`worker-feed: finish edit failed: ${(err as Error).message}`)
+      const outcome = classifyEditError(err)
+      if (outcome === 'rate_limited') {
+        noteRateLimited(h, err, 'finish')
+        // Re-stage for the heartbeat to re-drive after cooldown.
+        h.pendingFinish = view
+        return
+      }
+      if (outcome === 'not_modified') {
+        // Card already shows the finalized body — terminal edit succeeded.
+        h.lastBody = body
+        h.lastEditAt = nowFn()
+        h.pendingFinish = null
+        return
+      }
+      if (outcome === 'gone') {
+        // Message/chat gone — no card to finalize. Drop silently; the
+        // handback reply carries the result regardless.
+        h.pendingFinish = null
+        return
+      }
+      // 'transient' — re-stage for a heartbeat retry; log at debug.
+      h.pendingFinish = view
+      log(`worker-feed: finish transient error agent=${h.agentId}: ${(err as Error).message}`)
     }
   }
 
@@ -456,6 +601,36 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
       // (which would orphan a card that never finalizes). Restores the
       // structural safety the pre-first-paint `messageId == null` skip gave.
       if (!handles.has(h.agentId)) continue
+
+      // Deferred-finalize re-drive: a terminal edit that hit a 429 cooldown
+      // (or a transient error) was staged on `pendingFinish` by `doFinish`.
+      // Re-drive it once the cooldown has expired so a finished worker's card
+      // can't get stuck on its last running render. This is the deterministic
+      // backstop that replaces the old "stale but harmless" surrender — the
+      // framework owns ALIVE-and-done, wall-clock driven, no model in the loop.
+      // (The handle is still in the map because `finish()`'s `.finally(delete)`
+      // is chained AFTER `doFinish` and won't drain while a re-drive keeps the
+      // chain busy; once the terminal edit lands, `pendingFinish` is cleared
+      // and the `.finally` runs on the next chain settle.)
+      if (h.pendingFinish != null && now >= h.cooldownUntil) {
+        const view = h.pendingFinish
+        h.chain = h.chain
+          .then(() => doFinish(h, view))
+          .catch((err) => {
+            log(`worker-feed: heartbeat finalize re-drive error ${h.agentId}: ${(err as Error).message}`)
+          })
+          .finally(() => {
+            // Mirror `finish()`'s teardown: once the re-driven `doFinish`
+            // clears `pendingFinish` (terminal edit landed OR permanently
+            // failed), drop the handle. If it re-staged (another 429), the
+            // handle survives for the next heartbeat tick to retry.
+            if (handles.get(h.agentId)?.pendingFinish == null) {
+              handles.delete(h.agentId)
+            }
+          })
+        continue
+      }
+
       if (h.lastView == null) continue
       if (h.lastView.state !== 'running') continue
       if (now < h.cooldownUntil) continue
@@ -523,7 +698,19 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
       // No chat to post to (owner DM unconfigured) — don't create a
       // handle that would retry a failing send('') every tick.
       if (chatId.length === 0) return Promise.resolve()
-      let h = handles.get(agentId)
+      // Resurrection guard: a worker that has already been finalized
+      // (`doFinish` latched `finalized`) must not get a fresh running cue.
+      // A late watcher `onProgress` tick can arrive after `finish()`'s chain
+      // has fully settled and the handle was deleted — without this durable
+      // gate the tick would create a brand-new handle and paint a fresh
+      // `running` message on an already-done worker (the card lies). The
+      // heartbeat's orphan-paint guard covers the heartbeat tick only; the
+      // per-handle `finished` flag covers the pre-delete window; this set
+      // covers the post-delete window.
+      if (finalized.has(agentId)) return Promise.resolve()
+      const existing = handles.get(agentId)
+      if (existing?.finished === true) return Promise.resolve()
+      let h = existing
       if (h == null) {
         h = {
           agentId,
@@ -538,6 +725,8 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
           lastView: null,
           dispatchAtMs: null,
           stepStartedAtMs: null,
+          finished: false,
+          pendingFinish: null,
         }
         handles.set(agentId, h)
       }
@@ -556,11 +745,27 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
           log(`worker-feed: finish chain error ${agentId}: ${(err as Error).message}`)
         })
         .finally(() => {
-          handles.delete(agentId)
+          // Only tear down the handle once the terminal edit has actually
+          // landed (or permanently failed). If `doFinish` staged the edit on
+          // `pendingFinish` (a 429 cooldown / transient error was in effect),
+          // the handle must survive so the heartbeat can re-drive the
+          // finalize after cooldown. The heartbeat's re-drive chain ends by
+          // re-entering `doFinish`, which clears `pendingFinish` on success
+          // or permanent-failure — so this `.finally` deletes on the NEXT
+          // chain settle once there is nothing left to finalize. Without this
+          // guard, the `.finally` would delete the handle (and its staged
+          // pendingFinish) immediately after the first staged doFinish,
+          // stranding the card on its last running render.
+          if (handles.get(agentId)?.pendingFinish == null) {
+            handles.delete(agentId)
+          }
         })
       return h.chain
     },
     drop(agentId) {
+      // A dropped worker is also done — mark finalized so a late watcher
+      // tick can't resurrect a running card on it (same gate as `finish`).
+      markFinalized(agentId)
       handles.delete(agentId)
     },
     heartbeatTick,

package/telegram-plugin/worktree-watch-cwds.ts

@@ -1,29 +1,52 @@
 /**
  * Ownership filter for the worktree-isolated cwds the subagent-watcher should
  * additionally watch (deterministic-turn-liveness.md Known Gap 2 + the #2893
- * ownership-predicate review fix).
+ * ownership-predicate review fix + the #1116 / #2893 durable-identity fix).
  *
  * A sub-agent dispatched into a `switchroom worktree claim` cwd runs under a
  * different project-dir slug than the agent's own `agentCwd`, so the #1116
  * foreign-slug filter would skip it forever unless the watcher also watches
  * the slugs of worktrees THIS agent owns. This helper derives that set from
- * the host-global worktree registry, and it is deliberately fail-CLOSED:
+ * the host-global worktree registry, filtered by the agent's own identity.
  *
- *   - Unset/empty identity ⇒ contribute NOTHING. `ownerAgent` is optional in
- *     the registry, so a naive `r.ownerAgent === process.env.SWITCHROOM_AGENT_NAME`
- *     with the env var unset becomes `undefined === undefined` and matches
- *     every OWNERLESS record in the host-global registry — including other
- *     agents' worktrees. That is precisely the #1116 leak the filter exists to
- *     prevent, reintroduced by failing OPEN. With no identity we cannot prove
- *     ownership of anything, so we return `[]`.
- *   - A registry read failure ⇒ `[]` (best-effort; never disturb the base
- *     agentCwd watch).
- *   - Owner match ⇒ include, realpath'd. Claude Code mints the project slug off
- *     the process's PHYSICAL cwd, so a symlinked base (macOS `/tmp` →
+ * Identity resolution is two-tier (durable fix for the gap where a worktree
+ * worker whose identity can't be attributed gets NO live progress feed):
+ *
+ *   1. FAST PATH — `self` (`process.env.SWITCHROOM_AGENT_NAME`). Set
+ *      authoritatively by compose env (compose.ts) AND hoisted in start.sh
+ *      before the gateway fork, so this is present in the overwhelming
+ *      majority of runs.
+ *   2. DURABLE FALLBACK — when `self` is unset/empty, derive the identity
+ *      from `agentDir` (the agent's own directory, itself derived from
+ *      `TELEGRAM_STATE_DIR` = `<agentDir>/telegram`, which the gateway
+ *      already requires to be present before it even starts the watcher).
+ *      The basename of `agentDir` is `resolve(agents_dir, <name>)`'s leaf —
+ *      i.e. this agent's OWN name. This can only ever resolve to THIS
+ *      agent's identity, never another agent's, so it cannot mis-attribute:
+ *      a wrong basename matches zero registry records (fail-closed), it
+ *      never matches a DIFFERENT owner. Env is just the fast path; ownership
+ *      resolves correctly from durable config when env is missing.
+ *
+ * Fail-CLOSED, deliberately, and never mis-attributing:
+ *
+ *   - Owner match ⇒ include, realpath'd. Claude Code mints the project slug
+ *     off the process's PHYSICAL cwd, so a symlinked base (macOS `/tmp` →
  *     `/private/tmp`) would otherwise derive a slug that misses the physical
  *     one; realpath best-effort, falling back to the raw path.
+ *   - Ownerless registry records (`ownerAgent` undefined) are NEVER matched,
+ *     even with identity set — a naive `undefined === undefined` would leak
+ *     every other agent's ownerless worktree (the #1116 leak this exists to
+ *     prevent).
+ *   - A registry read failure ⇒ `[]` (best-effort; never disturb the base
+ *     agentCwd watch).
+ *   - BOTH env AND agentDir-derived identity unavailable ⇒ `[]` (same
+ *     fail-closed contract as before this fix — we never guess) but escalate
+ *     the log from the #2893 one-shot warn to a clear ERROR naming that
+ *     identity resolution fully failed, so the lost live feed is diagnosable.
+ *     Never throws, never mis-attributes.
  */
 import { realpathSync } from "node:fs";
+import { basename } from "node:path";
 
 export interface WorktreeOwnershipRecord {
   path: string;
@@ -31,22 +54,74 @@ export interface WorktreeOwnershipRecord {
 }
 
 export interface OwnedWorktreeCwdsOptions {
-  /** The agent's identity — `process.env.SWITCHROOM_AGENT_NAME`. */
+  /** The agent's identity — `process.env.SWITCHROOM_AGENT_NAME` (fast path). */
   self: string | undefined;
   /** The host-global registry read (`listRecords` from src/worktree/registry). */
   listRecords: () => WorktreeOwnershipRecord[];
+  /**
+   * Durable, non-env fallback source for identity: the agent's OWN directory
+   * (`resolveAgentDirFromEnv()` in the gateway). When `self` is unset/empty,
+   * the identity is derived as `basename(agentDir)`. Omit to disable the
+   * fallback (the pre-fix, env-only behaviour — used by the kill-switch).
+   */
+  agentDir?: string | null;
   /** Injectable for tests; defaults to `fs.realpathSync`. */
   realpath?: (p: string) => string;
+  /**
+   * Injectable derivation of the agent name from `agentDir`. Defaults to
+   * `path.basename`. Returns "" when it cannot derive a usable name.
+   */
+  deriveName?: (agentDir: string) => string;
+  /** Escalated-failure sink (both identity sources unavailable). */
+  log?: (msg: string) => void;
+}
+
+// One-shot guard so the escalated "identity fully unresolved" ERROR is emitted
+// ONCE per process rather than every rescan tick (the provider is re-invoked on
+// every tick). Mirrors the #2893 one-shot-warn ethos; exported reset for tests.
+let identityEscalated = false;
+export function __resetIdentityEscalationForTests(): void {
+  identityEscalated = false;
+}
+
+function defaultDeriveName(agentDir: string): string {
+  if (!agentDir || agentDir.trim().length === 0) return "";
+  const leaf = basename(agentDir).trim();
+  return leaf;
 }
 
 export function ownedWorktreeCwds(opts: OwnedWorktreeCwdsOptions): string[] {
-  const { self } = opts;
-  if (self == null || self === "") return [];
+  // Tier 1: env fast path. Tier 2: durable agentDir-derived fallback.
+  let resolved: string = opts.self != null ? opts.self : "";
+  if (resolved === "" && opts.agentDir != null && opts.agentDir !== "") {
+    const derive = opts.deriveName ?? defaultDeriveName;
+    resolved = derive(opts.agentDir) || "";
+  }
+
+  if (resolved === "") {
+    // Both env and durable config unavailable. Keep the historical
+    // fail-closed contract (return [] — never guess, never mis-attribute) but
+    // ESCALATE past the #2893 one-shot warn: name that identity resolution
+    // fully failed and the live worktree-worker feed is lost for this run.
+    if (!identityEscalated) {
+      identityEscalated = true;
+      opts.log?.(
+        "ERROR: worktree identity resolution FAILED — both " +
+          "SWITCHROOM_AGENT_NAME and the agentDir-derived fallback are " +
+          "unavailable. Worktree ownership cannot be attributed; a " +
+          "worktree-isolated background sub-agent will get NO live progress " +
+          "feed this run (its registry row is still reaped by the 1h safety " +
+          "net). This is a configuration fault, not a transient error.",
+      );
+    }
+    return [];
+  }
+
   const rp = opts.realpath ?? realpathSync;
   try {
     return opts
       .listRecords()
-      .filter((r) => r.ownerAgent === self)
+      .filter((r) => r.ownerAgent === resolved)
       .map((r) => {
         try {
           return rp(r.path);

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

@@ -124,11 +124,19 @@ class HindsightClient:
         tags: Optional[list] = None,
         tags_match: Optional[str] = None,
         tag_groups: Optional[object] = None,
+        prefer_observations: Optional[bool] = None,
         timeout: int = 10,
     ) -> dict:
         """Recall memories from a bank.
 
-        Returns the raw API response dict with 'results' list.
+        Returns the raw API response dict with 'results' list. Each result
+        carries a `scores` object (`RecallScores`) whose `final` field is the
+        engine's combined ranking score — callers sort the merged multi-bank
+        set by it before applying any count cap.
+
+        `prefer_observations=True` asks the engine to prefer deduped
+        observation statements over the raw facts they supersede, backfilling
+        the freed slots — denser coverage inside the same token/count budget.
         """
         path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/memories/recall"
         body = {
@@ -145,6 +153,8 @@ class HindsightClient:
             body["tags_match"] = tags_match
         if tag_groups:
             body["tag_groups"] = tag_groups
+        if prefer_observations is not None:
+            body["prefer_observations"] = prefer_observations
         return self._request("POST", path, body, timeout=timeout)
 
     def retain(

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

@@ -33,10 +33,17 @@ DEFAULTS = {
     # user's query terms and a memory's text terms. Memories below this
     # threshold are dropped before formatting. 0.0 disables the gate
     # (current behaviour: inject everything Hindsight returns up to the
-    # count cap). Hindsight's HTTP API does not expose similarity
-    # scores, so this is the switchroom-side quality filter — see #475.
+    # count cap). NOTE: Hindsight's HTTP recall API DOES return per-result
+    # relevance scores (`scores.final`, plus `.semantic`/`.keyword`/
+    # `.reranker`) — verified at runtime — and recall.py now reads and
+    # sorts the merged set by `scores.final`. This Jaccard gate is a
+    # separate lexical-overlap quality filter layered on top — see #475.
     "recallMinOverlap": 0.0,
     "recallTypes": ["world", "experience"],
+    # Switchroom-local: when True (default; Ken-approved ON) recall biases
+    # toward synthesized `observation`-tier facts. Escape hatch: pin off via
+    # `recallPreferObservations: false` in the user config — read in recall.py.
+    "recallPreferObservations": True,
     # Switchroom #2848 Stage B/C — deterministic directive capture.
     # When on (switchroom default; pinned true in the copied plugin
     # settings.json by applyHindsightSettingsOverrides), TWO deterministic

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

@@ -373,12 +373,18 @@ def _is_demoted_memory(memory) -> bool:
 
 # Switchroom #475 — lexical-overlap relevance gate.
 #
-# Hindsight's HTTP API does not return similarity scores. Without a
-# score the existing `recallMaxMemories` cap acts as a *floor* on
-# low-relevance prompts: weak matches still fill the slot up to N,
-# mis-steering the model. This gate computes Jaccard overlap between
-# the user's query terms and each memory's text terms, and drops
-# memories below a configurable threshold.
+# Hindsight's HTTP recall API DOES return per-result relevance scores
+# (`RecallResult.scores.final`, plus `.semantic`/`.keyword`/`.reranker`);
+# the merged multi-bank set is now sorted by `scores.final` before the
+# `recallMaxMemories` cap (see the sort just before the cap in
+# process_recall) so the most relevant memories survive the head-slice
+# 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
+# overlap between the user's query terms and each memory's text terms is a
+# query-independent absolute measure that drops memories below a
+# configurable threshold outright — something the relative sort does not do.
 #
 # Threshold default is 0.0 (disabled) so the gate is opt-in initially.
 # Operators tune via `memory.recall.min_overlap` in switchroom.yaml or
@@ -469,6 +475,40 @@ def _filter_by_overlap(results, query: str, threshold: float):
     return kept, dropped
 
 
+def _result_final_score(m) -> float:
+    """Return a result's engine relevance score (`scores.final`).
+
+    Switchroom Phase-1 precision. The Hindsight recall response attaches a
+    `scores` object to every result whose required `final` field is the
+    engine's combined ranking score (reranker + recency/temporal/proof
+    boosts). Results missing a usable score sort last so a malformed or
+    score-less entry can never starve a properly-ranked one.
+    """
+    if isinstance(m, dict):
+        scores = m.get("scores")
+        if isinstance(scores, dict):
+            val = scores.get("final")
+            if isinstance(val, (int, float)) and not isinstance(val, bool):
+                return float(val)
+    return float("-inf")
+
+
+def _sort_by_final_score(results):
+    """Sort merged multi-bank results by `scores.final` descending, in place.
+
+    Switchroom Phase-1 bank-starvation fix. The recall path appends
+    additional-bank (profile / shared / sender) results after the own-bank
+    results, then head-slices at `recallMaxMemories`. Before this sort, a
+    full own-bank result set silently dropped every additional-bank memory
+    at the cap regardless of relevance. Sorting by the engine's real
+    relevance score before the cap means the cap keeps the most relevant
+    memories cross-bank. Python's sort is stable, so ties preserve the
+    prior own-bank-first insertion order.
+    """
+    results.sort(key=_result_final_score, reverse=True)
+    return results
+
+
 def _write_recall_log(entry: dict) -> None:
     """Append a JSONL line to recall_log.jsonl. Bounded by line count.
 
@@ -986,6 +1026,11 @@ def main():
             tags=recall_tags,
             tags_match=tags_match,
             tag_groups=tag_groups,
+            # Switchroom Phase-1 precision — prefer deduped observation
+            # statements over the raw facts they supersede, backfilling freed
+            # slots for denser coverage inside the same budget. On by default;
+            # operators can pin off via `recallPreferObservations: false`.
+            prefer_observations=config.get("recallPreferObservations", True),
             # 8s in-script timeout leaves 4s headroom inside the 12s
             # UserPromptSubmit hook ceiling (see hooks.json:20) for cache
             # write + block formatting. Tightened from 10s in switchroom
@@ -1031,6 +1076,10 @@ def main():
                 tags=extra_tags,
                 tags_match=extra_tags_match,
                 tag_groups=extra_tag_groups,
+                # Switchroom Phase-1 precision — prefer deduped observation
+                # statements here too so additional banks contribute their
+                # densest statements to the merged, score-sorted set.
+                prefer_observations=config.get("recallPreferObservations", True),
                 # 8s in-script timeout leaves 4s headroom inside the 12s
                 # UserPromptSubmit hook ceiling (see hooks.json:20) for cache
                 # write + block formatting. Tightened from 10s in switchroom
@@ -1099,6 +1148,15 @@ def main():
     else:
         overlap_dropped = 0
 
+    # Switchroom Phase-1 precision — sort the merged primary + additional-bank
+    # result set by the engine's relevance score (`scores.final`) descending
+    # BEFORE the head-slice cap below. Previously additional-bank results were
+    # appended after own-bank results and sliced off, silently starving
+    # profile / shared / sender banks whenever own-bank filled the cap. Sorting
+    # by real relevance first means the cap keeps the most relevant memories
+    # regardless of source bank. Stable sort: ties keep own-bank-first order.
+    _sort_by_final_score(results)
+
     # Switchroom-local: client-side count cap. Plugin v0.4.0 has no
     # `recallTopK` in the Claude Code integration (Openclaw-only), and a
     # token budget alone doesn't bound count — a single long memory can

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

@@ -74,6 +74,7 @@ class _FakeClient:
         tags=None,
         tags_match=None,
         tag_groups=None,
+        prefer_observations=None,
         timeout=10,
     ):
         self.recall_calls.append(