switchroom 0.21.18 → 0.21.19

package/telegram-plugin/session-tail.ts

@@ -42,6 +42,7 @@ function isMultiAgentEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
 }
 import { classifyClaudeError, type OperatorEventKind } from './operator-events.js'
 import { isLitellmProxyLocal429, isTransientUpstreamSignal } from './model-unavailable.js'
+import { isConnectionDropText } from './connection-drop.js'
 import { createToolLabelSidecar, type ToolLabelSidecar, type SidecarOptions } from './tool-label-sidecar.js'
 import { isModelSentinel } from './model-label.js'
 
@@ -960,6 +961,25 @@ function extractRetryState(obj: Record<string, unknown>): {
   }
 }
 
+/**
+ * The OperatorEventKinds on which a connection-drop wording may be flagged as a
+ * genuine transport drop. INCLUSION (not exclusion) by design: a positively
+ * classified auth/quota/credit/rate-limit/overload wall is NEVER in this set,
+ * so a wrapped terminal error whose outer text coincidentally carries a drop
+ * wording is never mislabelled a drop. `transport-transient` is the natural
+ * mid-stream-abort kind; `unknown-4xx`/`unknown-5xx` is where a drop-worded
+ * line lands when `classifyClaudeError` does not recognise its wording (the
+ * exact Path-B bug this closes). Mirrors Path A's `transient`/`unknown` gate in
+ * `parseLlmError`, keeping the two classifiers in agreement.
+ */
+const CONNECTION_DROP_ELIGIBLE_KINDS: ReadonlySet<OperatorEventKind> =
+  new Set<OperatorEventKind>(['transport-transient', 'unknown-5xx', 'unknown-4xx'])
+
+/** True when `kind` may carry the connection-drop flag AND the text is a drop wording. */
+function isConnectionDrop(kind: OperatorEventKind, scanText: string): boolean {
+  return CONNECTION_DROP_ELIGIBLE_KINDS.has(kind) && isConnectionDropText(scanText)
+}
+
 export function detectErrorInTranscriptLine(
   line: string,
 ): {
@@ -972,6 +992,15 @@ export function detectErrorInTranscriptLine(
    *  error mid-retry is `transient:true, terminal:false`; the caller
    *  suppresses it (no operator card until the failure is terminal). */
   terminal: boolean
+  /**
+   * True when this line is a mid-stream connection / SSE drop (a transport
+   * connection loss), per the canonical `isConnectionDropText` matcher, gated
+   * to the transport/unknown kinds. Set consistently with `parseLlmError`'s
+   * `ParsedLlmError.connectionDrop` so a later PR can gate auto-resume on ONE
+   * reliable discriminator across both classification paths. Classification
+   * only in this PR; no caller acts on it yet.
+   */
+  connectionDrop: boolean
 } | null {
   if (!line || line.length > 2 * 1024 * 1024) return null
   let obj: Record<string, unknown>
@@ -1042,6 +1071,7 @@ export function detectErrorInTranscriptLine(
       detail: text || errStr || 'api error',
       transient: kind === 'rate-limited',
       terminal: true,
+      connectionDrop: isConnectionDrop(kind, `${text}\n${errStr}`),
     }
   }
 
@@ -1089,7 +1119,14 @@ export function detectErrorInTranscriptLine(
       ? retry.retryAttempt >= retry.maxRetries
       : isErrorLine
 
-  return { kind, raw, detail, transient, terminal }
+  return {
+    kind,
+    raw,
+    detail,
+    transient,
+    terminal,
+    connectionDrop: isConnectionDrop(kind, `${detail}\n${String(type ?? '')}`),
+  }
 }
 
 function extractDetailMessage(obj: Record<string, unknown> | null): string | null {

package/telegram-plugin/tests/llm-error-present.test.ts

@@ -27,6 +27,7 @@ import {
 } from '../llm-error-present.js'
 import { truncateDetailPreservingRequestId } from '../raw-error-scrub.js'
 import { projectTranscriptLine, detectErrorInTranscriptLine } from '../session-tail.js'
+import { isConnectionDropText } from '../connection-drop.js'
 import { renderOperatorEvent, type OperatorEvent } from '../operator-events.js'
 import { redact } from '../secret-detect/redact.js'
 
@@ -137,6 +138,188 @@ describe('parseLlmError — classification table', () => {
   })
 })
 
