switchroom 0.19.2 → 0.19.3

package/telegram-plugin/tests/session-tail-first-attach.test.ts

@@ -1,8 +1,13 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { mkdtempSync, rmSync, writeFileSync, statSync } from 'node:fs'
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, appendFileSync, statSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { computeFirstAttachCursor } from '../session-tail.js'
+import {
+  computeFirstAttachCursor,
+  getProjectsDirForCwd,
+  startSessionTail,
+  type SessionEvent,
+} from '../session-tail.js'
 
 /**
  * computeFirstAttachCursor: on first attach to a transcript, seek to EOF
@@ -63,3 +68,111 @@ describe('computeFirstAttachCursor', () => {
     expect(computeFirstAttachCursor(missing, 0)).toBe(0)
   })
 })
+
+// ── #3427 H2: first-attach replay marks `model` events as replayed ───────────
+//
+// A /model relaunch during an active turn is EXACTLY the shape that triggers
+// the in-flight-turn replay above: the new gateway attaches to the OLD
+// session's JSONL and replays its enqueue + assistant lines — which carry the
+// PRE-relaunch model. Those replayed `model` observations must be flagged so
+// the divergence tripwire (session-model-source) ignores them; live lines
+// appended after attach must NOT be flagged. Outcome-asserted against the
+// real tailer, not the source.
+
+describe('startSessionTail — replayed model events are flagged (#3427 H2)', () => {
+  const tempDirs: string[] = []
+  afterEach(() => {
+    for (const d of tempDirs) {
+      try { rmSync(d, { recursive: true, force: true }) } catch { /* ignore */ }
+    }
+    tempDirs.length = 0
+  })
+
+  function mkProjectsDir(): { claudeHome: string; cwd: string; projectsDir: string } {
+    const base = mkdtempSync(join(tmpdir(), 'first-attach-replayed-'))
+    tempDirs.push(base)
+    const cwd = join(base, 'agent')
+    const claudeHome = join(base, 'claude-home')
+    const projectsDir = getProjectsDirForCwd(cwd, claudeHome)
+    mkdirSync(projectsDir, { recursive: true })
+    return { claudeHome, cwd, projectsDir }
+  }
+
+  const wait = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+
+  const assistantModelLine = (model: string): string =>
+    JSON.stringify({
+      type: 'assistant',
+      message: { model, content: [{ type: 'text', text: 'hi' }] },
+    }) + '\n'
+
+  function modelEvents(events: SessionEvent[]): Array<{ model: string; replayed?: boolean }> {
+    return events.filter((e): e is Extract<SessionEvent, { kind: 'model' }> => e.kind === 'model')
+  }
+
+  it('mid-turn restart: replayed OLD-model lines carry replayed:true; a live line appended after attach does not', async () => {
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const file = join(projectsDir, 'sess.jsonl')
+    // The pre-relaunch session ended mid-turn: enqueue with no turn_duration,
+    // followed by an assistant line served by the OLD model.
+    writeFileSync(
+      file,
+      ENQUEUE + '\n' + DEQUEUE + '\n' + assistantModelLine('claude-opus-4-8'),
+    )
+
+    const events: SessionEvent[] = []
+    const handle = startSessionTail({
+      cwd,
+      claudeHome,
+      rescanIntervalMs: 50,
+      onEvent: (ev) => { events.push(ev) },
+    })
+    try {
+      await wait(200) // attach + replay the in-flight turn
+      const replayedBatch = modelEvents(events)
+      expect(replayedBatch.length).toBeGreaterThan(0)
+      // THE H2 false-positive shape: the old model arrives AFTER boot — but
+      // flagged, so the divergence tripwire skips it.
+      expect(replayedBatch[0]).toMatchObject({ model: 'claude-opus-4-8', replayed: true })
+
+      // The live session now writes its first assistant line (new model).
+      appendFileSync(file, assistantModelLine('claude-sonnet-5'))
+      await wait(200)
+      const all = modelEvents(events)
+      const live = all[all.length - 1]
+      expect(live.model).toBe('claude-sonnet-5')
+      expect(live.replayed).not.toBe(true)
+    } finally {
+      handle.stop()
+    }
+  })
+
+  it('completed-turn attach (no replay): appended model lines are never flagged', async () => {
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const file = join(projectsDir, 'sess.jsonl')
+    writeFileSync(
+      file,
+      ENQUEUE + '\n' + assistantModelLine('claude-opus-4-8') + TURN_DURATION + '\n',
+    )
+
+    const events: SessionEvent[] = []
+    const handle = startSessionTail({
+      cwd,
+      claudeHome,
+      rescanIntervalMs: 50,
+      onEvent: (ev) => { events.push(ev) },
+    })
+    try {
+      await wait(200) // attach seeks to EOF — no replay
+      expect(modelEvents(events)).toHaveLength(0)
+      appendFileSync(file, assistantModelLine('claude-sonnet-5'))
+      await wait(200)
+      const all = modelEvents(events)
+      expect(all.length).toBeGreaterThan(0)
+      expect(all[all.length - 1].model).toBe('claude-sonnet-5')
+      expect(all[all.length - 1].replayed).not.toBe(true)
+    } finally {
+      handle.stop()
+    }
+  })
+})

