switchroom 0.21.16 → 0.21.18

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/hooks/hooks.json

@@ -10,6 +10,15 @@
             "timeout": 30
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/orientation.py\"",
+            "timeout": 8
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [

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

@@ -64,6 +64,7 @@ from lib.directives import (  # noqa: E402
     parse_active_directives_block,
     rule_already_captured,
 )
+from lib import recall_buffer  # noqa: E402
 
 # Reuse Stage B's pleasantry scrub so "as always" / "always happy to help"
 # can't trip the high-confidence detector either. Imported lazily-safe: if
@@ -387,6 +388,37 @@ def invalidate_cache_on_directive_write(messages: list, config: dict) -> None:
         debug_log(config, f"Directives cache invalidation skipped (error): {e}")
 
 
+def invalidate_prefetch_buffer_on_directive_write(messages: list, config: dict, session_id: str) -> None:
+    """Drop this session's pending M4 prefetch buffer if this turn wrote a
+    directive (create/update/delete/retire).
+
+    red-team-M3 R2 (BLOCKER): the A4 cache invalidation above keeps the fresh
+    <active_directives> block current, but the M4 prefetch buffer carries a
+    RECALLED memories block captured at a prior turn's Stop — and a rule/
+    directive that was just retired can survive in that snapshot as recalled
+    text. Without this, a buffer prefetched while the rule was active would
+    re-inject the retired rule on the next turn (the exact §4.4 resurrection
+    failure), and `run_prefetch` bailing on an empty recall would leave that
+    stale buffer to be served on later turns too. Deleting the buffer + sentinel
+    here forces the consumer to fall to the synchronous, always-current path
+    (or the explicitly stale-marked fallback) instead of resurrecting it.
+
+    Only fires when `memoryPrefetchEnabled` is on (the buffer only exists then)
+    — a cheap no-op statting two absent files otherwise, so gated to avoid it.
+    Self-guarded; never raises (a Stop hook must not wedge a turn).
+    """
+    try:
+        if not messages or not config.get("memoryPrefetchEnabled", False):
+            return
+        idx, _text = find_last_human_turn(messages)
+        start = idx if idx is not None else -1
+        if turn_contains_directive_write(messages, start):
+            recall_buffer.invalidate(session_id or "unknown")
+            debug_log(config, "Prefetch buffer invalidated — turn wrote a directive (R2 resurrection guard)")
+    except Exception as e:  # pragma: no cover - defensive; Stop must not wedge
+        debug_log(config, f"Prefetch-buffer invalidation skipped (error): {e}")
+
+
 def read_transcript(transcript_path: str) -> list:
     """Read a JSONL transcript into a list of message dicts (role/content).
 
@@ -508,6 +540,7 @@ def main():
     #     and this is not an already-blocked re-fire.
     ttl = config.get("directivesCacheTtlSeconds", DIRECTIVES_CACHE_TTL_SECONDS)
     cache_on = isinstance(ttl, (int, float)) and ttl > 0
+    prefetch_on = bool(config.get("memoryPrefetchEnabled", False))
     verify_maybe = (
         config.get("directiveCaptureNudge", True)
         and config.get("directiveCaptureVerify", True)
@@ -515,7 +548,7 @@ def main():
     )
 
     messages: list = []
-    if cache_on or verify_maybe:
+    if cache_on or verify_maybe or prefetch_on:
         messages = read_transcript(hook_input.get("transcript_path", ""))
 
     # A4: invalidate the directives cache when this turn wrote a directive, so
@@ -524,6 +557,15 @@ def main():
     if cache_on:
         invalidate_cache_on_directive_write(messages, config)
 
+    # R2 (BLOCKER): invalidate this session's M4 prefetch buffer when this turn
+    # wrote/retired a directive, so a stale pre-retire snapshot can never
+    # resurrect the retired rule on a later turn. Self-guarded no-op when
+    # prefetch is off.
+    if prefetch_on:
+        invalidate_prefetch_buffer_on_directive_write(
+            messages, config, hook_input.get("session_id") or "unknown"
+        )
+
     try:
         reason = evaluate(hook_input, config, messages=messages)
     except Exception as e:  # never wedge a turn on a verify bug

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

@@ -519,3 +519,38 @@ class HindsightClient:
         if retain_mission:
             updates["retain_mission"] = retain_mission
         return self._request("PATCH", path, {"updates": updates}, timeout=timeout)
+
+    def list_mental_models(self, bank_id: str, timeout: int = 5) -> dict:
+        """List the mental models for a bank (Memory v2 M5 — orientation-at-boot).
+
+        The orientation SessionStart hook knows the orientation model by NAME
+        (the configured `memoryOrientationModel`), not by its `mm-…` id, so it
+        lists the bank's models and matches on name → id before reading content
+        (carve-M5 §0d/§3). Read-only GET on the ungated engine REST surface;
+        m5-0-probe measured the own-bank read at ~4ms on klanker.
+
+        REST: ``GET /v1/default/banks/{bank_id}/mental-models``. Returns the raw
+        response dict, expected to carry an ``items`` list where each item has at
+        least ``id`` and ``name``.
+        """
+        path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/mental-models"
+        return self._request("GET", path, timeout=timeout)
+
+    def get_mental_model(
+        self, bank_id: str, model_id: str, detail: str = "full", timeout: int = 5
+    ) -> dict:
+        """Read one mental model's content + freshness watermark (M5).
+
+        REST: ``GET /v1/default/banks/{bank_id}/mental-models/{model_id}?detail=full``
+        (m5-0-probe Q3/Q4 proved this returns ``content`` + the
+        ``last_refreshed_at`` watermark the staleness guard keys on, ~4ms warm).
+        Read-only; ungated. The caller wraps this in a generous read-timeout and
+        degrades to the cold notice on any error — a slow/failed read must never
+        block boot (carve §3 fail-safe).
+        """
+        bank = urllib.parse.quote(bank_id, safe="")
+        model = urllib.parse.quote(model_id, safe="")
+        path = f"/v1/default/banks/{bank}/mental-models/{model}"
+        if detail:
+            path = f"{path}?{urllib.parse.urlencode({'detail': detail})}"
+        return self._request("GET", path, timeout=timeout)

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

@@ -130,6 +130,20 @@ DEFAULTS = {
     # opt out per-agent via memory.profile_capture_nudge=false →
     # HINDSIGHT_PROFILE_CAPTURE_NUDGE.
     "profileCaptureNudge": True,
+    # Switchroom Memory v2 M3 Surface-A — directive-injection switch. When True
+    # (default), recall.py injects the `<active_directives>` block on every
+    # UserPromptSubmit at all three emit sites (main + prefetch/cache fast
+    # paths). When False (a flipped M3 canary), that injection is SUPPRESSED —
+    # the agent's standing rules come from the live rules block instead, which
+    # is the change that collapses the always-on directive-token spend (E-41).
+    # Suppression is fail-safe and re-checked every turn: it fires ONLY when a
+    # non-empty rules block is physically present in CLAUDE.md; a False flag
+    # with an empty/absent block keeps injecting AND emits a degraded-canary
+    # notice, so a zero-standing-rules turn is unreachable. Operators flip a
+    # canary per-agent via memory.inject_directives=false →
+    # HINDSIGHT_INJECT_DIRECTIVES; the ordered flip (rules_block live → migrate
+    # → this flag off) is enforced by `switchroom memory flip`.
+    "injectDirectives": True,
     # Switchroom #2873/#2903 Fix 6.2 — the BLOCKING half (Stage C
     # directive_verify.py Stop hook) split out from the advisory nudge. When
     # True (default) the verifier may block the stop once to re-prompt capture;
@@ -140,6 +154,23 @@ DEFAULTS = {
     # per-agent via memory.directive_capture_verify=false →
     # HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY.
     "directiveCaptureVerify": True,
+    # Memory v2 M5 — orientation-at-boot (Surface B). All four fail-safe by
+    # default so a stripped/absent key (the Zod-strip footgun, carve §1) boots
+    # exactly as pre-M5. `memoryOrientationEnabled` is the per-agent kill switch,
+    # default OFF (dark build — the orientation SessionStart hook no-ops before
+    # any bank resolve or network call when off). `memoryOrientationModel` is the
+    # mental-model NAME the hook resolves to an id (the agent's OWN bank).
+    # `memoryOrientationCadenceHours` is the per-agent refresh cadence tier
+    # (klanker/overlord 24, everyone else 48) the staleness guard's per-tier
+    # thresholds (1.5×/3×) key on. `memoryOrientationReinjectTurns` is the
+    # epic's optional per-turn re-inject knob, default 0 = SessionStart+compaction
+    # only (the cheap path; N>0 is the ~55M/30d-at-every-turn expensive variant,
+    # which is why it defaults off). Delivered per-agent via the scaffold
+    # settings.json stamp and overridable via the HINDSIGHT_ORIENTATION_* env.
+    "memoryOrientationEnabled": False,
+    "memoryOrientationModel": "orientation",
+    "memoryOrientationCadenceHours": 48,
+    "memoryOrientationReinjectTurns": 0,
     # Switchroom hindsight-leverage A4 — TTL (seconds) for the directives-list
     # cache on the recall critical path (see lib/directives.py). The list is
     # re-fetched at most once per TTL window for no-write turns; in-session
@@ -510,11 +541,27 @@ ENV_OVERRIDES = {
     # it; the switchroom default is on (settings.json pins true; recall.py falls
     # back to True).
     "HINDSIGHT_PROFILE_CAPTURE_NUDGE": ("profileCaptureNudge", bool),
+    # Switchroom Memory v2 M3 Surface-A: directive-injection switch on/off. Set
+    # by start.sh from agents.<name>.memory.inject_directives only when the
+    # operator overrode it; the switchroom default is on (settings.json pins
+    # true; recall.py falls back to True). False SUPPRESSES the
+    # <active_directives> injection for a flipped canary, fail-safe on a live
+    # rules block (see recall.py directive_injection_decision).
+    "HINDSIGHT_INJECT_DIRECTIVES": ("injectDirectives", bool),
     # Switchroom #2873/#2903 Fix 6.2: the Stage C block on/off, independent of
     # the Stage B nudge. Set by start.sh from
     # agents.<name>.memory.directive_capture_verify only when the operator
     # overrode it; the switchroom default is on.
     "HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY": ("directiveCaptureVerify", bool),
+    # Memory v2 M5 — orientation-at-boot. Env override channel for the four
+    # orientation knobs (settings.json carries the per-agent value; env wins for
+    # a docker-exec'd hook or an agent `env:` map). `memoryOrientationEnabled`
+    # is the per-agent kill switch (default off); the model NAME, cadence tier,
+    # and reinject count follow. See DEFAULTS above and carve-M5 §4.
+    "HINDSIGHT_ORIENTATION_ENABLED": ("memoryOrientationEnabled", bool),
+    "HINDSIGHT_ORIENTATION_MODEL": ("memoryOrientationModel", str),
+    "HINDSIGHT_ORIENTATION_CADENCE_HOURS": ("memoryOrientationCadenceHours", int),
+    "HINDSIGHT_ORIENTATION_REINJECT_TURNS": ("memoryOrientationReinjectTurns", int),
     # Switchroom hindsight-leverage A4 — directives-list cache TTL (seconds).
     # 0 disables the cache (rollback lever).
     "HINDSIGHT_DIRECTIVES_CACHE_TTL_SECONDS": ("directivesCacheTtlSeconds", int),