switchroom 0.19.19 → 0.19.22

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

@@ -3,9 +3,21 @@
 
 SessionStart calls into ``drain()`` to retry any retain payloads that
 ``session_end.py`` queued on failure (#1071). Each entry is retried up
-to ``MAX_ATTEMPTS`` (5) times; after that it's renamed to ``.dead`` so
-the queue no longer drains it but the operator can still inspect via
-``switchroom doctor``.
+to ``MAX_ATTEMPTS`` (5) times; after that a **permanently** failing entry
+(a 4xx that a re-POST cannot fix — see ``pending.is_permanent_failure``)
+is renamed to ``.dead`` so the queue no longer drains it but the operator
+can still inspect via ``switchroom doctor``. An entry failing on anything
+else — a 5xx, a timeout, a connection error — stays queued past the
+attempt budget: a transient upstream is never evidence that the memory
+is unsaveable, and retiring it would lose content the user believes was
+saved.
+
+An entry past the budget is DEMOTED rather than retired (``_drain_order``
+and ``_over_budget``): it sorts behind everything still inside its budget
+and abstains from the stall guard. That is what keeps "never destroy a
+memory" from degrading into "never drain anything" — the drain is
+sequential and oldest-first, so without the demotion three chronically
+failing entries sit at the head and end every run at zero progress.
 
 Boundaries
 ----------
@@ -36,8 +48,7 @@ accumulated backlog. Worse, they CREATE one: the per-entry timeout is
 clamped to the remaining hook budget (1-8s) while ``_retry_one`` posts
 synchronously and a real retain takes 30-90s, so **the server commits the
 document and the client always gives up before the ack**. The entry is
-never deleted and is re-posted on every session start, forever, until it
-hits ``MAX_ATTEMPTS`` and goes ``.dead``. The queue depth was a symptom
+never deleted and is re-posted on every session start. The queue depth was a symptom
 of that loop, not of lost memory: a full sweep of 5,751 queued entries on
 this fleet (2026-07-25) found **4,048 (70.4%) already existed as
 documents**, 3,815 of them with facts extracted.
@@ -95,6 +106,7 @@ from lib.pending import (
     MAX_ATTEMPTS,
     archive_reconciled,
     is_content_derived_document_id,
+    is_permanent_failure,
     iter_entries,
     mark_dead,
     update_attempt,
@@ -203,16 +215,30 @@ def _backlog_timeout() -> int:
     client-side timeout on a request the server then commits anyway.
 
     The default is DERIVED, not a literal: it is
-    ``retain_split.retain_client_deadline()`` (280s), the same deadline the
+    ``retain_split.retain_client_deadline()`` (310s), the same deadline the
     retain content bound is sized against. Those two must be ONE number.
     This function shipped as a bare ``180`` (#3599), and against a 180s
     deadline both halves of the retain budget break: a maximally-sized part
     is ~276s of sequential extraction, and the SERVER per-call timeout
-    derived in ``src/setup/hindsight.ts`` (#3611) is 204s — so the drain
+    derived in ``src/setup/hindsight.ts`` is larger still — so the drain
     client would abandon a request the server is still legitimately working
     on, leave the entry queued, and rebuild the re-post loop #3599 exists to
     kill, one size class up.
 
+    This is the OUTERMOST deadline of the paired-budget family, and it is the
+    one the 2026-07-26 backlog-recovery logs show as a fixed ~280.1s per-entry
+    give-up. That was not an unexplained third number: it is this default at
+    the then-current ``DEFAULT_RETAIN_CLIENT_DEADLINE_S = 280.0``, plus the
+    request's own setup overhead. It was WRONG for the same reason #3611's
+    204s was wrong — it did not cover hindsight's LiteLLM routing chain
+    (local 200s + OpenRouter fallback 90s + router margin 10s = 300s), so
+    every drained entry whose retain fell through to the fallback was
+    abandoned client-side at 280s while the server was still inside a
+    legitimate 300s budget. Raising the derivation's base to 310 fixes this
+    lane and the in-hook lane with the same number, by construction.
+    ``src/litellm/timeout-budget.ts`` is where the chain is declared, and
+    ``tests/setup/hindsight.test.ts`` fails if these drift apart again.
+
     ``HINDSIGHT_DRAIN_BACKLOG_TIMEOUT`` still overrides it outright;
     ``HINDSIGHT_RETAIN_CLIENT_DEADLINE_S`` moves the derivation and the
     content bound together.
@@ -348,6 +374,76 @@ def _document_state(entry: dict, timeout: int = 30):
         return None
 
 
+def _drain_order(entries: list[tuple[str, dict]]) -> list[tuple[str, dict]]:
+    """Oldest-first, but with budget-exhausted entries demoted to the back.
+
+    THE HEAD-OF-LINE BUG THIS EXISTS FOR. Since the permanence gate in
+    ``_record_failure``, an entry failing on anything transient stays queued
+    past ``MAX_ATTEMPTS`` indefinitely — deliberately, because a transient
+    upstream is not evidence the memory is unsaveable. But ``iter_entries()``
+    is oldest-first, and the entries that have been failing longest are by
+    construction the OLDEST, so they sit at the head of every drain. Backlog
+    concurrency defaults to 1 (``_backlog_concurrency``), so the drain is
+    sequential: three such entries in a row trip ``STALL_THRESHOLD`` and the
+    run breaks having drained nothing — and, because they never retire, it
+    breaks identically on every subsequent run. Measured on this branch before
+    this function existed: 6 queued entries, the 3 oldest raising
+    ``TimeoutError``, 4 consecutive ``drain_backlog`` runs each returning
+    ``stalled=True, drained=0`` with the queue depth still 6. The 3 healthy
+    entries behind them were never even attempted. On ``main`` the same repro
+    converges: run 0 retires the 3 heads to ``.dead`` and run 1 onward drains
+    normally. So the permanence gate, alone, traded "rarely destroys a memory"
+    for "eventually drains nothing at all".
+
+    ``.dead`` was doing double duty: it was the honesty policy AND it was the
+    queue's only un-wedging mechanism. Removing it as a policy has to leave
+    the un-wedging behind, and demotion is that — it keeps every property the
+    gate was added for (the entry is still queued, still retried, never
+    destroyed) while removing the one it broke (it can no longer starve a
+    healthy entry behind it).
+
+    The terminal condition for a permanently-unsaveable entry is therefore no
+    longer deletion but DEMOTION: ``attempt_count`` only ever climbs, so such
+    an entry crosses the budget once and stays in the back group for good,
+    where it can delay only itself. It is still reconciled for free on every
+    run — ``_reconcile_phase`` sweeps ALL entries with a sub-second presence
+    GET, in no particular order and with no stall guard — so an entry whose
+    document did land is still retired without a POST.
+
+    Ordering is a stable partition, so relative age is preserved inside each
+    group and FIFO still holds for everything that has not blown its budget.
+    """
+    fresh: list[tuple[str, dict]] = []
+    exhausted: list[tuple[str, dict]] = []
+    for path, entry in entries:
+        (exhausted if _over_budget(entry) else fresh).append((path, entry))
+    return fresh + exhausted
+
+
+def _over_budget(entry: dict) -> bool:
+    """Has this entry already burned its ``MAX_ATTEMPTS`` budget?
+
+    Such an entry is chronically failing but, since the permanence gate, is
+    never retired. It gets two demotions — last in the drain order
+    (``_drain_order``) and no vote in the stall guard (see below) — because
+    ordering alone does not close the wedge. Ordering fixes the common shape
+    (a few old poison entries in front of healthy ones), but not the shape
+    where the WHOLE queue is over budget: an upstream down for a week takes
+    every entry past 5 attempts, and when it recovers the partition is empty
+    on one side, the poisoned entries are at the head again, and the run
+    stalls before reaching the entries that would now succeed. Measured: with
+    ordering alone and all 6 entries at ``MAX_ATTEMPTS``, 4 consecutive runs
+    still returned ``stalled=True, drained=0``.
+    """
+    try:
+        return int(entry.get("attempt_count", 0)) >= MAX_ATTEMPTS
+    except (TypeError, ValueError):
+        # A hand-edited or corrupt counter must not decide ordering, and must
+        # not raise on the drain path. Treat it as fresh: the cost of guessing
+        # wrong here is one retry in the normal position, not a lost memory.
+        return False
+
+
 def _record_failure(
     config: dict,
     path: str,
@@ -358,16 +454,53 @@ def _record_failure(
     """Apply the per-entry failure policy. Returns the error class name.
 
     Shared by the sequential (SessionStart) and backlog drains so both age
-    entries toward ``.dead`` on exactly the same schedule.
+    entries toward ``.dead`` on exactly the same schedule — and, since the
+    permanence gate below, refuse to retire them on exactly the same rule.
     """
     err_class = type(e).__name__
     attempts = int(entry.get("attempt_count", 1))
-    if attempts >= MAX_ATTEMPTS:
+    # ``.dead`` retires a memory the user believes was saved, so it is gated on
+    # the failure being PERMANENT — a 4xx that re-POSTing cannot fix. A
+    # transient failure keeps its attempt counter climbing but stays queued,
+    # because an exhausted attempt budget is not evidence that the content is
+    # unpersistable.
+    #
+    # Before this gate, ANY five failures retired the entry. The dominant
+    # failure on this fleet is an HTTP 500 "Fact extraction failed … chunk 0:
+    # JSONDecodeError" — the extraction model returned an empty or non-JSON
+    # completion for one chunk on that sampling run. The identical content
+    # succeeds on a later attempt, so five unlucky samples were destroying
+    # memories that were never unsaveable. See ``pending.is_permanent_failure``.
+    #
+    # WHAT BOUNDS THIS, precisely — because an unbounded queue of undying
+    # entries would be a worse outcome than the bug this gate fixes.
+    #
+    # DISK is bounded by the queue's MAX_ENTRIES / MAX_BYTES caps, which shed
+    # the oldest entries into ``pending-evicted/`` (an archive, not a delete).
+    # Note what that bound is NOT: ``_evict_to_fit`` is called only from
+    # ``enqueue`` (lib/pending.py:933), so it fires on new writes, never on
+    # drain — and it "bounds" the queue by shedding memory unsaved, which is
+    # the very outcome this gate exists to avoid. It is a backstop, not the
+    # answer.
+    #
+    # PROGRESS is bounded by ``_drain_order`` / ``_over_budget``. An entry that
+    # can never be persisted no longer terminates by being destroyed; it
+    # terminates by being DEMOTED — sorted behind every entry still inside its
+    # budget, and stripped of its vote in the stall guard. ``attempt_count``
+    # only ever climbs, so the crossing happens once and is permanent. That is
+    # the real terminal condition, and it is what keeps a poisoned entry from
+    # starving the queue behind it. Without it, three such entries ended every
+    # drain at zero progress, permanently (tests/test_pending_wedge.py).
+    #
+    # The attempt counter itself was never a bound on either, and ``switchroom
+    # doctor`` still surfaces queue depth so the operator sees a growing tail.
+    if attempts >= MAX_ATTEMPTS and is_permanent_failure(e):
         marker = mark_dead(path, entry)
         summary["dead"] += 1
         print(
             f"[Hindsight] drain_pending: entry exceeded {MAX_ATTEMPTS} "
-            f"attempts, marking dead at {marker} (last error: {err_class}: {e})",
+            f"attempts on a permanent failure, marking dead at {marker} "
+            f"(last error: {err_class}: {e})",
             file=sys.stderr,
         )
     else:
@@ -375,7 +508,12 @@ def _record_failure(
         summary["retried"] += 1
         debug_log(
             config,
-            f"drain_pending: retry {attempts}/{MAX_ATTEMPTS} failed for {path} ({err_class}: {e})",
+            # ``attempts`` can now exceed MAX_ATTEMPTS — a transient failure
+            # keeps the entry queued past the budget instead of retiring it —
+            # so print the budget as a threshold, not as a fraction that would
+            # render the nonsense "retry 7/5".
+            f"drain_pending: retry {attempts} (budget {MAX_ATTEMPTS}) failed "
+            f"for {path} ({err_class}: {e})",
         )
     return err_class
 
@@ -440,7 +578,11 @@ def drain(
 
     summary = _new_summary()
 
-    entries = iter_entries()
+    # Budget-exhausted entries go last so they cannot starve the healthy ones
+    # behind them — see ``_drain_order``. Matters even more here than in the
+    # backlog drain: the in-hook budget is ~4s, so a single entry at the head
+    # that always burns its clamped timeout consumes the entire run.
+    entries = _drain_order(iter_entries())
     if not entries:
         debug_log(config, "drain_pending: queue empty")
         return summary
@@ -496,14 +638,30 @@ def drain(
             # allowance must not be handed out twice (#3599 review F2).
             _retry_one(entry, timeout=_clamp(timeout, budget, started))
         except Exception as e:
+            # Read the budget state BEFORE _record_failure: update_attempt
+            # mutates `entry["attempt_count"]` in place (lib/pending.py:1020),
+            # so asking afterwards would count the entry that just CROSSED the
+            # budget on this very failure as an abstainer, silently weakening
+            # the stall guard for ordinary entries.
+            abstains = _over_budget(entry)
             err_class = _record_failure(config, path, entry, e, summary)
-            if err_class == last_error_class:
-                consecutive_failures += 1
-            else:
-                consecutive_failures = 1
-                last_error_class = err_class
+            # STALL GUARD ABSTENTION — see ``_over_budget``. The guard exists
+            # to detect a broken UPSTREAM and stop hammering it. A chronically
+            # failing entry that has already burned its attempt budget is
+            # evidence about that ENTRY, not about the upstream, and letting it
+            # vote is what wedges the queue: it never retires, so it fails
+            # identically on every run, and three of them end every run before
+            # the healthy entries behind them are ever reached. It abstains —
+            # neither incrementing the counter nor resetting it, so a genuine
+            # upstream outage is still caught by the fresh entries around it.
+            if not abstains:
+                if err_class == last_error_class:
+                    consecutive_failures += 1
+                else:
+                    consecutive_failures = 1
+                    last_error_class = err_class
 
-            if consecutive_failures >= STALL_THRESHOLD:
+            if not abstains and consecutive_failures >= STALL_THRESHOLD:
                 summary["stalled"] = True
                 print(
                     f"[Hindsight] drain_pending: {consecutive_failures} consecutive "
@@ -641,7 +799,10 @@ def _drain_backlog_impl(
     backoff_ms = _p95_backoff_ms()
     started = time.monotonic()
 
-    entries = iter_entries()
+    # See ``_drain_order``: without this, three budget-exhausted entries at the
+    # head trip the stall guard on every run forever and the drain never makes
+    # progress again.
+    entries = _drain_order(iter_entries())
     if not entries:
         _blog("phase 2: nothing left to retain")
         return summary
@@ -728,15 +889,22 @@ def _drain_backlog_impl(
             # and breaking immediately after the tripping entry makes the
             # two paths bump exactly the same number of entries.
             err_class = type(err).__name__
-            if err_class == last_error_class:
-                consecutive_failures += 1
-            else:
-                consecutive_failures = 1
-                last_error_class = err_class
+            # STALL GUARD ABSTENTION for entries past their attempt budget —
+            # see ``_over_budget`` and the matching branch in the sequential
+            # drain. Evaluated here, before ``_record_failure``, which is both
+            # where the sequential drain evaluates it and necessary anyway
+            # because ``update_attempt`` mutates ``attempt_count`` in place.
+            abstains = _over_budget(entry)
+            if not abstains:
+                if err_class == last_error_class:
+                    consecutive_failures += 1
+                else:
+                    consecutive_failures = 1
+                    last_error_class = err_class
 
             _record_failure(config, path, entry, err, summary)
 
-            if consecutive_failures >= STALL_THRESHOLD:
+            if not abstains and consecutive_failures >= STALL_THRESHOLD:
                 summary["stalled"] = True
                 _blog(
                     f"{consecutive_failures} consecutive failures with "

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

@@ -10,7 +10,10 @@ entry into the bounded ``pending-reconciled/`` archive (the drain never
 deletes — see "Retiring an entry" below for that promise and its one
 bound, a full disk), failure bumps an attempt
 counter (up to MAX_ATTEMPTS) and leaves the entry for the run after
-that.
+that. Exhausting MAX_ATTEMPTS retires the entry to ``.dead`` only when
+the failure is PERMANENT (``is_permanent_failure`` — a 4xx a re-POST
+cannot fix). A transient failure never retires the memory, however many
+attempts it has burned.
 
 Layout
 ------
@@ -144,11 +147,19 @@ oversized payload into one entry PER PART (``lib/retain_split``) instead
 of writing a single giant entry. This is load-bearing, not tidiness. The
 daemon runs one sequential extraction LLM call per ``retain_chunk_size``
 chars, so an entry above the derived content bound cannot complete inside
-ANY client deadline — including the 280s out-of-hook backlog deadline that
+ANY client deadline — including the out-of-hook backlog deadline that
 ``drain_pending._backlog_timeout()`` now takes from the same derivation.
-Such an entry fails every drain, burns its ``MAX_ATTEMPTS``, and is
-renamed ``.dead``: the mechanism that stranded 154 of the 629 entries in
-the 2026-07-25 fleet backlog. Note this is orthogonal to the re-post loop
+Such an entry fails every drain and burns its ``MAX_ATTEMPTS``: the
+mechanism that stranded 154 of the 629 entries in the 2026-07-25 fleet
+backlog. (It is no longer renamed ``.dead`` for that — a client-side
+timeout is not a permanent failure — but it still never drains until it
+is split, so splitting remains the fix. Such an entry is therefore
+IMMORTAL, and ``enqueue`` is the only caller of the splitter, so one
+queued before #3610 is never split in place. That is precisely the shape
+``drain_pending._drain_order`` / ``_over_budget`` exist to contain: it is
+demoted behind every entry still inside its attempt budget and abstains
+from the stall guard, so it can delay only itself rather than wedging the
+drain.) Note this is orthogonal to the re-post loop
 #3599 fixed — a presence GET retires an oversized entry for free when the
 document IS already durable; splitting is what makes the entry drainable
 when it is NOT. Part document_ids are deterministic, so a part already
@@ -1027,6 +1038,74 @@ def update_attempt(path: str, entry: dict, error: BaseException) -> bool:
         return False
 
 
+#: HTTP statuses that are 4xx but describe a TRANSIENT condition, so they
+#: must be read as retryable despite the 4xx class.
+_RETRYABLE_4XX = frozenset({408, 425, 429})
+
+
+def is_permanent_failure(error: BaseException) -> bool:
+    """True when ``error`` can never succeed on a later identical retry.
+
+    This is the gate on ``mark_dead`` (see ``drain_pending._record_failure``).
+    Getting it wrong in the permissive direction costs a re-POST — which is an
+    upsert, so it costs time. Getting it wrong in the strict direction costs
+    the USER'S MEMORY. So the rule is deliberately asymmetric: an error is
+    permanent only when we can positively identify it as a client-side defect
+    in the request itself. Everything we cannot classify is retryable.
+
+    PERMANENT — a 4xx other than 408/425/429. The server understood us and
+    rejected the request: a malformed payload, an unknown bank, an oversized
+    body, a bad token. Re-POSTing the identical bytes reproduces it exactly,
+    so attempts are pure waste and ``.dead`` is the honest outcome.
+
+    RETRYABLE — everything else. Notably 5xx, which is what a failed
+    fact-extraction surfaces as::
+
+        HTTP 500 ...: {"detail": "Fact extraction failed: 1/1 chunks failed.
+        First failures: chunk 0: JSONDecodeError: Expecting value: line 1
+        column 1 (char 0)"}
+
+    That 500 means the extraction model returned an empty or non-JSON
+    completion for one chunk (measured 2026-07-26: Ollama returning
+    ``content: ""`` with all-zero usage, and gpt-oss-20b emitting a numbered
+    prose list instead of the JSON schema). It is a property of one sampling
+    run, NOT of the queued content — the very same entry succeeds on a later
+    attempt. Counting it toward ``MAX_ATTEMPTS`` is what turned a flaky model
+    into permanently lost memories: five unlucky samples and a real memory
+    went ``.dead``.
+
+    Timeouts, connection resets, DNS failures and anything unrecognised are
+    retryable for the same reason — none of them is evidence that the content
+    can never be persisted.
+
+    The fleet bears this out. A census of every ``.dead`` marker on this host
+    (2026-07-26, 129 markers across 10 agents) found the retiring error was
+    ``TimeoutError`` 128 times and ``URLError`` once. **Not one was a 4xx.**
+    Every permanently-lost memory here was lost to a transient failure, so
+    this gate would have kept all 129 queued and drainable. Two were retired
+    at 00:56Z that same morning — this was live, not historical.
+
+    ``client.HindsightClient._request`` re-raises ``urllib`` HTTP failures as
+    ``RuntimeError(f"HTTP {code} from {url}: {body}")`` with the original
+    ``HTTPError`` chained on ``__cause__``, so the status is read from the
+    cause when present and parsed out of the message otherwise (the message
+    form is what a de-chained/re-serialised error leaves behind).
+    """
+    code = getattr(error, "code", None)
+    cause = getattr(error, "__cause__", None)
+    if not isinstance(code, int) and cause is not None:
+        code = getattr(cause, "code", None)
+    if not isinstance(code, int):
+        text = str(error)
+        if text.startswith("HTTP "):
+            head = text[5:].split(" ", 1)[0]
+            if head.isdigit():
+                code = int(head)
+    if not isinstance(code, int):
+        return False
+    return 400 <= code < 500 and code not in _RETRYABLE_4XX
+
+
 def mark_dead(path: str, entry: dict) -> Optional[str]:
     """Convert an entry that exceeded ``MAX_ATTEMPTS`` into a permanent
     failure marker at ``<path>.dead`` so the queue no longer drains it

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

@@ -83,7 +83,7 @@ from typing import Optional
 #                               completion-token bucket; the runaway bucket is
 #                               a separate defect, fixed by capping
 #                               HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS).
-#   client_deadline     280 s  — the deadline of the DURABILITY path (the
+#   client_deadline     310 s  — the deadline of the DURABILITY path (the
 #                               out-of-hook backlog drain, #3599), deliberately
 #                               not the live Stop hook's 15s. The live path is
 #                               allowed to miss its deadline: it enqueues to
@@ -96,20 +96,31 @@ from typing import Optional
 #                               literal, and `src/setup/hindsight.ts`
 #                               (`HINDSIGHT_RETAIN_CLIENT_DEADLINE_S`, #3611)
 #                               mirrors it as the client half of that PR's
-#                               `server per-call timeout < client deadline`
-#                               assertion — which its derived 204s server
-#                               timeout satisfies against 280 and would NOT
-#                               against #3599's original 180s literal.
+#                               `hindsight per-call timeout < client deadline`
+#                               assertion. A test in `tests/setup/hindsight.test.ts`
+#                               enforces that the two stay equal, so the mirror
+#                               is checked, not merely asserted in prose.
+#                               WAS 280.0. Raised to 310 when the retain
+#                               per-call timeout became derived from the litellm
+#                               routing chain (`local 200 + fallback 90 +
+#                               margin 10 = 300`) instead of from the token
+#                               budget alone: #3611's 204s could not cover that
+#                               chain, so the retain OpenRouter fallback hop had
+#                               4s of headroom and could never complete. 310 is
+#                               that 300 plus the same one margin, so the plugin
+#                               always outlives hindsight by construction. It is
+#                               NOT a hand-set number on either side — change
+#                               `src/litellm/timeout-budget.ts` and both move.
 #
-#   floor(280 / 18.4) = 15 chunks  →  15 × 3000 = 45,000 chars
+#   floor(310 / 18.4) = 16 chunks  →  16 × 3000 = 48,000 chars
 #
 # Sanity check against the same backlog: every entry at or below 60,000 chars
-# drained successfully inside the 280s deadline (observed per-entry times
-# 0.3s–153.4s at concurrency 3), so 45,000 sits inside demonstrated-good
-# territory with margin for a slower model or a busier box.
+# drained successfully inside the (then 280s) deadline (observed per-entry
+# times 0.3s–153.4s at concurrency 3), so 48,000 still sits inside
+# demonstrated-good territory with margin for a slower model or a busier box.
 DEFAULT_RETAIN_CHUNK_SIZE = 3000
 DEFAULT_RETAIN_CHUNK_LATENCY_S = 18.4
-DEFAULT_RETAIN_CLIENT_DEADLINE_S = 280.0
+DEFAULT_RETAIN_CLIENT_DEADLINE_S = 310.0
 
 # Absolute floor: one chunk. A bound below one chunk would split every
 # transcript into extraction-sized confetti and is never the right answer.

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

@@ -1296,6 +1296,56 @@ def _combine_context(base, nudge) -> str:
     return "\n\n".join(parts)
 
 
+def degraded_recall_notice(bank_id, bank_timings) -> str:
+    """Switchroom #3619 — return the degraded-recall disclosure for this turn,
+    or "" when the agent's own bank answered.
+
+    Until now a recall whose own bank timed out was indistinguishable, from the
+    agent's side, from a bank that genuinely held nothing relevant: both
+    produced an empty block and silence. That ambiguity is what let a measured
+    ~90% own-bank timeout rate run for weeks unnoticed while every agent's
+    CLAUDE.md asserted recall "auto-fires on every inbound message" — the agent
+    had no way to know it was answering from an empty context, so it never said
+    so and the operator never saw it.
+
+    Only the agent's OWN bank warrants the notice: additional banks (a shared
+    profile bank, say) are supplementary, and a side-bank timeout does not mean
+    the agent lost its own memory. Matching is by `bank_id`, never by position
+    in `bank_timings` — the fan-out order is not stable.
+
+    Kept to a single short line on purpose: this fires on an already-degraded
+    turn, and a verbose block would spend the very budget the degradation is
+    starving. The caller must keep it OUT of the cached context (see
+    `_combine_context`) — it is per-turn state and would otherwise replay on a
+    later healthy cache hit.
+    """
+    if not bank_id or not bank_timings:
+        return ""
+    own = next(
+        (
+            bt
+            for bt in bank_timings
+            if isinstance(bt, dict) and bt.get("bank_id") == bank_id
+        ),
+        None,
+    )
+    if not own:
+        return ""
+    if own.get("timed_out"):
+        reason = "timed out"
+    elif own.get("errored"):
+        reason = "was unreachable"
+    else:
+        return ""
+    return (
+        f"[Hindsight] Memory recall was DEGRADED this turn: your own bank "
+        f"('{bank_id}') {reason}, so the memories below (if any) are "
+        f"incomplete and may be missing entirely. Treat an absence of "
+        f"relevant memory as UNKNOWN, not as 'nothing was remembered' — "
+        f"say so rather than asserting there is no prior context."
+    )
+
+
 def main():
     config = load_config()
 
@@ -2129,13 +2179,22 @@ def main():
         "transcript_fallback_truncated": transcript_fallback_telemetry["truncated"],
     })
 
-    # If neither block has content, there's nothing to inject — exit
+    # Switchroom #3619 — DEGRADED-RECALL DISCLOSURE. See
+    # `degraded_recall_notice` for why this exists and why only the agent's
+    # OWN bank counts.
+    degraded_block = degraded_recall_notice(bank_id, bank_timings)
+
+    # If no block has content, there's nothing to inject — exit
     # silently to avoid emitting an empty hookSpecificOutput. #2848: unless
     # the directive-capture nudge fired, in which case emit the nudge alone
     # (a correction with no memories/directives still needs the reminder).
+    # #3619: a degraded own-bank read is likewise worth emitting alone — that
+    # is precisely the turn on which the agent must not assume it remembers.
     if not directives_block and not memories_block and not transcript_fallback_block:
-        if nudge_block:
-            _emit_cached_context(nudge_block)
+        if degraded_block or nudge_block:
+            _emit_cached_context(
+                "\n\n".join([b for b in (degraded_block, nudge_block) if b])
+            )
         return
 
     # Compose final context. Directives block goes ABOVE memories so the
@@ -2143,6 +2202,12 @@ def main():
     # transcript fallback (#3369) goes LAST — it is the lowest-confidence
     # signal (raw transcript, not synthesized fact) and only present when
     # memories_block is empty by construction.
+    #
+    # #3619's degraded notice is deliberately NOT part of context_message: like
+    # the #2848 nudge it is per-turn state, and this string is what gets cached
+    # and written to LAST_RECALL_STATE. Caching it would replay "recall was
+    # DEGRADED" on later healthy cache hits; it is prepended at emit time
+    # instead, so a cache hit re-derives the turn's real condition.
     parts = []
     if directives_block:
         parts.append(directives_block)
@@ -2177,11 +2242,15 @@ def main():
 
     # Output JSON for Claude Code hook system. #2848: append the
     # directive-capture nudge (if it fired) at emit time — it's kept out of
-    # the cached / last-recall context above so it can't go stale.
+    # the cached / last-recall context above so it can't go stale. #3619: the
+    # degraded-recall notice is prepended for the same reason, and goes FIRST
+    # because it changes how everything after it should be read.
     output = {
         "hookSpecificOutput": {
             "hookEventName": "UserPromptSubmit",
-            "additionalContext": _combine_context(context_message, nudge_block),
+            "additionalContext": _combine_context(
+                _combine_context(degraded_block, context_message), nudge_block
+            ),
         }
     }
     json.dump(output, sys.stdout)