switchroom 0.19.1 → 0.19.3

package/telegram-plugin/tests/usage-footer-freshness.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Adversarial-review F1 + F2 — the /usage card must NEVER stamp "Live" when
+ * no account row carries usable live data.
+ *
+ * Root cause (F1): the gateway `/usage` handler decided the freshness footer
+ * from `probeResp.results.length > 0`. But opProbeQuota
+ * (src/auth/broker/server.ts) returns `{result:{ok:false}, served:"live"}`
+ * for a failed live probe against an EMPTY cache — a non-empty results array
+ * where every row is `ok:false`. `zipProbeResults` only marks
+ * `served==="cache"` rows stale, so those failed rows carry no cache stamp
+ * either. Result: on a fresh restart (empty cache) + a transient probe
+ * failure, every row rendered "⚠️ no data — probe failed" UNDER a false
+ * "Live · refreshed 0s ago" stamp.
+ *
+ * F2 (test gap): the footer decision had zero coverage. This drives the
+ * extracted decision (`deriveUsageFooterFreshness`) composed with the real
+ * card renderer (`renderUsageCard`) with an all-`ok:false`, no-cache broker
+ * stub and asserts the rendered footer is NOT "Live" — i.e. it would fail
+ * against the pre-fix `.length > 0` gate.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  deriveUsageFooterFreshness,
+  type AccountSnapshot,
+  type ProbeQuotaResultRow,
+} from '../auth-snapshot-format.js'
+import { renderUsageCard } from '../quota-bar-format.js'
+
+const NOW = new Date('2026-07-19T12:00:00Z')
+
+// Two accounts, no usable quota (the probe failed, nothing cached) — mirrors
+// what the gateway hands renderUsageCard when the broker cache is empty and
+// the live probe threw for every account.
+const NO_DATA_SNAPSHOTS: AccountSnapshot[] = [
+  { label: 'alice@example.com', isActive: true, quota: null, quotaError: 'probe failed' },
+  { label: 'bob@example.com', isActive: false, quota: null, quotaError: 'probe failed' },
+]
+
+// A broker probe-quota response where every row failed and nothing was served
+// from cache — the exact shape opProbeQuota returns for a failed live probe
+// against an empty cache.
+const ALL_FAILED_NO_CACHE: ProbeQuotaResultRow[] = [
+  { label: 'alice@example.com', result: { ok: false, reason: 'network error' }, served: 'live' },
+  { label: 'bob@example.com', result: { ok: false, reason: 'network error' }, served: 'live' },
+]
+
+const EXHAUSTED = new Map<string, boolean>()
+
+describe('deriveUsageFooterFreshness (F1)', () => {
+  it('flags probeFailed when every row is ok:false and there is no cache', () => {
+    const opts = deriveUsageFooterFreshness(ALL_FAILED_NO_CACHE, undefined, NOW.getTime())
+    // Would have been { liveProbedAtMs } under the old `.length > 0` gate.
+    expect(opts).toEqual({ probeFailed: true })
+    expect(opts.liveProbedAtMs).toBeUndefined()
+  })
+
+  it('stamps liveProbedAtMs when at least one row carries usable data', () => {
+    const rows: ProbeQuotaResultRow[] = [
+      ALL_FAILED_NO_CACHE[0],
+      {
+        label: 'bob@example.com',
+        result: {
+          ok: true,
+          data: {
+            fiveHourUtilizationPct: 12,
+            sevenDayUtilizationPct: 34,
+            fiveHourResetAt: null,
+            sevenDayResetAt: null,
+            representativeClaim: null,
+            overageStatus: null,
+            overageDisabledReason: null,
+            fiveHourUtilPresent: true,
+            sevenDayUtilPresent: true,
+          },
+        },
+        served: 'live',
+      },
+    ]
+    const opts = deriveUsageFooterFreshness(rows, undefined, NOW.getTime())
+    expect(opts).toEqual({ liveProbedAtMs: NOW.getTime() })
+    expect(opts.probeFailed).toBeUndefined()
+  })
+
+  it('gives cache-served data precedence over both live and failed', () => {
+    const capturedAt = NOW.getTime() - 60_000
+    expect(deriveUsageFooterFreshness(ALL_FAILED_NO_CACHE, capturedAt, NOW.getTime())).toEqual({
+      staleCachedAtMs: capturedAt,
+    })
+  })
+
+  it('flags probeFailed for a totally empty results array', () => {
+    expect(deriveUsageFooterFreshness([], undefined, NOW.getTime())).toEqual({ probeFailed: true })
+  })
+})
+
+describe('/usage card footer end-to-end (F2)', () => {
+  it('renders "probe failed", NOT "Live", when no row carries live data', () => {
+    const freshness = deriveUsageFooterFreshness(ALL_FAILED_NO_CACHE, undefined, NOW.getTime())
+    const card = renderUsageCard(NO_DATA_SNAPSHOTS, EXHAUSTED, { now: NOW, ...freshness })
+    expect(card).toContain('probe failed — no live data')
+    // The honesty invariant: no "Live" stamp when every row shows no data.
+    expect(card).not.toContain('Live')
+    // And the rows themselves are the no-data warning, not a fake 0% bar.
+    expect(card).toContain('no data — probe failed')
+  })
+
+  it('renders a "Live" footer when a row carries usable data', () => {
+    const liveSnapshots: AccountSnapshot[] = [
+      {
+        label: 'bob@example.com',
+        isActive: true,
+        quota: {
+          fiveHourUtilizationPct: 12,
+          sevenDayUtilizationPct: 34,
+          fiveHourResetAt: null,
+          sevenDayResetAt: null,
+          representativeClaim: null,
+          overageStatus: null,
+          overageDisabledReason: null,
+          fiveHourUtilPresent: true,
+          sevenDayUtilPresent: true,
+        },
+      },
+    ]
+    const freshness = deriveUsageFooterFreshness(
+      [
+        {
+          label: 'bob@example.com',
+          result: { ok: true, data: liveSnapshots[0].quota! },
+          served: 'live',
+        },
+      ],
+      undefined,
+      NOW.getTime(),
+    )
+    const card = renderUsageCard(liveSnapshots, EXHAUSTED, { now: NOW, ...freshness })
+    expect(card).toContain('Live · refreshed')
+    expect(card).not.toContain('probe failed')
+  })
+})

