switchroom 0.19.48 → 0.20.0

package/telegram-plugin/tests/ipc-server-buzz-peer.test.ts

@@ -0,0 +1,269 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { createConnection, type Socket } from "net";
+import { createIpcServer, type IpcServer, type IpcClient } from "../gateway/ipc-server.js";
+import type { OutboundToBuzzMessage } from "../gateway/ipc-protocol.js";
+
+/**
+ * Buzz co-channel Phase 2b — S7 role-disjointness, enforced as a GATEWAY CODE
+ * mechanism (not sidecar self-discipline). These are real-Unix-socket tests: a
+ * raw net client sends hand-crafted frames so we can exercise the adversarial
+ * orderings a well-behaved sidecar would never emit.
+ *
+ * The invariants (ipc-server.ts handleHelloBuzzPeer / handleRegister):
+ *   - a hello_buzz_peer parks the connection as the single Buzz peer, NEVER in
+ *     agentIndex (getClient stays undefined; the peer's agentName is null);
+ *   - register on a peer connection is refused (close+drop);
+ *   - hello on an already-registered connection is refused (close+drop);
+ *   - the peer rides the watchdog's agentName===null exemption (never evicted);
+ *   - the peer slot is released on disconnect (identity-checked).
+ */
+
+function tmpSocket(): string {
+  const dir = mkdtempSync(join(tmpdir(), "ipc-buzz-peer-"));
+  return join(dir, "test.sock");
+}
+function wait(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+const OUTBOUND: OutboundToBuzzMessage = {
+  type: "outbound_to_buzz",
+  correlationId: "c1",
+  agentName: "klanker",
+  channelId: "chan",
+  payload: { kind: "message", text: "x" },
+};
+
+describe("ipc-server — Buzz peer role-disjointness (S7)", () => {
+  const servers: IpcServer[] = [];
+  const sockets: Socket[] = [];
+
+  afterEach(async () => {
+    for (const s of sockets) { try { s.destroy(); } catch { /* ignore */ } }
+    sockets.length = 0;
+    for (const srv of servers) await srv.close();
+    servers.length = 0;
+  });
+
+  function makeServer(overrides: Partial<Parameters<typeof createIpcServer>[0]> = {}) {
+    const registered: IpcClient[] = [];
+    const server = createIpcServer({
+      socketPath: overrides.socketPath ?? tmpSocket(),
+      onClientRegistered: (c) => registered.push(c),
+      onClientDisconnected: () => {},
+      onToolCall: async (_c, m) => ({ type: "tool_call_result", id: m.id, success: true }),
+      onSessionEvent: () => {},
+      onPermissionRequest: () => {},
+      onHeartbeat: () => {},
+      onScheduleRestart: () => {},
+      ...overrides,
+    });
+    servers.push(server);
+    return { server, registered };
+  }
+
+  /** Open a raw client, resolve once connected. Detects server-side close. */
+  function rawClient(socketPath: string) {
+    const sock = createConnection(socketPath);
+    sockets.push(sock);
+    let closedByServer = false;
+    sock.on("close", () => { closedByServer = true; });
+    sock.on("error", () => { /* server may reset on refuse */ });
+    const send = (obj: unknown) => sock.write(JSON.stringify(obj) + "\n");
+    const ready = new Promise<void>((res) => sock.on("connect", () => res()));
+    return { sock, send, ready, wasClosed: () => closedByServer };
+  }
+
+  it("parks a hello_buzz_peer as the Buzz peer, NOT in agentIndex", async () => {
+    const path = tmpSocket();
+    const { server } = makeServer({ socketPath: path });
+    const c = rawClient(path);
+    await c.ready;
+    c.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(60);
+
+    // Addressable as the peer, but never as an agent bridge.
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(true);
+    expect(server.getClient("klanker")).toBeUndefined();
+  });
+
+  it("REFUSES a register after hello_buzz_peer (peer must never claim a slot)", async () => {
+    const path = tmpSocket();
+    const { server } = makeServer({ socketPath: path });
+    const c = rawClient(path);
+    await c.ready;
+    c.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(40);
+    c.send({ type: "register", agentName: "klanker" });
+    await wait(80);
+
+    // The offending connection was closed+dropped; no agent slot was created.
+    expect(c.wasClosed()).toBe(true);
+    expect(server.getClient("klanker")).toBeUndefined();
+  });
+
+  it("REFUSES a hello_buzz_peer after register (bridge must never become the peer)", async () => {
+    const path = tmpSocket();
+    const { server } = makeServer({ socketPath: path });
+    const c = rawClient(path);
+    await c.ready;
+    c.send({ type: "register", agentName: "klanker" });
+    await wait(40);
+    expect(server.getClient("klanker")).toBeDefined(); // registered as a bridge
+    c.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(80);
+
+    // The connection is closed+dropped; no Buzz peer was installed.
+    expect(c.wasClosed()).toBe(true);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(false);
+  });
+
+  it("EXEMPTS the peer from the heartbeat watchdog (agentName===null)", async () => {
+    const path = tmpSocket();
+    // Aggressive watchdog: 200ms timeout, no heartbeats from the peer.
+    const { server } = makeServer({ socketPath: path, heartbeatTimeoutMs: 200 });
+    const c = rawClient(path);
+    await c.ready;
+    c.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(60);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(true);
+
+    // Well past the timeout with no heartbeat — a registered bridge would be
+    // evicted, but the peer (agentName===null) is exempt and survives.
+    await wait(500);
+    expect(c.wasClosed()).toBe(false);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(true);
+  });
+
+  it("releases the peer slot on disconnect (sendToBuzzPeer → false)", async () => {
+    const path = tmpSocket();
+    const { server } = makeServer({ socketPath: path });
+    const c = rawClient(path);
+    await c.ready;
+    c.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(60);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(true);
+
+    c.sock.destroy();
+    await wait(100);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(false);
+  });
+
+  it("forwards outbound_to_buzz to the peer and delivers buzz_publish_result to the handler", async () => {
+    const path = tmpSocket();
+    const onBuzzPublishResult = vi.fn();
+    const { server } = makeServer({ socketPath: path, onBuzzPublishResult });
+    const c = rawClient(path);
+    const received: unknown[] = [];
+    c.sock.on("data", (d: Buffer) => {
+      for (const line of d.toString().split("\n")) {
+        if (line.trim()) received.push(JSON.parse(line));
+      }
+    });
+    await c.ready;
+    c.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(60);
+
+    // Hub → peer.
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(true);
+    await wait(40);
+    expect(received).toContainEqual(expect.objectContaining({ type: "outbound_to_buzz", correlationId: "c1" }));
+
+    // Peer → hub.
+    c.send({ type: "buzz_publish_result", correlationId: "c1", ok: true, eventId: "evt-x" });
+    await wait(60);
+    expect(onBuzzPublishResult).toHaveBeenCalledTimes(1);
+    expect(onBuzzPublishResult.mock.calls[0][1]).toMatchObject({ correlationId: "c1", ok: true, eventId: "evt-x" });
+  });
+
+  // ── MAJOR-1a: confused-deputy close on the agent→peer surface ─────────────
+  it("IGNORES buzz_publish_result from a NON-peer connection (MAJOR-1a)", async () => {
+    const path = tmpSocket();
+    const onBuzzPublishResult = vi.fn();
+    makeServer({ socketPath: path, onBuzzPublishResult });
+
+    // (1) A fresh anonymous client that never announced hello_buzz_peer forges a
+    // publish result carrying a valid-looking correlationId + a foreign eventId.
+    const impostor = rawClient(path);
+    await impostor.ready;
+    impostor.send({ type: "buzz_publish_result", correlationId: "forged-1", ok: true, eventId: "attacker-evt" });
+    await wait(80);
+    expect(onBuzzPublishResult).not.toHaveBeenCalled();
+
+    // (2) A registered AGENT bridge (also not the peer) is likewise refused.
+    const bridge = rawClient(path);
+    await bridge.ready;
+    bridge.send({ type: "register", agentName: "klanker" });
+    await wait(40);
+    bridge.send({ type: "buzz_publish_result", correlationId: "forged-2", ok: true, eventId: "attacker-evt-2" });
+    await wait(80);
+    expect(onBuzzPublishResult).not.toHaveBeenCalled();
+
+    // (3) Contrast — the REAL peer's result DOES reach the handler, proving the
+    // guard blocks impostors specifically, not the mechanism wholesale.
+    const peer = rawClient(path);
+    await peer.ready;
+    peer.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(40);
+    peer.send({ type: "buzz_publish_result", correlationId: "real-1", ok: true, eventId: "evt-real" });
+    await wait(80);
+    expect(onBuzzPublishResult).toHaveBeenCalledTimes(1);
+    expect(onBuzzPublishResult.mock.calls[0][1]).toMatchObject({ correlationId: "real-1" });
+  });
+
+  // ── MAJOR-1b: a fresh hello cannot displace a LIVE peer ───────────────────
+  it("REFUSES a second hello_buzz_peer while a LIVE peer is connected (MAJOR-1b)", async () => {
+    const path = tmpSocket();
+    const onBuzzPublishResult = vi.fn();
+    const { server } = makeServer({ socketPath: path, onBuzzPublishResult });
+
+    const peer1 = rawClient(path);
+    await peer1.ready;
+    peer1.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(60);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(true);
+
+    // An impostor tries to seize the peer slot with a fresh hello, then forge a
+    // publish result — the attack that would poison msgToBuzz.
+    const impostor = rawClient(path);
+    await impostor.ready;
+    impostor.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(60);
+    impostor.send({ type: "buzz_publish_result", correlationId: "forged", ok: true, eventId: "attacker-evt" });
+    await wait(80);
+
+    // The impostor was refused (close+drop); the real peer is UNDISTURBED and
+    // still the addressed peer; the forged result never reached the handler.
+    expect(impostor.wasClosed()).toBe(true);
+    expect(peer1.wasClosed()).toBe(false);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(true);
+    expect(onBuzzPublishResult).not.toHaveBeenCalled();
+  });
+
+  it("ALLOWS a legitimate reconnect after the prior peer connection CLOSES (MAJOR-1b)", async () => {
+    const path = tmpSocket();
+    const { server } = makeServer({ socketPath: path });
+
+    const peer1 = rawClient(path);
+    await peer1.ready;
+    peer1.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(60);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(true);
+
+    // The sidecar's socket drops (crash/restart); removeClient nulls the slot.
+    peer1.sock.destroy();
+    await wait(120);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(false);
+
+    // A fresh reconnect + hello must succeed — the refuse-only-while-alive rule
+    // must not brick a real reconnect.
+    const peer2 = rawClient(path);
+    await peer2.ready;
+    peer2.send({ type: "hello_buzz_peer", agentName: "klanker" });
+    await wait(60);
+    expect(peer2.wasClosed()).toBe(false);
+    expect(server.sendToBuzzPeer(OUTBOUND)).toBe(true);
+  });
+});

package/telegram-plugin/tests/operator-events-session-tail.test.ts

@@ -107,6 +107,42 @@ describe('detectErrorInTranscriptLine — error detection', () => {
     expect(result!.terminal).toBe(true)
   })
 
+  it('marks an in-flight transport-transient retry NOT terminal (does not count toward escalation)', () => {
+    // A flaky request Claude Code is internally retrying (retryAttempt <
+    // maxRetries), surfaced as a bare `server_error` with no status. Pre-fix
+    // `transient` was false for transport-transient, so it was UNCONDITIONALLY
+    // terminal → a single recoverable request retried 3x could cross the ≥3
+    // escalation threshold and fire the operator "Repeated stream failures"
+    // card. It must be transient + in-flight (suppressed), counting nothing.
+    const line = JSON.stringify({
+      type: 'system',
+      subtype: 'api_error',
+      error: { type: 'server_error', message: 'Connection closed mid-response' },
+      retryAttempt: 2,
+      maxRetries: 10,
+    })
+    const result = detectErrorInTranscriptLine(line)
+    expect(result!.kind).toBe('transport-transient')
+    expect(result!.transient).toBe(true)
+    // 2 < 10 — still retrying → in-flight → the caller suppresses it (not counted).
+    expect(result!.terminal).toBe(false)
+  })
+
+  it('marks an exhausted transport-transient retry terminal (counts toward escalation)', () => {
+    const line = JSON.stringify({
+      type: 'system',
+      subtype: 'api_error',
+      error: { type: 'server_error', message: 'Connection closed mid-response' },
+      retryAttempt: 10,
+      maxRetries: 10,
+    })
+    const result = detectErrorInTranscriptLine(line)
+    expect(result!.kind).toBe('transport-transient')
+    expect(result!.transient).toBe(true)
+    // retries exhausted → terminal → escalates.
+    expect(result!.terminal).toBe(true)
+  })
+
   it('marks non-transient errors terminal (always escalate)', () => {
     const line = JSON.stringify({
       type: 'api_error',
@@ -156,6 +192,33 @@ describe('detectErrorInTranscriptLine — error detection', () => {
     expect(result!.detail).toContain('hit your limit')
   })
 
+  // Regression — the transport-abort bug this PR fixes. On a mid-response stream
+  // abort Claude Code emits `isApiErrorMessage:true` with `error:"server_error"`
+  // and NO `apiErrorStatus`. Pre-fix that had no transport branch and fell
+  // through to the status fallback, FABRICATING `unknown-4xx` — a card carrying a
+  // wrong Reauth button, broadcast to every chat. It must classify
+  // transport-transient (terminal, non-transient) instead.
+  it('classifies the verbatim server_error mid-stream abort as transport-transient (not unknown-4xx)', () => {
+    // The exact on-disk shape: isApiErrorMessage, error "server_error", NO status.
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: {
+        role: 'assistant',
+        model: '<synthetic>',
+        content: [{ type: 'text', text: 'API Error: Connection closed mid-response' }],
+      },
+      error: 'server_error',
+      isApiErrorMessage: true,
+    })
+    const result = detectErrorInTranscriptLine(line)
+    expect(result).not.toBeNull()
+    expect(result!.kind).toBe('transport-transient')
+    expect(result!.kind).not.toBe('unknown-4xx')
+    // Claude writes this shape only after its own retries are exhausted → terminal.
+    expect(result!.terminal).toBe(true)
+    expect(result!.transient).toBe(false)
+  })
+
   // Regression — the carrie incident (2026-07-12). Anthropic also emits a
   // 429 for a TRANSIENT per-account burst / RPM throttle whose wording
   // explicitly negates the account-quota reading ("would exceed your

package/telegram-plugin/tests/operator-events.test.ts

@@ -142,13 +142,61 @@ describe('classifyClaudeError — safety: must never throw', () => {
   }
 })
 
-describe('classifyClaudeError — unknown-4xx is the default fallback', () => {
-  it('unknown object with no status defaults to unknown-4xx', () => {
-    expect(classifyClaudeError({ totally: 'unrecognised' })).toBe('unknown-4xx')
+describe('classifyClaudeError — no-status default is the neutral 5xx (never a fabricated 4xx)', () => {
+  it('unknown object with no status defaults to unknown-5xx, NOT unknown-4xx', () => {
+    // Regression: an unrecognized shape with no HTTP status used to fabricate
+    // `unknown-4xx`, whose card carried a wrong Reauth remedy broadcast to every
+    // chat. With no status the honest neutral default is unknown-5xx.
+    expect(classifyClaudeError({ totally: 'unrecognised' })).toBe('unknown-5xx')
+    expect(classifyClaudeError({ totally: 'unrecognised' })).not.toBe('unknown-4xx')
   })
 
-  it('empty string → unknown-4xx', () => {
-    expect(classifyClaudeError('')).toBe('unknown-4xx')
+  it('empty string → unknown-5xx', () => {
+    expect(classifyClaudeError('')).toBe('unknown-5xx')
+  })
+
+  it('still honors an explicit 4xx status', () => {
+    expect(classifyClaudeError({ status: 404 })).toBe('unknown-4xx')
+  })
+})
+
+describe('classifyClaudeError — transport-transient (mid-response stream abort)', () => {
+  it('classifies a bare server_error type as transport-transient', () => {
+    expect(classifyClaudeError({ type: 'server_error' })).toBe('transport-transient')
+  })
+
+  it('classifies server_error via error_code / code / nested error.type', () => {
+    expect(classifyClaudeError({ error_code: 'server_error' })).toBe('transport-transient')
+    expect(classifyClaudeError({ code: 'server_error' })).toBe('transport-transient')
+    expect(classifyClaudeError({ error: { type: 'server_error' } })).toBe('transport-transient')
+  })
+
+  it('classifies api_error (Anthropic HTTP 500) as transport-transient', () => {
+    expect(classifyClaudeError({ type: 'api_error' })).toBe('transport-transient')
+  })
+
+  it('classifies api_error/server_error carrying a 5xx status as transport-transient', () => {
+    expect(classifyClaudeError({ type: 'api_error', status: 500 })).toBe('transport-transient')
+    expect(classifyClaudeError({ type: 'server_error', status: 503 })).toBe('transport-transient')
+  })
+
+  it('does NOT swallow a status-bearing 4xx api_error (LiteLLM-wrapped 401) as transport-transient', () => {
+    // LiteLLM stamps a generic `type: "api_error"` on WRAPPED upstream faults
+    // that carry a 4xx status; session-tail threads that status through. The
+    // transport branch is guarded to status-less/5xx shapes, so the HTTP status
+    // wins and this surfaces an operator card (unknown-4xx) — NOT the silent
+    // transport-transient path. Branch-order regression guard: unlike the bare
+    // `{status:404}` test above, this exercises a TYPED api_error + 4xx status.
+    expect(classifyClaudeError({ type: 'api_error', status: 401 })).toBe('unknown-4xx')
+    expect(classifyClaudeError({ type: 'api_error', status: 401 })).not.toBe('transport-transient')
+    expect(classifyClaudeError({ type: 'server_error', status: 429 })).toBe('unknown-4xx')
+  })
+
+  it('does NOT fire on an unrelated error that merely mentions "server error" in prose', () => {
+    // Exact type/code equality only — never a message substring — so a genuine
+    // auth fault mislabeled with server-error prose still classifies as auth.
+    expect(classifyClaudeError({ type: 'authentication_error', message: 'server error while validating' }))
+      .toBe('credentials-invalid')
   })
 })
 
@@ -238,10 +286,25 @@ describe('renderOperatorEvent — agent-restarted-unexpectedly', () => {
 })
 
 describe('renderOperatorEvent — unknown-4xx', () => {
-  it('surfaces "API error (4xx)" with dismiss button', () => {
+  it('surfaces "API error (4xx)" with a Dismiss button and NO Reauth button', () => {
     const { text, keyboard } = renderOperatorEvent(makeEvent('unknown-4xx'))
     expect(text).toContain('4xx')
-    expect(keyboard.inline_keyboard.flat().some(b => b.callback_data?.includes('dismiss'))).toBe(true)
+    const buttons = keyboard.inline_keyboard.flat()
+    expect(buttons.some(b => b.callback_data?.includes('dismiss'))).toBe(true)
+    // Reauth was REMOVED — it is the wrong remedy for a catch-all client error,
+    // and Reauth buttons now live ONLY on credentials-* cards. Assert the OUTCOME.
+    expect(buttons.some(b => b.callback_data?.includes('op:reauth'))).toBe(false)
+    expect(buttons.some(b => b.callback_data?.includes('reauth'))).toBe(false)
+  })
+})
+
+describe('renderOperatorEvent — transport-transient (defensive fallback)', () => {
+  it('is calm and Dismiss-only — NEVER a Reauth button', () => {
+    const { text, keyboard } = renderOperatorEvent(makeEvent('transport-transient'))
+    expect(text).toContain('transport')
+    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)
   })
 })
 
@@ -289,6 +352,7 @@ describe('renderOperatorEvent — all kinds produce valid keyboard structure', (
     'rate-limited',
     'agent-crashed',
     'agent-restarted-unexpectedly',
+    'transport-transient',
     'unknown-4xx',
     'unknown-5xx',
     'config-warning',

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>"
 )