switchroom 0.17.10 → 0.18.6

package/telegram-plugin/gateway/gateway.ts

@@ -185,6 +185,12 @@ import {
 import { clearStaleTelegramPollingState } from '../startup-reset.js'
 import { gatewayStartupRetry } from './startup-network-retry.js'
 import { writeQuarantineMarker } from './quarantine.js'
+import {
+  runPersonDirectoryBootCheck,
+  safeResolvePersonName,
+  type PersonDirectory,
+  type RawPersonEntry,
+} from './resolve-person.js'
 // RFC H §7.3: auth-dashboard + auth-slot-parser deleted. Three chat
 // verbs (/auth show | use | rotate) talk to switchroom-auth-broker
 // via the thin client in src/auth/broker/client.ts.
@@ -294,6 +300,7 @@ import {
   shouldArmOrphanedReplyTimeout,
   ORPHANED_REPLY_TIMEOUT_MS,
   ORPHANED_REPLY_MAX_REARMS,
+  LivenessTracker,
 } from '../context-exhaustion.js'
 import {
   decideTurnFlush,
@@ -346,6 +353,7 @@ import {
   buildModelMenu,
   handleModelMenuCallback,
   isSrToClaudeTransition,
+  isValidModelArg,
   MODEL_CALLBACK_PREFIX,
   MODEL_CALLBACK_HEADER,
   MODEL_CALLBACK_SR,
@@ -357,6 +365,7 @@ import {
   type ModelMenuReply,
 } from './model-command.js'
 import { discoverModels, selectModel } from '../../src/agents/model-picker.js'
+import { resolveMainModel } from '../../src/agents/scaffold.js'
 import {
   parseEffortCommand,
   handleEffortCommand,
@@ -419,6 +428,7 @@ import {
   writeActivityCardRecord,
   clearActivityCardRecord,
   runActivityCardBootReaper,
+  runActivityCardMidSessionReaper,
   restartOrphanCardFinalizeText,
   type ActivityCardStoreFsSeam,
 } from './activity-card-store.js'
@@ -427,7 +437,7 @@ import { shouldSuppressRepresent } from './represent-guard.js'
 import { shouldDeferEscalationForBridge } from './escalation-bridge-gate.js'
 import { createInboundSpool } from './inbound-spool.js'
 import { purgeStaleTurnsForChat } from './turn-state-purge.js'
-import { decideInboundDelivery } from './inbound-delivery-gate.js'
+import { decideInboundDelivery, reserveInboundDelivery } from './inbound-delivery-gate.js'
 import { mayDrainBufferedInbound, shouldArmNoReplyDrain } from './serialize-drain-gate.js'
 import { decideFeedReopen } from './feed-reopen-gate.js'
 import {
@@ -662,6 +672,7 @@ import {
   findRecentTurnsForChat,
   getTurnByKey,
   markTurnResumed,
+  reapStaleOpenTurns,
 } from '../registry/turns-schema.js'
 import {
   buildResumeInterruptedInbound,
@@ -716,6 +727,12 @@ const ACCESS_FILE = join(STATE_DIR, 'access.json')
 const APPROVED_DIR = join(STATE_DIR, 'approved')
 const ENV_FILE = join(STATE_DIR, '.env')
 const INBOX_DIR = join(STATE_DIR, 'inbox')
+// person_id name resolution (docs/configuration.md). Sibling to
+// access.json but a COMPLETELY SEPARATE, purely config-derived file —
+// scaffold regenerates it on every reconcile via writeFileSyncIfChanged,
+// the gateway never mutates it, and (unlike access.json) it is read
+// exactly ONCE at boot into PERSON_DIRECTORY below — no hot-reload.
+const PEOPLE_FILE = join(STATE_DIR, 'people.json')
 
 /**
  * Trigger a restart of the agent + gateway pair.
@@ -1219,6 +1236,33 @@ function loadAccess(): Access {
   return BOOT_ACCESS ?? readAccessFile()
 }
 
+/**
+ * Read `people.json` (the scaffold's plain projection of `users:` entries
+ * that carry a `person_id`). Fail-open: ENOENT or corrupt/malformed JSON
+ * returns an empty array rather than throwing — this feature must never
+ * block startup. Unlike `access.json` this file is never gateway-mutated,
+ * so there's no "move corrupt file aside" concern; the scaffold owns and
+ * regenerates it on every reconcile.
+ */
+function readPeopleFile(): RawPersonEntry[] {
+  try {
+    const raw = readFileSync(PEOPLE_FILE, 'utf8')
+    const parsed = JSON.parse(raw) as { entries?: unknown }
+    if (!Array.isArray(parsed.entries)) return []
+    return parsed.entries as RawPersonEntry[]
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Boot-time-only person-name directory (see resolve-person.ts module doc).
+ * Populated exactly once by the boot-validation block in the startup IIFE
+ * below, then never reassigned or re-read from disk again for the life of
+ * this process — a config change requires an agent restart.
+ */
+let PERSON_DIRECTORY: PersonDirectory = { byTelegramKey: {} }
+
 function assertAllowedChat(chat_id: string | number): void {
   const id = String(chat_id)
   const access = loadAccess()
@@ -1483,6 +1527,64 @@ function resolveSubagentOriginChat(
   }
 }
 
+/**
+ * Tracks worker-feed agents whose owner-DM fallback has already been
+ * logged, so `resolveWorkerFeedChat` emits the routing-decision line once
+ * per agent instead of every watcher tick (~1/s). Capped FIFO at 256 — a
+ * late duplicate log is harmless (one extra stderr line), and the cap keeps
+ * the set bounded across a long gateway lifetime even if origin resolution
+ * is persistently broken fleet-wide (history disabled → every nested worker
+ * hits the fallback). A gateway restart clears it.
+ */
+const WORKER_FEED_FALLBACK_LOG_CAP = 256
+const workerFeedOwnerDmFallbackLogged = new Set<string>()
+
+/**
+ * Resolve a worker-feed destination chat with a guaranteed last resort.
+ *
+ * The universal-liveness contract is "any active work has a card, at any
+ * nesting depth, with or without a parent turn open." Origin resolution
+ * (`resolveSubagentOriginChat`) only succeeds when the ancestor turn row is
+ * in `turnsDb` and history is enabled; a depth-2+ worker whose chain can't
+ * be walked (history disabled, row reaped, ancestor never stamped) would
+ * otherwise fall through `fleetChatId || allowFrom[0]` and, if those are
+ * empty too, hit the `chatId.length === 0` skip in `workerActivityFeed.update`
+ * — painting NOTHING, silently. That is the one path most likely to violate
+ * "any and all active work has a card."
+ *
+ * This never returns `''`: the precedence is origin chat → fleet chat →
+ * first allowed chat (the owner DM). The owner DM is the durable floor —
+ * "wrong chat" beats "no card." A one-line routing-decision log flags the
+ * fallback so an operator can see the misroute without it reading as an
+ * error (it isn't one — the card surfaced).
+ */
+function resolveWorkerFeedChat(
+  agentId: string,
+  fleetChatId: string,
+): { chatId: string; threadId?: number } {
+  const origin = resolveSubagentOriginChat(agentId)
+  if (origin != null && origin.chatId.length > 0) return origin
+  if (fleetChatId.length > 0) return { chatId: fleetChatId }
+  const ownerDm = loadAccess().allowFrom[0] ?? ''
+  if (origin == null && fleetChatId.length === 0 && ownerDm.length > 0) {
+    // Routing decision, not a warning: origin resolution failed and no
+    // fleet chat is configured, so the nested worker's card lands in the
+    // owner DM. Logged ONCE per agent so the misroute is auditable
+    // without spamming every tick (the watcher drives onProgress ~1/s).
+    if (!workerFeedOwnerDmFallbackLogged.has(agentId)) {
+      workerFeedOwnerDmFallbackLogged.add(agentId)
+      if (workerFeedOwnerDmFallbackLogged.size > WORKER_FEED_FALLBACK_LOG_CAP) {
+        const oldest = workerFeedOwnerDmFallbackLogged.values().next().value
+        if (oldest != null) workerFeedOwnerDmFallbackLogged.delete(oldest)
+      }
+      process.stderr.write(
+        `telegram gateway: worker-feed origin unresolved agent=${agentId} — routing card to owner DM\n`,
+      )
+    }
+  }
+  return { chatId: ownerDm, threadId: origin?.threadId }
+}
+
 // ─── Periodic history reaper (#1073) ──────────────────────────────────────
 // The init-time prune in history.ts only touched the `messages` table.
 // `subagents` and `turns` in registry.db grew unbounded — every Agent()
@@ -1949,6 +2051,25 @@ const obligationEscalateInFlight = new Set<string>()
 // drain on the bare turn-end signal.
 const SERIALIZE_UNTIL_REPLIED_ENABLED =
   process.env.SWITCHROOM_SERIALIZE_UNTIL_REPLIED !== '0'
+// #2917 — rapid-fire per-chat FIFO. The #1556 delivery gate documents its
+// `turnInFlight` input as a LIVE read ("evaluated at delivery time — not a
+// receipt-time snapshot"), but handleInbound passes a receipt-time snapshot
+// (`turnInFlightAtReceipt`) taken at function entry. Under rapid-fire two
+// same-chat inbounds each snapshot "idle" during the other's async lead-in
+// (attachment download, composer-clear), both pass the gate, and both are
+// delivered — so replies come back reordered (observed 1,2,4,5,3,7,8,6). The
+// fix reads the gate LIVE off `claudeBusyKeys` (which does NOT yet contain
+// THIS inbound's own key — that is only marked at delivery — so it can't
+// self-block) AND reserves the key synchronously BEFORE the composer-clear
+// await, so a concurrent same-chat inbound observes the reservation and
+// buffers behind it, preserving FIFO. Nothing is dropped: a buffered inbound
+// drains on turn-complete / idle exactly as before. Kill switch (=0) restores
+// the receipt-snapshot behaviour. Only the non-cutover path is affected — the
+// delivery-machine cutover keeps its own at-receipt machine snapshot (reading
+// the machine live WOULD self-block, since its inbound event already advanced
+// it for this key).
+const SERIALIZE_INBOUND_DELIVERY_ENABLED =
+  process.env.SWITCHROOM_SERIALIZE_INBOUND_DELIVERY !== '0'
 // Component 2 (bounded no-reply escape hatch). A turn that legitimately
 // ends with NO reply (handback ack, NO_REPLY marker, silent-end) sets
 // finalAnswerDelivered=false and would block the serialize gate forever.
@@ -2348,13 +2469,15 @@ type CurrentTurn = {
   silentAnchorText: string
   capturedText: string[]
   orphanedReplyTimeoutId: ReturnType<typeof setTimeout> | null
-  // How many times the orphaned-reply backstop timer has been re-armed
-  // mid-tool-call instead of firing a synthetic turn_end. Bounded so a
-  // genuinely wedged single long-running tool still surfaces: the cap is
-  // ORPHANED_REPLY_MAX_REARMS (20 × 30 s = 10 min of genuine tool activity).
-  // Reset to 0 on a fresh enqueue; NOT reset on text/tool_label re-arms —
-  // only a new turn resets the budget.
-  orphanedReplyRearmCount: number
+  // Per-turn liveness tracker for the orphaned-reply backstop. Owns
+  // `lastStreamEventAt` (stamped on ANY genuine stream event so a model
+  // reasoning pause keeps the turn "recently streaming" and re-arms the fuse
+  // instead of firing) and the rearm counter (bounded by
+  // ORPHANED_REPLY_MAX_REARMS so a genuinely wedged single tool that never
+  // streams still surfaces after the cap). The counter is zeroed on every
+  // genuine stream event, so the cap only bites CONSECUTIVE silent expiries.
+  // Fresh instance per enqueue (below). See context-exhaustion.ts.
+  liveness: LivenessTracker
   // Component 3 (turn-origin reply routing). A stable per-turn identity,
   // `${registryKey-or-chatKey}#${startedAt}`, assigned when the turn
   // starts and stamped into the inbound meta (`origin_turn_id`) so a reply
@@ -4044,9 +4167,26 @@ async function resolveCompactCard(
       { chat_id: card.chatId, verb: `proactiveCompact.${kind}` },
     );
   } catch (err) {
+    // Best-effort status-card edit — a transport hiccup (429 / "not
+    // modified" / message gone) is not a liveness-logic error and must
+    // not log a "card edit failed" warning (the warning-as-excuse-for-a-
+    // stale-card anti-pattern). Only a genuine unexpected error warrants
+    // a line; transport classes are silent.
+    const desc = err instanceof Error ? err.message : String(err);
+    const low = desc.toLowerCase();
+    if (
+      low.includes('not modified') ||
+      low.includes('not found') ||
+      low.includes("can't be edited") ||
+      low.includes('cannot be edited') ||
+      low.includes('not enough rights') ||
+      low.includes('429') ||
+      low.includes('retry after')
+    ) {
+      return;
+    }
     process.stderr.write(
-      `telegram gateway: proactive-compact ${kind} card edit failed: ` +
-        `${err instanceof Error ? err.message : String(err)}\n`,
+      `telegram gateway: proactive-compact ${kind} card edit failed: ${desc}\n`,
     );
   }
 }
@@ -6230,6 +6370,127 @@ async function activityCardBootReaper(): Promise<void> {
     )
   }
 }
+// ─── Mid-session stale-card reaper (#2918) ──────────────────────────────────
+// The boot reapers (markOrphanedWithTimeoutClassification + activityCardBoot-
+// Reaper) run ONCE at startup. A turn whose owning SDK subprocess dies
+// mid-session (SIGKILL / OOM / crash) without a clean end leaves its turns-DB
+// row `ended_at IS NULL` and its activity card frozen on "working…" until the
+// NEXT gateway boot — often many hours. This periodic sweep, running inside the
+// live gateway, finalizes those orphans without waiting for a restart.
+//
+// LIVENESS (the critical correctness guard): a turn/card is reaped ONLY when no
+// live in-flight turn owns it. The live set is derived from `currentTurnMap`
+// (per-topic byKey) PLUS the singleton `currentTurn` mirror, so it is correct
+// whether or not the per-topic-isolation flag is on. A healthy long-running
+// turn is always in that set and is never swept. A TTL gate is a secondary
+// guard against the just-started-not-yet-tracked race.
+//
+// Kill switch: set SWITCHROOM_MID_SESSION_CARD_REAPER=0 to disable (clean
+// revert, mirrors #2919). TTL/interval overridable via env for tuning.
+const MID_SESSION_CARD_REAPER_ENABLED =
+  process.env.SWITCHROOM_MID_SESSION_CARD_REAPER !== '0'
+const MID_SESSION_CARD_REAPER_TTL_MS = (() => {
+  const v = Number(process.env.SWITCHROOM_MID_SESSION_CARD_REAPER_TTL_MS)
+  return Number.isFinite(v) && v > 0 ? v : 15 * 60_000 // 15 min
+})()
+const MID_SESSION_CARD_REAPER_INTERVAL_MS = (() => {
+  const v = Number(process.env.SWITCHROOM_MID_SESSION_CARD_REAPER_INTERVAL_MS)
+  return Number.isFinite(v) && v > 0 ? v : 5 * 60_000 // 5 min
+})()
+
+// Snapshot the turn_keys / topic keys owned by a live in-flight turn right now.
+function liveTurnKeySets(): { registryKeys: Set<string>; topicKeys: Set<string> } {
+  const registryKeys = new Set<string>()
+  const topicKeys = new Set<string>()
+  const add = (t: CurrentTurn | null | undefined): void => {
+    if (t == null) return
+    if (t.registryKey != null && t.registryKey.length > 0) registryKeys.add(t.registryKey)
+    topicKeys.add(statusKey(t.sessionChatId, t.sessionThreadId))
+  }
+  for (const t of currentTurnMap.byKey.values()) add(t)
+  add(currentTurn) // flag-OFF store + most-recent mirror
+  return { registryKeys, topicKeys }
+}
+
+async function runMidSessionCardReaper(): Promise<void> {
+  if (!MID_SESSION_CARD_REAPER_ENABLED) return
+  const now = Date.now()
+  const { registryKeys, topicKeys } = liveTurnKeySets()
+
+  // 1) Stamp ownerless open turns-DB rows (the durable spinner signal).
+  if (turnsDb != null) {
+    try {
+      const { reaped, reapedTurnKeys } = reapStaleOpenTurns(turnsDb, {
+        activeTurnKeys: registryKeys,
+        ttlMs: MID_SESSION_CARD_REAPER_TTL_MS,
+        now,
+      })
+      if (reaped > 0) {
+        process.stderr.write(
+          `telegram gateway: mid-session reaper stamped ${reaped} orphaned turn(s) ` +
+            `as 'restart' (${reapedTurnKeys.join(',')})\n`,
+        )
+      }
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: mid-session turn reaper error: ${(err as Error).message}\n`,
+      )
+    }
+  }
+
+  // 2) Finalize the leftover visible activity card(s) for those dead turns.
+  if (activityCardPersistEnabled) {
+    try {
+      const { finalized, vanished, total } = await runActivityCardMidSessionReaper({
+        path: ACTIVITY_CARD_STORE_PATH,
+        fs: activityCardStoreFs,
+        isLive: (record) => topicKeys.has(record.turnKey),
+        ttlMs: MID_SESSION_CARD_REAPER_TTL_MS,
+        now,
+        finalizeCard: (record) =>
+          robustApiCall(
+            () =>
+              lockedBot.api.editMessageText(
+                record.chatId,
+                record.activityMessageId,
+                richMessage(restartOrphanCardFinalizeText(record.startedAt)),
+                {},
+              ),
+            {
+              chat_id: record.chatId,
+              ...(record.threadId != null ? { threadId: record.threadId } : {}),
+              verb: 'activity-card.mid-session-reap-finalize',
+            },
+          ),
+        unpinCard: (record) =>
+          robustApiCall(
+            () => lockedBot.api.unpinChatMessage(record.chatId, record.activityMessageId),
+            {
+              chat_id: record.chatId,
+              ...(record.threadId != null ? { threadId: record.threadId } : {}),
+              verb: 'activity-card.mid-session-reap-unpin',
+            },
+          ),
+      })
+      if (total > 0) {
+        process.stderr.write(
+          `telegram gateway: activity-card: mid-session finalized ${finalized}/${total} ` +
+            `(vanished ${vanished}/${total}) orphaned card(s) (at-most-once)\n`,
+        )
+      }
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: mid-session card reaper error: ${(err as Error).message}\n`,
+      )
+    }
+  }
+}
+
+const midSessionCardReaper = setInterval(() => {
+  void runMidSessionCardReaper()
+}, MID_SESSION_CARD_REAPER_INTERVAL_MS)
+midSessionCardReaper.unref()
+
 // 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
@@ -6596,6 +6857,11 @@ function parsePositiveMsEnv(name: string, fallbackMs: number): number {
   const n = Number(raw)
   return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallbackMs
 }
+// Orphaned-reply "recently streaming" window (thinking-pause fix). If a genuine
+// stream event landed within this window, the fuse re-arms instead of firing —
+// so a long model reasoning pause (which emits no text/tool events) is
+// survivable while a genuine multi-minute hang still surfaces. Default 120 s.
+const ORPHANED_REPLY_STREAM_WINDOW_MS = parsePositiveMsEnv('SWITCHROOM_ORPHANED_REPLY_STREAM_WINDOW_MS', 120_000)
 const SILENCE_FALLBACK_MS = parsePositiveMsEnv('SWITCHROOM_SILENCE_FALLBACK_MS', 300_000)
 const SILENCE_FALLBACK_HARD_MS = parsePositiveMsEnv('SWITCHROOM_SILENCE_FALLBACK_HARD_MS', 900_000)
 // #2527 — mid-turn liveness floor threshold (default 45s). Still gates the
@@ -12411,20 +12677,32 @@ function resetOrphanedReplyTimeout(): void {
           }
           return false
         })()
-        if (working || humanWaiting) {
-          const underCap = t.orphanedReplyRearmCount < ORPHANED_REPLY_MAX_REARMS
-          if (humanWaiting || underCap) {
-            t.orphanedReplyRearmCount++
-            process.stderr.write(
-              `telegram gateway: orphaned-reply fuse expired — re-arming` +
-              ` (rearm ${t.orphanedReplyRearmCount}/${ORPHANED_REPLY_MAX_REARMS},` +
-              ` in_flight=${toolFlightTracker.inFlightCount()},` +
-              ` human_wait=${humanWaiting},` +
-              ` bg_work=${pendingProgress.hasPendingAsyncDispatch(turnKey)})\n`,
-            )
-            resetOrphanedReplyTimeout()
-            return
-          }
+        // Route the rearm decision through the per-turn LivenessTracker. It
+        // rearms when working OR recently-streaming (thinking-pause survival)
+        // OR human-waiting; working/recently-streaming rearms count against
+        // ORPHANED_REPLY_MAX_REARMS while human-wait rearms stay uncapped.
+        const now = Date.now()
+        const recentlyStreaming = t.liveness.recentlyStreaming(now, ORPHANED_REPLY_STREAM_WINDOW_MS)
+        const decision = t.liveness.decideOnExpiry({
+          working,
+          humanWaiting,
+          now,
+          windowMs: ORPHANED_REPLY_STREAM_WINDOW_MS,
+          maxRearms: ORPHANED_REPLY_MAX_REARMS,
+        })
+        if (decision.rearm) {
+          process.stderr.write(
+            `telegram gateway: orphaned-reply fuse expired — re-arming` +
+            ` (rearm ${t.liveness.orphanedReplyRearmCount}/${ORPHANED_REPLY_MAX_REARMS},` +
+            ` in_flight=${toolFlightTracker.inFlightCount()},` +
+            ` human_wait=${humanWaiting},` +
+            ` recently_streaming=${recentlyStreaming},` +
+            ` bg_work=${pendingProgress.hasPendingAsyncDispatch(turnKey)})\n`,
+          )
+          resetOrphanedReplyTimeout()
+          return
+        }
+        if (decision.countsAgainstCap) {
           process.stderr.write(
             `telegram gateway: orphaned-reply rearm cap reached (${ORPHANED_REPLY_MAX_REARMS}) — forcing backstop despite working state\n`,
           )
@@ -12732,7 +13010,22 @@ async function drainActivitySummary(
         turn.activityLastSentRender = target
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err)
-        if (!msg.includes('message is not modified')) {
+        const low = msg.toLowerCase()
+        // Transport-class failures (429, message gone, "not modified") must
+        // NOT inflate `activityDrainFailures` — that counter flags a turn as
+        // DEGRADED on turn-end, and a transient rate-limit or an
+        // already-deleted message is not a logic defect. Counting them would
+        // false-flag a healthy turn. "not modified" is success; gone/429 are
+        // retried or harmless. Only a genuine send/open failure counts.
+        const isTransport =
+          low.includes('not modified') ||
+          low.includes('not found') ||
+          low.includes("can't be edited") ||
+          low.includes('cannot be edited') ||
+          low.includes('not enough rights') ||
+          low.includes('429') ||
+          low.includes('retry after')
+        if (!isTransport) {
           turn.activityDrainFailures += 1
           // Surface the failing anchor + topic: the resume-400 bug fed a
           // fabricated 13-digit message_id as the reply anchor here, so every
@@ -12900,11 +13193,19 @@ function feedHeartbeatTick(): void {
     //               durable record once it completes.
     //   - 'emit'  → genuine in-flight post-answer activity; render the card below.
     const subagentAt = turn.subagentActivityAt
+    // Fix 3 (sub-agent-delegation freeze): a foreground `Task`/`Agent` still
+    // tracked in `turn.foregroundSubAgents` is POSITIVE evidence the worker
+    // has not reported finished — see the doc comment on
+    // `PostAnswerLivenessInput.stillDispatched` in turn-liveness-floor.ts for
+    // why this must bypass the staleness cap rather than let a single long
+    // silent step freeze the card mid-delegation.
+    const stillDispatched = turn.foregroundSubAgents.size > 0
     const livenessVerdict = evaluatePostAnswerLiveness({
       subagentActivityAt: subagentAt,
       finalAnswerDeliveredAt: turn.finalAnswerDeliveredAt,
       now: Date.now(),
       staleCapMs: POST_ANSWER_LIVENESS_STALE_MS,
+      stillDispatched,
     })
     if (livenessVerdict !== 'emit' || subagentAt == null) return // idle gap or stale worker → stay silent (the `== null` also narrows subagentAt for the elapsed below)
     // A background worker is genuinely active after the answer. Open or maintain
@@ -13074,7 +13375,23 @@ function clearActivitySummary(turn: CurrentTurn, finalHtmlOverride?: string | nu
           { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.delete' },
         )
       } catch (err) {
-        process.stderr.write(`telegram gateway: activity-summary delete failed: ${err}\n`)
+        // Best-effort teardown of a status card. A transport-class failure
+        // (message already deleted, chat gone, 429) is not a liveness-logic
+        // error — "message to delete not found" is the desired end state
+        // here, and a 429 on a teardown delete is retried by robustApiCall.
+        // Stay silent on those; warn only on a genuinely unexpected error.
+        const msg = err instanceof Error ? err.message : String(err)
+        const low = msg.toLowerCase()
+        if (
+          low.includes('not modified') ||
+          low.includes('not found') ||
+          low.includes('not enough rights') ||
+          low.includes('429') ||
+          low.includes('retry after')
+        ) {
+          return
+        }
+        process.stderr.write(`telegram gateway: activity-summary delete failed: ${msg}\n`)
       }
       return
     }
@@ -13100,10 +13417,26 @@ function clearActivitySummary(turn: CurrentTurn, finalHtmlOverride?: string | nu
         { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.finalize' },
       )
     } catch (err) {
+      // Same transport-class discipline as the delete path: the card
+      // finalize is a best-effort liveness edit. "not modified" = the card
+      // already shows the finalized body (success); "not found" / "not
+      // enough rights" = the message is gone (nothing to finalize); 429 is
+      // retried by robustApiCall. None of those are liveness-logic errors
+      // and none warrant a stderr warning. Warn only on the unexpected.
       const msg = err instanceof Error ? err.message : String(err)
-      if (!msg.includes('message is not modified')) {
-        process.stderr.write(`telegram gateway: activity-summary finalize failed: ${msg}\n`)
+      const low = msg.toLowerCase()
+      if (
+        low.includes('not modified') ||
+        low.includes('not found') ||
+        low.includes("can't be edited") ||
+        low.includes('cannot be edited') ||
+        low.includes('not enough rights') ||
+        low.includes('429') ||
+        low.includes('retry after')
+      ) {
+        return
       }
+      process.stderr.write(`telegram gateway: activity-summary finalize failed: ${msg}\n`)
     }
   })
 }
@@ -13278,6 +13611,22 @@ function surfaceConsolidationLegibility(
 }
 
 function handleSessionEvent(ev: SessionEvent): void {
+  // Per-turn liveness stamp (orphaned-reply thinking-pause fix). Stamp
+  // lastStreamEventAt AND reset the rearm counter on ANY genuine stream event,
+  // under ONE shared predicate: a live turn is present and this is not the
+  // synthetic durationMs===-1 turn_end (the fire callback's own re-dispatch).
+  // The counter reset MUST live here at the dispatcher — NOT inside
+  // resetOrphanedReplyTimeout() (which is called from the fire callback one
+  // line after the counter increments) and NOT tied to a single case (e.g.
+  // tool_result does not call resetOrphanedReplyTimeout). onStreamEvent applies
+  // the `!(turn_end && -1)` half of the predicate internally.
+  {
+    const liveTurn = currentTurn
+    if (liveTurn != null) {
+      const durationMs = ev.kind === 'turn_end' ? ev.durationMs : undefined
+      liveTurn.liveness.onStreamEvent(ev.kind, durationMs, Date.now())
+    }
+  }
   switch (ev.kind) {
     case 'enqueue': {
       // Drain any orphaned typing-wrap entries left over from a crashed
@@ -13314,6 +13663,14 @@ function handleSessionEvent(ev: SessionEvent): void {
           prior.answerStream.stop()
           prior.answerStream = null
         }
+        // Bounded-leak hardening (A5): clear the prior turn's orphaned-reply
+        // fuse before it is superseded. The fire callback re-reads currentTurn
+        // and no-ops on a stale turn, but proactively clearing the timer avoids
+        // a bounded pile-up of dangling timers across rapid steer/queue turns.
+        if (prior?.orphanedReplyTimeoutId != null) {
+          clearTimeout(prior.orphanedReplyTimeoutId)
+          prior.orphanedReplyTimeoutId = null
+        }
         // #1067: swap the entire turn atom in one assignment. Every
         // handler captures `const turn = currentTurn` at entry, so a
         // captured-then-awaited read can't reattribute to the new turn.
@@ -13373,7 +13730,9 @@ function handleSessionEvent(ev: SessionEvent): void {
           silentAnchorText: '',
           capturedText: [],
           orphanedReplyTimeoutId: null,
-          orphanedReplyRearmCount: 0,
+          // Fresh liveness tracker: lastStreamEventAt seeded to the turn start
+          // so a turn that never streams still trips the fuse after windowMs.
+          liveness: new LivenessTracker(startedAt),
           turnId,
           registryKey: null,
           noReplyDrainTimer: null,
@@ -14043,10 +14402,25 @@ function handleSessionEvent(ev: SessionEvent): void {
       if (ev.durationMs === -1) {
         const turn = currentTurn
         const key = turn != null ? statusKey(turn.sessionChatId, turn.sessionThreadId) : ''
-        if (isLegitimatelyWorking(key)) {
+        // Widened to also suppress while the turn is RECENTLY STREAMING — a
+        // model reasoning pause emits no tool/text events (so
+        // isLegitimatelyWorking is false) but a genuine stream landed within
+        // the window, so the turn is alive and must not be torn down.
+        // ACCEPTED TRADE-OFF (F3): the context-exhaustion recovery latency via
+        // THIS backstop path grows from ~30 s to ~120-150 s, because the
+        // "Prompt is too long" marker is itself a genuine `text` event that
+        // stamps recentlyStreaming. This is acceptable — the primary
+        // context-exhaustion teardown is the immediate `endCurrentTurnAtomic`
+        // in `case 'text'` (isContextExhaustionText) above; this backstop only
+        // matters if that path is missed, and it still COMPLETES once the
+        // window lapses. Recovery is delayed, never suppressed forever.
+        const recentlyStreaming =
+          turn != null && turn.liveness.recentlyStreaming(Date.now(), ORPHANED_REPLY_STREAM_WINDOW_MS)
+        if (isLegitimatelyWorking(key) || recentlyStreaming) {
           process.stderr.write(
             `telegram gateway: synthetic turn_end suppressed — legitimately working` +
             ` (in_flight=${toolFlightTracker.inFlightCount()},` +
+            ` recently_streaming=${recentlyStreaming},` +
             ` bg_work=${turn != null ? pendingProgress.hasPendingAsyncDispatch(key) : false})\n`,
           )
           return
@@ -15340,30 +15714,32 @@ async function handleInbound(
   // network RTT) but not a user-perceived end-to-end measurement.
   const inboundReceivedAt = Date.now()
 
-  // Phase 2b shadow: inbound arrival. Emit BEFORE the snapshot/gate
-  // logic so the machine sees the event at the same point in time the
-  // imperative code would. The machine internally handles fresh-turn
-  // vs mid-turn — its decision will be visible in the gw-trace shadow
-  // line emitted to stderr.
-  const _shadowKey = statusKey(ctx.chat?.id != null ? String(ctx.chat.id) : '0', ctx.message?.message_thread_id) as _ChatKey
-  // PR3b-cutover: snapshot the machine's in-turn state BEFORE the
-  // inbound event advances it. A fresh-turn inbound transitions the
-  // machine idle→in_turn; reading after the emit would see THIS
-  // message's own just-started turn and self-block it (the same
-  // self-block hazard the claudeBusyKeys snapshot below guards). When
-  // the kill-switch is off this is null and the gate uses the legacy
+  // PR3b-cutover: snapshot the machine's in-turn state AT RECEIPT, before
+  // this handler emits the `inbound` event (that emit is DEFERRED below to
+  // the delivery-commit point — search DEFERRED_INBOUND_EMIT). A fresh-turn
+  // inbound transitions the machine idle→in_turn; reading after the emit
+  // would see THIS message's own just-started turn and self-block it (the
+  // same self-block hazard the claudeBusyKeys snapshot below guards). Null
+  // when the kill-switch is off, in which case the gate uses the legacy
   // claudeBusyKeys read.
+  //
+  // WHY THE INBOUND EMIT IS DEFERRED (overlord /usage wedge, 2026-07-08):
+  // the `inbound` event drives the now-AUTHORITATIVE turn-in-flight gate
+  // (turnInFlightForGate → isMachineInTurn). Emitting it HERE — at handler
+  // entry, before the intercept gauntlet below (permission-reply, /auth
+  // paste-back, interrupt-empty, secret-detect drop, …) — drove the machine
+  // into `bridge_alive_in_turn` for messages that then EARLY-RETURN as an
+  // intercept and never become a turn. No delivery, no claudeBusyKeys mark,
+  // and critically no `turnEnd` ever fires, so the machine held the gate
+  // closed until the 5-min TTL tick force-cleared it — buffering every
+  // subsequent inbound (including /usage) the whole time. That is exactly
+  // the dangerous `machine_over_holds` divergence gate-parity-probe.ts
+  // flags. The imperative claudeBusyKeys tracker got it right (never marked
+  // busy for the intercepted message); the machine was mis-fed. Fix: emit
+  // `inbound` only once the message clears every intercept and reaches the
+  // deliver-or-buffer decision, keeping the machine in lockstep with the
+  // imperative delivery lifecycle it models.
   const machineInTurnAtReceipt = isDeliveryCutoverEnabled() ? isMachineInTurn() : null
-  shadowEmit({
-    kind: 'inbound',
-    key: _shadowKey,
-    msg: {
-      msgId: ctx.message?.message_id ?? 0,
-      isSteering: false, // refined in PR 3 — for now shadow conservatively classifies as non-steering
-      payload: null,
-    },
-    at: Date.now(),
-  })
 
   // #1556 self-blocking fix (v0.12.22): snapshot the live turn-state
   // BEFORE the fresh-turn branch (line ~7357) sets activeTurnStartedAt
@@ -16435,12 +16811,28 @@ async function handleInbound(
     TOPIC_FRAMING_ENABLED && messageThreadId != null
       ? 'This message belongs to the current topic only — answer ONLY this question, in this topic. Do not also answer a pending message from another topic.'
       : undefined
+  // person_id name resolution (docs/configuration.md, resolve-person.ts):
+  // chat-scoped, boot-time-static lookup — falls back to today's raw
+  // id/username behavior (fail-open) whenever unresolved or when group
+  // membership can't be positively confirmed from access.json's allowFrom.
+  // Never touches access.json itself and never blocks/denies anything.
+  const rawUser = from.username ?? String(from.id)
+  const displayUser = safeResolvePersonName(
+    PERSON_DIRECTORY,
+    {
+      telegramId: String(from.id),
+      username: from.username,
+      isDm: isDmChatId(chat_id),
+      groupAllowFrom: access.groups[chat_id]?.allowFrom,
+    },
+    rawUser,
+  )
   const inboundMsg: InboundMessage = {
     type: 'inbound',
     chatId: chat_id,
     ...(messageThreadId != null ? { threadId: messageThreadId } : {}),
     messageId: msgId ?? 0,
-    user: from.username ?? String(from.id),
+    user: displayUser,
     userId: from.id,
     ts: ctx.message?.date ?? Math.floor(Date.now() / 1000),
     text: effectiveText,
@@ -16455,7 +16847,7 @@ async function handleInbound(
     meta: {
       chat_id,
       ...(msgId != null ? { message_id: String(msgId) } : {}),
-      user: from.username ?? String(from.id),
+      user: displayUser,
       user_id: String(from.id),
       ts: new Date((ctx.message?.date ?? 0) * 1000).toISOString(),
       ...(messageThreadId != null ? { message_thread_id: String(messageThreadId) } : {}),
@@ -16560,6 +16952,29 @@ async function handleInbound(
     return
   }
 
+  // DEFERRED_INBOUND_EMIT — drive the delivery state machine's `inbound`
+  // event HERE, not at handler entry. Every intercept/early-return above
+  // (permission-reply, /auth paste-back, interrupt-empty, secret-detect
+  // drop, drop/pair) has been passed, so any message reaching this point is
+  // a genuine turn the imperative code is about to deliver or buffer. That
+  // keeps the machine's authoritative turn-in-flight state in lockstep with
+  // the imperative delivery it models and can never be advanced into
+  // `bridge_alive_in_turn` by a message that never becomes a turn — the
+  // overlord /usage wedge of 2026-07-08 (see machineInTurnAtReceipt above).
+  // isSteering is now the real classification (computed at ~line 16289), so
+  // the machine correctly distinguishes a mid-turn steer (delivered, no new
+  // turn) from a fresh turn.
+  shadowEmit({
+    kind: 'inbound',
+    key: statusKey(chat_id, messageThreadId) as _ChatKey,
+    msg: {
+      msgId: msgId ?? 0,
+      isSteering,
+      payload: null,
+    },
+    at: Date.now(),
+  })
+
   // PR2 obligation-ledger OPEN — BEFORE the buffer-until-idle / deliver split so
   // a mid-turn cross-topic inbound (the 715 case) is tracked whether it is
   // buffered or delivered now. Idempotent + gated; no-op when the flag is off.
@@ -16569,21 +16984,32 @@ async function handleInbound(
     effectiveText,
   })
 
-  if (
-    decideInboundDelivery({
-      turnInFlight: turnInFlightAtReceipt,
-      isSteering,
-      // Interrupt-marker carve-out (2026-05-24): the `!`-prefixed body
-      // must bypass the "buffer-until-turn-complete" gate because the
-      // SIGINT'd turn often doesn't emit turn_complete, leaving the
-      // body stranded in pendingInboundBuffer indefinitely. The
-      // `interrupt` const is computed at the start of handleInbound
-      // (line ~7606) and remains in scope here. When the user fires
-      // `!`-with-body, this delivers the body as a fresh inbound to
-      // the freshly-killed bridge.
-      isInterrupt: interrupt.isInterrupt,
-    }) === 'buffer-until-idle'
-  ) {
+  // #2917: read the gate LIVE (not the receipt snapshot) on the default path
+  // so a sibling same-chat inbound delivered during THIS handler's async
+  // lead-in is observed here. Reading `claudeBusyKeys` live is self-block-safe:
+  // THIS inbound's own key is only added at delivery (below), never by the
+  // fresh-turn init bundle — so the live read never sees its own key. The
+  // delivery-machine cutover keeps its at-receipt machine snapshot (a live
+  // machine read WOULD self-block, since the inbound event already advanced
+  // the machine for this key). Kill switch (=0) restores the pure snapshot.
+  const gateTurnInFlight =
+    SERIALIZE_INBOUND_DELIVERY_ENABLED && machineInTurnAtReceipt == null
+      ? claudeBusyKeys.size > 0
+      : turnInFlightAtReceipt
+  const deliveryGate = reserveInboundDelivery({
+    turnInFlight: gateTurnInFlight,
+    isSteering,
+    // Interrupt-marker carve-out (2026-05-24): the `!`-prefixed body
+    // must bypass the "buffer-until-turn-complete" gate because the
+    // SIGINT'd turn often doesn't emit turn_complete, leaving the
+    // body stranded in pendingInboundBuffer indefinitely. The
+    // `interrupt` const is computed at the start of handleInbound
+    // (line ~7606) and remains in scope here. When the user fires
+    // `!`-with-body, this delivers the body as a fresh inbound to
+    // the freshly-killed bridge.
+    isInterrupt: interrupt.isInterrupt,
+  })
+  if (deliveryGate.decision === 'buffer-until-idle') {
     pendingInboundBuffer.push(selfAgent, inboundMsg)
     process.stderr.write(
       `telegram gateway: inbound held mid-turn agent=${selfAgent} ` +
@@ -16607,6 +17033,18 @@ async function handleInbound(
     return
   }
 
+  // #2917: reserve the chat's busy key SYNCHRONOUSLY here — before the
+  // composer-clear await below — so a concurrent same-chat inbound reaching
+  // the LIVE gate above observes this in-flight delivery and buffers behind it
+  // (per-chat FIFO). Without this, both handlers pass the gate during each
+  // other's async lead-in and race to the bridge, reordering the replies.
+  // Only fresh-turn deliveries reserve (steering/interrupt amend a running
+  // turn and must not). Released below if the send misses (bridge offline).
+  let reservedBusyKey: string | null = null
+  if (deliveryGate.reserve && SERIALIZE_INBOUND_DELIVERY_ENABLED && machineInTurnAtReceipt == null) {
+    reservedBusyKey = markClaudeBusyForInbound(inboundMsg)
+  }
+
   // Pre-send composer clear (the marko wedge). The inbound is about to be
   // delivered as an MCP `notifications/claude/channel` notification, which
   // the unmodified CLI appends into its composer and auto-submits ONLY when
@@ -16636,7 +17074,10 @@ async function handleInbound(
 
   const delivered = ipcServer.sendToAgent(selfAgent, inboundMsg)
   if (delivered) {
-    const busyKey = markClaudeBusyForInbound(inboundMsg)
+    // Reuse the key reserved synchronously above (#2917) when present, else
+    // mark now — markClaudeBusyForInbound is idempotent (lockstep re-stamp),
+    // so a re-mark is safe and returns the same chat key.
+    const busyKey = reservedBusyKey ?? markClaudeBusyForInbound(inboundMsg)
     // Track until claude acks via `enqueue` (the marko drop-wedge): if no ack
     // lands, the message stranded in the composer and the sweep re-delivers
     // it. Track ONLY messages that produce an `enqueue` to ack against —
@@ -16658,6 +17099,15 @@ async function handleInbound(
     }
   }
   if (!delivered) {
+    // #2917: the synchronous reservation assumed delivery; the send missed
+    // (bridge offline), so release it in lockstep — otherwise the orphaned
+    // busy key would gate every subsequent inbound into the buffer until the
+    // orphan reaper clears it. The message itself is buffered below, so FIFO
+    // is still preserved (it drains in order on the next bridge register).
+    if (reservedBusyKey != null) {
+      claudeBusyKeys.delete(reservedBusyKey)
+      claudeBusyKeySince.delete(reservedBusyKey)
+    }
     // Only persist fresh user turns to the durable spool. Steering / `!`
     // interrupt / empty bodies are mid-turn amendments or no-ops that would
     // arrive orphaned if replayed as a fresh turn after a restart — drop them
@@ -18223,7 +18673,7 @@ interface ModelDepsRestartContext {
 }
 
 function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & ModelCommandDeps {
-  return {
+  const deps: ModelMenuDeps & ModelCommandDeps = {
     discover: (a) => discoverModels(a),
     discoverSrModels: async () => {
       // /model/info lives on the ROOT proxy (model-mapped surface), NOT the
@@ -18329,7 +18779,25 @@ function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & M
         )
       }
     },
+    /**
+     * Session-only switch TO an sr-* (LiteLLM/OpenRouter) model. claude's
+     * native `/model` picker rejects unknown sr-* ids, so we can't inject.
+     * Write the token to the `.session-model-override` carrier file (start.sh
+     * consumes it on the next boot and launches `claude --model <token>`), set
+     * the in-memory session-model so /status stays honest across the restart
+     * window, then run the SAME restart dispatch as scheduleRestart above.
+     */
+    scheduleModelRelaunch: async (model: string, reason: string) => {
+      const agentDir = resolveAgentDirFromEnv()
+      if (!agentDir) throw new Error('agent dir unresolvable — cannot write session-model carrier')
+      // Carrier: single line, token + newline, no quoting (start.sh strips
+      // whitespace and shape-gates). One-shot — consumed on the next boot.
+      writeFileSync(join(agentDir, '.session-model-override'), `${model}\n`, 'utf8')
+      activeSessionModelOverride = model
+      await deps.scheduleRestart(reason)
+    },
   }
+  return deps
 }
 
 function modelMenuReplyMarkup(reply: ModelMenuReply): InlineKeyboard | undefined {
@@ -19804,25 +20272,21 @@ async function runQuotaWatch(opts: { bootTick?: boolean } = {}): Promise<void> {
     }
   } catch (err) {
     process.stderr.write(`telegram gateway: quota-watch: probe for crossing accounts failed: ${err}\n`)
-    if (!tuning.sendOnProbeFail) {
-      // A quota notification must never carry numbers we could not verify
-      // live. Leave the crossing accounts' state untouched — the
-      // transition re-evaluates (and re-probes) on the next 15-min tick.
-      // Persist any reconciles already applied, then bail.
-      if (reconciledCount > 0) {
-        try {
-          saveQuotaWatchState(stateDir, mutatedState)
-        } catch (saveErr) {
-          process.stderr.write(`telegram gateway: quota-watch state persist failed: ${saveErr}\n`)
-        }
+    // A quota notification must never carry numbers we could not verify
+    // live. Leave the crossing accounts' state untouched — the
+    // transition re-evaluates (and re-probes) on the next 15-min tick.
+    // Persist any reconciles already applied, then bail.
+    if (reconciledCount > 0) {
+      try {
+        saveQuotaWatchState(stateDir, mutatedState)
+      } catch (saveErr) {
+        process.stderr.write(`telegram gateway: quota-watch state persist failed: ${saveErr}\n`)
       }
-      process.stderr.write(
-        `telegram gateway: quota-watch: deferring ${pendingTransitions.length} notification(s) until probe succeeds\n`,
-      )
-      return
     }
-    // Legacy (SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL=1): fall through
-    // and send from cached data.
+    process.stderr.write(
+      `telegram gateway: quota-watch: deferring ${pendingTransitions.length} notification(s) until probe succeeds\n`,
+    )
+    return
   }
 
   // Build final notifications, enriching the snapshot with fresh probe
@@ -19872,7 +20336,7 @@ async function runQuotaWatch(opts: { bootTick?: boolean } = {}): Promise<void> {
         // State normalised by the time of the probe — don't notify.
         continue
       }
-    } else if (!tuning.sendOnProbeFail) {
+    } else {
       // No verified fresh data for this account (per-account probe failure
       // or label missing from the batch result). Same rule as the batch
       // throw above: never send unverified numbers. State untouched —
@@ -22554,7 +23018,15 @@ async function handleAuthDashboardCallback(ctx: Context): Promise<void> {
         tz,
         now: renderNow,
         demo: refreshDemo,
-        ...(staleCachedAtMs != null ? { staleCachedAtMs } : { liveProbedAtMs: renderNow.getTime() }),
+        // Honesty backstop (same as /usage): a TOTAL probe failure (zero
+        // result rows, nothing served from cache) renders an explicit
+        // "probe failed" marker instead of a false "Live" footer next to
+        // no-data rows.
+        ...(staleCachedAtMs != null
+          ? { staleCachedAtMs }
+          : probeResp.results.length > 0
+            ? { liveProbedAtMs: renderNow.getTime() }
+            : { probeFailed: true }),
       })
       const kbRows = buildSnapshotKeyboard(snapshots, { now: renderNow, demo: refreshDemo })
       const inline_keyboard = kbRows.map((row) =>
@@ -23020,21 +23492,49 @@ bot.command('usage', async ctx => {
         // flight; a TTL-hit or failed-probe fallback is tagged served:"cache",
         // which we surface as a "⚠ cached Nm ago" footer instead of a false
         // live stamp.
+        const renderNow = new Date()
         const probeResp = await client.probeQuota(state.accounts.map((a) => a.label)).catch(() => ({ results: [] }))
         const { quotas, staleCachedAtMs } = zipProbeResults(
           state.accounts.map((a) => a.label),
           probeResp.results,
         )
-        const { renderAuthSnapshotFormat2, buildSnapshotsFromState, buildSnapshotKeyboard } = await import(
+        const { buildSnapshotsFromState, buildSnapshotKeyboard } = await import(
           '../auth-snapshot-format.js'
         )
-        const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? 'UTC'
+        const { renderUsageCard } = await import('../quota-bar-format.js')
         const snapshots = buildSnapshotsFromState(state, quotas)
-        const text = renderAuthSnapshotFormat2(snapshots, {
-          tz,
-          now: new Date(),
+        // /usage renders the compact quota-bar block (at-a-glance headroom +
+        // pace tick per window) plus a two-line footer — the actionable
+        // cross-account recommendation verdict and the freshness marker (`⚠
+        // cached Nm ago` when the probe was served stale from cache, else
+        // `Live · refreshed Nm ago`). The old Format 2 table
+        // (renderAuthSnapshotFormat2) is no longer appended here (operator
+        // call, 2026-07-10): the two views were redundant and the table
+        // doubled the message length. Every per-window reset the table
+        // carried has an equivalent in the bar rows' `pct% / <time-left>`
+        // segment, just relative instead of absolute — no info lost; the
+        // recommendation + cached/live footer the table used to carry are
+        // preserved by renderUsageCard.
+        const exhaustedByLabel = new Map<string, boolean>(
+          state.accounts.map((a) => [a.label, a.exhausted]),
+        )
+        const text = renderUsageCard(snapshots, exhaustedByLabel, {
+          now: renderNow,
           demo,
-          ...(staleCachedAtMs != null ? { staleCachedAtMs } : { liveProbedAtMs: Date.now() }),
+          // #2495 Change 2 — a TTL-hit / failed-probe fallback is tagged
+          // served:"cache"; surface it as `⚠ cached Nm ago` instead of a
+          // false live stamp. Otherwise stamp the live refresh time.
+          // Honesty backstop: a TOTAL probe failure (the .catch above
+          // returned `{results: []}` and nothing was served from cache)
+          // must render an explicit "probe failed" marker, NOT a false
+          // "Live" stamp next to "⚠️ no data" rows. Without this the
+          // footer claimed "Live · refreshed 0s ago" while every account
+          // row said "no data — probe failed" (#2959 review finding).
+          ...(staleCachedAtMs != null
+            ? { staleCachedAtMs }
+            : probeResp.results.length > 0
+              ? { liveProbedAtMs: renderNow.getTime() }
+              : { probeFailed: true }),
         })
         // Preserve the Switch/Refresh/usage/Add inline keyboard on the
         // rich-message render — the table card carries the same actions the
@@ -23385,14 +23885,41 @@ bot.on('callback_query:data', async ctx => {
     // We track whether we applied the interim edit so we can skip the
     // toastOnly short-circuit if we did — a toastOnly return after the interim
     // edit would leave the menu stuck button-less.
-    let didInterimSrEdit = false
+    // sr-* TARGET tap: switch TO a non-Claude (LiteLLM/OpenRouter) model.
+    // Parity with the text `/model sr-*` path — claude's native picker rejects
+    // unknown sr-* ids, so an in-place inject can't set them. Carry the token
+    // across a graceful restart (the `.session-model-override` carrier) and
+    // relaunch `claude --model sr-*`. Session-only; reverts to the configured
+    // default on the next restart. The sr-* → Claude direction is handled below
+    // via the SELECT/alias outcome + isSrToClaudeTransition.
     if (data.startsWith(MODEL_CALLBACK_SR)) {
-      const srLabel = escapeHtmlForTg(srFriendlyLabel(data.slice(MODEL_CALLBACK_SR.length)))
+      const srName = data.slice(MODEL_CALLBACK_SR.length)
+      const srLabel = escapeHtmlForTg(srFriendlyLabel(srName))
+      if (!isValidModelArg(srName)) {
+        await ctx
+          .editMessageText(richMessage('❌ Invalid model name'), { reply_markup: { inline_keyboard: [] } })
+          .catch(() => {})
+        return
+      }
       await ctx
-        .editMessageText(richMessage(`⏳ Switching session to **${srLabel}**…`), { reply_markup: { inline_keyboard: [] } })
+        .editMessageText(
+          richMessage(`🔄 Switching session to **${srLabel}** — restarting (~30s). _Session-only; reverts to the configured default on the next restart._`),
+          { reply_markup: { inline_keyboard: [] } },
+        )
         .catch(() => {})
-      didInterimSrEdit = true
+      try {
+        await modelDeps.scheduleModelRelaunch(srName, `user: /model ${srName} (session-only relaunch, menu)`)
+      } catch (err) {
+        await ctx
+          .editMessageText(
+            richMessage(`❌ Could not switch to **${srLabel}**: ${escapeHtmlForTg((err as Error)?.message ?? String(err))}`),
+            { reply_markup: { inline_keyboard: [] } },
+          )
+          .catch(() => {})
+      }
+      return
     }
+    const didInterimSrEdit = false
     try {
       const prevSessionModel = activeSessionModelOverride
       const outcome = await handleModelMenuCallback(data, modelDeps)
@@ -26066,6 +26593,32 @@ void (async () => {
 
       if (!didOneTimeSetup) {
         didOneTimeSetup = true
+
+        // person_id name resolution (docs/configuration.md, resolve-person.ts):
+        // ONE-TIME boot validation, NOT periodic. `PERSON_DIRECTORY` is
+        // built exactly once, here, from the static in-memory `people.json`
+        // the scaffold projected from `switchroom.yaml`'s `users:` block —
+        // a config change requires an agent restart, this never re-reads.
+        // The orchestration (per-entry validation + dead-man's-switch) is
+        // in the pure, unit-tested `runPersonDirectoryBootCheck` — this
+        // block only performs the resulting I/O (stderr log + the EXISTING
+        // fleet-alert path at low/config severity, kind: 'config-warning',
+        // which must never page like a real outage).
+        {
+          const bootCheck = runPersonDirectoryBootCheck(readPeopleFile)
+          PERSON_DIRECTORY = bootCheck.directory
+          process.stderr.write(bootCheck.logLine + '\n')
+          if (bootCheck.alertDetail != null) {
+            emitGatewayOperatorEvent({
+              kind: 'config-warning',
+              agent: process.env.SWITCHROOM_AGENT_NAME ?? '-',
+              detail: bootCheck.alertDetail,
+              suggestedActions: [],
+              firstSeenAt: new Date(),
+            })
+          }
+        }
+
         void registerSwitchroomBotCommands().catch(() => {})
 
         // #613 fix: pre-warm the chatAvailableReactions cache for every
@@ -26376,6 +26929,73 @@ void (async () => {
           }
         } catch {}
 
+        // ─── Session-model re-hydration + LiteLLM-down alert (session relaunch) ───
+        //
+        // start.sh writes the EFFECTIVE launched model to `.active-session-model`
+        // on every boot (the model actually passed to `claude --model`). Re-hydrate
+        // the in-memory session-model override from it so `/status` and the welcome
+        // card stay honest after a session-relaunch restart. Only treat it as an
+        // override when it differs from the configured/default model — a plain boot
+        // on the configured model leaves the override null.
+        //
+        // Also consume the `.session-model-alert` sentinel: start.sh drops it when
+        // it had to DROP an sr-* override because LiteLLM was unreachable at boot
+        // (booting on the configured default instead of 4xx-ing against Anthropic).
+        // We turn it into a loud Telegram message to the operator, then delete it.
+        try {
+          const smAgentDir = resolveAgentDirFromEnv()
+          if (smAgentDir) {
+            const activePath = join(smAgentDir, '.active-session-model')
+            if (existsSync(activePath)) {
+              try {
+                const launched = readFileSync(activePath, 'utf8').trim()
+                const configured = (() => {
+                  type AgentListResp = { agents: Array<{ name: string; model?: string | null }> }
+                  const d = switchroomExecJson<AgentListResp>(['agent', 'list'])
+                  const raw = d?.agents?.find(a => a.name === getMyAgentName())?.model ?? null
+                  // Resolve through the SAME resolver start.sh's scaffold uses, so an
+                  // unset (`null`) or `model: "default"` config value maps to the
+                  // switchroom default model id — matching the EFFECTIVE model start.sh
+                  // wrote to `.active-session-model`. Comparing the raw (unresolved)
+                  // value would flag every ordinary restart of a default-model agent as
+                  // a phantom session override.
+                  return resolveMainModel(raw ?? undefined)
+                })()
+                activeSessionModelOverride =
+                  launched.length > 0 && launched !== configured ? launched : null
+              } catch { /* leave override as-is on a bad read */ }
+            }
+
+            const alertPath = join(smAgentDir, '.session-model-alert')
+            if (existsSync(alertPath)) {
+              let alertText: string | null = null
+              try {
+                alertText = readFileSync(alertPath, 'utf8').trim()
+              } catch { alertText = null }
+              try { unlinkSync(alertPath) } catch { /* best-effort */ }
+              if (alertText && alertText.length > 0) {
+                // Notify EVERY operator, not just allowFrom[0]. Each send is wrapped
+                // in its own catch so one operator's failure (blocked bot, bad chat
+                // id) never stops the rest, and the outer boot flow never crashes.
+                const operators = loadAccess().allowFrom
+                for (const operator of operators) {
+                  if (!operator) continue
+                  void lockedBot.api
+                    .sendMessage(operator, `⚠️ ${alertText}`)
+                    .catch((err: unknown) =>
+                      process.stderr.write(
+                        `telegram gateway: session-model alert send failed for ${operator}: ${(err as Error)?.message ?? String(err)}\n`,
+                      ),
+                    )
+                }
+                process.stderr.write(`telegram gateway: session-model: LiteLLM-down override drop — ${alertText}\n`)
+              }
+            }
+          }
+        } catch (err) {
+          process.stderr.write(`telegram gateway: session-model re-hydration failed: ${(err as Error)?.message ?? String(err)}\n`)
+        }
+
         // Credit-exhaustion watcher (#348). Reads `<agentDir>/.claude/.claude.json`
         // for `cachedExtraUsageDisabledReason`. Fires a Telegram notification
         // on transition into / out of fatal billing states (out_of_credits,
@@ -26593,6 +27213,20 @@ void (async () => {
                 ownedWorktreeCwds({
                   self: process.env.SWITCHROOM_AGENT_NAME,
                   listRecords: listWorktreeRecords,
+                  // Durable, non-env identity fallback (#1116 / #2893): when
+                  // SWITCHROOM_AGENT_NAME is somehow unset, derive this
+                  // agent's own identity from its own directory so worktree
+                  // ownership still resolves (env is only the fast path).
+                  // `watcherAgentDir` is guaranteed non-null in this branch
+                  // (the whole watcher is gated on it above). Kill-switch
+                  // SWITCHROOM_WORKTREE_IDENTITY_FALLBACK=0 restores the
+                  // pre-fix env-only behaviour.
+                  agentDir:
+                    process.env.SWITCHROOM_WORKTREE_IDENTITY_FALLBACK === '0'
+                      ? undefined
+                      : watcherAgentDir,
+                  log: (msg) =>
+                    process.stderr.write(`telegram gateway: ${msg}\n`),
                 }),
               // Bug 0 fix: previously omitted, leaving the watcher unable to
               // write liveness/stall/turn_end updates to the registry DB.
@@ -26939,8 +27573,8 @@ void (async () => {
                     orphanStatusEnabled,
                   })
                   if (surface === 'worker-feed') {
-                    const origin = resolveSubagentOriginChat(agentId)
-                    const wkChat = origin?.chatId || fleetChatId || (loadAccess().allowFrom[0] ?? '')
+                    const wk = resolveWorkerFeedChat(agentId, fleetChatId)
+                    const wkChat = wk.chatId
                     void workerActivityFeed?.update(
                       agentId,
                       wkChat,
@@ -26952,7 +27586,7 @@ void (async () => {
                         elapsedMs,
                         state: 'running',
                       },
-                      origin?.threadId,
+                      wk.threadId,
                     )?.then(() => reconcileWorkerPin(agentId, wkChat, true))
                     return
                   }
@@ -27077,8 +27711,8 @@ void (async () => {
                 // resolved (the pinned-card fleet that used to carry the chat
                 // is gone — see resolveSubagentOriginChat).
                 if (workerFeedEnabled) {
-                  const origin = resolveSubagentOriginChat(agentId)
-                  const wkChat = origin?.chatId || fleetChatId || (loadAccess().allowFrom[0] ?? '')
+                  const wk = resolveWorkerFeedChat(agentId, fleetChatId)
+                  const wkChat = wk.chatId
                   void workerActivityFeed?.update(
                     agentId,
                     wkChat,
@@ -27093,7 +27727,7 @@ void (async () => {
                       elapsedMs,
                       state: 'running',
                     },
-                    origin?.threadId,
+                    wk.threadId,
                   )?.then(() => reconcileWorkerPin(agentId, wkChat, true))
                   return
                 }