package/telegram-plugin/tests/usage-mask.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Adversarial-review F4 — `/usage` account-label masking policy.
+ *
+ * A group with an empty `allowFrom` authorizes every member, so the quota
+ * card would leak per-account email labels to a broadly shared group unless
+ * masked. `shouldMaskUsageLabels` (gateway/usage-mask.ts) is the pure
+ * decision the gateway feeds into the existing demo-mask machinery.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { shouldMaskUsageLabels } from '../gateway/usage-mask.js'
+
+describe('shouldMaskUsageLabels (F4)', () => {
+  it('never masks in a private (operator DM) chat', () => {
+    expect(shouldMaskUsageLabels('private', undefined)).toBe(false)
+    expect(shouldMaskUsageLabels('private', [])).toBe(false)
+    expect(shouldMaskUsageLabels('private', ['123'])).toBe(false)
+  })
+
+  it('masks in a group with an EMPTY allowFrom (open membership)', () => {
+    expect(shouldMaskUsageLabels('group', [])).toBe(true)
+    expect(shouldMaskUsageLabels('group', undefined)).toBe(true)
+    expect(shouldMaskUsageLabels('supergroup', [])).toBe(true)
+  })
+
+  it('does NOT mask in a group with a curated non-empty allowFrom', () => {
+    expect(shouldMaskUsageLabels('group', ['123'])).toBe(false)
+    expect(shouldMaskUsageLabels('supergroup', ['123', '456'])).toBe(false)
+  })
+
+  it('masks defensively for any other chat type reaching a quota render', () => {
+    expect(shouldMaskUsageLabels('channel', undefined)).toBe(true)
+    expect(shouldMaskUsageLabels(undefined, undefined)).toBe(true)
+  })
+})

package/telegram-plugin/tests/worker-feed-dispatch.test.ts

@@ -72,6 +72,33 @@ describe('resolveWorkerFeedDispatch (#2002 regression pin)', () => {
     expect(resolveWorkerFeedDispatch(null, 'sub-agent').feedModel).toBeNull()
     expect(resolveWorkerFeedDispatch(makeSub({ model: null }), 'sub-agent').feedModel).toBeNull()
   })
+
+  // F3 (progress-card fork model) — outcome coverage. The dispatch-time seed is
+  // suppressed for forks at the hook (subagent-tracker-pretool.mjs), so a fork
+  // row carries model=null and the card omits the model until the watcher writes
+  // the transcript model. resolveWorkerFeedDispatch simply surfaces the row's
+  // CURRENT model, so these assert the feed-level outcomes on top of that.
+  it('(b) a fork row carries no dispatch-time model → feedModel null (card omits it until transcript)', () => {
+    // What the hook now writes for a fork dispatch: agent_type 'fork', model null
+    // (the ignored override is not persisted).
+    const forkRow = makeSub({ background: true, agent_type: 'fork', model: null })
+    expect(resolveWorkerFeedDispatch(forkRow, 'sub-agent').feedModel).toBeNull()
+  })
+
+  it('(a) once the watcher overwrites the row model from the transcript, feedModel reflects the transcript model', () => {
+    // Transcript wins: the watcher (recordSubagentModel) overwrites the row's
+    // model column in place, so the resolved feedModel is the transcript value —
+    // even for a fork that started with model=null.
+    const afterTranscript = makeSub({ background: true, agent_type: 'fork', model: 'claude-opus-4-8' })
+    expect(resolveWorkerFeedDispatch(afterTranscript, 'sub-agent').feedModel).toBe('claude-opus-4-8')
+  })
+
+  it('(c) a mid-run model switch is reflected: feedModel tracks the row’s latest recorded model', () => {
+    // The watcher writes model-on-change; the row holds the LATEST model, so a
+    // later substantive tick resolves the switched-to model.
+    const switchedTo = makeSub({ background: true, model: 'sr-glm-5' })
+    expect(resolveWorkerFeedDispatch(switchedTo, 'sub-agent').feedModel).toBe('sr-glm-5')
+  })
 })
 
 describe('gateway onFinish — fix #1: resultText-driven handback fallback (model)', () => {

package/telegram-plugin/tests/worker-feed-pin-persistence.test.ts

@@ -5,7 +5,12 @@ import {
   type BotApiForWorkerFeed,
 } from '../worker-activity-feed.js'
 import { reconcilePin, type PinBotApi } from '../status-pin-driver.js'
-import type { PinState, DesiredPin } from '../status-pin.js'
+import { decidePinAction, type PinState, type DesiredPin } from '../status-pin.js'
+import {
+  reconcileAndPersistStatusPin,
+  loadStatusPins,
+  type StatusPinStoreFsSeam,
+} from '../gateway/status-pin-store.js'
 
 /**
  * Outcome tests for the invisible-worker-cards fix (2026-07-15).
@@ -119,6 +124,131 @@ async function flush(): Promise<void> {
   for (let i = 0; i < 8; i++) await new Promise((r) => setImmediate(r))
 }
 
+/** In-memory fs seam with atomic rename, mirroring status-pin-store.test.ts. */
+function memFs(): { fs: StatusPinStoreFsSeam; files: Map<string, string> } {
+  const files = new Map<string, string>()
+  const fs: StatusPinStoreFsSeam = {
+    readFileSync: (p) => {
+      if (!files.has(p)) throw new Error(`ENOENT ${p}`)
+      return files.get(p)!
+    },
+    writeFileSync: (p, d) => {
+      files.set(p, d)
+    },
+    renameSync: (a, b) => {
+      if (!files.has(a)) throw new Error(`ENOENT ${a}`)
+      files.set(b, files.get(a)!)
+      files.delete(a)
+    },
+    existsSync: (p) => files.has(p),
+  }
+  return { fs, files }
+}
+
+/**
+ * A pin harness that routes the feed's `reconcilePin` hook through the REAL
+ * persistence path (`reconcileAndPersistStatusPin`) against a memFs-backed
+ * status-pins.json — exactly as the gateway wires it: read prev claim → decide
+ * → map to a persist op → reconcileAndPersistStatusPin(applyPin=reconcilePin).
+ * This lets a test INSPECT THE FILE across steady-state edits (F1).
+ */
+function makePersistingPinHarness(path: string) {
+  const { fs } = memFs()
+  const claims = new Map<string, PinState>()
+  const pinCalls: number[] = []
+  const unpinCalls: number[] = []
+  const api: PinBotApi = {
+    pinChatMessage: async (_c, id) => {
+      pinCalls.push(id)
+    },
+    unpinChatMessage: async (_c, id) => {
+      unpinCalls.push(id)
+    },
+  }
+  async function reconcile(key: string, chatId: string, desired: DesiredPin): Promise<void> {
+    const prev = claims.get(key) ?? null
+    const action = decidePinAction(prev, desired)
+    const op = action.kind === 'pin'
+      ? ({ kind: 'pin', messageId: action.messageId } as const)
+      : ({ kind: 'clear' } as const)
+    const next = await reconcileAndPersistStatusPin({
+      path,
+      fs,
+      pinKey: key,
+      chatId,
+      op,
+      applyPin: () => reconcilePin({ api, chatId, prevState: prev, desired }),
+      log: () => {},
+    })
+    if (next == null) claims.delete(key)
+    else claims.set(key, next)
+  }
+  const reconcilePinFn = (args: {
+    feedKey: string
+    chatId: string
+    threadId?: number
+    messageId: number | null
+  }): void => {
+    const key = `wk:group:${args.feedKey}`
+    if (args.messageId != null) void reconcile(key, args.chatId, { pinned: true, messageId: args.messageId })
+    else void reconcile(key, args.chatId, { pinned: false })
+  }
+  return {
+    reconcilePinFn,
+    fs,
+    pinCalls,
+    unpinCalls,
+    rows: () => loadStatusPins(path, fs),
+  }
+}
+
+describe('worker-feed pin persistence — durable status-pins.json survives steady-state edits (F1)', () => {
+  const PATH = '/state/agent/telegram/status-pins.json'
+
+  it('preserves the wk:group row across many steady-state edits (noop-clear must NOT delete it)', async () => {
+    const bot = makeFakeBot()
+    const pin = makePersistingPinHarness(PATH)
+    let clock = 0
+    const feed = createWorkerActivityFeed({
+      bot,
+      now: () => clock,
+      firstPaintMinMs: 0,
+      minEditIntervalMs: 0,
+      reconcilePin: pin.reconcilePinFn,
+    })
+
+    // First paint → message posted, pinned once, durable row written.
+    clock = 1000
+    await feed.update('w1', 'chat', view({ elapsedMs: 1000, toolCount: 1 }))
+    await flush()
+    const msgId = bot.sent[0].messageId
+    expect(pin.pinCalls).toEqual([msgId])
+    expect(pin.rows()).toHaveLength(1)
+    const pinKey = pin.rows()[0].pinKey
+    expect(pinKey).toMatch(/^wk:group:/)
+    expect(pin.rows()).toEqual([
+      { pinKey, chatId: 'chat', messageId: msgId },
+    ])
+
+    // Many steady-state edits — the feed calls syncPin on EVERY edit, each a
+    // re-pin of the SAME id → noop → a `clear` op with a LIVE claim. Pre-fix the
+    // clear branch deleted the durable row here; the fix preserves it.
+    for (let i = 2; i <= 8; i++) {
+      clock = i * 1000
+      await feed.update('w1', 'chat', view({ elapsedMs: i * 1000, toolCount: i }))
+      await flush()
+    }
+
+    // The durable row is STILL on disk (inspect the file), and no extra pin/
+    // unpin API call was issued across all those steady-state edits.
+    expect(pin.rows()).toEqual([
+      { pinKey, chatId: 'chat', messageId: msgId },
+    ])
+    expect(pin.pinCalls).toEqual([msgId]) // exactly one pin, ever
+    expect(pin.unpinCalls).toEqual([]) // never unpinned
+  })
+})
+
 describe('worker-feed pin persistence — steady-state re-pin (invisible-worker-cards)', () => {
   it('re-pins on a steady-state edit when the claim was lost, and does NOT re-pin when already correct (no storm)', async () => {
     const bot = makeFakeBot()

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