+// ─── Connection-drop classification (PR 0: unify drop classification) ─────────
+//
+// The two classifiers historically disagreed about a mid-stream connection /
+// SSE drop: Path A (`parseLlmError`) mapped it to a transient/network error,
+// while Path B (`detectErrorInTranscriptLine`) let a drop-worded line whose
+// wording `classifyClaudeError` did not recognise fall through to a generic
+// `unknown-*` terminal. These blocks assert the SAME line is now identifiable
+// as a connection drop on BOTH paths — and, critically, that auth / quota /
+// overload / provider-credit walls are NEVER flagged as drops on either path
+// (the greedy-matcher failure mode that would later cause a wrong auto-resume).
+
+const OPENROUTER_402_CREDIT =
+  'litellm.APIError: OpenrouterException - {"error":{"code":402,"message":"Your account or API key has insufficient credits. Add more credits and retry the request.","metadata":{"provider_name":"openrouter"}}}'
+
+/** Build the v2.1.x `isApiErrorMessage` synthetic-assistant transcript line. */
+function apiErrorLine(text: string, opts: { error?: string; status?: number } = {}): string {
+  return JSON.stringify({
+    type: 'assistant',
+    message: { role: 'assistant', model: '<synthetic>', content: [{ type: 'text', text }] },
+    isApiErrorMessage: true,
+    ...(opts.error != null ? { error: opts.error } : { error: '' }),
+    ...(opts.status != null ? { apiErrorStatus: opts.status } : {}),
+  })
+}
+
+describe('connection-drop — identifiable on BOTH classification paths', () => {
+  // The canonical mid-stream abort shape: isApiErrorMessage + error:"server_error",
+  // NO status. Path A sees the worded string; Path B sees the transcript line.
+  it('a "Connection closed mid-response" line is a connection-drop on Path A AND Path B', () => {
+    const wording = 'API Error: Connection closed mid-response'
+
+    // Path A
+    const a = parseLlmError(wording)
+    expect(a.connectionDrop).toBe(true)
+    expect(a.kind).toBe('transient')
+    expect(a.source).toBe('network')
+
+    // Path B
+    const b = detectErrorInTranscriptLine(apiErrorLine(wording, { error: 'server_error' }))
+    expect(b).not.toBeNull()
+    expect(b!.connectionDrop).toBe(true)
+    expect(b!.kind).toBe('transport-transient')
+  })
+
+  // The exact Path-B bug: a drop-worded line whose wording `classifyClaudeError`
+  // does NOT recognise (no server_error type, no status) fell through to
+  // unknown-5xx. It must STILL be flagged a connection-drop.
+  it('a "socket hang up" line unknown to classifyClaudeError is still a connection-drop on both paths', () => {
+    const wording = 'API Error: socket hang up'
+
+    const a = parseLlmError(wording)
+    expect(a.connectionDrop).toBe(true)
+
+    const b = detectErrorInTranscriptLine(apiErrorLine(wording))
+    expect(b).not.toBeNull()
+    expect(b!.kind).toBe('unknown-5xx') // classifyClaudeError does not recognise the wording…
+    expect(b!.connectionDrop).toBe(true) // …yet the drop is identified anyway.
+  })
+
+  // The wrapper-error line shape (`type:"error"`, nested error object).
+  it('a server_error wrapper line carrying a drop wording is a connection-drop on Path B', () => {
+    const line = JSON.stringify({
+      type: 'error',
+      error: { type: 'server_error', message: 'Connection closed mid-response' },
+    })
+    const b = detectErrorInTranscriptLine(line)
+    expect(b).not.toBeNull()
+    expect(b!.kind).toBe('transport-transient')
+    expect(b!.connectionDrop).toBe(true)
+  })
+
+  // EPIPE is a genuine drop wording that `detectModelUnavailable` does not
+  // classify as network — Path A lands it on `unknown`, but it must still be a
+  // connection-drop (proving the discriminator is NOT tied to source:'network').
+  it('EPIPE is a connection-drop on Path A even though its kind stays unknown', () => {
+    const a = parseLlmError('write EPIPE: half-dead socket')
+    expect(a.kind).toBe('unknown')
+    expect(a.connectionDrop).toBe(true)
+  })
+})
+
+describe('connection-drop — negatives (auth / quota / overload / provider-credit are NEVER drops)', () => {
+  it('auth is not a connection-drop on either path', () => {
+    const a = parseLlmError('authentication_error: OAuth token expired, please refresh')
+    expect(a.kind).toBe('auth')
+    expect(a.connectionDrop).toBe(false)
+
+    const b = detectErrorInTranscriptLine(
+      apiErrorLine('authentication_error: OAuth token expired', { error: 'authentication_error', status: 401 }),
+    )
+    expect(b).not.toBeNull()
+    expect(b!.connectionDrop).toBe(false)
+  })
+
+  it('quota_wall is not a connection-drop on either path', () => {
+    const a = parseLlmError("You've hit your limit · resets 5pm")
+    expect(a.kind).toBe('quota_wall')
+    expect(a.connectionDrop).toBe(false)
+
+    const b = detectErrorInTranscriptLine(
+      apiErrorLine("You've hit your limit · resets 5pm", { error: 'rate_limit_error', status: 429 }),
+    )
+    expect(b).not.toBeNull()
+    expect(b!.kind).toBe('quota-exhausted')
+    expect(b!.connectionDrop).toBe(false)
+  })
+
+  it('overload_529 is not a connection-drop on either path', () => {
+    const a = parseLlmError('Overloaded (overloaded_error) — HTTP 529')
+    expect(a.kind).toBe('overload_529')
+    expect(a.connectionDrop).toBe(false)
+
+    const b = detectErrorInTranscriptLine(apiErrorLine('Overloaded', { error: 'overloaded_error' }))
+    expect(b).not.toBeNull()
+    expect(b!.connectionDrop).toBe(false)
+  })
+
+  it('provider_credit is not a connection-drop on either path', () => {
+    const a = parseLlmError(OPENROUTER_402_CREDIT)
+    expect(a.kind).toBe('provider_credit')
+    expect(a.connectionDrop).toBe(false)
+
+    const b = detectErrorInTranscriptLine(apiErrorLine(OPENROUTER_402_CREDIT, { status: 402 }))
+    expect(b).not.toBeNull()
+    expect(b!.kind).toBe('provider-credit-exhausted')
+    expect(b!.connectionDrop).toBe(false)
+  })
+
+  // The single highest-risk case: a wrapped auth/quota wall whose OUTER text
+  // coincidentally carries a drop wording ("fetch failed") must NOT be flagged a
+  // drop — the classification wins over the wording, on both paths.
+  it('a wrapped auth error whose outer text says "fetch failed" is NOT a connection-drop', () => {
+    const a = parseLlmError('authentication_error: invalid api key (underlying: fetch failed)')
+    expect(a.kind).toBe('auth')
+    expect(a.connectionDrop).toBe(false)
+
+    const b = detectErrorInTranscriptLine(
+      JSON.stringify({
+        type: 'error',
+        error: { type: 'authentication_error', message: 'invalid api key; underlying: fetch failed' },
+      }),
+    )
+    expect(b).not.toBeNull()
+    expect(b!.kind).toBe('credentials-invalid')
+    expect(b!.connectionDrop).toBe(false)
+  })
+})
+
+describe('isConnectionDropText — the canonical matcher is conservative', () => {
+  it('matches the canonical drop wordings', () => {
+    for (const s of [
+      'socket hang up',
+      'read ECONNRESET',
+      'connect ECONNREFUSED 1.2.3.4:443',
+      'write EPIPE',
+      'fetch failed',
+      'network error',
+      'Connection closed mid-response',
+      'connection lost',
+      'Premature close',
+      'the stream disconnected unexpectedly',
+    ]) {
+      expect(isConnectionDropText(s)).toBe(true)
+    }
+  })
+
+  it('does NOT over-match "upstream"/"downstream"/"terminated" or auth/quota wording', () => {
+    for (const s of [
+      'the upstream provider returned a result',
+      'downstream consumer finished',
+      'the worker terminated cleanly',
+      'authentication_error: invalid api key',
+      "You've hit your usage limit",
+      'overloaded_error',
+      'insufficient credits',
+      '',
+    ]) {
+      expect(isConnectionDropText(s)).toBe(false)
+    }
+  })
+})
+
 // ─── local-time render ───────────────────────────────────────────────────────
 
 describe('renderLlmError / formatResetLocal — local-time rendering', () => {

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

@@ -75,8 +75,18 @@ def run_prefetch(hook_input: dict, config: dict) -> bool:
     that could take the Stop hook (and thus the turn) down with it."""
     session_id = hook_input.get("session_id") or "unknown"
 
-    prompt = (hook_input.get("prompt") or hook_input.get("user_prompt") or "").strip()
-    if prompt.startswith("<task-notification"):
+    # F6 — junk gate derived from the TRANSCRIPT's last human turn, not from a
+    # `hook_input["prompt"]` field. A Stop hook's input carries only
+    # session_id/transcript_path/stop_hook_active — never `prompt`/`user_prompt`
+    # — so the old `hook_input.get("prompt")` gate was permanently empty and
+    # NEVER fired, meaning prefetch would run on `<task-notification>` turns once
+    # lit. `_last_human_prompt` reads the same last-human turn the speculative
+    # query is derived from, so the gate now fires on exactly the synthetic
+    # follow-up turns `recall.py`'s synchronous gate skips (honouring the same
+    # `recallSkipTaskNotification` switch).
+    transcript_path = hook_input.get("transcript_path") or ""
+    query = _last_human_prompt(transcript_path)
+    if config.get("recallSkipTaskNotification", True) and query.startswith("<task-notification"):
         debug_log(config, "Prefetch: task-notification turn, skipping")
         return False
 
@@ -97,9 +107,8 @@ def run_prefetch(hook_input: dict, config: dict) -> bool:
     except Exception as exc:  # pragma: no cover - defensive
         debug_log(config, f"Prefetch: delta retain failed, continuing without it: {exc}")
 
-    # Step 2 — speculative recall.
-    transcript_path = hook_input.get("transcript_path") or ""
-    query = _last_human_prompt(transcript_path)
+    # Step 2 — speculative recall (query derived above from the transcript's
+    # last human turn).
     if not query:
         debug_log(config, "Prefetch: no usable query, nothing to prefetch")
         return False
@@ -123,6 +132,25 @@ def run_prefetch(hook_input: dict, config: dict) -> bool:
         debug_log(config, "Prefetch: no candidates, nothing to buffer")
         return False
 
+    # F5 — CURATE before buffering, through the SAME pipeline the synchronous
+    # recall path enforces (demote-drop, relevance sort, score floor, and the
+    # `recallMaxMemories` cap). Calling recall's shared helper — rather than
+    # `format_memories(results)` on the raw set — is what stops a demoted or
+    # uncapped memory from reaching the buffer and bypassing curation the sync
+    # path applies (carve §6.1 sharing requirement). Imported lazily so the
+    # flag-off no-op in `main()` never pays recall.py's import cost.
+    try:
+        import recall  # noqa: PLC0415 - lazy, kept off the flag-off no-op path
+
+        results = recall.curate_recall_results(results, config, bank_id)
+    except Exception as exc:  # pragma: no cover - defensive
+        debug_log(config, f"Prefetch: curation failed, skipping buffer: {exc}")
+        return False
+
+    if not results:
+        debug_log(config, "Prefetch: all candidates filtered by curation, nothing to buffer")
+        return False
+
     from lib.content import format_memories
 
     memories_block = format_memories(results)

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

@@ -92,6 +92,13 @@ _IMPORT_ELAPSED_SECONDS = time.monotonic() - _IMPORT_START_MONOTONIC
 
 LAST_RECALL_STATE = "last_recall.json"
 RECALL_CACHE_STATE = "recall_cache.json"
+# M4 P-REC F3 — the last prefetch-buffer sentinel token this session has
+# already CONSUMED, keyed by session_id. Persisted across turns so a buffer
+# produced at turn N and consumed at N+1 is not re-served as "fresh" at
+# N+2..N+k when no newer sentinel has landed (the stale-buffer-served-as-fresh
+# class). A dict {session_id: token}; capped like the other per-session state.
+PREFETCH_CONSUMED_STATE = "prefetch_consumed.json"
+_PREFETCH_CONSUMED_MAX_SESSIONS = 10000
 
 # Switchroom hindsight-leverage A3 — label for the directives fetch slot in the
 # parallel fan-out. Distinct from any bank_id (banks can't start with "__") so a
@@ -500,12 +507,6 @@ def _emit_cached_context(context: str) -> None:
     )
 
 
-_PREFETCH_DEGRADED_NOTICE = (
-    "⏳ prefetch not ready and no prior recall is cached for this session — "
-    "proceeding without injected memory this turn."
-)
-
-
 def stale_recall_notice(memories_context: str) -> str:
     """Wrap a PRIOR turn's cached memories-only block in an explicit
     staleness marker for the M4 prefetch-buffer fallback path.
@@ -528,6 +529,100 @@ def stale_recall_notice(memories_context: str) -> str:
     )
 
 
+def _read_consumed_token(session_id: str) -> "int | None":
+    """Return the last prefetch sentinel token this session already consumed,
+    or None if none is recorded. Failure-tolerant — any read/parse error
+    returns None (treat as "nothing consumed yet", the fail-open direction that
+    at worst re-serves once, never suppresses forever)."""
+    state = read_state(PREFETCH_CONSUMED_STATE, {}) or {}
+    if not isinstance(state, dict):
+        return None
+    token = state.get(session_id)
+    return int(token) if isinstance(token, (int, float)) else None
+
+
+def _write_consumed_token(session_id: str, token: int) -> None:
+    """Persist `token` as the last sentinel this session has consumed. Bounded
+    to `_PREFETCH_CONSUMED_MAX_SESSIONS` entries. Best-effort — write_state
+    never raises."""
+    state = read_state(PREFETCH_CONSUMED_STATE, {}) or {}
+    if not isinstance(state, dict):
+        state = {}
+    state[session_id] = int(token)
+    if len(state) > _PREFETCH_CONSUMED_MAX_SESSIONS:
+        # Drop the numerically-smallest tokens (oldest producers) first.
+        for k in sorted(
+            state.keys(),
+            key=lambda k: state[k] if isinstance(state[k], (int, float)) else 0,
+        )[: len(state) - _PREFETCH_CONSUMED_MAX_SESSIONS]:
+            state.pop(k, None)
+    write_state(PREFETCH_CONSUMED_STATE, state)
+
+
+def curate_recall_results(results, config, bank_id):
+    """M4 F5 — the SHARED recall curation pipeline, so the async prefetch
+    producer (`prefetch.py`) can never drift from the guarantees the
+    synchronous recall path enforces.
+
+    Applies, in order, the exact same module-level primitives the synchronous
+    path composes inline: drop demote-tagged memories (`_is_demoted_memory`),
+    sort by engine relevance (`_sort_by_final_score`), apply the optional
+    absolute score floor when it is configured for ALL turns
+    (`_filter_by_min_score`; the `degraded`-scope floor is a synchronous-path
+    concept the speculative single-bank prefetch cannot evaluate, so it is
+    honoured here only when `recallMinScoreScope` is `all`, matching what the
+    sync path does on a healthy own-bank turn), and finally the
+    `recallMaxMemories` head cap with per-bank slot reservation
+    (`_reserve_bank_slots`).
+
+    Returns the curated result list. Never mutates the caller's list in a way
+    that changes its length before returning (it rebinds internally). Pure —
+    no I/O, no network — so it is safe to call from the producer hook.
+    """
+    if not results:
+        return results
+
+    # 1) demote-from-recall drop (Switchroom #432 4.4) — before any cap so the
+    #    cap fills with non-demoted hits.
+    results = [m for m in results if not _is_demoted_memory(m)]
+
+    # 2) relevance sort (Phase-1 bank-starvation fix) — in place on our copy.
+    _sort_by_final_score(results)
+
+    # 3) optional absolute score floor (#3837). The sync path binds this on
+    #    `all` scope always, and on `degraded` scope only when the own-bank
+    #    read degraded. A prefetch is a healthy speculative read (no degraded
+    #    signal), so we bind only the `all` scope here — identical to the sync
+    #    path's decision on a non-degraded turn.
+    min_score_floor = config.get("recallMinScore", 0.0)
+    if isinstance(min_score_floor, bool) or not isinstance(min_score_floor, (int, float)):
+        min_score_floor = 0.0
+    min_score_floor = float(min_score_floor)
+    min_score_scope = config.get("recallMinScoreScope", "degraded")
+    if min_score_floor > 0 and min_score_scope == "all":
+        results, _dropped = _filter_by_min_score(results, min_score_floor)
+
+    # 4) recallMaxMemories head cap + per-bank slot reservation. `_reserve_
+    #    bank_slots` is a passthrough when cap<=0 or the set already fits, and
+    #    with the fleet-default 0/0 floors on a single-bank prefetch it reduces
+    #    to a plain head-slice — the same slice the sync path takes.
+    recall_max_memories = config.get("recallMaxMemories", 0)
+    if (
+        isinstance(recall_max_memories, int)
+        and recall_max_memories > 0
+        and len(results) > recall_max_memories
+    ):
+        results, _own, _add = _reserve_bank_slots(
+            results,
+            recall_max_memories,
+            bank_id,
+            config.get("recallOwnBankMinSlots", 0),
+            config.get("recallAdditionalBankMinSlots", 0),
+        )
+
+    return results
+
+
 def _handle_prefetch_buffer(config: dict, hook_input: dict, prompt: str) -> bool:
     """M4 P-REC Fix C (consumer side) — join the Stop-hook producer's
     prefetch buffer for this session instead of running recall
@@ -535,10 +630,12 @@ def _handle_prefetch_buffer(config: dict, hook_input: dict, prompt: str) -> bool
 
     Gated entirely by `config.get("memoryPrefetchEnabled", False)` at the
     caller; this function assumes the flag is already on. Returns True iff
-    it emitted an `additionalContext` payload (fresh hit, stale fallback, or
-    the explicit degraded notice) and the caller should return without
-    running the synchronous path. Returns False on a clean no-op miss (flag
-    effectively off / nothing to say) so the caller falls through.
+    it emitted an `additionalContext` payload (fresh buffer hit, stale
+    fallback, or a directives-only block) and the caller should return
+    without running the synchronous path. Returns False on a miss with
+    nothing to serve — cold start, no fresh buffer, no stale prior recall,
+    no directives — so the caller falls through to SYNCHRONOUS recall (M4
+    F4: the first turn of a fresh/post-restart session must still recall).
 
     Never raises past this function's own boundary in normal operation —
     every internal step is wrapped so a bug here degrades to "fall through
@@ -547,6 +644,13 @@ def _handle_prefetch_buffer(config: dict, hook_input: dict, prompt: str) -> bool
     """
     session_id = hook_input.get("session_id") or "unknown"
 
+    # M4 F3 — the sentinel token this session has ALREADY consumed on a prior
+    # turn. Threaded into both `poll_for_sentinel` and `read_if_fresh` so a
+    # buffer produced at turn N and consumed at N+1 is treated as STALE (not
+    # re-served as fresh) at N+2..N+k until a strictly-newer sentinel lands.
+    # None on a cold session (nothing consumed yet).
+    last_consumed = _read_consumed_token(session_id)
+
     # Cold-start short-circuit (red-team MAJOR finding): if this session has
     # NEVER produced a sentinel, polling the full cap on every single
     # session-open turn would cost ~the poll cap on every fresh session —
@@ -556,9 +660,9 @@ def _handle_prefetch_buffer(config: dict, hook_input: dict, prompt: str) -> bool
         debug_log(config, "Prefetch buffer: no sentinel ever written for this session, cold-start skip")
     else:
         cap_ms = int(config.get("memoryPrefetchPollCapMs", 400))
-        recall_buffer.poll_for_sentinel(session_id, last_consumed_token=None, cap_ms=cap_ms)
+        recall_buffer.poll_for_sentinel(session_id, last_consumed_token=last_consumed, cap_ms=cap_ms)
 
-    payload, _token = recall_buffer.read_if_fresh(session_id, last_consumed_token=None)
+    payload, _token = recall_buffer.read_if_fresh(session_id, last_consumed_token=last_consumed)
 
     # Directives stay on the synchronous, always-fresh path (M3 rule) even
     # in the fast path — fetched here directly, never from the buffer.
@@ -584,6 +688,12 @@ def _handle_prefetch_buffer(config: dict, hook_input: dict, prompt: str) -> bool
         directives_block = None
 
     if payload is not None:
+        # M4 F3 — record this token as consumed BEFORE emitting, so the next
+        # turn's `read_if_fresh` rejects the same buffer as stale unless the
+        # producer has since written a strictly-newer sentinel. `_token` is the
+        # sentinel token `read_if_fresh` just validated as fresh.
+        if _token is not None:
+            _write_consumed_token(session_id, _token)
         memories_block = payload.get("context") or ""
         parts = [b for b in (_dir_notice, directives_block, memories_block) if b]
         if not parts:
@@ -607,11 +717,15 @@ def _handle_prefetch_buffer(config: dict, hook_input: dict, prompt: str) -> bool
         _emit_cached_context("\n\n".join([b for b in (_dir_notice, directives_block) if b]))
         return True
 
-    # Nothing fresh, nothing stale, nothing cached — say so explicitly
-    # rather than silently emitting no context (so a degraded turn is
-    # legible, matching the #3619 degraded-disclosure precedent).
-    _emit_cached_context(_PREFETCH_DEGRADED_NOTICE)
-    return True
+    # M4 F4 — nothing fresh, nothing stale, nothing cached (the cold-start /
+    # first-turn / no-prior-recall case). Return False so the caller runs the
+    # SYNCHRONOUS recall path, which is exactly the path that should run on a
+    # turn where no prefetch could possibly exist yet. Emitting a degraded
+    # notice and returning True here (the previous behaviour) short-circuited
+    # sync recall and handed a fresh/post-restart session ZERO memories plus a
+    # degraded banner on its very first turn — the opposite of the docstring's
+    # "a miss falls through to sync recall" contract.
+    return False
 
 
 def _emit_directives_only(config: dict, hook_input: dict) -> None:

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

@@ -233,14 +233,105 @@ class KillSwitchOffTests(PrefetchPipelineBase):
 
 
 class JunkGateTests(PrefetchPipelineBase):
-    def test_task_notification_turn_is_skipped(self):
-        _write_transcript(self.transcript_path, [("user", "irrelevant")])
-        with patch("prefetch.retain_module.run_retain", side_effect=AssertionError("must not retain a task-notification turn")):
-            wrote = prefetch.run_prefetch(
-                self._hook_input("<task-notification>done</task-notification>"), self._config()
-            )
+    def test_task_notification_in_transcript_skips_before_retain(self):
+        # F6 (regression guard): a real Stop-hook input carries NO `prompt`
+        # field — only session_id / transcript_path / stop_hook_active — so the
+        # junk gate MUST derive from the transcript's last human turn. When that
+        # turn is a `<task-notification>` envelope, prefetch skips ENTIRELY:
+        # no delta retain, no recall, no buffer. This fails on the pre-fix code,
+        # whose `hook_input.get("prompt")` gate is permanently empty on real
+        # input and therefore lets retain run on a task-notification turn.
+        _write_transcript(
+            self.transcript_path,
+            [("user", "<task-notification>sub-agent done</task-notification>")],
+        )
+        real_stop_input = {
+            "session_id": SESSION,
+            "transcript_path": self.transcript_path,
+            "stop_hook_active": True,
+            "cwd": "/tmp",
+        }  # deliberately NO `prompt` / `user_prompt` key — mirrors real input
+        retain_spy = mock.Mock(return_value={"status": "ok"})
+        with patch("prefetch.retain_module.run_retain", retain_spy):
+            wrote = prefetch.run_prefetch(real_stop_input, self._config())
         self.assertFalse(wrote)
+        retain_spy.assert_not_called()
         self.assertFalse(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+        self.assertFalse(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+    def test_gate_keys_off_transcript_not_a_phantom_prompt_field(self):
+        # The mirror of the above: a genuine human turn in the transcript with
+        # a STRAY `prompt="<task-notification>"` on the hook input (the shape the
+        # old harness faked). The gate must key off the transcript (a real turn)
+        # and PROCEED, proving it no longer reads `hook_input["prompt"]`. Fails
+        # on the pre-fix code, which reads the phantom field and wrongly skips.
+        _write_transcript(self.transcript_path, [("user", "we shipped the release on friday")])
+        client = mock.Mock()
+        client.recall.side_effect = lambda *a, **kw: {"results": [
+            {"text": "we shipped the release on friday", "type": "fact",
+             "mentioned_at": "2026-01-01", "id": "r1", "scores": {"final": 0.9}},
+        ]}
+        hook_input = {
+            "session_id": SESSION,
+            "transcript_path": self.transcript_path,
+            "prompt": "<task-notification>phantom</task-notification>",
+            "cwd": "/tmp",
+        }
+        with patch("prefetch.retain_module.run_retain", return_value={"status": "ok"}), \
+                patch("prefetch.HindsightClient", return_value=client), \
+                patch("prefetch.get_api_url", return_value="http://fake"):
+            wrote = prefetch.run_prefetch(hook_input, self._config())
+        self.assertTrue(wrote)
+        self.assertTrue(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+
+
+class CurationSharingTests(PrefetchPipelineBase):
+    """F5 — the producer must run recalled candidates through recall's shared
+    curation pipeline (demote-drop + `recallMaxMemories` cap) BEFORE buffering,
+    so the buffer path cannot inject what the synchronous path would filter."""
+
+    def _run_with_results(self, results, config):
+        _write_transcript(self.transcript_path, [("user", "what do you remember about deploys")])
+        client = mock.Mock()
+        client.recall.side_effect = lambda *a, **kw: {"results": [dict(m) for m in results]}
+        with patch("prefetch.retain_module.run_retain", return_value={"status": "ok"}), \
+                patch("prefetch.HindsightClient", return_value=client), \
+                patch("prefetch.get_api_url", return_value="http://fake"):
+            wrote = prefetch.run_prefetch(self._hook_input("what do you remember about deploys"), config)
+        buffered = ""
+        if wrote:
+            payload = recall_buffer._read_buffer_payload(SESSION) or {}
+            buffered = payload.get("context") or ""
+        return wrote, buffered
+
+    def test_demote_tagged_memory_is_dropped_before_buffering(self):
+        results = [
+            {"text": "keep me visible", "type": "fact", "mentioned_at": "2026-01-01",
+             "id": "k1", "scores": {"final": 0.9}},
+            {"text": "secret demoted note", "type": "fact", "mentioned_at": "2026-01-01",
+             "id": "d1", "scores": {"final": 0.8}, "tags": ["demote-from-recall"]},
+        ]
+        _wrote, buffered = self._run_with_results(results, self._config())
+        self.assertIn("keep me visible", buffered)
+        self.assertNotIn(
+            "secret demoted note", buffered,
+            "a demote-from-recall memory must never reach the prefetch buffer",
+        )
+
+    def test_candidate_set_above_cap_is_truncated_before_buffering(self):
+        results = [
+            {"text": f"candidate {i}", "type": "fact", "mentioned_at": "2026-01-01",
+             "id": f"m{i}", "scores": {"final": 1.0 - i * 0.01}}
+            for i in range(12)
+        ]
+        config = self._config()
+        config["recallMaxMemories"] = 8
+        _wrote, buffered = self._run_with_results(results, config)
+        injected = sum(1 for i in range(12) if f"candidate {i}" in buffered)
+        self.assertEqual(
+            injected, 8,
+            "the prefetch buffer must honour recallMaxMemories, same as the sync path",
+        )
 
 
 if __name__ == "__main__":