switchroom 0.16.28 → 0.16.38

package/telegram-plugin/gateway/gateway.ts

@@ -48,6 +48,26 @@ import {
   type GifSendArgs,
 } from '../sticker-aliases.js'
 import { transcribeViaWhisper } from '../voice-transcribe.js'
+import { transcribeViaSidecar } from '../voice-transcribe-sidecar.js'
+import {
+  synthesizeViaSidecar,
+  chunkTtsText,
+  clampTtsSpeed,
+} from '../voice-synthesize-sidecar.js'
+import {
+  VoiceOnDemandCache,
+  mintVoiceOnDemandToken,
+  isVoiceOnDemandCallback,
+  parseVoiceOnDemandToken,
+  buildListenKeyboard,
+  mayInjectListenButton,
+} from '../voice-ondemand.js'
+
+/** Fleet default TTS speed when voice_out is enabled but speed is unset —
+ *  slightly brisker than neutral (Ken's chosen default). */
+const VOICE_OUT_DEFAULT_SPEED = 1.1
+import { normalizeForSpeech } from '../voice-normalize-text.js'
+import { synthesizeViaOpenAi } from '../voice-synthesize.js'
 import {
   createTelegraphAccount,
   createTelegraphPage,
@@ -65,6 +85,9 @@ import {
 import { StatusReactionController } from '../status-reactions.js'
 import { DeferredDoneReactions } from '../reaction-defer.js'
 import { createWorkerActivityFeed, isWorkerActivityFeedEnabled } from '../worker-activity-feed.js'
+import { reconcilePin, type PinBotApi } from '../status-pin-driver.js'
+import type { PinState, DesiredPin } from '../status-pin.js'
+import { decidePinAction } from '../status-pin.js'
 import { formatTurnLifecycle, detectStatusSurfaceDegraded } from './status-surface-log.js'
 import { parseSourceMessageId } from './source-message-id.js'
 import {
@@ -73,11 +96,14 @@ import {
   duplicateDenyMessage,
   isRecentTimeoutDuplicate,
   PERMISSION_TTL_MS,
+  approvalTtlMs,
   ttlForTool,
   buildTimedOutCardEdits,
   STALE_TAP_NOTICE,
   type PermissionCardRef,
 } from './permission-timeout.js'
+import { renderVaultRequestAccessCard } from './vault-request-access-card.js'
+import { createPermissionCardStore } from './permission-card-store.js'
 import { pickRecoveredPermissionOrigin } from './permission-card-origin.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
 import { appendActivityLabel, clipNarrative, renderActivityFeedWithNested, type SessionActivityHeader } from '../tool-activity-summary.js'
@@ -140,6 +166,10 @@ import {
   runMicrosoftConnectPoll,
 } from './microsoft-connect-flow.js'
 import { resolveAuthBrokerSocketPath } from '../../src/auth/broker/client.js'
+import { materializeVoiceKey } from '../../src/telegram/materialize-voice-key.js'
+import { materializeSidecarToken } from '../../src/telegram/materialize-sidecar-token.js'
+import { loadHostCapabilities } from '../../src/setup/host-capabilities.js'
+import type { VoiceEngine } from '../../src/setup/gpu-detect.js'
 import { createFleetFallbackGate } from '../fleet-fallback-gate.js'
 import { createFleetFallbackResumeGate } from '../fleet-fallback-resume.js'
 import { resolveExhaustUntil } from './exhaust-until.js'
@@ -195,7 +225,7 @@ const REPLY_TO_TEXT_MAX = 200
 const SILENT_END_FALLBACK_TEXT =
   '⚠️ The agent finished working but didn’t send a reply — your last ' +
   'message may not have been answered. Please try asking again.'
-import { splitMarkdownChunks, hardSliceToCap, repairEscapedWhitespace, normalizeParagraphBreaks, escapeMarkdown, RICH_MESSAGE_MAX_CHARS } from '../format.js'
+import { splitMarkdownChunks, hardSliceToCap, repairEscapedWhitespace, normalizeParagraphBreaks, addParagraphSpacers, escapeMarkdown, RICH_MESSAGE_MAX_CHARS } from '../format.js'
 import { richMessage } from '../rich-send.js'
 import { scrubVoice } from '../text-voice-scrub.js'
 import {
@@ -341,6 +371,15 @@ import {
   obligationEscalationText,
 } from './obligation-ledger.js'
 import { loadObligations, persistObligations } from './obligation-store.js'
+import {
+  loadStatusPins,
+  pinnedMessageIsOurs,
+  reconcileAndPersistStatusPin,
+  runStatusPinBootCleanup,
+  type PersistedStatusPin,
+  type StatusPinPersistOp,
+  type TrackedStatusPin,
+} from './status-pin-store.js'
 import { driveEscalation } from './escalation-drive.js'
 import { shouldSuppressRepresent } from './represent-guard.js'
 import { createInboundSpool } from './inbound-spool.js'
@@ -362,6 +401,9 @@ import {
 } from './emission-authority.js'
 import { CurrentTurnMap } from './current-turn-map.js'
 import { resolveAnswerThreadId } from './answer-thread-resolve.js'
+import { resolveChatIdFallback } from './chat-id-fallback.js'
+import { decideObligationTurnEnd } from './obligation-turn-end.js'
+import { maybeRotate } from './turns-jsonl-rotate.js'
 import {
   createDeliveryQueue,
   trackDelivery,
@@ -385,6 +427,7 @@ import { dispatchEffects, isDispatchEnabled } from './inbound-delivery-machine-d
 import { maybeFireWarmup } from './prefix-warmup.js'
 import {
   buildVaultGrantApprovedInbound,
+  buildVaultGrantApprovedCardText,
   buildVaultGrantDeniedInbound,
   buildVaultSaveCompletedInbound,
   buildVaultSaveFailedInbound,
@@ -428,6 +471,8 @@ import type {
   QuotaWallDetectedMessage,
   PostSkillProposalMessage,
   PermissionEvent,
+  RolloutStatusPostMessage,
+  RolloutStatusEditMessage,
 } from './ipc-protocol.js'
 import { DebounceBuffer, HourCap, buildReactionInboundMeta, buildReactionInboundText, evaluateTriggerCandidate, isGroupChat, resolveReactionsConfig, truncatePreview, type PendingReaction, type ReactionBatch, type ReactionsResolvedConfig } from './reaction-trigger.js'
 import { buildReactionDispatchInbound, evaluateReactionDispatch, resolveReactionDispatchConfig, type ReactionDispatchResolvedConfig } from './reaction-dispatch.js'
@@ -599,6 +644,7 @@ process.on('beforeExit', () => {
 
 // ─── Env + state dir ──────────────────────────────────────────────────────
 const STATE_DIR = process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
+const permCardStore = createPermissionCardStore(STATE_DIR)
 const ACCESS_FILE = join(STATE_DIR, 'access.json')
 const APPROVED_DIR = join(STATE_DIR, 'approved')
 const ENV_FILE = join(STATE_DIR, '.env')
@@ -950,12 +996,42 @@ type Access = {
   /** Voice-in transcription config (#578 spike). When `enabled` is
    *  true and provider is 'openai', inbound voice/audio messages are
    *  downloaded and transcribed via Whisper, then surface as the
-   *  user's inbound text. API key read from
-   *  ~/.switchroom/openai-api-key. Off by default. */
+   *  user's inbound text. The provider API key is a `vault:` reference
+   *  (`api_key`, default `vault:openai/api-key`) resolved through the
+   *  vault broker at use-time — never read from a plaintext file. Off by
+   *  default. */
   voice_in?: {
     enabled?: boolean
     provider?: 'openai'
     language?: string
+    api_key?: string
+  }
+  /** Outbound spoken replies via TTS (PR-C2). When enabled, the agent's
+   *  text reply is synthesized into an OGG/Opus voice note and sent
+   *  alongside (or instead of) the text, per `reply_mode`. The 'kokoro'
+   *  engine uses the local voice sidecar (POST /tts) and is only active
+   *  when the host voice verdict is local (SWITCHROOM_VOICE_ENGINE ===
+   *  'local'); 'openai' is an honest-exception cloud path gated on an
+   *  `api_key` vault ref. Voice is best-effort and fully non-fatal — any
+   *  TTS error falls back to the text reply. ONE voice note per response:
+   *  the reply is speech-normalized (markdown/symbols stripped) and, for the
+   *  kokoro sidecar, sent in a SINGLE /tts call that returns one concatenated
+   *  file. Off by default. */
+  voice_out?: {
+    enabled?: boolean
+    engine?: 'kokoro' | 'openai'
+    voice?: string
+    reply_mode?: 'voice+text' | 'voice-only' | 'on-demand'
+    /** Kokoro-engine playback speed. Clamped to 0.5–2.0; defaults to 1.1
+     *  when voice_out is enabled but speed is unset (the fleet default —
+     *  slightly brisker than neutral). Ignored by the OpenAI path. */
+    speed?: number
+    /** OpenAI-engine only: per-voice-note chunk size (default 600) used to
+     *  split a long reply across sequential notes, since OpenAI's TTS input
+     *  has a hard cap. Ignored by the kokoro path, which sends the whole
+     *  reply in one call (the sidecar owns length + concatenation). */
+    max_chars?: number
+    api_key?: string
   }
   /** Telegraph long-reply publishing (#579). When enabled, replies
    *  above `threshold` chars publish to Telegraph and the agent's
@@ -1049,6 +1125,7 @@ function readAccessFile(): Access {
       // `access.telegraph`, `access.stickers`) silently see undefined.
       stickers: parsed.stickers,
       voice_in: parsed.voice_in,
+      voice_out: parsed.voice_out,
       telegraph: parsed.telegraph,
     }
   } catch (err) {
@@ -3206,6 +3283,19 @@ function purgeReactionTracking(key: string, endingTurn?: CurrentTurn): void {
   // successor turn; the timer's own turnId match is the second guard, this is
   // the first. Idempotent — a no-op when no timer is registered.
   stopEarlyLivenessOpen(key as string)
+  // Status-pin: turn end is the canonical unpin point for the foreground
+  // pin. `purgeReactionTracking` is the single turn-end owner (all normal /
+  // abnormal exit branches funnel here), so this is the one place the
+  // foreground status pin is dropped. Idempotent: a no-op when nothing was
+  // pinned (trivial turn that never opened a status message). The
+  // drop-on-unpin contract in reconcilePin guarantees state clears even if
+  // the unpin API throws — a stuck pin can never outlive its turn.
+  {
+    const pinChatId = endingTurn != null
+      ? endingTurn.sessionChatId
+      : chatIdOfChatKey(key as _ChatKey)
+    void reconcileStatusPin(`fg:${key}`, pinChatId, { pinned: false })
+  }
   if (msgInfo) {
     const agentDir = resolveAgentDirFromEnv()
     if (agentDir != null) removeActiveReaction(agentDir, msgInfo.chatId, msgInfo.messageId)
@@ -3401,7 +3491,20 @@ function emitTurnRecord(turn: CurrentTurn, endedAt: number): void {
         status: turn.finalAnswerDelivered ? 'complete' : 'no_reply',
         turn_id: turn.turnId,
       }) + '\n'
-    appendFileSync('/state/agent/turns.jsonl', rec)
+    const turnsPath = '/state/agent/turns.jsonl'
+    // Size-cap rotation: keep at most one rotated generation so the file can't
+    // grow unbounded on a long-lived agent. Best-effort (never throws).
+    maybeRotate(turnsPath, {
+      statSize: (p) => {
+        try {
+          return statSync(p).size
+        } catch {
+          return undefined
+        }
+      },
+      rename: (from, to) => renameSync(from, to),
+    })
+    appendFileSync(turnsPath, rec)
   } catch {
     // best-effort — never let metrics emission break turn teardown
   }
@@ -3457,7 +3560,7 @@ function endCurrentTurnAtomic(turn: CurrentTurn): void {
   // At turn_end with replyCalled=true the model explicitly signalled completion
   // AND replied, so the obligation is satisfied regardless of finalAnswerDelivered.
   if (OBLIGATION_LEDGER_ENABLED) {
-    if (turn.finalAnswerDelivered || turn.replyCalled) {
+    if (decideObligationTurnEnd(turn.finalAnswerDelivered, turn.replyCalled) === 'close') {
       obligationLedger.close(turn.turnId)
     } else {
       // Turn ended WITHOUT any reply (no ack, no answer). If this turn was
@@ -4671,7 +4774,10 @@ interface PendingVaultRequestSave {
   staged_at: number
 }
 const pendingVaultRequestSaves = new Map<string, PendingVaultRequestSave>()
-const VAULT_REQUEST_SAVE_TTL_MS = 10 * 60 * 1000
+// Gateway-side reap window for a staged vault-save card. Tracks the operator
+// approval-card lifetime (config-driven, 60-min default) so the reap never
+// races ahead of the card the operator is still looking at.
+const VAULT_REQUEST_SAVE_TTL_MS = approvalTtlMs()
 function sweepPendingVaultRequestSaves(): void {
   const cutoff = Date.now() - VAULT_REQUEST_SAVE_TTL_MS
   for (const [k, v] of pendingVaultRequestSaves) {
@@ -4716,7 +4822,9 @@ interface PendingVaultRequestAccess {
   staged_at: number
 }
 const pendingVaultRequestAccesses = new Map<string, PendingVaultRequestAccess>()
-const VAULT_REQUEST_ACCESS_TTL_MS = 10 * 60 * 1000
+// Gateway-side reap window for a staged vault-access card. Tracks the operator
+// approval-card lifetime (config-driven, 60-min default) — see approvalTtlMs.
+const VAULT_REQUEST_ACCESS_TTL_MS = approvalTtlMs()
 function sweepPendingVaultRequestAccesses(): void {
   const cutoff = Date.now() - VAULT_REQUEST_ACCESS_TTL_MS
   for (const [k, v] of pendingVaultRequestAccesses) {
@@ -5024,6 +5132,7 @@ const pendingStateReaper = setInterval(() => {
         `${timeoutMinutes}m)\n`,
       )
       pendingPermissions.delete(k)
+      permCardStore.remove(k)
     }
   }
   // Drop no-repeat suppression entries past the safety-cap window (the primary
@@ -5481,6 +5590,273 @@ const CLEAR_STATUS_ON_COMPLETION = (() => {
   return v === '1' || v === 'true' || v === 'on' || v === 'yes'
 })()
 
+// Whether to SILENTLY pin the already-rendered status message while its work
+// is in-flight (auto-unpinned on completion). Default ON (silent + low-risk):
+// keeps in-flight work in view when the conversation scrolls past it. This is
+// the ONE sanctioned pin under `chat-is-the-single-source-of-truth` — it pins
+// a message the chat ALREADY rendered (the per-turn activity/status message,
+// the `🛠 Worker` message), never a new parallel surface, never with a device
+// buzz. Opt OUT per agent via channels.telegram.pin_status_while_working: false
+// (→ this env). See status-pin.ts / status-pin-driver.ts and
+// `reference/invariants.md` § chat-is-the-single-source-of-truth.
+const PIN_STATUS_WHILE_WORKING = (() => {
+  const raw = process.env.SWITCHROOM_TG_PIN_STATUS_WHILE_WORKING
+  if (raw == null) return true // default ON
+  const v = raw.trim().toLowerCase()
+  return !(v === '0' || v === 'false' || v === 'off' || v === 'no')
+})()
+
+// ─── Status-pin: single-owner state + reconcile ────────────────────────────
+// EXACTLY ONE owner of pin state. Every desired-state change for a key routes
+// through `reconcileStatusPin`, which computes ONE action (pin|unpin|noop) via
+// the pure `decidePinAction` and executes it through `reconcilePin` (which
+// drops the claim on unpin even if the API throws — so pin state can never get
+// stuck). Two desired-state sources feed distinct keys:
+//   - foreground: `fg:<statusKey>` — pinned while the per-turn activity message
+//     is in-flight; unpinned at the canonical turn-end (purgeReactionTracking).
+//   - background: `wk:<agentId>`   — pinned while the `🛠 Worker` message runs;
+//     unpinned on that worker's completion (worker-feed finish).
+// It does NOT touch the reply / stream_reply send handlers (the v1 bug was send
+// handlers unconditionally unpinning on every send) and runs NO polling
+// watchdog / getChat().pinned_message reconciler.
+const statusPinState = new Map<string, PinState>()
+// Companion registry: pinKey → chatId, so the pre-restart sweep can unpin
+// owned pins without threading the chat id through every call site. Written on
+// every desired-pinned reconcile, cleared alongside the state on unpin.
+const statusPinChatIds = new Map<string, string>()
+
+// Durable snapshot of the pin claim set on the persistent per-agent volume
+// (STATE_DIR = /state/agent/telegram in prod). Closes the crash hole: the
+// in-memory Maps alone empty on restart, so a status pin left dangling by a
+// crashed session is never unpinned and the service-message-deletion handler
+// can't recognise it as ours. Every reconcile persists the current claim set;
+// boot cleanup (statusPinBootCleanup, wired after lockedBot is defined) unpins
+// each persisted entry and clears the store. STATIC mode and feature-off skip
+// disk. Mirrors obligation-store.ts.
+const STATUS_PIN_STORE_PATH = join(STATE_DIR, 'status-pins.json')
+const statusPinStoreFs = {
+  readFileSync: (p: string) => readFileSync(p, 'utf8'),
+  writeFileSync: (p: string, d: string) => writeFileSync(p, d),
+  renameSync: (a: string, b: string) => renameSync(a, b),
+  existsSync: (p: string) => existsSync(p),
+}
+const statusPinPersistEnabled = !STATIC && PIN_STATUS_WHILE_WORKING
+
+// The full live claim set as persisted rows (confirmed pins), from the Maps.
+function snapshotStatusPins(): PersistedStatusPin[] {
+  const snapshot: PersistedStatusPin[] = []
+  for (const [pinKey, state] of statusPinState) {
+    const chatId = statusPinChatIds.get(pinKey)
+    if (chatId == null) continue
+    snapshot.push({ pinKey, chatId, messageId: state.messageId })
+  }
+  return snapshot
+}
+
+// The live claim set EXCLUDING one key — used by reconcileAndPersistStatusPin so
+// it can rewrite the whole set atomically while it flips that one key's record
+// between pending / confirmed / absent.
+function snapshotStatusPinsExcept(exceptKey: string): PersistedStatusPin[] {
+  return snapshotStatusPins().filter((p) => p.pinKey !== exceptKey)
+}
+
+// The Bot API surface the pin driver needs. `lockedBot` is defined later; wrap
+// lazily so this helper can be declared alongside the state it owns.
+function statusPinApi(): PinBotApi {
+  return {
+    pinChatMessage: (chat_id, message_id, opts) =>
+      robustApiCall(
+        () => lockedBot.api.pinChatMessage(chat_id, message_id, opts),
+        { chat_id: String(chat_id), verb: 'status-pin.pin' },
+      ),
+    unpinChatMessage: (chat_id, message_id) =>
+      robustApiCall(
+        () => lockedBot.api.unpinChatMessage(chat_id, message_id),
+        { chat_id: String(chat_id), verb: 'status-pin.unpin' },
+      ),
+  }
+}
+
+/**
+ * Boot-time orphan cleanup — thin gateway wrapper over the pure
+ * `runStatusPinBootCleanup` (which owns the load → best-effort-unpin →
+ * empty-store contract). Binds the live fs seam, the robust unpin api, and the
+ * gateway logger.
+ *
+ * MUST run ONLY after this gateway wins the startup mutex (the store is a
+ * shared per-agent file; a losing double-boot would unpin the live holder's
+ * legitimate pins). Runs before any new pin claim is written, so the emptied
+ * store leaves the service-message handler's ownership check with no false
+ * positives.
+ */
+async function statusPinBootCleanup(): Promise<void> {
+  if (!statusPinPersistEnabled) return
+  const api = statusPinApi()
+  const { cleared, total } = await runStatusPinBootCleanup({
+    path: STATUS_PIN_STORE_PATH,
+    fs: statusPinStoreFs,
+    unpin: (chatId, messageId) => api.unpinChatMessage(chatId, messageId),
+  })
+  if (total > 0) {
+    process.stderr.write(
+      `telegram gateway: status-pin: cleared ${cleared}/${total} ` +
+        `orphaned pin(s) from a prior session\n`,
+    )
+  }
+}
+// NOTE: statusPinBootCleanup() is deliberately NOT invoked here at import time.
+// The status-pin store is a SHARED per-agent file, and cleanup issues real
+// unpinChatMessage calls. On a double-boot the losing gateway must NOT touch
+// that shared state — its unpins would strip pins the STILL-ALIVE holder
+// legitimately owns. So the call is gated on winning the startup mutex
+// (top-level await below); see the acquireStartupLock block.
+
+/**
+ * The single entry point that mutates pin state for `pinKey`. Serialises
+ * nothing itself — callers fire-and-forget; the pure decision + drop-on-unpin
+ * contract keep state consistent. No-op when the feature is disabled.
+ */
+async function reconcileStatusPin(
+  pinKey: string,
+  chatId: string,
+  desired: DesiredPin,
+): Promise<void> {
+  // Fire-and-forget hard boundary. Most callers invoke this as
+  // `void reconcileStatusPin(...)` (auto status-pin is best-effort — it must
+  // never affect turn flow). reconcilePin already swallows pin/unpin API
+  // errors via onError, but the surrounding persistence + Map bookkeeping
+  // (and any future edge) could still reject the returned promise. A rejected
+  // fire-and-forget promise becomes a process-level `unhandledRejection` which
+  // the gateway's handler crashes on — that is exactly how a benign
+  // "not enough rights to manage pinned messages" 400 in a supergroup took the
+  // whole gateway down (marko, 2026-07-01). Auto status-pin is cosmetic; it
+  // must NEVER be able to crash the gateway. Any throw here is logged and
+  // absorbed. (The `pin_message` MCP tool still surfaces failures to the agent
+  // as a normal tool-error — that path is `executePinMessage`, not this one.)
+  try {
+    await reconcileStatusPinInner(pinKey, chatId, desired)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    process.stderr.write(
+      `telegram gateway: status-pin reconcile absorbed error ` +
+        `(key=${pinKey} chat=${chatId}): ${msg}\n`,
+    )
+  }
+}
+
+async function reconcileStatusPinInner(
+  pinKey: string,
+  chatId: string,
+  desired: DesiredPin,
+): Promise<void> {
+  if (!PIN_STATUS_WHILE_WORKING) return
+  if (chatId.length === 0) return
+  const prev = statusPinState.get(pinKey) ?? null
+
+  const runReconcile = () =>
+    reconcilePin({
+      api: statusPinApi(),
+      chatId,
+      prevState: prev,
+      desired,
+      onError: (phase, err) => {
+        const msg = err instanceof Error ? err.message : String(err)
+        process.stderr.write(
+          `telegram gateway: status-pin ${phase} failed (key=${pinKey} chat=${chatId}): ${msg}\n`,
+        )
+      },
+    })
+
+  // Classify the action so we persist INTENT before the pin API call. Only a
+  // fresh `pin` of a message that isn't already our claim opens the leak window
+  // (the API call actually pins something new); everything else (unpin, noop,
+  // re-pin of the same id) clears / leaves the record and is safe to persist
+  // after. See reconcileAndPersistStatusPin for the ordering rationale.
+  const action = decidePinAction(prev, desired)
+  const op: StatusPinPersistOp =
+    action.kind === 'pin'
+      ? { kind: 'pin', messageId: action.messageId }
+      : { kind: 'clear' }
+
+  if (!statusPinPersistEnabled) {
+    // Persistence off (STATIC / feature-off): just reconcile + update Maps.
+    const next = await runReconcile()
+    if (next == null) {
+      statusPinState.delete(pinKey)
+      statusPinChatIds.delete(pinKey)
+    } else {
+      statusPinState.set(pinKey, next)
+      statusPinChatIds.set(pinKey, chatId)
+    }
+    return
+  }
+
+  // Persist-BEFORE-pin ordering lives in reconcileAndPersistStatusPin: for a
+  // pin it writes a `pending` record first, then confirms it after the API call
+  // lands (or drops it on failure). A crash in the window leaves a pending
+  // record boot cleanup will unpin. In-memory Maps are updated from the result.
+  const next = await reconcileAndPersistStatusPin({
+    path: STATUS_PIN_STORE_PATH,
+    fs: statusPinStoreFs,
+    pinKey,
+    chatId,
+    op,
+    snapshotOthers: () => snapshotStatusPinsExcept(pinKey),
+    applyPin: runReconcile,
+  })
+  if (next == null) {
+    statusPinState.delete(pinKey)
+    statusPinChatIds.delete(pinKey)
+  } else {
+    statusPinState.set(pinKey, next)
+    statusPinChatIds.set(pinKey, chatId)
+  }
+}
+
+/**
+ * Background-worker desired-pin, driven off the live `🛠 Worker` message.
+ * Reads the worker feed's current message_id (the EXISTING message — we pin
+ * what the feed already rendered, never a new send) and reconciles a silent
+ * pin while it's running / an unpin on completion. No-op until the feed has
+ * actually painted a message for this worker (trivial sub-second workers stay
+ * silent and are never pinned). Keyed `wk:<agentId>`.
+ */
+function reconcileWorkerPin(
+  agentId: string,
+  chatId: string | null,
+  running: boolean,
+): void {
+  if (!PIN_STATUS_WHILE_WORKING) return
+  const key = `wk:${agentId}`
+  if (!running) {
+    // Unpin: recover the chat we pinned in (caller may not have it at
+    // completion). No-op when nothing was pinned for this worker.
+    const unpinChat = chatId ?? statusPinChatIds.get(key)
+    if (unpinChat == null) return
+    void reconcileStatusPin(key, unpinChat, { pinned: false })
+    return
+  }
+  if (chatId == null) return
+  const messageId = workerActivityFeed?.messageIdOf(agentId) ?? null
+  if (messageId == null) return // no message painted yet — nothing to pin
+  void reconcileStatusPin(key, chatId, { pinned: true, messageId })
+}
+
+/** Unpin every owned status pin — used by the pre-restart sweep so a
+ *  crash / interrupt never leaves a permanent pin behind. Best-effort;
+ *  clears the claim regardless of the unpin outcome (drop-on-unpin). */
+async function unpinAllStatusPins(): Promise<void> {
+  const keys = [...statusPinState.keys()]
+  for (const key of keys) {
+    const st = statusPinState.get(key)
+    if (st == null) continue
+    // Recover the chat id from the state map's companion key registry.
+    const chatId = statusPinChatIds.get(key)
+    if (chatId == null) { statusPinState.delete(key); continue }
+    await reconcileStatusPin(key, chatId, { pinned: false })
+  }
+}
+
 // Activity feed. The gateway streams a live "what it's doing" tool-activity
 // feed for every turn. The PreToolUse sidecar emits a `tool_label` per tool
 // call (flush-independent, so it stays real-time on fast/clustered-tool
@@ -5628,6 +6004,12 @@ function ensureIssuesCard(chatId: string, threadId: number | undefined): void {
     process.stderr.write(
       `telegram gateway: wrote PID file ${GATEWAY_PID_PATH} pid=${process.pid} startedAt=${GATEWAY_STARTED_AT_MS}\n`,
     )
+    // We WON the startup mutex — this gateway is the sole live owner of the
+    // shared per-agent status-pin store, so it's now safe to clean up orphaned
+    // pins from a prior (dead) session. Gated here (not at import time) so a
+    // LOSING double-boot never unpins the live holder's legitimate pins.
+    // Fire-and-forget: cleanup is best-effort and must not block boot.
+    void statusPinBootCleanup()
   } catch (err) {
     process.stderr.write(
       `telegram gateway: boot.lock_acquire_failed err=${(err as Error).message} agent=${SWITCHROOM_AGENT_NAME}\n`,
@@ -5639,6 +6021,11 @@ function ensureIssuesCard(chatId: string, threadId: number | undefined): void {
     try {
       writePidFile(GATEWAY_PID_PATH, { pid: process.pid, startedAtMs: GATEWAY_STARTED_AT_MS })
       process.stderr.write(`telegram gateway: wrote PID file ${GATEWAY_PID_PATH} pid=${process.pid} startedAt=${GATEWAY_STARTED_AT_MS} (mutex-fallback)\n`)
+      // Mutex was unavailable (link() unsupported fs); the legacy pid-file
+      // probe + 409-retry loop is still the liveness guard on this path. A
+      // successful writePidFile here means no live holder was detected, so
+      // running orphan cleanup is consistent with the pre-mutex behaviour.
+      void statusPinBootCleanup()
     } catch (writeErr) {
       process.stderr.write(`telegram gateway: writePidFile failed: ${writeErr}\n`)
     }
@@ -7118,6 +7505,14 @@ const ipcServer: IpcServer = createIpcServer({
         const pend = pendingPermissions.get(requestId)
         if (pend && sent && typeof sent.message_id === 'number') {
           pend.cards.push({ chatId, messageId: sent.message_id })
+          permCardStore.add({
+            requestId,
+            chatId,
+            messageId: sent.message_id,
+            startedAt: pend.startedAt,
+            toolName: pend.tool_name,
+            cardText: pend.card_text,
+          })
         }
       }).catch(e => {
         process.stderr.write(`telegram gateway: permission_request send to ${chatId} failed: ${e}\n`)
@@ -7556,6 +7951,81 @@ const ipcServer: IpcServer = createIpcServer({
     })
   },
 
+  // #2726 — hostd-initiated rollout status message. Part 1 uses this only for
+  // the terminal ping; Part 2 uses the same post as the FIRST narration
+  // message, then EDITs it (onRolloutStatusEdit) as later phases arrive. This
+  // is an ORDINARY operator-DM message, NOT a pinned card — the framework
+  // speaking a plain progress line in the chat. We reply with the message_id so
+  // hostd can edit it later; a post failure replies ok:false (hostd then just
+  // won't edit — the durable audit log remains the record).
+  async onRolloutStatusPost(client: IpcClient, msg: RolloutStatusPostMessage) {
+    const self = process.env.SWITCHROOM_AGENT_NAME
+    if (self && msg.agentName !== self) {
+      process.stderr.write(
+        `telegram gateway: rollout_status_post rejected — agent mismatch (${msg.agentName} != ${self})\n`,
+      )
+      try {
+        client.send({ type: 'rollout_status_posted', requestId: msg.requestId, ok: false, reason: 'agent mismatch' })
+      } catch { /* best effort */ }
+      return
+    }
+    const operator = loadAccess().allowFrom[0]
+    if (operator === undefined) {
+      process.stderr.write(`telegram gateway: rollout_status_post — no operator chat (allowFrom empty)\n`)
+      try {
+        client.send({ type: 'rollout_status_posted', requestId: msg.requestId, ok: false, reason: 'no operator chat' })
+      } catch { /* best effort */ }
+      return
+    }
+    try {
+      const sent = await robustApiCall(
+        () =>
+          // allow-raw-bot-api: rich progress line, routed through robustApiCall.
+          bot.api.sendRichMessage(operator, richMessage(msg.text), {}),
+        { chat_id: String(operator), verb: 'rollout-status-post' },
+      )
+      const messageId = (sent as { message_id: number }).message_id
+      process.stderr.write(
+        `telegram gateway: rollout_status_post agent=${msg.agentName} request=${msg.requestId} message_id=${messageId}\n`,
+      )
+      try {
+        client.send({ type: 'rollout_status_posted', requestId: msg.requestId, ok: true, messageId })
+      } catch { /* best effort */ }
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: rollout_status_post send failed: ${(err as Error).message}\n`,
+      )
+      try {
+        client.send({ type: 'rollout_status_posted', requestId: msg.requestId, ok: false, reason: (err as Error).message })
+      } catch { /* best effort */ }
+    }
+  },
+
+  // #2726 Part 2 — edit the previously-posted rollout status message in place as
+  // later phases arrive. Fire-and-forget: an edit failure (incl. Telegram 429)
+  // is swallowed here and NEVER surfaced back toward the roll. hostd owns the
+  // debounce + 429 retry cadence; this handler is a thin edit relay.
+  onRolloutStatusEdit(_client: IpcClient, msg: RolloutStatusEditMessage) {
+    const self = process.env.SWITCHROOM_AGENT_NAME
+    if (self && msg.agentName !== self) {
+      process.stderr.write(
+        `telegram gateway: rollout_status_edit rejected — agent mismatch (${msg.agentName} != ${self})\n`,
+      )
+      return
+    }
+    const operator = loadAccess().allowFrom[0]
+    if (operator === undefined) {
+      process.stderr.write(`telegram gateway: rollout_status_edit — no operator chat (allowFrom empty)\n`)
+      return
+    }
+    void swallowingApiCall(
+      () =>
+        // allow-raw-bot-api: in-place edit of the ordinary status message.
+        bot.api.editMessageText(operator, msg.messageId, richMessage(msg.text), {}),
+      { chat_id: String(operator), verb: 'rollout-status-edit' },
+    )
+  },
+
   onInjectInbound(_client: IpcClient, msg: InjectInboundMessage) {
     // Cron fires (incl. cheap-cron, whose session events are dropped before
     // currentTurn is set) are real activity — re-arm idle auto-clear so a
@@ -8129,6 +8599,197 @@ function redactOutboundText(text: string, site: string): string {
   return masked
 }
 
+/** Default per-voice-note chunk size (chars). A long reply is split into
+ *  sequential voice notes of roughly this size on sentence/paragraph
+ *  boundaries. Only the OpenAI (cloud) engine still uses this — the kokoro
+ *  sidecar now takes the whole reply in one call and returns a single note. */
+const VOICE_OUT_DEFAULT_CHUNK_CHARS = 600
+
+/** Hard ceiling for a single OpenAI TTS request. OpenAI's TTS input caps at
+ *  4096 chars, so client-side chunks for that engine never exceed this; the
+ *  reply is spoken across sequential notes when it's longer. (The kokoro path
+ *  no longer chunks — the sidecar owns length and returns one file.) */
+const VOICE_OUT_HARD_CHUNK_CAP = 4096
+
+/**
+ * On-demand voice-out (reply_mode='on-demand'). Instead of synthesizing at
+ * reply time, the gateway appends a single "🔊 Listen" inline button carrying
+ * a reserved `voice:<token>` callback_data; audio is synthesized + sent only
+ * when the user taps it. This keeps the voice pipeline subscription-honest and
+ * visible — zero GPU/sidecar work happens behind the user's back.
+ *
+ * We cache the (speech-normalized text, voice, speed) needed to synthesize by
+ * TOKEN, not message_id, because the message_id is not known at send time.
+ * Bounded LRU with a TTL so a stale button (tapped an hour later) degrades to
+ * a graceful "expired" toast rather than pinning reply text in memory forever.
+ */
+const voiceOnDemandCache = new VoiceOnDemandCache()
+
+type VoiceOutAccess = NonNullable<Access['voice_out']>
+
+/**
+ * Resolve whether outbound TTS is active for this reply, and how
+ * (engine + reply_mode + the plain-text TTS chunks). PR-C2.
+ *
+ * Mirrors the voice-IN engine-resolution precedence (message:voice
+ * handler): the compose-injected SWITCHROOM_VOICE_ENGINE verdict gates the
+ * local 'kokoro' engine, exactly like the STT sidecar. The 'openai' engine
+ * is an honest-exception cloud path gated on an api_key vault ref — it does
+ * NOT require a local verdict.
+ *
+ * Returns null when voice-out is off / not applicable; otherwise a plan the
+ * caller acts on. `ttsChunks` is speech-normalized plain text (markdown and
+ * TTS-mispronounced symbols removed — see normalizeForSpeech).
+ *
+ * ONE voice note per response: the kokoro (local sidecar) path now sends the
+ * WHOLE normalized reply to `/tts` in a SINGLE call — the sidecar chunks +
+ * concatenates internally on the GPU and returns a single ogg/opus file — so
+ * `ttsChunks` is a single element for kokoro. `max_chars` is no longer a hard
+ * client-side splitter for kokoro; it's retired for that path (the sidecar
+ * owns length). The openai (cloud) engine keeps client-side chunking because
+ * OpenAI's TTS input has its own hard cap; each chunk is one voice note.
+ */
+function resolveVoiceOutPlan(
+  voiceOut: VoiceOutAccess | undefined,
+  replyText: string,
+): {
+  engine: 'kokoro' | 'openai'
+  voice?: string
+  speed: number
+  apiKeyRef?: string
+  replyMode: 'voice+text' | 'voice-only' | 'on-demand'
+  ttsChunks: string[]
+} | null {
+  if (voiceOut?.enabled !== true) return null
+
+  const engine = voiceOut.engine ?? 'kokoro'
+
+  // Engine gating mirrors the voice-in handler precedence: the
+  // compose-injected env wins, then the persisted host-capabilities file,
+  // then a fail-safe 'cloud'. The in-container ~/.switchroom is a read-only
+  // view that does NOT carry host-capabilities.json, so the env is
+  // load-bearing in-fleet (see message:voice). Kokoro requires 'local';
+  // openai requires a resolvable api_key.
+  if (engine === 'kokoro') {
+    const envVoiceEngine = process.env.SWITCHROOM_VOICE_ENGINE
+    const voiceEngine: VoiceEngine =
+      envVoiceEngine === 'local' || envVoiceEngine === 'cloud'
+        ? envVoiceEngine
+        : loadHostCapabilities()?.voice.engine ?? 'cloud'
+    if (voiceEngine !== 'local') return null
+  }
+
+  // Speech-normalized TTS input: strip markdown AND translate/drop the
+  // symbols TTS mispronounces (~, backticks, arrows, tables, code fences,
+  // link URLs) REGARDLESS of mode so the engine reads clean prose. Applied
+  // for BOTH engines — the older partial stripMarkdown pass leaked `~`,
+  // code fences and arrows.
+  const ttsText = normalizeForSpeech(replyText)
+  if (ttsText.length === 0) return null
+
+  // ONE voice note for kokoro: the sidecar accepts arbitrarily long text and
+  // returns a single concatenated ogg/opus file, so we send the whole reply
+  // in one call — no client-side splitting, no multi-sendVoice. `max_chars`
+  // is retired as a hard splitter here.
+  //
+  // OpenAI still needs client-side chunking (its TTS input has a hard cap),
+  // so for that engine we split at the engine cap; each chunk is one note.
+  let ttsChunks: string[]
+  if (engine === 'kokoro') {
+    ttsChunks = [ttsText]
+  } else {
+    const chunkChars = Math.min(
+      voiceOut.max_chars ?? VOICE_OUT_DEFAULT_CHUNK_CHARS,
+      VOICE_OUT_HARD_CHUNK_CAP,
+    )
+    ttsChunks = chunkTtsText(ttsText, chunkChars)
+  }
+  if (ttsChunks.length === 0) return null
+
+  // Kokoro playback speed: default 1.1 (fleet default) when unset, clamped to
+  // 0.5–2.0. Threaded into the /tts body by synthesizeVoiceOut. The OpenAI
+  // path ignores it.
+  const speed = clampTtsSpeed(voiceOut.speed, VOICE_OUT_DEFAULT_SPEED)
+
+  return {
+    engine,
+    voice: voiceOut.voice,
+    speed,
+    apiKeyRef: voiceOut.api_key,
+    replyMode: voiceOut.reply_mode ?? 'voice+text',
+    ttsChunks,
+  }
+}
+
+/**
+ * Synthesize `ttsText` into OGG/Opus bytes via the configured engine.
+ * Best-effort: returns null on ANY failure (logged to stderr), never
+ * throws. The caller treats null as "voice unavailable, fall back to
+ * text". PR-C2.
+ */
+async function synthesizeVoiceOut(plan: {
+  engine: 'kokoro' | 'openai'
+  voice?: string
+  speed?: number
+  apiKeyRef?: string
+  ttsText: string
+}): Promise<Uint8Array | null> {
+  try {
+    if (plan.engine === 'kokoro') {
+      const token = await materializeSidecarToken()
+      if (!token) return null // materializeSidecarToken already logged why.
+      const result = await synthesizeViaSidecar({
+        token,
+        text: plan.ttsText,
+        voice: plan.voice,
+        speed: plan.speed,
+      })
+      if (!result.ok) {
+        process.stderr.write(
+          `telegram gateway: voice-out: local sidecar synthesis failed reason=${result.reason}` +
+            (result.detail ? ` detail=${JSON.stringify(result.detail).slice(0, 100)}` : '') +
+            '\n',
+        )
+        return null
+      }
+      process.stderr.write(
+        `telegram gateway: voice-out: local sidecar synthesized ${result.audio.length} bytes in ${result.durationMs}ms ` +
+          `voice=${result.voice ?? '?'} audio_s=${result.audioSeconds ?? '?'} chars=${plan.ttsText.length}\n`,
+      )
+      return result.audio
+    }
+
+    // engine === 'openai' — honest-exception cloud path.
+    const apiKey = await materializeVoiceKey({ apiKeyRef: plan.apiKeyRef })
+    if (!apiKey) return null // materializeVoiceKey already logged why.
+    const result = await synthesizeViaOpenAi({
+      apiKey,
+      text: plan.ttsText,
+      voice: plan.voice,
+    })
+    if (!result.ok) {
+      process.stderr.write(
+        `telegram gateway: voice-out: openai synthesis failed reason=${result.reason}` +
+          (result.detail ? ` detail=${JSON.stringify(result.detail).slice(0, 100)}` : '') +
+          '\n',
+      )
+      return null
+    }
+    process.stderr.write(
+      `telegram gateway: voice-out: openai synthesized ${result.audio.length} bytes in ${result.durationMs}ms ` +
+        `voice=${result.voice} chars=${plan.ttsText.length}\n`,
+    )
+    return result.audio
+  } catch (err) {
+    // Defence in depth: the synth helpers never throw, but the vault
+    // materialize calls might. Voice is best-effort — swallow + fall back.
+    process.stderr.write(
+      `telegram gateway: voice-out: synthesis threw (non-fatal): ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return null
+  }
+}
+
 async function executeReply(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
   // #1664 — pin the turn this reply belongs to at entry. The
   // finalAnswerDelivered write near the end of this function runs after
@@ -8149,18 +8810,20 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   //   null because clearTurnStarted fired ≥5 min of model silence, but the model
   //   finally called reply after the poke).
   const chat_id = (() => {
-    const _a = loadAccess()
-    if (_a.allowFrom.includes(_rawChatId) || _rawChatId in _a.groups) return _rawChatId
-    const fallbackChatId = turn?.sessionChatId ?? lastActiveTurnChatId
-    if (fallbackChatId && (_a.allowFrom.includes(fallbackChatId) || fallbackChatId in _a.groups)) {
-      const tier = turn == null ? 'last-known' : 'active'
+    const resolved = resolveChatIdFallback(
+      _rawChatId,
+      loadAccess(),
+      turn?.sessionChatId,
+      lastActiveTurnChatId,
+      turn != null,
+    )
+    if (resolved.tier !== 'raw') {
       process.stderr.write(
         `telegram gateway: reply: model passed chat_id "${_rawChatId}" (not allowlisted) — ` +
-          `routing to ${tier} turn chat "${fallbackChatId}"\n`,
+          `routing to ${resolved.tier} turn chat "${resolved.chatId}"\n`,
       )
-      return fallbackChatId
     }
-    return _rawChatId // let assertAllowedChat below throw the human-readable error
+    return resolved.chatId // raw tier → let assertAllowedChat throw the human-readable error
   })()
   const rawText = args.text as string | undefined
   if (rawText == null || rawText === '') throw new Error('reply: text is required and cannot be empty')
@@ -8233,6 +8896,11 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   const protectContent = args.protect_content === true
   const quoteText = args.quote_text as string | undefined
   const access = loadAccess()
+  // Outbound TTS plan (PR-C2). Resolved once here (engine gating + mode +
+  // plain-text TTS input); synthesis happens just before the send so a
+  // voice-only reply can suppress the text chunk loop on success. Voice is
+  // fully best-effort — every failure below falls back to the text reply.
+  const voiceOutPlan = resolveVoiceOutPlan(access.voice_out, text)
   const configParseMode = access.parseMode ?? 'html'
   const format = (args.format as string | undefined) ?? configParseMode
   const disableLinkPreview = args.disable_web_page_preview != null
@@ -8400,7 +9068,12 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   // ships the raw GFM markdown via `sendRichMessage`. `effectiveText` is the
   // raw text either way (no HTML/MarkdownV2 rendering happens here anymore).
   const literalText = format === 'text'
-  const effectiveText: string = text
+  // Paragraph-spacing fix (rich-message regression after #2669). The rich GFM
+  // renderer collapses a `\n\n` gap TIGHT, so multi-paragraph replies render
+  // jammed together — unlike the old HTML path. Inject a visible blank-line
+  // spacer into prose `\n\n` gaps on the rich path only. The literal
+  // (`format:'text'`) path must stay byte-exact, so it is left untouched.
+  const effectiveText: string = literalText ? text : addParagraphSpacers(text)
 
   assertAllowedChat(chat_id)
 
@@ -8469,6 +9142,60 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     : splitMarkdownChunks(effectiveText, limit)
   const sentIds: number[] = []
 
+  // Outbound TTS synthesis (PR-C2). Done BEFORE the text send so a
+  // voice-only reply can suppress the text chunks on success. ONE voice note
+  // per response for the kokoro path (ttsChunks is a single element — the
+  // whole normalized reply — synthesized in one /tts call). The OpenAI path
+  // may still produce several ordered notes (one per chunk) because of its
+  // input cap. Ken is often on a bike/driving and can't read the screen, so
+  // the full answer must be SPOKEN. Best-effort: a chunk that fails to
+  // synthesize is skipped; if NOTHING synthesizes the text path proceeds
+  // unchanged so the answer is never dropped.
+  // on-demand is a LOCAL-engine (kokoro) feature only: the tap handler
+  // synthesizes via the local sidecar, so a Listen button is only meaningful
+  // when the resolved engine is kokoro. resolveVoiceOutPlan already gated the
+  // local host verdict for kokoro, so engine==='kokoro' here implies the
+  // sidecar is available. For engine==='openai' + reply_mode='on-demand' we do
+  // NOT inject a button (its taps would dead-end on the local sidecar) — we
+  // fall through to the normal immediate-synth path so the openai reply behaves
+  // exactly like a normal openai voice reply.
+  const useOnDemandButton =
+    voiceOutPlan != null &&
+    voiceOutPlan.replyMode === 'on-demand' &&
+    voiceOutPlan.engine === 'kokoro'
+
+  const voiceOggs: Uint8Array[] = []
+  // Skip reply-time synthesis ONLY when we're actually deferring to a Listen
+  // button (kokoro on-demand). An openai on-demand config still synthesizes
+  // immediately below.
+  if (voiceOutPlan != null && !useOnDemandButton) {
+    for (const chunkText of voiceOutPlan.ttsChunks) {
+      const ogg = await synthesizeVoiceOut({
+        engine: voiceOutPlan.engine,
+        voice: voiceOutPlan.voice,
+        speed: voiceOutPlan.speed,
+        apiKeyRef: voiceOutPlan.apiKeyRef,
+        ttsText: chunkText,
+      })
+      // Skip a failed chunk but keep going — a partial spoken answer still
+      // beats silence; full-fail (no oggs at all) falls back to text below.
+      if (ogg != null) voiceOggs.push(ogg)
+    }
+    if (voiceOggs.length < voiceOutPlan.ttsChunks.length) {
+      process.stderr.write(
+        `telegram gateway: voice-out: synthesized ${voiceOggs.length}/${voiceOutPlan.ttsChunks.length} voice-note chunk(s)\n`,
+      )
+    }
+  }
+  // Suppress the text body ONLY when voice-only AND we synthesized the FULL
+  // set of chunks (every part of the answer is spoken). A partial or total
+  // synthesis failure leaves the text path running so the answer still
+  // lands in full — never drop the user's answer silently.
+  const suppressText =
+    voiceOutPlan?.replyMode === 'voice-only' &&
+    voiceOutPlan.ttsChunks.length > 0 &&
+    voiceOggs.length === voiceOutPlan.ttsChunks.length
+
   // #271: validate inline_keyboard and namespace any callback_data with
   // the `agent:` prefix so the gateway's callback_query dispatcher can
   // round-trip taps back to this agent without colliding with
@@ -8490,6 +9217,50 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     replyMarkup = { inline_keyboard: wrapAgentCallbacks(rawKeyboard) }
   }
 
+  // on-demand voice: append a single '🔊 Listen' button that synthesizes the
+  // spoken reply only when tapped. The button carries a RAW `voice:<token>`
+  // callback_data (NOT wrapped with the agent: prefix) so the dispatcher
+  // handles it internally and never routes it to the agent as an inbound.
+  //
+  // Collision gate: inject ONLY when the reply carries no agent-authored
+  // buttons. If the agent supplied its own keyboard, the callback dispatcher's
+  // single_use strip (keyboardIsSingleUse) governs that whole message; adding
+  // a foreign single_use:false button would flip that message to a mixed
+  // keyboard and defeat the agent's double-fire protection. Keep it simple —
+  // agent buttons present → skip the Listen button for this message.
+  //
+  // useOnDemandButton already gates on engine==='kokoro': an openai on-demand
+  // config never reaches here (it synthesized immediately above), so a Listen
+  // button is never minted for an engine whose taps would dead-end on the
+  // local sidecar.
+  if (
+    useOnDemandButton &&
+    voiceOutPlan!.ttsChunks.length > 0 &&
+    voiceOutPlan!.ttsChunks[0]!.length > 0
+  ) {
+    if (!mayInjectListenButton(rawKeyboard)) {
+      process.stderr.write(
+        'telegram gateway: voice-out on-demand: agent supplied inline_keyboard — skipping Listen button (single_use collision gate)\n',
+      )
+    } else {
+      // Token is intentionally GLOBAL (not chat-keyed): under the single-tenant
+      // invariant the operator is the only authorized sender across all chats,
+      // and the tap handler re-checks access.allowFrom before synthesizing, so
+      // a token needs no per-chat scoping to be safe.
+      const token = mintVoiceOnDemandToken()
+      voiceOnDemandCache.put(token, {
+        // ttsChunks[0] is already normalizeForSpeech(reply) (kokoro path).
+        text: voiceOutPlan.ttsChunks[0]!,
+        ...(voiceOutPlan.voice != null ? { voice: voiceOutPlan.voice } : {}),
+        speed: voiceOutPlan.speed,
+      })
+      // The keyboard stays after the tap (never stripped) so it can be
+      // replayed. The gate above guarantees this is the ONLY button on the
+      // message, so keeping it is safe (no agent buttons to protect).
+      replyMarkup = buildListenKeyboard(token)
+    }
+  }
+
   const replySKey = streamKey(chat_id, threadId)
   suppressPtyPreview.add(replySKey)
   let previewMessageId: number | null = null
@@ -8739,6 +9510,12 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
 
   try {
     for (let i = 0; i < chunks.length; i++) {
+      // PR-C2: voice-only mode with a successful synthesis suppresses the
+      // text body — the spoken voice note IS the reply. Bail before the
+      // first chunk send (sentIds stays empty for text); the voice send
+      // below lands the answer. Any other mode (voice+text, or voice-only
+      // that fell back) sends the text chunks as normal.
+      if (suppressText) break
       const shouldReplyTo =
         reply_to != null && replyMode !== 'off' && (replyMode === 'all' || i === 0)
       const isLastChunk = i === chunks.length - 1
@@ -8894,6 +9671,76 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     stopTypingLoop(chat_id, threadId ?? null)
   }
 
+  // Outbound voice notes (PR-C2). Sent IN ORDER, AFTER the text body
+  // (voice+text) or INSTEAD of it (voice-only, where suppressText skipped
+  // the chunk loop). A long reply produces SEVERAL notes — each spoken in
+  // sequence so the whole answer is heard, never truncated. Best-effort and
+  // fully non-fatal: a sendVoice failure must NEVER break the text reply
+  // path. In voice-only mode a failure would leave the user with an
+  // incomplete spoken answer, so on the FIRST send failure we recover by
+  // sending the full text once and stop sending further notes.
+  for (let v = 0; v < voiceOggs.length; v++) {
+    const oggBytes = voiceOggs[v]!
+    const voiceOpts: Record<string, unknown> = {
+      // Quote the user's message only on the FIRST voice note (mirrors the
+      // text chunk loop's first-chunk reply behaviour).
+      ...(v === 0 && reply_to != null && replyMode !== 'off'
+        ? { reply_parameters: { message_id: reply_to } }
+        : {}),
+      ...(threadId != null ? { message_thread_id: threadId } : {}),
+      ...(disableNotification ? { disable_notification: true } : {}),
+    }
+    try {
+      const sentVoice = await retryWithThreadFallback<{ message_id: number; message_thread_id?: number }>(
+        robustApiCall,
+        (tid) => {
+          const opts = { ...voiceOpts }
+          if (tid != null) opts.message_thread_id = tid
+          else delete opts.message_thread_id
+          // allow-raw-bot-api: adapter callback INSIDE retryWithThreadFallback→robustApiCall; the THREAD_NOT_FOUND fallback is handled by the wrapper.
+          return lockedBot.api.sendVoice(chat_id, new InputFile(Buffer.from(oggBytes)), opts as never)
+        },
+        { threadId, chat_id, verb: 'sendVoice' },
+      )
+      sentIds.push(sentVoice.message_id)
+      logOutbound(
+        'reply',
+        chat_id,
+        sentVoice.message_id,
+        voiceOutPlan?.ttsChunks[v]?.length ?? 0,
+        `voice-note=${v + 1}/${voiceOggs.length}`,
+      )
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      process.stderr.write(
+        `telegram gateway: voice-out: sendVoice ${v + 1}/${voiceOggs.length} failed (non-fatal): ${msg}\n`,
+      )
+      // voice-only fell over mid-stream with text suppressed → recover by
+      // sending the FULL text body once so the answer still lands, then
+      // stop sending further notes (the text now carries everything).
+      if (suppressText) {
+        try {
+          const opts: Record<string, unknown> = {
+            ...(reply_to != null && replyMode !== 'off'
+              ? { reply_parameters: { message_id: reply_to } }
+              : {}),
+            ...(threadId != null ? { message_thread_id: threadId } : {}),
+            ...(disableNotification ? { disable_notification: true } : {}),
+          }
+          // allow-raw-bot-api: voice-only recovery fallback — the rich path already ran/was skipped; send the source text plainly so the answer is never lost.
+          const sent = await lockedBot.api.sendMessage(chat_id, effectiveText, opts as never)
+          sentIds.push(sent.message_id)
+          logOutbound('reply', chat_id, sent.message_id, effectiveText.length, 'voice-only-text-recovery')
+        } catch (textErr) {
+          process.stderr.write(
+            `telegram gateway: voice-out: voice-only text recovery ALSO failed: ${textErr instanceof Error ? textErr.message : String(textErr)}\n`,
+          )
+        }
+        break
+      }
+    }
+  }
+
   // #710: remember per-button agent meta (ack_text / single_use) keyed
   // by the message that actually carries the keyboard — that's the last
   // text chunk, since the keyboard is attached only on isLastChunk.
@@ -9154,6 +10001,31 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
   const turn = currentTurn
   if (!args.chat_id) throw new Error('stream_reply: chat_id is required')
   if (args.text == null || args.text === '') throw new Error('stream_reply: text is required and cannot be empty')
+  // chat_id allowlist fallback — mirrors executeReply (~8725). stream_reply is
+  // the primary final-answer path, so a wrong/late chat_id (int/string mismatch,
+  // or the model echoing the wrong identifier after a silence poke flipped
+  // currentTurn to null) would otherwise fail assertAllowedChat in the stream
+  // controller → an invisible reply. Rewrite args.chat_id in place so every
+  // downstream consumer (origin resolution, dedup key, the send) sees the
+  // corrected value. Tier 1: live turn's sessionChatId. Tier 2: last-known
+  // turn's chat (survives silence poke — Bug D fix; currentTurn is null).
+  {
+    const _rawChatId = String(args.chat_id ?? '')
+    const resolved = resolveChatIdFallback(
+      _rawChatId,
+      loadAccess(),
+      turn?.sessionChatId,
+      lastActiveTurnChatId,
+      turn != null,
+    )
+    if (resolved.tier !== 'raw') {
+      process.stderr.write(
+        `telegram gateway: stream_reply: model passed chat_id "${_rawChatId}" (not allowlisted) — ` +
+          `routing to ${resolved.tier} turn chat "${resolved.chatId}"\n`,
+      )
+      args.chat_id = resolved.chatId
+    }
+  }
   // Thread precedence (matches executeReply; component 3 — turn-origin
   // routing): when the model passes no explicit message_thread_id, inject
   // the ORIGIN turn's thread (matched by origin_turn_id) — authoritative
@@ -9379,6 +10251,7 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
       retry: robustApiCall,
       repairEscapedWhitespace,
       normalizeParagraphBreaks,
+      addParagraphSpacers,
       assertAllowedChat,
       resolveThreadId,
       disableLinkPreview: access.disableLinkPreview !== false,
@@ -10428,31 +11301,6 @@ function buildVaultRequestAccessKeyboard(stageId: string): { inline_keyboard: Ar
   }
 }
 
-function renderVaultRequestAccessCard(req: PendingVaultRequestAccess): string {
-  const lines: string[] = []
-  const scopeLabel = req.scope === 'write' ? 'write' : 'read'
-  const days = Math.round(req.ttl_seconds / 86400)
-  const durationLabel = days >= 1 ? `${days}d` : `${Math.round(req.ttl_seconds / 3600)}h`
-  lines.push(`🔐 **${escapeHtmlForTg(req.agent)}** wants vault access`)
-  lines.push(`key: \`${req.key}\``)
-  lines.push(`scope: \`${scopeLabel}\` · duration: \`${durationLabel}\``)
-  // #1790 — always render the why-line, even when the agent omitted
-  // `reason`. Rendering "not provided" makes a missing rationale
-  // visibly an agent-side failure (the tool description nudges the
-  // model to supply one — see executeVaultRequestAccess); skipping
-  // the line silently used to make the omission look like a card-
-  // template choice, which the operator couldn't tell apart from a
-  // legitimate "no reason needed" case.
-  if (req.reason && req.reason.length > 0) {
-    lines.push(`why: _${escapeHtmlForTg(req.reason)}_`)
-  } else {
-    lines.push(`why: _not provided_`)
-  }
-  lines.push('')
-  lines.push(`_Tap Approve to mint a scoped grant token (same flow as \`switchroom vault grant\`). Tap Deny to refuse — the agent will receive a denial result._`)
-  return lines.join('\n')
-}
-
 /**
  * `vault_request_access` tool — agent surfaces an approval card asking
  * the operator to grant a vault ACL it doesn't yet have. See #1012.
@@ -10632,7 +11480,7 @@ async function executeEditMessage(args: Record<string, unknown>): Promise<unknow
   // paragraph breaks for the rich path. A literal-text edit (`format:'text'`)
   // skips paragraph normalization — it must edit byte-for-byte as given.
   let editRawText = repairEscapedWhitespace(args.text as string)
-  if (!editLiteralText) editRawText = normalizeParagraphBreaks(editRawText)
+  if (!editLiteralText) editRawText = addParagraphSpacers(normalizeParagraphBreaks(editRawText))
   // Outbound secret scrub (#2044): an edit must not re-introduce a raw
   // secret into a live bubble or the history row. Mask before scrub/send.
   editRawText = redactOutboundText(editRawText, 'edit_message')
@@ -11133,6 +11981,16 @@ async function drainActivitySummary(
           )
           turn.activityMessageId = sent.message_id
           turn.activityEverOpened = true
+          // Status-pin: the per-turn status message just opened — it's the
+          // in-flight "what it's doing" surface. Silently pin it so the turn
+          // stays in view when the feed scrolls past. Keyed to the same
+          // status-key the canonical turn-end (purgeReactionTracking) unpins.
+          // Fire-and-forget; the single-owner reconcile keeps state consistent.
+          void reconcileStatusPin(
+            `fg:${statusKey(chat, thread)}`,
+            chat,
+            { pinned: true, messageId: sent.message_id },
+          )
         } else {
           const id = turn.activityMessageId
           await robustApiCall(
@@ -15448,6 +16306,15 @@ async function sweepBeforeSelfRestart(): Promise<void> {
   const agentDir = resolveAgentDirFromEnv()
   if (agentDir == null) return
   // #1122 PR3: pre-restart progress-card pin sweep removed with the card.
+  // Status-pin: unpin every status pin we own before we hand control to the
+  // restart, so a crash / interrupt / config-bounce never leaves a permanent
+  // pin stuck at the top of the chat. Best-effort; the drop-on-unpin contract
+  // clears the claim even if the API throws.
+  try {
+    await unpinAllStatusPins()
+  } catch (err) {
+    process.stderr.write(`telegram gateway: pre-restart status-pin sweep threw: ${(err as Error).message}\n`)
+  }
   try {
     await sweepActiveReactions(
       agentDir,
@@ -17159,6 +18026,7 @@ async function handlePermissionSlash(ctx: Context, behavior: 'allow' | 'deny'):
     action: naturalAction(details.tool_name, details.input_preview),
   })
   pendingPermissions.delete(request_id)
+  permCardStore.remove(request_id)
   process.stderr.write(
     `[telegram gateway] slash-${behavior} request_id=${request_id} tool=${details.tool_name} by=${senderId}\n`,
   )
@@ -18861,9 +19729,16 @@ async function performVaultAccessApproval(
       .editMessageText(
         pending.chat_id,
         pending.card_message_id,
-        `✅ Granted **${escapeHtmlForTg(pending.agent)}** ${pending.scope} access to ` +
-        `\`${pending.key}\` for ${days}d. ` +
-        richMessage(`(grant \`${id}\`)` + footer),
+        richMessage(
+          buildVaultGrantApprovedCardText({
+            agentEscaped: escapeHtmlForTg(pending.agent),
+            scope: pending.scope,
+            key: pending.key,
+            days,
+            grantId: id,
+            footer,
+          }),
+        ),
         { reply_markup: { inline_keyboard: [] } },
       )
       .catch(() => {})
@@ -20855,7 +21730,7 @@ bot.command('usage', async ctx => {
           }
           return hit?.result ?? { ok: false as const, reason: 'broker returned no result for account' }
         })
-        const { renderAuthSnapshotFormat2, buildSnapshotsFromState } = await import(
+        const { renderAuthSnapshotFormat2, buildSnapshotsFromState, buildSnapshotKeyboard } = await import(
           '../auth-snapshot-format.js'
         )
         const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? 'UTC'
@@ -20866,7 +21741,22 @@ bot.command('usage', async ctx => {
           demo,
           ...(staleCachedAtMs != null ? { staleCachedAtMs } : { liveProbedAtMs: Date.now() }),
         })
-        await switchroomReply(ctx, text, { html: true })
+        // Preserve the Switch/Refresh/usage/Add inline keyboard on the
+        // rich-message render — the table card carries the same actions the
+        // /auth snapshot does. switchroomReply routes through the rich path
+        // (replyWithRichMessage), which accepts reply_markup. Build a grammy
+        // InlineKeyboard so the markup type matches switchroomReply's contract.
+        const kbRows = buildSnapshotKeyboard(snapshots, { now: new Date() })
+        const keyboard = new InlineKeyboard()
+        kbRows.forEach((row, ri) => {
+          if (ri > 0) keyboard.row()
+          for (const b of row) {
+            if (b.callbackData) keyboard.text(b.text, b.callbackData)
+            else if (b.insertText) keyboard.switchInlineCurrent(b.text, b.insertText)
+            else keyboard.text(b.text, 'auth:noop')
+          }
+        })
+        await switchroomReply(ctx, text, { html: true, reply_markup: keyboard })
         return
       }
     }
@@ -21544,6 +22434,110 @@ bot.on('callback_query:data', async ctx => {
     return
   }
 
+  // on-demand voice: '🔊 Listen' buttons carry a reserved `voice:<token>`
+  // callback_data. Handle INTERNALLY here — synthesize the cached reply text
+  // and send it as a native voice note. This MUST run before the agent:
+  // routing below so a tap never reaches the agent as an inbound message.
+  if (isVoiceOnDemandCallback(data)) {
+    const access = loadAccess()
+    const senderId = String(ctx.from.id)
+    if (!access.allowFrom.includes(senderId)) {
+      await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
+      return
+    }
+    const token = parseVoiceOnDemandToken(data)
+    const entry = token != null ? voiceOnDemandCache.get(token) : null
+    if (entry == null) {
+      await ctx
+        .answerCallbackQuery({ text: 'Voice expired — send again to hear it.' })
+        .catch(() => {})
+      return
+    }
+    await ctx.answerCallbackQuery({ text: '🔊 Synthesizing…' }).catch(() => {})
+    const cbChatId = String(ctx.chat?.id ?? ctx.from.id)
+    const cbMessageId = ctx.callbackQuery?.message?.message_id
+    const cbThreadId = (() => {
+      const msg = ctx.callbackQuery?.message
+      if (msg && 'is_topic_message' in msg && msg.is_topic_message && 'message_thread_id' in msg) {
+        const tid = (msg as { message_thread_id?: number }).message_thread_id
+        return typeof tid === 'number' ? tid : undefined
+      }
+      return undefined
+    })()
+    // Local sidecar (kokoro) synthesis — same helper the immediate voice-out
+    // path uses. On-demand is a local-engine feature; the cache is only
+    // populated when resolveVoiceOutPlan gated the local verdict.
+    const sidecarToken = await materializeSidecarToken()
+    if (!sidecarToken) {
+      await ctx
+        .answerCallbackQuery({ text: 'Voice sidecar unavailable — try again later.' })
+        .catch(() => {})
+      return
+    }
+    const result = await synthesizeViaSidecar({
+      token: sidecarToken,
+      text: entry.text,
+      voice: entry.voice,
+      speed: entry.speed,
+    })
+    if (!result.ok) {
+      process.stderr.write(
+        `telegram gateway: voice-out on-demand: synthesis failed reason=${result.reason}\n`,
+      )
+      await ctx
+        .answerCallbackQuery({ text: `Voice failed: ${result.reason}` })
+        .catch(() => {})
+      return
+    }
+    try {
+      // Native voice note (NOT a document), quote-replying the button's
+      // message.
+      await robustApiCall(
+        () =>
+          bot.api.sendVoice(
+            cbChatId,
+            // allow-raw-bot-api: single native voice-note send for an on-demand Listen tap.
+            new InputFile(Buffer.from(result.audio)),
+            {
+              ...(cbMessageId != null ? { reply_parameters: { message_id: cbMessageId } } : {}),
+              ...(cbThreadId != null ? { message_thread_id: cbThreadId } : {}),
+            } as never,
+          ),
+        {
+          chat_id: cbChatId,
+          verb: 'voice-ondemand.sendVoice',
+          ...(cbThreadId != null ? { threadId: cbThreadId } : {}),
+        },
+      )
+      // Single-use on SUCCESS: strip the '🔊 Listen' keyboard so the button
+      // can't be re-tapped now that the audio has been delivered. Mirrors the
+      // agent-button single_use strip (keyboardIsSingleUse) house style.
+      // Best-effort + non-fatal — a failed strip only leaves a replayable
+      // button, never drops the delivered audio. Only reached on a successful
+      // sendVoice; expiry / synth-failure / sidecar-unavailable all return
+      // earlier WITHOUT stripping, so the user can retry those.
+      if (cbMessageId != null) {
+        await robustApiCall(
+          () =>
+            bot.api.editMessageReplyMarkup(cbChatId, cbMessageId, {
+              reply_markup: { inline_keyboard: [] },
+            }),
+          {
+            chat_id: cbChatId,
+            verb: 'voice-ondemand.strip-listen-keyboard',
+            ...(cbThreadId != null ? { threadId: cbThreadId } : {}),
+          },
+        ).catch(() => {})
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      process.stderr.write(
+        `telegram gateway: voice-out on-demand: sendVoice failed (non-fatal): ${msg}\n`,
+      )
+    }
+    return
+  }
+
   // #271: agent-emitted inline_keyboard callbacks. Namespaced with
   // an `agent:` prefix in inline-keyboard-callbacks.ts so they can
   // round-trip without colliding with infrastructure prefixes above.
@@ -21741,6 +22735,7 @@ bot.on('callback_query:data', async ctx => {
     }
 
     pendingPermissions.delete(request_id)
+    permCardStore.remove(request_id)
 
     // (2) Dispatch the in-flight permission verdict IMMEDIATELY — before
     // any host round-trip — so the turn never blocks on persistence.
@@ -21964,6 +22959,7 @@ bot.on('callback_query:data', async ctx => {
     : null
   const grantAgent = selfAgentName()
   pendingPermissions.delete(request_id)
+  permCardStore.remove(request_id)
   if (timeBox && grantAgent) {
     recordScopedGrant(scopedGrants, grantAgent, timeBox.rule, Date.now(), scopedTtl)
     process.stderr.write(
@@ -22001,6 +22997,25 @@ bot.on('callback_query:data', async ctx => {
   const baseText = msg && 'text' in msg && msg.text
     ? escapeHtmlForTg(msg.text)
     : ''
+  // NO SPLIT (#card-ux): the agent-voiced "got it, continuing: <action>"
+  // continuation folds into THIS card edit — below the verdict label — instead
+  // of spawning a separate message. formatPermissionResumeMessage returns the
+  // same GFM markdown the standalone message used, so the wording is
+  // unchanged; it just rides in the card the operator already tapped. The
+  // separate message went to EVERY resolvePermissionCardTargets() surface; the
+  // in-place edit deliberately touches only the tapped card (a single, legible
+  // card, no fan-out). The turn-resume trigger (dispatchPermissionVerdict) is
+  // untouched below — only the USER-VISIBLE second message collapses. Honours
+  // the SWITCHROOM_RESUME_MSG=0 kill-switch (suppresses the continuation line,
+  // as it suppressed the separate message before).
+  const resumeLine = process.env.SWITCHROOM_RESUME_MSG === '0'
+    ? ''
+    : formatPermissionResumeMessage({
+        agentName: process.env.SWITCHROOM_AGENT_NAME ?? null,
+        behavior: behavior as 'allow' | 'deny',
+        action: resumeAction,
+      })
+  const labelWithResume = resumeLine ? `${htmlLabel}\n\n${resumeLine}` : htmlLabel
   // #1150 audit: P0 fix — was `editMessageText` WITHOUT reply_markup
   // strip, leaving the [Allow][Deny][Always] keyboard live after the
   // decision. Operator could re-tap and flip Deny → Allow after the
@@ -22008,7 +23023,7 @@ bot.on('callback_query:data', async ctx => {
   // strips the keyboard atomically with the status-line edit.
   await finalizeCallback(ctx, {
     ackText: ackText.slice(0, 200),
-    newText: baseText ? `${baseText}\n\n${htmlLabel}` : htmlLabel,
+    newText: baseText ? `${baseText}\n\n${labelWithResume}` : labelWithResume,
     synthInbound: () => {
       // No `rule` → the bridge does NOT cache this (truly once on the bridge);
       // any 30-min stickiness lives only in scopedGrants (recorded above).
@@ -22020,10 +23035,11 @@ bot.on('callback_query:data', async ctx => {
       // Un-park the status reaction: 🙏 → working, re-arming the stall
       // watchdog that setAwaiting() suspended.
       resumeReactionAfterVerdict()
-      postPermissionResumeMessage({
-        behavior: behavior as 'allow' | 'deny',
-        action: resumeAction,
-      })
+      // card-folded-resume: the visible "continuing…" line is folded into the
+      // card edit above (labelWithResume), so we deliberately do NOT
+      // postPermissionResumeMessage here — that would re-introduce the split
+      // second message this fix (card-ux fix 3) removes. The turn still resumes
+      // via dispatchPermissionVerdict + resumeReactionAfterVerdict above.
     },
   })
 })
@@ -22091,12 +23107,42 @@ bot.on('message:voice', async ctx => {
   // SOMETHING — better than silent drops.
   const access = loadAccess()
   const voiceIn = access.voice_in
-  if (voiceIn?.enabled && voiceIn?.provider === 'openai') {
-    const transcript = await maybeTranscribeVoice(
-      voice.file_id,
-      voice.mime_type,
-      voiceIn.language,
-    )
+  // Engine selection (PR-B2): the persisted host verdict decides HOW we
+  // transcribe. `local` → the in-fleet GPU sidecar (no third-party key,
+  // vision #3 + #4); anything else → the OpenAI cloud provider. The local
+  // path needs no `provider === 'openai'` gate — it has no API key — so we
+  // route to the sidecar whenever voice_in is enabled AND the host verdict
+  // is `local`. The cloud path keeps its existing openai gate.
+  // Source precedence: the compose-injected SWITCHROOM_VOICE_ENGINE env
+  // (set per-agent by compose-gen from the host verdict — PR-B3) wins,
+  // then the persisted host-capabilities file, then a fail-safe `cloud`.
+  // The env is load-bearing in-fleet: the in-container `~/.switchroom`
+  // is a read-only constructed view that does NOT carry the host's
+  // host-capabilities.json, so without the env the file lookup always
+  // misses and every agent silently falls back to `cloud`. Narrow the
+  // env value to the VoiceEngine union so a bogus value can't leak
+  // through — anything but 'local'/'cloud' is ignored and we fall back.
+  const envVoiceEngine = process.env.SWITCHROOM_VOICE_ENGINE
+  const voiceEngine: VoiceEngine =
+    envVoiceEngine === 'local' || envVoiceEngine === 'cloud'
+      ? envVoiceEngine
+      : loadHostCapabilities()?.voice.engine ?? 'cloud'
+  const localEnabled = voiceIn?.enabled === true && voiceEngine === 'local'
+  const cloudEnabled =
+    voiceIn?.enabled === true && voiceEngine !== 'local' && voiceIn?.provider === 'openai'
+  if (localEnabled || cloudEnabled) {
+    const transcript = localEnabled
+      ? await maybeTranscribeVoiceLocal(
+          voice.file_id,
+          voice.mime_type,
+          voiceIn?.language,
+        )
+      : await maybeTranscribeVoice(
+          voice.file_id,
+          voice.mime_type,
+          voiceIn?.language,
+          voiceIn?.api_key,
+        )
     if (transcript != null) {
       const text = ctx.message.caption
         ? `${ctx.message.caption}\n\n[voice transcript] ${transcript}`
@@ -22121,33 +23167,24 @@ bot.on('message:voice', async ctx => {
  * are logged to stderr but never thrown — voice-in is a UX
  * enhancement, not a critical path.
  */
-async function maybeTranscribeVoice(
-  fileId: string,
-  mimeType: string | undefined,
-  language: string | undefined,
-): Promise<string | null> {
-  // Read API key from the operator-managed file. Same pattern as
-  // webhook-secrets.json — simpler than vault integration for the
-  // spike. Future: resolve through vault once the abstraction
-  // matures.
-  let apiKey: string | null = null
-  try {
-    const path = require('path').join(require('os').homedir(), '.switchroom', 'openai-api-key')
-    if (existsSync(path)) {
-      apiKey = readFileSync(path, 'utf-8').trim()
-    }
-  } catch (err) {
-    process.stderr.write(`telegram gateway: voice-in: failed to read api key: ${(err as Error).message}\n`)
-    return null
-  }
-  if (!apiKey) {
-    process.stderr.write(`telegram gateway: voice-in: enabled but no api key at ~/.switchroom/openai-api-key — falling back\n`)
-    return null
-  }
+/**
+ * Filename hint for the multipart body. Telegram voice is OGG/Opus; agents
+ * may also attach mp3/m4a/wav which arrive as message:audio. Match the mime
+ * so the decoder (Whisper / faster-whisper) gets a usable extension.
+ */
+function voiceFilenameExt(mimeType: string | undefined): string {
+  return mimeType?.includes('mp3') ? 'mp3'
+    : mimeType?.includes('m4a') ? 'm4a'
+    : mimeType?.includes('wav') ? 'wav'
+    : 'ogg'
+}
 
-  // Download the audio bytes from Telegram. Same shape as
-  // executeDownloadAttachment but in-memory rather than to disk.
-  let audioBytes: Uint8Array
+/**
+ * Download a Telegram voice attachment into memory. Shared by the cloud
+ * (Whisper) and local (sidecar) transcription paths. Returns the bytes on
+ * success, or null on any failure (caller falls back). Never throws.
+ */
+async function downloadVoiceBytes(fileId: string): Promise<Uint8Array | null> {
   try {
     const file = await bot.api.getFile(fileId)
     if (!file.file_path) {
@@ -22160,7 +23197,7 @@ async function maybeTranscribeVoice(
       process.stderr.write(`telegram gateway: voice-in: telegram download HTTP ${res.status}\n`)
       return null
     }
-    audioBytes = new Uint8Array(await res.arrayBuffer())
+    return new Uint8Array(await res.arrayBuffer())
   } catch (err) {
     // Sanitize: never let the bot token leak into log lines via the
     // download URL — strip anything that looks like a token.
@@ -22168,19 +23205,78 @@ async function maybeTranscribeVoice(
     process.stderr.write(`telegram gateway: voice-in: download failed: ${msg}\n`)
     return null
   }
+}
 
-  // Filename hint — Telegram voice is OGG/Opus; agents may also
-  // attach mp3/m4a/etc which arrive as message:audio (handled
-  // separately). Match the mime to give Whisper a usable extension.
-  const ext = mimeType?.includes('mp3') ? 'mp3'
-    : mimeType?.includes('m4a') ? 'm4a'
-    : mimeType?.includes('wav') ? 'wav'
-    : 'ogg'
+/**
+ * Transcribe a Telegram voice note via the LOCAL GPU STT sidecar (PR-B2).
+ * Used when the host voice verdict is `local`. Resolves the shared-secret
+ * token from the vault (voice/sidecar-token), downloads the audio, and
+ * POSTs it to the sidecar at loopback (the gateway is network_mode: host).
+ * Returns the transcript on success, null on any failure (caller falls
+ * back to the legacy "(voice message)" envelope). Never throws.
+ */
+async function maybeTranscribeVoiceLocal(
+  fileId: string,
+  mimeType: string | undefined,
+  language: string | undefined,
+): Promise<string | null> {
+  const token = await materializeSidecarToken()
+  if (!token) {
+    // materializeSidecarToken already logged the specific reason.
+    return null
+  }
+
+  const audioBytes = await downloadVoiceBytes(fileId)
+  if (!audioBytes) return null
+
+  const result = await transcribeViaSidecar({
+    token,
+    audio: audioBytes,
+    filename: `voice.${voiceFilenameExt(mimeType)}`,
+    language,
+  })
+
+  if (!result.ok) {
+    process.stderr.write(
+      `telegram gateway: voice-in: local sidecar transcription failed reason=${result.reason}` +
+      (result.detail ? ` detail=${JSON.stringify(result.detail).slice(0, 100)}` : '') +
+      '\n',
+    )
+    return null
+  }
+
+  process.stderr.write(
+    `telegram gateway: voice-in: local sidecar transcribed ${audioBytes.length} bytes in ${result.durationMs}ms ` +
+    `lang=${result.language ?? '?'} audio_s=${result.audioSeconds ?? '?'} chars=${result.text.length}\n`,
+  )
+  return result.text
+}
+
+async function maybeTranscribeVoice(
+  fileId: string,
+  mimeType: string | undefined,
+  language: string | undefined,
+  apiKeyRef: string | undefined,
+): Promise<string | null> {
+  // Resolve the STT key through the vault broker at use-time (PR-A:
+  // voice STT vault-unify). The configured `voice_in.api_key` is a
+  // `vault:<key>` reference (default `vault:openai/api-key`); the
+  // resolved value is held in memory only — never written to disk or
+  // surfaced into the agent prompt. On any failure we return null and
+  // the caller falls back to the legacy "(voice message)" envelope.
+  const apiKey = await materializeVoiceKey({ apiKeyRef })
+  if (!apiKey) {
+    // materializeVoiceKey already logged the specific reason.
+    return null
+  }
+
+  const audioBytes = await downloadVoiceBytes(fileId)
+  if (!audioBytes) return null
 
   const result = await transcribeViaWhisper({
     apiKey,
     audio: audioBytes,
-    filename: `voice.${ext}`,
+    filename: `voice.${voiceFilenameExt(mimeType)}`,
     language,
   })
 
@@ -22627,6 +23723,66 @@ bot.on('message:checklist_tasks_added' as Parameters<typeof bot.on>[0], (ctx) =>
   handleChecklistUpdate(ctx as unknown as Context, 'checklist_tasks_added')
 })
 
+// Suppress the "pinned a message" service message Telegram inserts when OUR
+// silent status-pin fires. The pin call passes `disable_notification: true`,
+// which kills the PUSH notification but NOT the in-chat service message — so
+// delete that service message as it lands, but ONLY for pins we own (tracked
+// in `statusPinState`). Manual/operator pins are never silent and are never
+// touched. Only silent status pins reach here as an OUR-pin match, so the
+// ownership check is the guard.
+//
+// Race tolerance: the service update can arrive before `reconcileStatusPin`
+// has stored the new PinState (the pin API call resolves, Telegram emits the
+// service message, and only then does the reconcile write the Map). A single
+// short retry covers that window; if it's still not one of ours, we leave the
+// service message alone.
+bot.on('message:pinned_message', async ctx => {
+  const pinnedId = ctx.msg.pinned_message?.message_id
+  if (pinnedId == null) return
+  const chatId = String(ctx.chat.id)
+  const serviceMsgId = ctx.msg.message_id
+
+  // Chat-scoped ownership (see pinnedMessageIsOurs): the match requires BOTH
+  // the messageId AND that the tracked entry lives in THIS chat, so a pin id
+  // colliding across chats can't delete a foreign (e.g. operator-manual) pin
+  // notice. statusPinChatIds is the companion pinKey→chatId map written on
+  // every desired-pinned reconcile.
+  const trackedPins = (): TrackedStatusPin[] => {
+    const out: TrackedStatusPin[] = []
+    for (const [pinKey, state] of statusPinState) {
+      const c = statusPinChatIds.get(pinKey)
+      if (c != null) out.push({ chatId: c, messageId: state.messageId })
+    }
+    return out
+  }
+  const isOurs = () => pinnedMessageIsOurs(trackedPins(), chatId, pinnedId)
+
+  if (!isOurs()) {
+    // Tolerate the reconcile-store race: wait briefly, then re-check once.
+    await new Promise(resolve => setTimeout(resolve, 250))
+    if (!isOurs()) return
+  }
+
+  try {
+    await robustApiCall(
+      () => lockedBot.api.deleteMessage(chatId, serviceMsgId),
+      { chat_id: chatId, verb: 'status-pin.delete-service-message' },
+    )
+  } catch (err) {
+    // Best-effort: a failure to delete the service message is cosmetic only —
+    // the "pinned a message" line just stays. The most likely cause in a
+    // supergroup/forum is the bot lacking can_delete_messages admin right, so
+    // surface a concise one-liner (robustApiCall rethrows this case without
+    // logging a reason) rather than swallowing silently — an operator sees WHY.
+    const msg = err instanceof Error ? err.message : String(err)
+    process.stderr.write(
+      `telegram gateway: status-pin: could not delete pin service message ` +
+        `(chat=${chatId} msg=${serviceMsgId}) — likely missing can_delete_messages ` +
+        `admin right in this chat: ${msg}\n`,
+    )
+  }
+})
+
 // ─── Reaction-trigger runtime state (#1074) ──────────────────────────────
 //
 // Bot-message reactions in the configured allowlist trigger a synthetic
@@ -23562,6 +24718,40 @@ void (async () => {
         // tracks the live turn from there.
         try { removeTurnActiveMarker(STATE_DIR) } catch { /* best-effort */ }
 
+        // Strip stale permission cards from prior gateway session. Any entry
+        // still in the store was never resolved (gateway died before the
+        // operator tapped or the reaper ran). The operator might have seen
+        // those cards and tapped them — if so, they got STALE_TAP_NOTICE
+        // ("already resolved") which is misleading. Edit the messages to
+        // remove the keyboard and show a clear "restarted" notice instead.
+        void (async () => {
+          const stale = permCardStore.loadAll()
+          if (stale.length === 0) return
+          process.stderr.write(
+            `telegram gateway: boot-sweep: stripping ${stale.length} stale permission card(s) from prior gateway session\n`,
+          )
+          for (const card of stale) {
+            const toolLabel = card.toolName ?? 'unknown tool'
+            const notice = `🔒 **${toolLabel}**\n\n⚠️ *Gateway restarted — this request is no longer active. Ask your agent to try again if needed.*`
+            try {
+              // allow-raw-bot-api: targeted by message_id; no thread needed; fire-and-forget boot sweep
+              await bot.api.editMessageText(
+                card.chatId,
+                card.messageId,
+                richMessage(notice),
+                { reply_markup: { inline_keyboard: [] } },
+              )
+            } catch (err) {
+              // Card may already be deleted, edited, or in an inaccessible chat — benign
+              process.stderr.write(
+                `telegram gateway: boot-sweep: stale-card strip failed ` +
+                `${card.chatId}:${card.messageId}: ${(err as Error).message}\n`,
+              )
+            }
+          }
+          permCardStore.clear()
+        })()
+
         // Boot-time pin sweep
         try {
           const bootAccess = loadAccess()
@@ -24147,6 +25337,8 @@ void (async () => {
                       elapsedMs: durationMs,
                       state: outcome === 'failed' ? 'failed' : 'done',
                     })
+                    // Status-pin: worker done — drop its pin.
+                    reconcileWorkerPin(agentId, null, false)
                   }
                   return
                 }
@@ -24164,6 +25356,8 @@ void (async () => {
                     elapsedMs: durationMs,
                     state: outcome === 'failed' ? 'failed' : 'done',
                   })
+                  // Status-pin: worker done — drop its pin.
+                  reconcileWorkerPin(agentId, null, false)
                 }
 
                 const handbackOrigin = resolveSubagentOriginChat(agentId)
@@ -24291,9 +25485,10 @@ void (async () => {
                   })
                   if (surface === 'worker-feed') {
                     const origin = resolveSubagentOriginChat(agentId)
+                    const wkChat = origin?.chatId || fleetChatId || (loadAccess().allowFrom[0] ?? '')
                     void workerActivityFeed?.update(
                       agentId,
-                      origin?.chatId || fleetChatId || (loadAccess().allowFrom[0] ?? ''),
+                      wkChat,
                       {
                         description: dispatch.feedDescription,
                         lastTool,
@@ -24303,7 +25498,7 @@ void (async () => {
                         state: 'running',
                       },
                       origin?.threadId,
-                    )
+                    )?.then(() => reconcileWorkerPin(agentId, wkChat, true))
                     return
                   }
                   if (surface !== 'nest') return // 'skip' — orphan-status off
@@ -24425,9 +25620,10 @@ void (async () => {
                 // is gone — see resolveSubagentOriginChat).
                 if (workerFeedEnabled) {
                   const origin = resolveSubagentOriginChat(agentId)
+                  const wkChat = origin?.chatId || fleetChatId || (loadAccess().allowFrom[0] ?? '')
                   void workerActivityFeed?.update(
                     agentId,
-                    origin?.chatId || fleetChatId || (loadAccess().allowFrom[0] ?? ''),
+                    wkChat,
                     {
                       description: dispatch.feedDescription,
                       lastTool,
@@ -24437,7 +25633,7 @@ void (async () => {
                       state: 'running',
                     },
                     origin?.threadId,
-                  )
+                  )?.then(() => reconcileWorkerPin(agentId, wkChat, true))
                   return
                 }