package/vendor/hindsight-memory/CHANGELOG.md

@@ -4,6 +4,108 @@
 
 ### Changed (switchroom divergence)
 
+- **`recallContextTurns` default `1` → `2`** (switchroom hindsight-leverage
+  PR2, workstream A2). A bare follow-up user message ("and the port?", "what
+  about staging?") now embeds together with its antecedent human turn in the
+  recall query, instead of recalling on the pronoun alone. Depends on PR1's
+  (#3435) `<channel>` envelope strip so the composed 2-turn query stays
+  envelope-free (both the trailing latest segment and the `Prior context:`
+  lines). The composition is bounded by `recallMaxQueryChars` (800) —
+  `truncate_recall_query` preserves the latest turn and drops oldest context
+  first, so a large antecedent can never blow the recall query budget.
+- **New `recallTranscriptTailBytes` (default `262144`)** — latency bound for
+  multi-turn recall. With `recallContextTurns > 1` now the default, every
+  recall reads the transcript to slice prior turns; `read_transcript_messages`
+  now byte-tail-bounds that read (seek to `EOF - tail_bytes`, discard the
+  partial first line, parse only complete trailing lines) so the added
+  per-recall read stays O(1) regardless of session `.jsonl` size. `0` reads the
+  whole file (rollback lever). Env: `HINDSIGHT_RECALL_TRANSCRIPT_TAIL_BYTES`.
+
+### Added (switchroom divergence)
+
+- **retain.py + recall.py: lesson/anti-pattern tagging → recall demotion**
+  (switchroom hindsight-leverage PR9, workstream E2, #398). Closes the corpus-
+  hygiene half of #398: a retained transcript that captures a self-recognised
+  lesson ("lesson learned", "note to self:") or a failure mode ("anti-pattern:",
+  "what not to do") is now deterministically tagged (`lesson` / `anti-pattern`)
+  at retain time by `retain.detect_lesson_tags` — a case-insensitive substring
+  match against the configurable `lessonTagMarkers` map (NOT model-dependent),
+  wired into `build_retain_payload` so it applies to both Stop-hook and sidechain
+  retains without clobbering configured `retainTags`. Recall then DEMOTES those
+  tags via the PR5 score-penalty weight map: `recall._effective_tag_weights`
+  merges built-in `lessonDemotionWeights` (`{lesson: 0.85, anti-pattern: 0.5}`)
+  UNDER `recallTagWeights`, so a failure-mode-adjacent transcript ranks below a
+  clean equal-score session memory yet is NEVER hard-dropped (re-rank, not the
+  demote-tag DROP filter) and still surfaces when it is the only relevant hit.
+  Precedence: an explicit `recallTagWeights` entry wins over the built-in for the
+  same tag; the PR5 `sidechain: 0.8` seed composes cleanly. Toggles:
+  `HINDSIGHT_LESSON_TAGGING=false` (retain side), `HINDSIGHT_LESSON_DEMOTION=false`
+  (recall side) as rollback levers; `HINDSIGHT_LESSON_TAG_MARKERS` /
+  `HINDSIGHT_LESSON_DEMOTION_WEIGHTS` (JSON) for overrides. NON-GOAL
+  (epic-recorded): the historical corpus is NOT re-tagged — this fires on NEW
+  retains only. Acceptance: `scripts/tests/test_lesson_tagging.py`.
+
+- **recall.py: parallel multi-bank recall under one shared deadline**
+  (switchroom hindsight-leverage PR3, workstream A3 stage 2). The directives
+  fetch and every bank recall (own + additional/profile/shared/sender banks)
+  now run CONCURRENTLY in daemon threads via `lib/parallel_recall.py`
+  (`run_parallel`), bounded by ONE shared deadline
+  (`recallParallelDeadlineSeconds`, default 10 = the 12s UserPromptSubmit hook
+  ceiling minus 2s headroom). Serially the round-trips SUM, so a heavy
+  multi-bank agent could breach the ceiling and drop recall entirely; parallel
+  makes the critical path the SLOWEST slot. A slot still running at the deadline
+  is abandoned (daemon thread, reaped on process exit) and marked `timed_out` —
+  a straggler bank can never hold the hook open past its ceiling; `recall.py`'s
+  `__main__` additionally `os._exit(0)`s (after a stdout flush) as a
+  belt-and-suspenders. The directives slot is dedicated and composes with the A4
+  directives cache (a cache HIT returns near-instantly with no HTTP). Env-gated
+  rollback: `HINDSIGHT_RECALL_PARALLEL=false` restores the pre-A3 serial path.
+  The `deadline_hit` telemetry field (shipped interim in PR1) is FINALIZED:
+  True when any bank raised a hard per-request timeout OR any bank/directives
+  slot was abandoned at the shared deadline; serial mode reduces to the pre-A3
+  per-bank-only form so both modes' `recall_log.jsonl` rows stay comparable in
+  the breach baseline. New log fields: `recall_mode`, `deadline_budget_ms`
+  (the CONFIGURED budget), `deadline_effective_ms` (the smaller wait the slots
+  actually got after pre-fan-out spend; null in serial mode / on cache hits),
+  `directives_timed_out`. Acceptance: `scripts/tests/test_recall_parallel_deadline.py`
+  (stub-timing tests proving a 3s bank cannot breach a 0.6s deadline).
+
+- **SubagentStop sidechain retain** (switchroom hindsight-leverage PR5). New
+  `scripts/subagent_retain.py`, registered on the `SubagentStop` event in
+  `hooks/hooks.json` (async, 15s). Delegated (Task-tool / sub-agent) work was
+  the biggest systematic memory hole — the main-session Stop retain only reads
+  the parent `transcript_path`, so a worker's process facts reached memory only
+  as its terse final report. This hook retains a bounded window (last 40 human
+  turns) of the *sidechain* transcript, tagged `sidechain` +
+  `parent_session:<id>`, with a deterministic content-derived `document_id` in a
+  distinct namespace (`{session}-sub-{agent}-r{start}-{end}`) so re-fires upsert.
+  Failures enqueue to the same `pending-retains` durability queue the Stop retain
+  uses. A **volume gate** (< 6 human turns OR < 2,000 chars of non-tool-result
+  text) skips trivial forks (every Task fires SubagentStop, including
+  10-second ones). Empirically probed on Claude Code 2.1.215: the hook input
+  carries a first-class `agent_transcript_path` pointing at
+  `<project>/<session>/subagents/agent-<agent_id>.jsonl` (used as the primary
+  path), with a directory-scan of the newest `isSidechain:true` jsonl as the
+  fallback for CLIs that omit the field. `reconcile_tail.py` and any transcript
+  sweeper now **skip** sidechain transcripts (shared
+  `content.transcript_first_line_is_sidechain` predicate) so the boot reconciler
+  cannot re-retain a sub-agent fork as a pseudo-session — untagged, at full
+  recall weight, bypassing the volume gate — which its recursive `**/*.jsonl`
+  glob would otherwise do one restart after any worker.
+
+- **recall.py: `recallTagWeights` per-tag score penalty** (switchroom
+  hindsight-leverage PR5). A `{tag: multiplier}` config map (default `{}`,
+  env `HINDSIGHT_RECALL_TAG_WEIGHTS`) applied to each result's `scores.final`
+  immediately before the relevance sort. Unlike the demote-tag DROP filter
+  (`_is_demoted_memory`), which removes a tagged memory from recall entirely,
+  this DEMOTES (down-ranks) a memory while keeping it recallable when it is the
+  only relevant hit — the "reduced weight" the drop filter cannot express.
+  Switchroom's scaffold seeds `{"sidechain": 0.8}` so delegated-worker
+  process-memories rank just below first-party session memory. **Candidate to
+  upstream** — a general recall-shaping primitive, not switchroom-specific.
+
+### Changed (switchroom divergence)
+
 - **retain.py: decouple chunked window-slicing from the `retainEveryNTurns > 1`
   throttle** (switchroom Phase 6b). Previously the chunked sliding-window only
   applied when `retainEveryNTurns > 1`; with `retainEveryNTurns=1` (switchroom

package/vendor/hindsight-memory/README.md

@@ -183,8 +183,9 @@ Auto-recall runs on every user prompt. It queries Hindsight for relevant memorie
 | `recallBudget` | `HINDSIGHT_RECALL_BUDGET` | `"mid"` | Controls how hard Hindsight searches for memories. `"low"` = fast, fewer strategies; `"mid"` = balanced; `"high"` = thorough, slower. Affects latency directly. |
 | `recallMaxTokens` | `HINDSIGHT_RECALL_MAX_TOKENS` | `1024` | Maximum number of tokens in the recalled memory block. Lower values reduce context usage but may truncate relevant memories. |
 | `recallTypes` | — | `["world", "experience"]` | Which memory types to retrieve. `"world"` = general facts; `"experience"` = personal experiences; `"observation"` = raw observations. |
-| `recallContextTurns` | `HINDSIGHT_RECALL_CONTEXT_TURNS` | `1` | How many prior conversation turns to include when composing the recall query. `1` = only the latest user message; higher values give more context but may dilute the query. |
+| `recallContextTurns` | `HINDSIGHT_RECALL_CONTEXT_TURNS` | `2` | How many prior conversation turns to include when composing the recall query. `1` = only the latest user message; `2` (default) also embeds the antecedent human turn so a bare follow-up ("and the port?") recalls with context instead of on the pronoun alone. Higher values give more context but may dilute the query. The composed query is always bounded by `recallMaxQueryChars` (latest turn preserved, oldest context dropped first). |
 | `recallMaxQueryChars` | `HINDSIGHT_RECALL_MAX_QUERY_CHARS` | `800` | Maximum character length of the query sent to Hindsight. Longer queries are truncated. |
+| `recallTranscriptTailBytes` | `HINDSIGHT_RECALL_TRANSCRIPT_TAIL_BYTES` | `262144` | Latency bound for multi-turn recall (`recallContextTurns > 1`): read only the last N bytes of the session transcript when slicing prior turns, so the per-recall read stays cheap on long sessions. `0` reads the whole file. |
 | `recallRoles` | — | `["user", "assistant"]` | Which message roles to include when building the recall query from prior turns. |
 | `recallTags` | `HINDSIGHT_RECALL_TAGS` | `[]` | Optional tags to pass to the recall API, such as `["memory_type:rule"]`. The env var accepts JSON or a comma-separated list. |
 | `recallTagsMatch` | `HINDSIGHT_RECALL_TAGS_MATCH` | `"any"` | Tag matching mode used with `recallTags` or `recallTagGroups`: `"any"`, `"all"`, `"any_strict"`, or `"all_strict"`. |

package/vendor/hindsight-memory/hooks/hooks.json

@@ -43,6 +43,18 @@
         ]
       }
     ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/subagent_retain.py\"",
+            "timeout": 15,
+            "async": true
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

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

@@ -59,6 +59,8 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 from lib.config import debug_log, load_config  # noqa: E402
 from lib.directives import (  # noqa: E402
+    DIRECTIVES_CACHE_TTL_SECONDS,
+    invalidate_directives_cache,
     parse_active_directives_block,
     rule_already_captured,
 )
@@ -317,6 +319,70 @@ def directive_recorded_after(messages: list, start_index: int) -> bool:
     return False
 
 
+# --- Directives-cache invalidation (switchroom hindsight-leverage A4) ---------
+#
+# recall.py caches the bank's active-directives list with a short TTL to skip an
+# HTTP round-trip on the critical path. That cache would otherwise stay stale
+# until the TTL elapsed — so this Stop hook, which already re-reads the turn's
+# transcript, deletes the cache whenever the just-ended turn performed a
+# directive WRITE (create/update/delete). The next recall then re-fetches, so an
+# in-session directive change is visible in the very next turn's
+# <active_directives> block (cross-process writes still rely on TTL alone).
+
+# Matches the hindsight directive-write MCP tools by their bare or namespaced
+# name, e.g. "create_directive", "mcp__hindsight__update_directive",
+# "delete_directive". Read-only "list_directives" is deliberately excluded.
+_DIRECTIVE_WRITE_TOOL_RE = re.compile(r"(?:create|update|delete)_directive")
+
+
+def _is_directive_write_tool(name) -> bool:
+    return isinstance(name, str) and bool(_DIRECTIVE_WRITE_TOOL_RE.search(name))
+
+
+def turn_contains_directive_write(messages: list, start_index: int) -> bool:
+    """True if any assistant turn after ``start_index`` issued a directive-write
+    tool_use (create/update/delete). ``start_index = -1`` scans all messages
+    (used when there is no human turn, e.g. a synthetic/cron inbound that still
+    wrote a directive). Pure inspection; no API call."""
+    for msg in messages[start_index + 1:]:
+        if not isinstance(msg, dict) or msg.get("role") != "assistant":
+            continue
+        content = msg.get("content")
+        if not isinstance(content, list):
+            continue
+        for p in content:
+            if (
+                isinstance(p, dict)
+                and p.get("type") == "tool_use"
+                and _is_directive_write_tool(p.get("name", ""))
+            ):
+                return True
+    return False
+
+
+def invalidate_cache_on_directive_write(messages: list, config: dict) -> None:
+    """Delete the directives cache if this turn wrote a directive.
+
+    Takes the ALREADY-READ transcript ``messages`` (main() reads the transcript
+    exactly once and shares it with the capture verifier — a Stop hook must not
+    parse a multi-MB session twice). Only the tail after the last human turn is
+    scanned, since only writes issued THIS turn matter. Runs independently of
+    the capture-verify decision (and of the directiveCaptureNudge knob) — the
+    cache is a separate feature. Best-effort; never raises, so a bug here can
+    never wedge Stop.
+    """
+    try:
+        if not messages:
+            return
+        idx, _text = find_last_human_turn(messages)
+        start = idx if idx is not None else -1
+        if turn_contains_directive_write(messages, start):
+            invalidate_directives_cache()
+            debug_log(config, "Directives cache invalidated — turn wrote a directive")
+    except Exception as e:  # pragma: no cover - defensive; Stop must not wedge
+        debug_log(config, f"Directives cache invalidation skipped (error): {e}")
+
+
 def read_transcript(transcript_path: str) -> list:
     """Read a JSONL transcript into a list of message dicts (role/content).
 
@@ -348,11 +414,15 @@ def read_transcript(transcript_path: str) -> list:
     return messages
 
 
-def evaluate(hook_input: dict, config: dict) -> str | None:
+def evaluate(hook_input: dict, config: dict, messages: list | None = None) -> str | None:
     """Core decision. Returns a block reason string, or None to allow stop.
 
     None → the turn is allowed to end (no-op). A non-empty string → block the
     stop once and feed the string back to the model.
+
+    ``messages`` is the pre-read transcript when the caller already parsed it
+    (main() reads once and shares it); when None, the transcript is read here so
+    direct callers/tests keep the old single-arg contract.
     """
     # Same knob as Stage B — disabling the nudge disables this verification.
     if not config.get("directiveCaptureNudge", True):
@@ -371,7 +441,8 @@ def evaluate(hook_input: dict, config: dict) -> str | None:
         debug_log(config, "Directive-capture verify: stop_hook_active, not re-blocking")
         return None
 
-    messages = read_transcript(hook_input.get("transcript_path", ""))
+    if messages is None:
+        messages = read_transcript(hook_input.get("transcript_path", ""))
     if not messages:
         return None
 
@@ -423,8 +494,34 @@ def main():
         config = load_config()
     except Exception:
         return
+
+    # Read the transcript AT MOST ONCE and share it with both consumers below
+    # (a Stop hook must not parse a multi-MB session twice, nor at all when
+    # nothing here needs it). Two features want the transcript:
+    #   * A4 directives-cache invalidation — only when the cache is enabled
+    #     (TTL > 0); with the cache off there is nothing to invalidate.
+    #   * capture-verify (evaluate) — only when the nudge+verify knobs are on
+    #     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
+    verify_maybe = (
+        config.get("directiveCaptureNudge", True)
+        and config.get("directiveCaptureVerify", True)
+        and not hook_input.get("stop_hook_active")
+    )
+
+    messages: list = []
+    if cache_on or verify_maybe:
+        messages = read_transcript(hook_input.get("transcript_path", ""))
+
+    # A4: invalidate the directives cache when this turn wrote a directive, so
+    # the change is visible on the very next recall. Independent of the
+    # capture-verify decision below and self-guarded — runs on every Stop.
+    if cache_on:
+        invalidate_cache_on_directive_write(messages, config)
+
     try:
-        reason = evaluate(hook_input, config)
+        reason = evaluate(hook_input, config, messages=messages)
     except Exception as e:  # never wedge a turn on a verify bug
         debug_log(config, f"Directive-capture verify error (allowing stop): {e}")
         return

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

@@ -71,8 +71,28 @@ DEFAULTS = {
     # per-agent via memory.directive_capture_verify=false →
     # HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY.
     "directiveCaptureVerify": True,
-    "recallContextTurns": 1,
+    # 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
+    # directive writes invalidate the cache immediately via directive_verify.py.
+    # 0 disables the cache (live fetch every turn — the A4 rollback lever).
+    "directivesCacheTtlSeconds": 120,
+    # Switchroom hindsight-leverage A2 (PR2): default 2 so a bare follow-up
+    # user message ("and the port?", "what about staging?") embeds together
+    # with its antecedent turn, instead of recalling on the pronoun alone.
+    # Bounded by recallMaxQueryChars (truncate_recall_query preserves the
+    # latest turn and drops oldest context first) so the composition can never
+    # blow the recall query budget; the transcript read is byte-tail-bounded
+    # by recallTranscriptTailBytes so the added per-turn read stays O(1).
+    "recallContextTurns": 2,
     "recallMaxQueryChars": 800,
+    # Switchroom hindsight-leverage A2 (PR2) — latency bound for the multi-turn
+    # composition. With recallContextTurns>1 now the default, EVERY recall reads
+    # the transcript to slice the last N human turns. A long session's .jsonl can
+    # grow to many MB, so read only the last N bytes (complete trailing lines);
+    # the last 2-3 human turns always live at the tail. 0 disables the bound
+    # (read the whole file — the pre-A2 behaviour / rollback lever).
+    "recallTranscriptTailBytes": 262144,
     "recallRoles": ["user", "assistant"],
     # Upstream 962140eef — optional recall tag filters passed through to the
     # recall API, plus per-additional-bank overrides keyed by bank ID.
@@ -80,6 +100,19 @@ DEFAULTS = {
     "recallTagsMatch": "any",
     "recallTagGroups": None,
     "recallAdditionalBankFilters": {},
+    # Switchroom (hindsight-leverage PR5) — per-tag recall score weights. A map
+    # of ``{tag: multiplier}`` applied to each result's ``scores.final`` just
+    # before the final relevance sort/cap in recall.py. A weight < 1.0 DEMOTES
+    # (down-ranks) memories carrying that tag without DROPPING them — distinct
+    # from the hard demote-tag drop filter (`_is_demoted_memory`), which removes
+    # a memory from recall entirely. This is the "reduced weight" the drop
+    # filter cannot express: a demoted memory still surfaces when it is the only
+    # relevant hit, just below equal-scoring untagged memories. Default {} =
+    # no-op (identity weighting). Switchroom's scaffold seeds
+    # ``{"sidechain": 0.8}`` so delegated sub-agent process-memories rank just
+    # under first-party session memories. Env: HINDSIGHT_RECALL_TAG_WEIGHTS
+    # (JSON object).
+    "recallTagWeights": {},
     "recallPromptPreamble": (
         "Relevant memories from past conversations (prioritize recent when "
         "conflicting). Only use memories that are directly useful to continue "
@@ -95,6 +128,56 @@ DEFAULTS = {
     "retainContext": "claude-code",
     "retainTags": [],
     "retainMetadata": {},
+    # Switchroom hindsight-leverage E2 / PR9 (#398) — lesson & anti-pattern
+    # tagging at retain time. When on (default), build_retain_payload scans the
+    # formatted transcript slice for explicit lesson / anti-pattern markers and
+    # attaches the matching tag(s) to the retain. This is the retain-side half of
+    # #398: a transcript that captures a failure mode ("anti-pattern:", "what not
+    # to do") or a self-recognised lesson ("lesson learned", "note to self:") is
+    # tagged so the recall-side score-penalty weight map (recallTagWeights, PR5)
+    # can DEMOTE it below clean first-party session memories — without ever hard-
+    # dropping it. NON-GOAL (epic-recorded): historical corpus is NOT re-tagged;
+    # this fires on NEW retains only. Detection is deterministic substring match
+    # (case-insensitive), never model-dependent. Disable via
+    # HINDSIGHT_LESSON_TAGGING=false (rollback lever).
+    "lessonTagging": True,
+    # Marker map {tag: [substrings]}. A slice whose lower-cased text contains ANY
+    # of a tag's substrings gets that tag. Deliberately explicit prefixes to keep
+    # false positives low — a passing mention of the word "lesson" should not tag
+    # a whole transcript; an explicit "lesson learned" / "anti-pattern:" should.
+    # Operators can extend/replace via HINDSIGHT_LESSON_TAG_MARKERS (JSON object).
+    "lessonTagMarkers": {
+        "lesson": [
+            "lesson learned",
+            "lessons learned",
+            "lesson:",
+            "note to self:",
+            "for next time:",
+            "takeaway:",
+            "key takeaway",
+        ],
+        "anti-pattern": [
+            "anti-pattern:",
+            "anti pattern:",
+            "antipattern:",
+            "what not to do",
+            "do not do this again",
+            "don't do this again",
+            "failure mode:",
+        ],
+    },
+    # Switchroom hindsight-leverage E2 / PR9 (#398) — recall-side demotion weights
+    # for the lesson/anti-pattern tags above. Merged UNDER recallTagWeights at
+    # recall time (an explicit recallTagWeights entry for the same tag WINS), so
+    # lesson/anti-pattern transcripts are down-ranked out of the box while the
+    # PR5 sidechain seed and any operator override still compose cleanly. A raw
+    # transcript that merely discusses a failure mode should rank below a clean
+    # session memory of equal engine score, yet still surface when it is the only
+    # relevant hit (re-rank, never drop). Set HINDSIGHT_LESSON_DEMOTION=false to
+    # disable the built-in weights (rollback lever); override individual weights
+    # via recallTagWeights / HINDSIGHT_RECALL_TAG_WEIGHTS.
+    "lessonDemotion": True,
+    "lessonDemotionWeights": {"lesson": 0.85, "anti-pattern": 0.5},
     # Switchroom #3244 — boot reconciliation of un-committed transcript tails.
     # On by default; the load-bearing recovery for work an abrupt session death
     # (SIGKILL/OOM/watchdog) skipped. Disable per-agent via
@@ -102,6 +185,46 @@ DEFAULTS = {
     # HINDSIGHT_RECONCILE_{LOOKBACK_H,MAX_TURNS,BUDGET_S} bounds (read directly).
     "reconcileOnStart": True,
     "recallAdditionalBanks": [],
+    # Switchroom hindsight-leverage A3 — parallelise multi-bank recall.
+    # When on (default), the directives fetch and every bank recall run
+    # concurrently in daemon threads under ONE shared deadline
+    # (recallParallelDeadlineSeconds), so total critical-path latency is the
+    # SLOWEST slot instead of their SUM. Set false
+    # (HINDSIGHT_RECALL_PARALLEL=false) to restore the pre-A3 serial path —
+    # the rollback lever if the parallel path ever misbehaves.
+    "recallParallel": True,
+    # Shared deadline (seconds) for the whole parallel recall section. Sized
+    # at the UserPromptSubmit hook ceiling (12s, hooks.json) MINUS 2s headroom
+    # for block formatting + cache write + stdout flush, so a straggler bank
+    # can never push the hook past its ceiling. Slots still unfinished when the
+    # deadline elapses are abandoned (daemon threads) and marked timed_out.
+    "recallParallelDeadlineSeconds": 10,
+    # Switchroom hindsight-leverage E1 / PR8 (#3369) — bounded transcript-grep
+    # fallback. Boot reconciliation (reconcile_tail.py) closes the crash-loss
+    # window at the NEXT SessionStart, but between an abrupt kill and that boot,
+    # live recall returns nothing for the lost turns because the fact layer was
+    # never told about them. When on (default) AND every bank returned zero
+    # results AND no bank/directives slot hit its deadline (deadline_hit False —
+    # so a timed-out bank can't masquerade as a genuinely empty fact layer, the
+    # #3369 sequencing constraint that depends on A3's shared-deadline telemetry),
+    # recall greps the CURRENT session's transcript tail for turns that mention
+    # the query's terms and injects them as a clearly-labelled, lower-confidence
+    # fallback block. Everything is bounded: the tail read (…MaxBytes), the number
+    # of matched turns (…MaxTurns), the emitted characters (…MaxChars), and the
+    # grep wall-time (…DeadlineMs). Set false (HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK
+    # =false) to disable — the rollback lever.
+    "recallTranscriptFallback": True,
+    # Tail bytes read from the session transcript for the grep. 256 KiB covers
+    # many turns of recent conversation while keeping the read well inside the
+    # hook budget; only the LAST max_bytes are read (partial first line dropped).
+    "recallTranscriptFallbackMaxBytes": 262144,
+    # Hard ceiling on matched turns injected into the fallback block.
+    "recallTranscriptFallbackMaxTurns": 6,
+    # Hard ceiling on the fallback block's excerpt characters.
+    "recallTranscriptFallbackMaxChars": 2000,
+    # Wall-clock bound (ms) on the grep itself — abandons scanning older turns
+    # once exceeded so the fallback can never eat the recall critical path.
+    "recallTranscriptFallbackDeadlineMs": 1500,
     # Connection
     "hindsightApiUrl": None,
     "hindsightApiToken": None,
@@ -140,6 +263,12 @@ ENV_OVERRIDES = {
     "HINDSIGHT_AUTO_RECALL": ("autoRecall", bool),
     "HINDSIGHT_AUTO_RETAIN": ("autoRetain", bool),
     "HINDSIGHT_RETAIN_MODE": ("retainMode", str),
+    # Switchroom hindsight-leverage E2 / PR9 (#398) — lesson/anti-pattern tagging
+    # + recall demotion toggles and overrides.
+    "HINDSIGHT_LESSON_TAGGING": ("lessonTagging", bool),
+    "HINDSIGHT_LESSON_TAG_MARKERS": ("lessonTagMarkers", dict),
+    "HINDSIGHT_LESSON_DEMOTION": ("lessonDemotion", bool),
+    "HINDSIGHT_LESSON_DEMOTION_WEIGHTS": ("lessonDemotionWeights", dict),
     # Switchroom #3244 — boot reconciliation on/off (default on).
     "HINDSIGHT_RECONCILE_ON_START": ("reconcileOnStart", bool),
     "HINDSIGHT_RECALL_BUDGET": ("recallBudget", str),
@@ -171,13 +300,33 @@ ENV_OVERRIDES = {
     # agents.<name>.memory.directive_capture_verify only when the operator
     # overrode it; the switchroom default is on.
     "HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY": ("directiveCaptureVerify", bool),
+    # Switchroom hindsight-leverage A4 — directives-list cache TTL (seconds).
+    # 0 disables the cache (rollback lever).
+    "HINDSIGHT_DIRECTIVES_CACHE_TTL_SECONDS": ("directivesCacheTtlSeconds", int),
+    # Switchroom hindsight-leverage A3 — parallel multi-bank recall toggle +
+    # shared deadline. HINDSIGHT_RECALL_PARALLEL=false is the serial rollback
+    # lever; the deadline is the ceiling-minus-2s hard budget (see DEFAULTS).
+    "HINDSIGHT_RECALL_PARALLEL": ("recallParallel", bool),
+    "HINDSIGHT_RECALL_PARALLEL_DEADLINE_SECONDS": ("recallParallelDeadlineSeconds", int),
+    # Switchroom hindsight-leverage E1 / PR8 (#3369) — transcript-grep fallback
+    # toggle + bounds. HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK=false is the rollback
+    # lever; the others tune the byte / turn / char / time bounds.
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK": ("recallTranscriptFallback", bool),
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK_MAX_BYTES": ("recallTranscriptFallbackMaxBytes", int),
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK_MAX_TURNS": ("recallTranscriptFallbackMaxTurns", int),
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK_MAX_CHARS": ("recallTranscriptFallbackMaxChars", int),
+    "HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK_DEADLINE_MS": ("recallTranscriptFallbackDeadlineMs", int),
     "HINDSIGHT_RECALL_MAX_QUERY_CHARS": ("recallMaxQueryChars", int),
     "HINDSIGHT_RECALL_CONTEXT_TURNS": ("recallContextTurns", int),
+    # Switchroom hindsight-leverage A2 — byte-tail bound for the multi-turn
+    # transcript read (0 = read whole file / rollback lever).
+    "HINDSIGHT_RECALL_TRANSCRIPT_TAIL_BYTES": ("recallTranscriptTailBytes", int),
     # Upstream 962140eef — recall tag filters. The tags env var accepts JSON
     # or a comma-separated list; the others must be JSON.
     "HINDSIGHT_RECALL_TAGS": ("recallTags", list),
     "HINDSIGHT_RECALL_TAGS_MATCH": ("recallTagsMatch", str),
     "HINDSIGHT_RECALL_TAG_GROUPS": ("recallTagGroups", dict),
+    "HINDSIGHT_RECALL_TAG_WEIGHTS": ("recallTagWeights", dict),
     "HINDSIGHT_RECALL_ADDITIONAL_BANK_FILTERS": ("recallAdditionalBankFilters", dict),
     "HINDSIGHT_API_PORT": ("apiPort", int),
     "HINDSIGHT_DAEMON_IDLE_TIMEOUT": ("daemonIdleTimeout", int),