switchroom 0.18.3 → 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.
@@ -721,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.
@@ -1224,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()
@@ -1488,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()
@@ -4070,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`,
     );
   }
 }
@@ -12896,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
@@ -13246,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
     }
@@ -13272,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`)
     }
   })
 }
@@ -16650,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,
@@ -16670,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) } : {}),
@@ -22841,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) =>
@@ -23307,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
@@ -26380,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
@@ -27334,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,
@@ -27347,7 +27586,7 @@ void (async () => {
                         elapsedMs,
                         state: 'running',
                       },
-                      origin?.threadId,
+                      wk.threadId,
                     )?.then(() => reconcileWorkerPin(agentId, wkChat, true))
                     return
                   }
@@ -27472,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,
@@ -27488,7 +27727,7 @@ void (async () => {
                       elapsedMs,
                       state: 'running',
                     },
-                    origin?.threadId,
+                    wk.threadId,
                   )?.then(() => reconcileWorkerPin(agentId, wkChat, true))
                   return
                 }