switchroom 0.21.17 → 0.21.19

package/telegram-plugin/uat/flip/tier2-probe-runner.ts

@@ -0,0 +1,327 @@
+#!/usr/bin/env bun
+/**
+ * M3 directive-flip UAT — Tier-2 behavioural probe runner.
+ *
+ * The model-in-the-loop half of the flip gate: drives a real Telegram
+ * user-account (the same mtcute `Driver` the rest of `uat/` uses) against a
+ * TARGET agent and, per probe, verifies the agent still HONOURS its migrated
+ * guardrails in live conversation. Deterministic scoring only — every reply is
+ * regex-matched against the probe's `passPattern` (see `probe-scoring.ts`); NO
+ * LLM judge.
+ *
+ * Per probe: DM the benign prompt → `expectMessage` for the agent's answer →
+ * score → repeat k times with ≥`spacingMs` between sends (default 30s, which
+ * dominates the gateway's coalescing gap and keeps us under the user-account
+ * flood cap). Folds k attempts into GREEN (3/3) / AMBER (2/3) / RED (≤1/3), and
+ * writes one `flip/results/<agent>.<phase>.json` conforming to
+ * `Tier2ProbeResults`. A separate baseline + postflip run produce two files a
+ * caller diffs with `detectRegressions` (postflip rate < baseline rate).
+ *
+ * SAFETY: this runner only ever SENDS benign questions. It never flips an
+ * agent, never edits config, and the probe suites are authored to contain no
+ * actionable instruction with tool side-effects. Point it only at internal
+ * test agents.
+ *
+ * Targeting mirrors `runners/agent-self-sufficiency.ts`: `--agent name:@bot`
+ * (repeatable) or `UAT_FLEET="name:@bot,..."`. Auth env (via repo-root `.env`,
+ * loaded by `loadUatEnv`): TELEGRAM_API_ID, TELEGRAM_API_HASH,
+ * TELEGRAM_UAT_DRIVER_SESSION.
+ *
+ * Usage:
+ *   bun telegram-plugin/uat/flip/tier2-probe-runner.ts \
+ *       --agent test-harness:@meken_switchroom_test_bot \
+ *       --phase baseline
+ *
+ *   # smoke: one benign probe, single repeat
+ *   bun telegram-plugin/uat/flip/tier2-probe-runner.ts \
+ *       --agent test-harness:@meken_switchroom_test_bot --phase baseline --k 1 --smoke
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Driver, type ObservedMessage } from "../driver.js";
+import { loadUatEnv } from "../load-env.js";
+import { expectMessage, isAnswer } from "../assertions.js";
+import { loadProbeSuite, type ProbeSpec, type ProbeSuite } from "./probe-suite.js";
+import {
+  foldPhase,
+  foldProbe,
+  scoreAttempt,
+} from "./probe-scoring.js";
+import type { Tier2ProbeAttempt, Tier2ProbeOutcome, Tier2ProbeResults, ProbePhase } from "./gate.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+// ─── CLI / env parsing ──────────────────────────────────────────────────────
+
+interface AgentTarget {
+  name: string;
+  botUsername: string;
+}
+
+interface CliConfig {
+  agents: AgentTarget[];
+  phase: ProbePhase;
+  /** Repeats per probe. Default 3. */
+  k: number;
+  /** Minimum gap between sends of the same probe, ms. Default 30_000. */
+  spacingMs: number;
+  /** Per-reply observation deadline, ms. Default 120_000. */
+  replyTimeoutMs: number;
+  /** Output directory for `<agent>.<phase>.json`. Default `<flip>/results`. */
+  outDir: string;
+  /** Explicit suite path override (single-agent runs). */
+  suitePath?: string;
+  /** Smoke mode: run only the FIRST probe of the suite, k forced to its value
+   *  (typically 1). Proves transport without a full behavioural sweep. */
+  smoke: boolean;
+}
+
+function fail(msg: string): never {
+  process.stderr.write(`[tier2] ${msg}\n`);
+  process.exit(2);
+}
+
+function parseCli(argv: readonly string[]): CliConfig {
+  const agents = new Map<string, AgentTarget>();
+  let phase: ProbePhase = (process.env.UAT_FLIP_PHASE as ProbePhase) || "baseline";
+  let k = Number.parseInt(process.env.UAT_PROBE_K ?? "3", 10);
+  let spacingMs = Number.parseInt(process.env.UAT_PROBE_SPACING_MS ?? "30000", 10);
+  let replyTimeoutMs = Number.parseInt(process.env.UAT_PROBE_TIMEOUT_MS ?? "120000", 10);
+  let outDir = process.env.UAT_PROBE_OUT_DIR ?? path.join(HERE, "results");
+  let suitePath: string | undefined;
+  let smoke = false;
+
+  const envFleet = process.env.UAT_FLEET;
+  if (envFleet) {
+    for (const tok of envFleet.split(",")) {
+      const [name, bot] = tok.split(":").map((s) => s.trim());
+      if (name && bot) agents.set(name, { name, botUsername: bot });
+    }
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i]!;
+    const next = (): string => {
+      const v = argv[++i];
+      if (v === undefined) fail(`${tok}: missing value`);
+      return v;
+    };
+    switch (tok) {
+      case "--agent": {
+        const v = next();
+        const [name, bot] = v.split(":").map((s) => s.trim());
+        if (!name || !bot) fail(`--agent expects "<name>:@<bot-username>"; got "${v}"`);
+        agents.set(name, { name, botUsername: bot });
+        break;
+      }
+      case "--phase": {
+        const v = next();
+        if (v !== "baseline" && v !== "postflip") fail(`--phase must be baseline|postflip; got "${v}"`);
+        phase = v;
+        break;
+      }
+      case "--k":
+        k = Number.parseInt(next(), 10);
+        break;
+      case "--spacing-ms":
+        spacingMs = Number.parseInt(next(), 10);
+        break;
+      case "--reply-timeout-ms":
+        replyTimeoutMs = Number.parseInt(next(), 10);
+        break;
+      case "--out-dir":
+        outDir = next();
+        break;
+      case "--suite":
+        suitePath = next();
+        break;
+      case "--smoke":
+        smoke = true;
+        break;
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+        break;
+      default:
+        if (tok.startsWith("--")) fail(`unknown flag: ${tok}`);
+    }
+  }
+
+  if (agents.size === 0) {
+    fail('no agent targeted. Pass --agent <name>:@<bot> or set UAT_FLEET. Tier-2 probes only ever target internal TEST agents.');
+  }
+  if (!Number.isFinite(k) || k < 1) fail(`--k must be a positive integer; got ${k}`);
+  if (suitePath && agents.size > 1) {
+    fail("--suite is a single-agent override; pass exactly one --agent with it");
+  }
+
+  return {
+    agents: [...agents.values()],
+    phase,
+    k,
+    spacingMs,
+    replyTimeoutMs,
+    outDir,
+    ...(suitePath ? { suitePath } : {}),
+    smoke,
+  };
+}
+
+function printHelp(): void {
+  process.stdout.write(`M3 directive-flip Tier-2 behavioural probe runner
+
+Required env (or fail loud):
+  TELEGRAM_API_ID, TELEGRAM_API_HASH, TELEGRAM_UAT_DRIVER_SESSION
+
+Flags:
+  --agent NAME:@BOT      Target agent. Repeatable. (INTERNAL TEST AGENTS ONLY.)
+  --phase baseline|postflip   Which flip phase this run records. Default baseline.
+  --k N                  Repeats per probe. Default 3.
+  --spacing-ms N         Min gap between sends of a probe. Default 30000.
+  --reply-timeout-ms N   Per-reply deadline. Default 120000.
+  --out-dir DIR          Results dir. Default <flip>/results.
+  --suite PATH           Suite override (single --agent). Default probes/<agent>.probes.json.
+  --smoke                Run only the first probe (transport check).
+
+Env equivalents: UAT_FLEET, UAT_FLIP_PHASE, UAT_PROBE_K, UAT_PROBE_SPACING_MS,
+  UAT_PROBE_TIMEOUT_MS, UAT_PROBE_OUT_DIR
+`);
+}
+
+// ─── Live probe execution ─────────────────────────────────────────────────────
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, Math.max(0, ms)));
+
+/**
+ * Send one probe prompt and wait for the agent's answer. Uses the prescribed
+ * seam: `sendText` then `expectMessage(driver, botId, matcher, {timeout})`,
+ * where the matcher is `isAnswer` so worker-feed / activity-card surfaces and
+ * the driver's own echo are excluded. Returns a scored {@link Tier2ProbeAttempt}.
+ */
+async function runOneAttempt(
+  driver: Driver,
+  botUserId: number,
+  driverUserId: number,
+  spec: ProbeSpec,
+  timeoutMs: number,
+): Promise<Tier2ProbeAttempt> {
+  const startedAt = Date.now();
+  try {
+    await driver.sendText(botUserId, spec.prompt);
+  } catch (err) {
+    return scoreAttempt(spec, "", Date.now() - startedAt, "error", `send failed: ${(err as Error).message}`);
+  }
+  try {
+    const answer: ObservedMessage = await expectMessage(
+      driver,
+      botUserId,
+      (m) => isAnswer(m, driverUserId),
+      { timeout: timeoutMs, senderFilter: { notUserId: driverUserId } },
+    );
+    return scoreAttempt(spec, answer.text, Date.now() - startedAt, "reply");
+  } catch (err) {
+    const msg = (err as Error).message;
+    const kind = /within \d+ms/.test(msg) ? "timeout" : "error";
+    return scoreAttempt(spec, "", Date.now() - startedAt, kind, msg);
+  }
+}
+
+async function runAgent(
+  driver: Driver,
+  driverUserId: number,
+  target: AgentTarget,
+  suite: ProbeSuite,
+  suiteLabel: string,
+  cli: CliConfig,
+): Promise<Tier2ProbeResults> {
+  process.stdout.write(`\n[tier2] ─── agent: ${target.name} (${target.botUsername}) phase=${cli.phase} ───\n`);
+  const botUserId = await driver.resolveBotUserId(target.botUsername);
+  process.stdout.write(`[tier2] resolved ${target.botUsername} → bot_user_id=${botUserId}\n`);
+
+  const probes = cli.smoke ? suite.probes.slice(0, 1) : suite.probes;
+  if (cli.smoke) process.stdout.write(`[tier2] SMOKE mode: running only "${probes[0]?.id}"\n`);
+
+  const outcomes: Tier2ProbeOutcome[] = [];
+  for (const spec of probes) {
+    const attempts: Tier2ProbeAttempt[] = [];
+    for (let rep = 0; rep < cli.k; rep++) {
+      const a = await runOneAttempt(driver, botUserId, driverUserId, spec, cli.replyTimeoutMs);
+      attempts.push(a);
+      const glyph = a.pass ? "✓" : a.outcome === "timeout" ? "·" : "✗";
+      process.stdout.write(
+        `[tier2]   ${glyph} ${spec.id} rep ${rep + 1}/${cli.k} (${a.outcome}, ${a.durationMs}ms)\n`,
+      );
+      // Space repeats of the SAME probe by ≥ spacingMs (respect coalescing +
+      // flood limits). No wait after the final repeat of the final probe.
+      const isLast = rep === cli.k - 1 && spec === probes[probes.length - 1];
+      if (!isLast) await sleep(cli.spacingMs);
+    }
+    const folded = foldProbe(spec, attempts);
+    process.stdout.write(`[tier2]   → ${spec.id}: ${folded.verdict} (${folded.passCount}/${folded.k})\n`);
+    outcomes.push(folded);
+  }
+
+  return foldPhase(target.name, cli.phase, suiteLabel, outcomes);
+}
+
+// ─── Main ──────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  loadUatEnv();
+  const cli = parseCli(process.argv.slice(2));
+
+  const apiId = Number.parseInt(process.env.TELEGRAM_API_ID ?? "", 10);
+  if (!Number.isFinite(apiId)) fail("TELEGRAM_API_ID missing or non-integer — see telegram-plugin/uat/SETUP.md");
+  const apiHash = process.env.TELEGRAM_API_HASH ?? "";
+  if (!apiHash) fail("TELEGRAM_API_HASH missing — see SETUP.md");
+  const session = process.env.TELEGRAM_UAT_DRIVER_SESSION ?? "";
+  if (!session) fail("TELEGRAM_UAT_DRIVER_SESSION missing — run `bun run uat:login` first (SETUP.md §4)");
+
+  // Resolve + validate every suite BEFORE connecting, so a bad suite fails
+  // without spending a live session.
+  const plans = cli.agents.map((target) => {
+    const suitePath = cli.suitePath ?? path.join(HERE, "probes", `${target.name}.probes.json`);
+    const suite = loadProbeSuite(suitePath);
+    if (suite.agent !== target.name) {
+      fail(`suite ${suitePath} declares agent "${suite.agent}" but target is "${target.name}"`);
+    }
+    return { target, suite, suiteLabel: path.basename(suitePath) };
+  });
+
+  process.stdout.write(`[tier2] connecting to Telegram as the UAT driver account...\n`);
+  const driver = new Driver({ apiId, apiHash, session });
+  await driver.connect();
+  const driverUserId = await driver.getMyUserId();
+  process.stdout.write(`[tier2] driver user_id=${driverUserId}\n`);
+
+  mkdirSync(cli.outDir, { recursive: true });
+  const written: string[] = [];
+  try {
+    for (const plan of plans) {
+      const results = await runAgent(driver, driverUserId, plan.target, plan.suite, plan.suiteLabel, cli);
+      const outPath = path.join(cli.outDir, `${plan.target.name}.${cli.phase}.json`);
+      writeFileSync(outPath, `${JSON.stringify(results, null, 2)}\n`, "utf-8");
+      written.push(outPath);
+      process.stdout.write(
+        `[tier2] wrote ${outPath} — phase ${results.pass ? "PASS" : "FAIL"} ` +
+          `(${(results.probes ?? []).filter((p) => p.verdict === "GREEN").length}/${(results.probes ?? []).length} GREEN)\n`,
+      );
+    }
+  } finally {
+    await driver.disconnect();
+  }
+
+  process.stdout.write(`\n[tier2] done. wrote ${written.length} result file(s):\n`);
+  for (const w of written) process.stdout.write(`  ${w}\n`);
+}
+
+// Only run when invoked directly (not when imported by a test).
+if (import.meta.main) {
+  main().catch((err) => {
+    process.stderr.write(`[tier2] fatal: ${(err as Error).stack ?? err}\n`);
+    process.exit(1);
+  });
+}

package/telegram-plugin/uat/runners/scorer.ts

@@ -60,7 +60,7 @@ export function scoreReply(
  * whitespace. Permissive on purpose — the scorer's regex matches
  * against words, not formatting.
  */
-function stripMarkdown(s: string): string {
+export function stripMarkdown(s: string): string {
   return s
     .replace(/```[\s\S]*?```/g, " ")
     .replace(/`([^`]+)`/g, "$1")

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: