switchroom 0.19.48 → 0.20.1

package/telegram-plugin/tests/reply-to-buffer-fallback.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Reply-to buffer fallback + role tag + native partial-quote preference.
+ *
+ * WHAT THESE PIN (post-reset conversation continuity)
+ * ---------------------------------------------------
+ * The real incident: after a session reset (`resume_mode: handoff` → fresh
+ * session, transcript gone) a user native-REPLIED to one of the BOT's OWN
+ * messages ("is this added as a calendar invite yet?"). Telegram delivers
+ * `reply_to_message.message_id` on such a reply but NOT the message's `.text`
+ * (it omits the text when the reply target is the bot's own message), so the
+ * live update carried no antecedent — and the agent had to guess. The bot had
+ * already persisted that outbound to `history.db` via `recordOutbound`
+ * (role='assistant'); the fix reads it back.
+ *
+ * These are OUTCOME tests against the real pure builders, not the code paths:
+ *   - `resolveReplyToFromBuffer` recovers the text AND the role from a buffer
+ *     hit, truncates to the cap, and — critically — sets BOTH the raw
+ *     `replyToText` (which the gateway's recordInbound write persists, so the
+ *     DB row is non-NULL for future briefings) and the escaped form (for the
+ *     envelope). A test that only checked the envelope would pass on the
+ *     rejected envelope-only design and miss the NULL-row regression.
+ *   - The history-disabled / lookup-throws guard degrades silently (no throw).
+ *   - A non-empty LIVE reply text is never overwritten.
+ *   - `buildReplyForwardContext` prefers `message.quote.text` (a native
+ *     partial quote) over the full parent `.text`.
+ *   - `buildInboundEnvelope` emits `reply_to_role` when known and `reply_to_text`
+ *     from the recovered escaped form.
+ *
+ * The persisted-row-non-NULL half of the 1a contract (which needs a real
+ * bun:sqlite history.db) lives in reply-to-buffer-history.test.ts (bun).
+ */
+
+import { describe, it, expect } from 'vitest'
+import type { Context } from 'grammy'
+import {
+  buildReplyForwardContext,
+  resolveReplyToFromBuffer,
+  buildInboundEnvelope,
+  type EnvelopeBuildParams,
+} from '../gateway/inbound-router.js'
+
+const REPLY_TO_TEXT_MAX = 200
+
+/** A minimal grammy Context carrying only the message fields the builders read. */
+function makeCtx(message: Record<string, unknown>): Context {
+  return { message: { date: 1_700_000_000, ...message } } as unknown as Context
+}
+
+describe('resolveReplyToFromBuffer — reply-to buffer fallback (1a)', () => {
+  it('recovers a bot-authored antecedent: sets raw text, escaped text, AND role', () => {
+    // Live update: a native reply to the bot's own message → id present, text empty.
+    const out = resolveReplyToFromBuffer({
+      replyToMessageId: 42,
+      replyToText: undefined,
+      replyToTextEscaped: undefined,
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup: (id) =>
+        id === 42
+          ? { role: 'assistant', text: 'Added the calendar invite for Friday 3pm.' }
+          : null,
+    })
+    // Raw text (for the SQLite recordInbound write — NOT envelope-only).
+    expect(out.replyToText).toBe('Added the calendar invite for Friday 3pm.')
+    // Escaped form (for the channel-meta reply_to_text).
+    expect(out.replyToTextEscaped).toBe('Added the calendar invite for Friday 3pm.')
+    // Role disambiguates "you are replying to the bot's own message".
+    expect(out.replyToRole).toBe('assistant')
+  })
+
+  it("tags a person's message as role='user'", () => {
+    const out = resolveReplyToFromBuffer({
+      replyToMessageId: 7,
+      replyToText: undefined,
+      replyToTextEscaped: undefined,
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup: () => ({ role: 'user', text: 'the thing I asked earlier' }),
+    })
+    expect(out.replyToRole).toBe('user')
+    expect(out.replyToText).toBe('the thing I asked earlier')
+  })
+
+  it('truncates the recovered text to REPLY_TO_TEXT_MAX (raw and escaped)', () => {
+    const long = 'x'.repeat(500)
+    const out = resolveReplyToFromBuffer({
+      replyToMessageId: 1,
+      replyToText: undefined,
+      replyToTextEscaped: undefined,
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup: () => ({ role: 'assistant', text: long }),
+    })
+    // Raw: sliced to max-1 chars + ellipsis = exactly max glyphs.
+    expect([...(out.replyToText ?? '')].length).toBe(REPLY_TO_TEXT_MAX)
+    expect(out.replyToText?.endsWith('…')).toBe(true)
+    expect([...(out.replyToTextEscaped ?? '')].length).toBe(REPLY_TO_TEXT_MAX)
+  })
+
+  it('does NOT overwrite a non-empty LIVE reply text (reply to a person, or a partial quote)', () => {
+    const lookup = () => {
+      throw new Error('lookup must not be called when live text is present')
+    }
+    const out = resolveReplyToFromBuffer({
+      replyToMessageId: 9,
+      replyToText: 'live raw text',
+      replyToTextEscaped: 'live escaped text',
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup,
+    })
+    expect(out.replyToText).toBe('live raw text')
+    expect(out.replyToTextEscaped).toBe('live escaped text')
+    expect(out.replyToRole).toBeUndefined()
+  })
+
+  it('history-disabled guard: never calls lookup, degrades to id-only, does not throw', () => {
+    let called = false
+    const call = () =>
+      resolveReplyToFromBuffer({
+        replyToMessageId: 5,
+        replyToText: undefined,
+        replyToTextEscaped: undefined,
+        historyEnabled: false,
+        replyToTextMax: REPLY_TO_TEXT_MAX,
+        lookup: () => {
+          called = true
+          throw new Error('requireDb would throw with history disabled')
+        },
+      })
+    expect(call).not.toThrow()
+    expect(called).toBe(false)
+    expect(call().replyToText).toBeUndefined()
+    expect(call().replyToRole).toBeUndefined()
+  })
+
+  it('a lookup that throws (requireDb mid-run) degrades silently', () => {
+    let out: ReturnType<typeof resolveReplyToFromBuffer> | undefined
+    expect(() => {
+      out = resolveReplyToFromBuffer({
+        replyToMessageId: 5,
+        replyToText: undefined,
+        replyToTextEscaped: undefined,
+        historyEnabled: true,
+        replyToTextMax: REPLY_TO_TEXT_MAX,
+        lookup: () => {
+          throw new Error('SQLITE_ERROR')
+        },
+      })
+    }).not.toThrow()
+    expect(out?.replyToText).toBeUndefined()
+    expect(out?.replyToRole).toBeUndefined()
+  })
+
+  it('a missing row (reacted-to message predates retention) yields id-only', () => {
+    const out = resolveReplyToFromBuffer({
+      replyToMessageId: 999,
+      replyToText: undefined,
+      replyToTextEscaped: undefined,
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup: () => null,
+    })
+    expect(out.replyToText).toBeUndefined()
+    expect(out.replyToRole).toBeUndefined()
+  })
+
+  it('a row with empty text still surfaces the role (authorship known, text redacted)', () => {
+    const out = resolveReplyToFromBuffer({
+      replyToMessageId: 3,
+      replyToText: undefined,
+      replyToTextEscaped: undefined,
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup: () => ({ role: 'assistant', text: '' }),
+    })
+    expect(out.replyToRole).toBe('assistant')
+    expect(out.replyToText).toBeUndefined()
+  })
+})
+
+describe('buildReplyForwardContext — native partial-quote preference (2a)', () => {
+  it('prefers message.quote.text over the full parent .text', () => {
+    const ctx = makeCtx({
+      reply_to_message: { message_id: 100, text: 'the entire long parent message body' },
+      quote: { text: 'the exact fragment I selected', position: 5, is_manual: true },
+    })
+    const out = buildReplyForwardContext({ ctx, coalescedForwardOrigins: undefined, replyToTextMax: REPLY_TO_TEXT_MAX })
+    expect(out.replyToMessageId).toBe(100)
+    expect(out.replyToText).toBe('the exact fragment I selected')
+    expect(out.replyToTextEscaped).toBe('the exact fragment I selected')
+  })
+
+  it('falls back to the parent .text when there is no quote', () => {
+    const ctx = makeCtx({
+      reply_to_message: { message_id: 101, text: 'parent body only' },
+    })
+    const out = buildReplyForwardContext({ ctx, coalescedForwardOrigins: undefined, replyToTextMax: REPLY_TO_TEXT_MAX })
+    expect(out.replyToText).toBe('parent body only')
+  })
+
+  it('leaves reply text empty when the bot-authored parent carries no text (the 1a trigger)', () => {
+    const ctx = makeCtx({ reply_to_message: { message_id: 102 } })
+    const out = buildReplyForwardContext({ ctx, coalescedForwardOrigins: undefined, replyToTextMax: REPLY_TO_TEXT_MAX })
+    expect(out.replyToMessageId).toBe(102)
+    expect(out.replyToText).toBeUndefined()
+    expect(out.replyToTextEscaped).toBeUndefined()
+  })
+})
+
+function makeEnvelopeParams(overrides: Partial<EnvelopeBuildParams>): EnvelopeBuildParams {
+  return {
+    ctx: makeCtx({}),
+    chat_id: '5550001',
+    messageThreadId: undefined,
+    msgId: 200,
+    effectiveText: 'is this added as a calendar invite yet?',
+    imagePath: undefined,
+    attachment: undefined,
+    attachmentCount: 0,
+    extraMeta: {},
+    from: { id: 111, username: 'alice' },
+    access: { groups: {} },
+    isSteering: false,
+    isQueuedPrefix: false,
+    isQueuedMidTurn: false,
+    priorTurnInProgress: false,
+    secondsSinceTurnStart: undefined,
+    priorAssistantPreview: undefined,
+    replyToMessageId: 42,
+    replyToTextEscaped: undefined,
+    replyToRole: undefined,
+    forwardOriginMeta: {},
+    topicFramingEnabled: false,
+    personDirectory: { byTelegramKey: {} },
+    isDmChatId: () => true,
+    ...overrides,
+  }
+}
+
+describe('buildInboundEnvelope — reply_to_role + reply_to_text emission', () => {
+  it('emits reply_to_role and reply_to_text when the buffer fallback recovered them', () => {
+    const msg = buildInboundEnvelope(
+      makeEnvelopeParams({
+        replyToMessageId: 42,
+        replyToTextEscaped: 'Added the calendar invite for Friday 3pm.',
+        replyToRole: 'assistant',
+      }),
+    )
+    expect(msg.meta?.reply_to_message_id).toBe('42')
+    expect(msg.meta?.reply_to_text).toBe('Added the calendar invite for Friday 3pm.')
+    expect(msg.meta?.reply_to_role).toBe('assistant')
+  })
+
+  it('omits reply_to_role when unknown (no buffer hit) but still emits the id', () => {
+    const msg = buildInboundEnvelope(
+      makeEnvelopeParams({ replyToMessageId: 42, replyToTextEscaped: undefined, replyToRole: undefined }),
+    )
+    expect(msg.meta?.reply_to_message_id).toBe('42')
+    expect('reply_to_role' in (msg.meta ?? {})).toBe(false)
+    expect('reply_to_text' in (msg.meta ?? {})).toBe(false)
+  })
+
+  it("emits reply_to_role='user' for a recovered person message", () => {
+    const msg = buildInboundEnvelope(
+      makeEnvelopeParams({
+        replyToTextEscaped: 'the thing I asked earlier',
+        replyToRole: 'user',
+      }),
+    )
+    expect(msg.meta?.reply_to_role).toBe('user')
+  })
+})

package/telegram-plugin/tests/reply-to-buffer-history.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Reply-to buffer fallback — REAL history.db integration (1a persistence half).
+ *
+ * The pure-builder outcomes live in reply-to-buffer-fallback.test.ts (vitest).
+ * This file pins the half that needs a real bun:sqlite `history.db`: that the
+ * recovered antecedent is actually PERSISTED to the inbound row (reply_to_text
+ * non-NULL), not just emitted on the envelope. Envelope-only was the rejected
+ * design — it leaves the DB row NULL and starves the next handoff briefing,
+ * which reads reply_to_text back out of this store. So this drives the exact
+ * production chain: recordOutbound (the bot's own message) → lookup it back →
+ * resolveReplyToFromBuffer → recordInbound(reply_to_text) → read the row.
+ *
+ * Runs under `bun test` (bun:sqlite is a Bun built-in vitest/Node can't
+ * resolve); vitest-excluded in vitest.config.ts, covered by the bun `tests/`
+ * target in telegram-plugin/scripts/bun-test-ci.sh.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import { mkdtempSync, rmSync, existsSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  initHistory,
+  recordInbound,
+  recordOutbound,
+  lookupMessageRoleAndText,
+  query,
+  _resetForTests,
+} from '../history.js'
+import { resolveReplyToFromBuffer } from '../gateway/inbound-router.js'
+
+const REPLY_TO_TEXT_MAX = 200
+const CHAT = '5550001'
+
+let stateDir: string
+
+beforeEach(() => {
+  stateDir = mkdtempSync(join(tmpdir(), 'reply-to-buffer-'))
+  initHistory(stateDir, 30)
+})
+
+afterEach(() => {
+  _resetForTests()
+  if (existsSync(stateDir)) rmSync(stateDir, { recursive: true, force: true })
+})
+
+describe('reply-to buffer fallback persists the recovered antecedent (1a)', () => {
+  it('a native reply to the bot own message recovers text+role from history and writes a non-NULL row', () => {
+    // 1. The bot sent a message earlier; recordOutbound persisted it (role='assistant').
+    const botMsgId = 4242
+    recordOutbound({
+      chat_id: CHAT,
+      thread_id: null,
+      message_ids: [botMsgId],
+      texts: ['Added the calendar invite for Friday 3pm.'],
+      ts: 1000,
+    })
+
+    // 2. Session reset happened (transcript gone). The user native-replies to
+    //    that bot message. Telegram gives us the id but NOT the text, so the
+    //    live reply text is empty — exactly the incident condition.
+    const recovered = resolveReplyToFromBuffer({
+      replyToMessageId: botMsgId,
+      replyToText: undefined,
+      replyToTextEscaped: undefined,
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup: (id) => lookupMessageRoleAndText(CHAT, id),
+    })
+
+    // The buffer recovered both the text and the authorship.
+    expect(recovered.replyToText).toBe('Added the calendar invite for Friday 3pm.')
+    expect(recovered.replyToRole).toBe('assistant')
+
+    // 3. The gateway records the inbound with the recovered reply_to_text.
+    const userMsgId = 4300
+    recordInbound({
+      chat_id: CHAT,
+      thread_id: null,
+      message_id: userMsgId,
+      user: 'alice',
+      user_id: '111',
+      ts: 2000,
+      text: 'is this added as a calendar invite yet?',
+      reply_to_message_id: botMsgId,
+      reply_to_text: recovered.replyToText ?? null,
+    })
+
+    // 4. THE outcome that would fail on the old bug and the rejected
+    //    envelope-only design: the persisted inbound row's reply_to_text is
+    //    non-NULL and carries the recovered antecedent.
+    const rows = query({ chat_id: CHAT, thread_id: null, limit: 10 })
+    const inboundRow = rows.find((r) => r.message_id === userMsgId) as
+      | { reply_to_text?: string | null; reply_to_message_id?: number | null }
+      | undefined
+    expect(inboundRow).toBeDefined()
+    expect(inboundRow!.reply_to_message_id).toBe(botMsgId)
+    expect(inboundRow!.reply_to_text).not.toBeNull()
+    expect(inboundRow!.reply_to_text).toBe('Added the calendar invite for Friday 3pm.')
+  })
+
+  it('a reply target absent from history (predates retention) writes a NULL row without throwing — no regression', () => {
+    const missingId = 99999
+    const recovered = resolveReplyToFromBuffer({
+      replyToMessageId: missingId,
+      replyToText: undefined,
+      replyToTextEscaped: undefined,
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup: (id) => lookupMessageRoleAndText(CHAT, id),
+    })
+    expect(recovered.replyToText).toBeUndefined()
+    expect(recovered.replyToRole).toBeUndefined()
+
+    const userMsgId = 4301
+    recordInbound({
+      chat_id: CHAT,
+      thread_id: null,
+      message_id: userMsgId,
+      user: 'alice',
+      user_id: '111',
+      ts: 2000,
+      text: 'what about this one?',
+      reply_to_message_id: missingId,
+      reply_to_text: recovered.replyToText ?? null,
+    })
+    const rows = query({ chat_id: CHAT, thread_id: null, limit: 10 })
+    const inboundRow = rows.find((r) => r.message_id === userMsgId) as
+      | { reply_to_text?: string | null }
+      | undefined
+    expect(inboundRow).toBeDefined()
+    expect(inboundRow!.reply_to_text ?? null).toBeNull()
+  })
+})

package/telegram-plugin/tests/user-failure-notices.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  emitTransportTransientEvent,
+  flushDeferredUserNotices,
+  noteTransportTransientAndShouldEscalate,
+  renderTransportEscalationCard,
+  resetTransportTransientEscalation,
+  type UserFailureNoticeDeps,
+} from '../gateway/user-failure-notices.js'
+import type { OperatorEvent } from '../operator-events.js'
+import type { PendingUserNotice } from '../pending-user-notice.js'
+
+// ─── Fake deps: capture every side effect, drive time explicitly ─────────────
+
+interface Capture {
+  recorded: OperatorEvent[]
+  scheduled: Array<{ chatIds: string[]; agent: string; kind: string; key: string | undefined; atMs: number }>
+  sent: Array<{ chatId: string; text: string; hasKeyboard: boolean }>
+  logs: string[]
+  /** Notices the fake gate will release on the next resolveNotices call. */
+  resolvedQueue: PendingUserNotice[]
+  lastResolve?: { delivered: boolean; key: string }
+}
+
+function makeDeps(over?: {
+  allowFrom?: string[]
+  liveTurnKey?: string | undefined
+  now?: number
+}): { deps: UserFailureNoticeDeps; cap: Capture } {
+  const cap: Capture = { recorded: [], scheduled: [], sent: [], logs: [], resolvedQueue: [] }
+  const deps: UserFailureNoticeDeps = {
+    now: () => over?.now ?? 1_000,
+    allowFrom: () => over?.allowFrom ?? ['op', 'user-a', 'user-b'],
+    liveTurnKey: () => ('liveTurnKey' in (over ?? {}) ? over!.liveTurnKey : 'chat:topic'),
+    record: (e) => cap.recorded.push(e),
+    scheduleUserNotice: (i) => cap.scheduled.push(i),
+    resolveNotices: (delivered, key) => {
+      cap.lastResolve = { delivered, key }
+      // Emulate the real gate: a delivered reply drops everything.
+      return delivered ? [] : cap.resolvedQueue
+    },
+    send: (chatId, text, keyboard) => cap.sent.push({ chatId, text, hasKeyboard: keyboard != null }),
+    log: (m) => cap.logs.push(m),
+  }
+  return { deps, cap }
+}
+
+function ev(overrides?: Partial<OperatorEvent>): OperatorEvent {
+  return {
+    kind: 'transport-transient',
+    agent: 'gymbro',
+    detail: 'API Error: Connection closed mid-response',
+    suggestedActions: [],
+    firstSeenAt: new Date('2026-08-02T00:00:00Z'),
+    ...overrides,
+  }
+}
+
+beforeEach(() => resetTransportTransientEscalation())
+
+// ─── emitTransportTransientEvent — outcomes ──────────────────────────────────
+
+describe('emitTransportTransientEvent', () => {
+  it('records history and schedules a deferred user notice, but sends NO card (single event)', () => {
+    const { deps, cap } = makeDeps()
+    emitTransportTransientEvent(ev(), deps)
+    // history recorded for /status
+    expect(cap.recorded).toHaveLength(1)
+    expect(cap.recorded[0].kind).toBe('transport-transient')
+    // user notice scheduled to ALL allowlist chats, keyed to the live turn
+    expect(cap.scheduled).toHaveLength(1)
+    expect(cap.scheduled[0].chatIds).toEqual(['op', 'user-a', 'user-b'])
+    expect(cap.scheduled[0].key).toBe('chat:topic')
+    // NO broadcast / escalation card for a single event
+    expect(cap.sent).toHaveLength(0)
+  })
+
+  it('records even when there is no allowlist, but schedules nothing', () => {
+    const { deps, cap } = makeDeps({ allowFrom: [] })
+    emitTransportTransientEvent(ev(), deps)
+    expect(cap.recorded).toHaveLength(1)
+    expect(cap.scheduled).toHaveLength(0)
+    expect(cap.sent).toHaveLength(0)
+  })
+
+  it('carries an undefined notice key when there is no live turn', () => {
+    const { deps, cap } = makeDeps({ liveTurnKey: undefined })
+    emitTransportTransientEvent(ev(), deps)
+    expect(cap.scheduled[0].key).toBeUndefined()
+  })
+})
+
+// ─── Escalation: >=3 within the window → exactly ONE operator-only card ───────
+
+describe('transport-transient escalation bound', () => {
+  it('sends exactly ONE operator-only Dismiss-only card at the 3rd event in the window', () => {
+    const { deps, cap } = makeDeps()
+    emitTransportTransientEvent(ev(), deps) // 1 — no card
+    emitTransportTransientEvent(ev(), deps) // 2 — no card
+    expect(cap.sent).toHaveLength(0)
+    emitTransportTransientEvent(ev(), deps) // 3 — ONE card
+    expect(cap.sent).toHaveLength(1)
+    // operator-only: goes to the allowlist HEAD, and carries a keyboard (Dismiss)
+    expect(cap.sent[0].chatId).toBe('op')
+    expect(cap.sent[0].hasKeyboard).toBe(true)
+    expect(cap.sent[0].text).toContain('Repeated stream failures')
+    // and only ONE — a 4th event in the same (reset) window does not re-fire yet
+    emitTransportTransientEvent(ev(), deps) // 4
+    expect(cap.sent).toHaveLength(1)
+  })
+
+  it('does not escalate when the events fall outside the window', () => {
+    // Two events far apart never reach threshold-3-within-window.
+    expect(noteTransportTransientAndShouldEscalate('gymbro', 0)).toBe(false)
+    expect(noteTransportTransientAndShouldEscalate('gymbro', 60 * 60_000)).toBe(false)
+    expect(noteTransportTransientAndShouldEscalate('gymbro', 120 * 60_000)).toBe(false)
+  })
+
+  it('counts per-agent — one agent bursting does not escalate another', () => {
+    expect(noteTransportTransientAndShouldEscalate('a', 0)).toBe(false)
+    expect(noteTransportTransientAndShouldEscalate('a', 1)).toBe(false)
+    expect(noteTransportTransientAndShouldEscalate('b', 2)).toBe(false)
+    // a's 3rd crosses; b has only seen 1
+    expect(noteTransportTransientAndShouldEscalate('a', 3)).toBe(true)
+    expect(noteTransportTransientAndShouldEscalate('b', 4)).toBe(false)
+  })
+})
+
+describe('renderTransportEscalationCard', () => {
+  it('is Dismiss-only with NO Reauth button', () => {
+    const { keyboard, text } = renderTransportEscalationCard('gymbro')
+    const buttons = keyboard.inline_keyboard.flat()
+    expect(buttons.some((b) => b.callback_data?.includes('dismiss'))).toBe(true)
+    expect(buttons.some((b) => b.callback_data?.includes('reauth'))).toBe(false)
+    expect(text).toContain('gymbro')
+  })
+})
+
+// ─── flushDeferredUserNotices — turn-outcome gate ────────────────────────────
+
+describe('flushDeferredUserNotices', () => {
+  it('sends nothing when the turn delivered a reply (notice dropped)', () => {
+    const { deps, cap } = makeDeps()
+    cap.resolvedQueue = [{ chatIds: ['user-a'], text: 'notice', agent: 'gymbro', kind: 'transport-transient', atMs: 1, key: 'k' }]
+    flushDeferredUserNotices(/* turnDeliveredReply */ true, 'k', deps)
+    expect(cap.lastResolve).toEqual({ delivered: true, key: 'k' })
+    expect(cap.sent).toHaveLength(0)
+  })
+
+  it('flushes the plain notice (no keyboard) when the turn ended reply-less', () => {
+    const { deps, cap } = makeDeps()
+    cap.resolvedQueue = [{ chatIds: ['user-a', 'user-b'], text: 'notice', agent: 'gymbro', kind: 'transport-transient', atMs: 1, key: 'k' }]
+    flushDeferredUserNotices(/* turnDeliveredReply */ false, 'k', deps)
+    expect(cap.sent.map((s) => s.chatId)).toEqual(['user-a', 'user-b'])
+    // plain user notice — never a card/keyboard
+    expect(cap.sent.every((s) => s.hasKeyboard === false)).toBe(true)
+    expect(cap.sent.every((s) => s.text === 'notice')).toBe(true)
+  })
+
+  it('does nothing when no notices resolve', () => {
+    const { deps, cap } = makeDeps()
+    flushDeferredUserNotices(false, 'k', deps)
+    expect(cap.sent).toHaveLength(0)
+  })
+})

package/telegram-plugin/voice-normalize-text.ts

@@ -431,6 +431,11 @@ export function normalizeForSpeech(input: string): string {
   s = s.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
 
   // 3. Links [text](url) → text ; drop the URL entirely.
+  // FUTURE (not built): the Kokoro sidecar's misaki G2P (docker/voice-sidecar/
+  // server.py) accepts a per-word phoneme override via `[word](/phoneme/)`
+  // markup. Wiring a caller-supplied pronunciation override end-to-end would
+  // mean detecting that `/…/` form HERE and passing it through instead of
+  // collapsing it to the link text below. Deliberately left as a hook.
   s = s.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
 
   // 4. Autolinks <https://…> and bare URLs → "a link" (never spell a URL).

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

@@ -136,6 +136,10 @@ _VERIFY_BLOCK_REASON = (
     "UNLESS an equivalent active directive already exists (see the "
     "<active_directives> block for this turn) — in that case it is already "
     "saved; do NOT create a duplicate, just finish.\n"
+    "If the rule can be enforced deterministically — a settings.json hook, "
+    "a permission rule, a skill/script edit, or a config change — prefer "
+    "that (instead of, or in addition to, the directive) and say which you "
+    "did; reserve a directive for judgment rules code cannot enforce.\n"
     "If, on reflection, it was only a one-off instruction for this task, do "
     "NOT create a directive — just finish your reply normally.\n"
     "This verification fires once per turn.\n"

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

@@ -1442,8 +1442,13 @@ _DIRECTIVE_CAPTURE_NUDGE = (
     "(verbatim, in the user’s own words) BEFORE you answer, so the "
     "correction survives future sessions. UNLESS an equivalent active "
     "directive already exists (see any <active_directives> block above) — "
-    "in that case it is already saved; do NOT create a duplicate. If it’s "
-    "only a one-off instruction, ignore this note and just answer.\n"
+    "in that case it is already saved; do NOT create a duplicate. If the "
+    "rule can be enforced deterministically — a settings.json hook, a "
+    "permission rule, a skill/script edit, or a config change — prefer "
+    "that (instead of, or in addition to, the directive) and say which "
+    "you did; reserve a directive for judgment rules code can’t enforce. "
+    "If it’s only a one-off instruction, ignore this note and just "
+    "answer.\n"
     "</directive_capture_check>"
 )