switchroom 0.18.3 → 0.18.7

package/telegram-plugin/gateway/pending-card-expiry.ts

@@ -0,0 +1,98 @@
+/**
+ * Pure, injectable core for expiring an agent-initiated approval card
+ * (vault_request_access / vault_request_save / request_secret /
+ * mental_model_propose) whose TTL elapsed with no operator tap.
+ *
+ * Extracted from gateway.ts so the ORDERING and FAULT-ISOLATION contract is
+ * unit-testable behaviorally (pending-card-expiry.test.ts), not just pinned by
+ * source-text regex:
+ *
+ *   1. remove() FIRST — the in-memory map entry + durable store record are
+ *      dropped before anything else, so the expiry is single-shot: a second
+ *      reaper tick (or a concurrent lazy sweep) can never double-fire the
+ *      synthetic wake for the same card.
+ *   2. editCard() — best-effort ⌛ card strip; a Telegram failure never blocks
+ *      the wake.
+ *   3. recordMiss() — the missed-approvals re-offer entry is written BEFORE
+ *      the deliver attempt, so a throwing IPC socket can't lose the re-offer:
+ *      even if the wake never lands, the operator's return re-surfaces it.
+ *   4. deliver() — the timeout synthetic, wrapped in try/catch. A half-dead
+ *      client socket that throws on write is contained here: the error is
+ *      logged, `delivered: false` is returned, and the caller's sweep loop
+ *      continues to the remaining entries/families.
+ *
+ * Every step is individually guarded — one failing dependency never skips the
+ * later steps or escapes to the caller (the reaper's setInterval callback,
+ * where an escaped throw would take the whole gateway down via
+ * uncaughtException).
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+export interface ExpireCardDeps {
+  /** Drop the in-memory map entry AND the durable store record. Runs first. */
+  remove: () => void
+  /** Best-effort ⌛ card edit (strip keyboard). Failures are swallowed. */
+  editCard: () => void
+  /** Build the timeout synthetic inbound for this card's family. */
+  buildInbound: () => InboundMessage
+  /** Inject the synthetic (turn-safe gate). May throw on a dead socket. */
+  deliver: (inbound: InboundMessage) => boolean
+  /** Record the missed-approvals re-offer entry. Runs BEFORE deliver. */
+  recordMiss: () => void
+  /** Error sink (stderr in production). */
+  log: (msg: string) => void
+}
+
+export interface ExpireCardResult {
+  delivered: boolean
+}
+
+export function expirePendingCard(deps: ExpireCardDeps): ExpireCardResult {
+  // 1. Single-shot: entry gone before any fallible side effect.
+  deps.remove()
+  // 2. Card strip is cosmetic — never let it block the wake.
+  try {
+    deps.editCard()
+  } catch (err) {
+    deps.log(`card-expiry: card edit failed: ${(err as Error).message}`)
+  }
+  // 3. Re-offer entry BEFORE the deliver attempt so a throwing deliver can't
+  //    lose it (the operator's return still re-surfaces the missed card).
+  try {
+    deps.recordMiss()
+  } catch (err) {
+    deps.log(`card-expiry: missed-approval record failed: ${(err as Error).message}`)
+  }
+  // 4. The wake itself — contained so one dead socket doesn't skip the
+  //    remaining entries in the caller's sweep loop.
+  let delivered = false
+  try {
+    delivered = deps.deliver(deps.buildInbound())
+  } catch (err) {
+    deps.log(`card-expiry: timeout synthetic delivery failed: ${(err as Error).message}`)
+  }
+  return { delivered }
+}
+
+/**
+ * Sweep one pending-card map: expire every entry past its TTL via `expire`,
+ * guarding each entry so one throwing expiry can't skip the rest of the map
+ * (or, at the caller, the remaining families).
+ */
+export function sweepExpiredEntries<T>(
+  map: Map<string, T>,
+  isExpired: (value: T, now: number) => boolean,
+  expire: (stageId: string, value: T, now: number) => void,
+  now: number,
+  log: (msg: string) => void,
+): void {
+  for (const [k, v] of map) {
+    if (!isExpired(v, now)) continue
+    try {
+      expire(k, v, now)
+    } catch (err) {
+      log(`card-expiry: expire threw for stage=${k}: ${(err as Error).message}`)
+    }
+  }
+}

package/telegram-plugin/gateway/pending-card-store.ts

@@ -0,0 +1,173 @@
+/**
+ * Persistence store for in-flight AGENT-INITIATED approval cards that park
+ * the requesting agent until the operator taps: `vault_request_access`,
+ * `vault_request_save`, `request_secret`, and `mental_model_propose`.
+ *
+ * Problem (mirror of the permission-card `permission-card-store.ts` bug): the
+ * gateway holds each staged request in an in-memory Map only
+ * (`pendingVaultRequestAccesses`, `pendingVaultRequestSaves`,
+ * `pendingSecretRequests`, `pendingMentalModelProposes`). When the gateway
+ * restarts (crash OR container restart), every entry is lost. The card in
+ * Telegram keeps its live inline keyboard, so when the operator taps it later
+ * they hit the "Card expired — ask the agent to re-request" tombstone: no
+ * grant, no injected inbound, and the agent that ended its turn to WAIT on the
+ * card stays parked forever.
+ *
+ * Fix: persist the METADATA for every posted card to a JSON file in STATE_DIR.
+ * On each resolution (tap / TTL-expire) remove the entry. On gateway boot,
+ * restore surviving entries into the in-memory maps so a post-restart tap on a
+ * still-valid (unexpired) card works exactly like a pre-restart tap.
+ *
+ * SECRETS HYGIENE — LOAD-BEARING: this file is written to disk unencrypted.
+ * It MUST NOT carry any secret VALUE. `vault_request_save` stages a secret
+ * value in gateway memory; only its key/metadata is persisted here (never the
+ * value), so a restored save card is re-associated with a tap but cannot
+ * complete the write — the caller degrades gracefully (tells the agent the
+ * value was lost to a restart). `request_secret` never holds a value at
+ * staging time (the value arrives after the tap), so its metadata is safe to
+ * persist. The "no value field" invariant is enforced by the record types
+ * below (PersistedVaultSaveCard has no `value` member, so a callsite can't
+ * compile one in) and pinned by the on-disk sentinel test in
+ * pending-card-store.test.ts.
+ *
+ * File format: JSON array of PersistedApprovalCard objects. Written
+ * synchronously (mode 0o600) to avoid interleaving on concurrent card posts;
+ * production rate is a handful of cards, so the file stays tiny.
+ */
+
+import { readFileSync, writeFileSync, unlinkSync, chmodSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** The four agent-initiated approval-card families we persist. */
+export type ApprovalCardFamily =
+  | 'vault_request_access'
+  | 'vault_request_save'
+  | 'request_secret'
+  | 'mental_model_propose'
+
+interface BasePersistedCard {
+  family: ApprovalCardFamily
+  /** The staging id embedded in the card's callback_data (dedup + re-associate). */
+  stageId: string
+  /** Agent that requested (process.env.SWITCHROOM_AGENT_NAME). */
+  agent: string
+  /** Chat the card was rendered into; edited on tap / expiry. */
+  chatId: string
+  /** Card message id (filled after the card is sent). */
+  cardMessageId?: number
+  /** Forum topic the agent was working in, if any. */
+  threadId?: number
+  /** Unix-ms staging timestamp — the TTL clock. Preserved across restart. */
+  stagedAt: number
+}
+
+export interface PersistedVaultAccessCard extends BasePersistedCard {
+  family: 'vault_request_access'
+  key: string
+  scope: 'read' | 'write'
+  reason?: string
+  ttlSeconds: number
+}
+
+export interface PersistedVaultSaveCard extends BasePersistedCard {
+  family: 'vault_request_save'
+  key: string
+  kind: 'string' | 'binary'
+  why?: string
+  // NOTE: NO `value` — the staged secret never touches disk.
+}
+
+export interface PersistedSecretRequestCard extends BasePersistedCard {
+  family: 'request_secret'
+  key: string
+  reason?: string
+}
+
+export interface PersistedMentalModelCard extends BasePersistedCard {
+  family: 'mental_model_propose'
+  spec: {
+    name: string
+    source_query: string
+    refresh_after_consolidation?: boolean
+    max_tokens?: number
+  }
+  reason?: string
+}
+
+export type PersistedApprovalCard =
+  | PersistedVaultAccessCard
+  | PersistedVaultSaveCard
+  | PersistedSecretRequestCard
+  | PersistedMentalModelCard
+
+export interface PendingCardStore {
+  /** Record a newly-posted card. Idempotent on stageId (replaces in place). */
+  add(entry: PersistedApprovalCard): void
+  /** Remove the entry for this stageId (resolved — tap or TTL). */
+  remove(stageId: string): void
+  /** All persisted entries (for boot-time restore). */
+  loadAll(): PersistedApprovalCard[]
+  /** Delete the backing file entirely. */
+  clear(): void
+}
+
+export function createPendingCardStore(stateDir: string): PendingCardStore {
+  const filePath = join(stateDir, 'pending-approval-cards.json')
+
+  function read(): PersistedApprovalCard[] {
+    try {
+      const raw = readFileSync(filePath, 'utf-8')
+      const parsed = JSON.parse(raw)
+      return Array.isArray(parsed) ? (parsed as PersistedApprovalCard[]) : []
+    } catch {
+      return []
+    }
+  }
+
+  function write(entries: PersistedApprovalCard[]): void {
+    try {
+      writeFileSync(filePath, JSON.stringify(entries), { encoding: 'utf-8', mode: 0o600 })
+      // `mode` only applies when writeFileSync CREATES the file; an existing
+      // file keeps its prior perms. Re-assert 0600 on every write so the file
+      // can never stay laxer than intended.
+      chmodSync(filePath, 0o600)
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: pending-card-store write failed: ${(err as Error).message}\n`,
+      )
+    }
+  }
+
+  return {
+    add(entry) {
+      const entries = read()
+      const idx = entries.findIndex(e => e.stageId === entry.stageId)
+      if (idx >= 0) {
+        entries[idx] = entry
+      } else {
+        entries.push(entry)
+      }
+      write(entries)
+    },
+
+    remove(stageId) {
+      const entries = read()
+      const filtered = entries.filter(e => e.stageId !== stageId)
+      if (filtered.length !== entries.length) {
+        write(filtered)
+      }
+    },
+
+    loadAll() {
+      return read()
+    },
+
+    clear() {
+      try {
+        unlinkSync(filePath)
+      } catch {
+        // File may not exist — that's fine.
+      }
+    },
+  }
+}

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -150,9 +150,19 @@ export function redeliverBufferedInbound(
  *  approvals, subagent handbacks, warmup, reaction triggers) all tag a
  *  `meta.source`; the user-message inbound built in gateway.ts sets none.
  *  Restricting to source-less inbounds keeps merge-on-drain away from the
- *  #1150 wake-up class entirely. */
+ *  #1150 wake-up class entirely.
+ *
+ *  Button taps (#271, `meta.button_callback`) are ALSO excluded even though
+ *  they carry no `meta.source`: `mergeRun` keeps only the anchor (last)
+ *  message's meta, so a tap merged with an adjacent buffered user text would
+ *  silently drop its `button_callback_data`/`button_text` whenever the text
+ *  is last — the agent would see the `[user tapped button: …]` line without
+ *  the machine-readable payload. Taps deliver individually. */
 function isMergeableUserInbound(msg: InboundMessage): boolean {
-  return msg.type === 'inbound' && (msg.meta == null || msg.meta.source == null)
+  return (
+    msg.type === 'inbound' &&
+    (msg.meta == null || (msg.meta.source == null && msg.meta.button_callback == null))
+  )
 }
 
 function inboundHasMedia(msg: InboundMessage): boolean {

package/telegram-plugin/gateway/resolve-person.ts

@@ -0,0 +1,304 @@
+/**
+ * Boot-time-only, chat-scoped resolution of a raw Telegram id/username into
+ * a human `person_id` (e.g. "Lisa") for display in the `<channel>` tag's
+ * `user` attribute.
+ *
+ * Design (converged after adversarial review — see the PR description for
+ * the tradeoffs, do not re-litigate here):
+ *
+ *   - No MCP tool. Not callable by agents — display-only, gateway-internal.
+ *   - No hot-reload. `PersonDirectory` is built ONCE at gateway boot from
+ *     the static in-memory `people.json` the scaffold projected from
+ *     `switchroom.yaml`'s `users:` block. A config change requires an agent
+ *     restart to take effect — this file never re-reads anything.
+ *   - `access.json` (the fail-CLOSED allow-list) is a completely separate
+ *     concern and is never touched here. This feature is fail-OPEN: an
+ *     unresolved id/username falls back to today's behavior (the caller
+ *     keeps using the raw id/username) — it never blocks or denies
+ *     anything.
+ *   - Chat-scoped: a resolved name is only ever returned for a chat/group
+ *     the person is actually a member of. In a DM the chat IS the sender,
+ *     so resolution always applies. In a group, resolution only applies if
+ *     the sender's id or username is explicitly present in that group's
+ *     `allowFrom` (read from the EXISTING `access.json`/`loadAccess()`
+ *     data — no new membership source). An empty/unset group `allowFrom`
+ *     means membership can't be positively confirmed, so we conservatively
+ *     do NOT resolve (the raw id/username is shown instead) — a name safe
+ *     in a 1:1 DM could be a bigger leak in a shared group.
+ *   - Per-entry validation: a malformed `users:` entry (duplicate
+ *     `person_id` claimed by two different keys, empty/invalid
+ *     `person_id`, no `telegram_ids`) drops ONLY that one entry — it never
+ *     blanks resolution for the whole fleet. `buildPersonDirectory` never
+ *     throws; every failure mode is reported via its `dropped` return
+ *     value instead, so the caller can route it through the existing
+ *     fleet-alert path (`emitGatewayOperatorEvent` in gateway.ts) at
+ *     low/config severity — this must never page like a real outage.
+ *
+ * Fix note (accepted soft mitigation — see docs/configuration.md): there is
+ * no automated enforcement that a configured `person_id` stays safe to show
+ * if a group's membership changes AFTER the entry is written. This is an
+ * operator-discipline convention, not a closed gap. Low severity today —
+ * only two `person_id`s are configured fleet-wide.
+ */
+
+export interface RawPersonEntry {
+  /** The `users:` map key (e.g. "lisa") — carried through for alert text. */
+  key: string
+  person_id: string
+  telegram_ids: string[]
+}
+
+export interface PersonDirectoryEntry {
+  key: string
+  personId: string
+  /** Normalized (lowercased, no leading "@") telegram ids/usernames. */
+  telegramKeys: string[]
+}
+
+export interface PersonDirectory {
+  /** normalized telegram id/username -> directory entry */
+  byTelegramKey: Record<string, PersonDirectoryEntry>
+}
+
+export interface DroppedPersonEntry {
+  key: string
+  reason: string
+  /**
+   * Name-scrubbed reason CLASS — the same rejection without the embedded
+   * `person_id` human-name value or the colliding telegram id. Used to
+   * build the broadcast `alertDetail` so a config-warning card (which
+   * `emitGatewayOperatorEvent` sends to EVERY `allowFrom` chat, including
+   * group chats where the named person may NOT be a member) never surfaces
+   * a human name that the display path (`resolvePersonName`) deliberately
+   * chat-scopes. The verbose `reason` is still carried for the operator's
+   * own stderr `logLine` (private, not broadcast).
+   */
+  reasonClass: string
+}
+
+export interface BuildPersonDirectoryResult {
+  directory: PersonDirectory
+  dropped: DroppedPersonEntry[]
+}
+
+/** Normalize a telegram id or @username for keying: trim, strip a leading
+ * "@", lowercase (Telegram usernames are case-insensitive). */
+function normalizeTelegramKey(raw: string): string {
+  return raw.trim().replace(/^@/, '').toLowerCase()
+}
+
+/**
+ * Validate and dedupe raw `users:` `person_id` entries into a lookup
+ * directory. Never throws — every rejection is reported via `dropped`
+ * instead, per the fail-open / drop-only-that-entry design.
+ *
+ * Drop reasons:
+ *   - missing/blank `key` or `person_id`
+ *   - `telegram_ids` missing or empty (nothing to key the entry by)
+ *   - `person_id` already claimed by an earlier (different) entry key —
+ *     first-declared entry wins, the later duplicate is dropped whole
+ *     (not just the colliding id) so the alert is unambiguous about which
+ *     entry lost
+ *   - a `telegram_id`/username already claimed by an earlier (different)
+ *     entry key — same first-declared-wins convention: the later duplicate
+ *     is dropped whole so the alert is unambiguous about which entry lost
+ *     and we never silently last-write-wins a numeric id into the wrong
+ *     person's name
+ */
+export function buildPersonDirectory(entries: readonly RawPersonEntry[]): BuildPersonDirectoryResult {
+  const byTelegramKey: Record<string, PersonDirectoryEntry> = {}
+  const dropped: DroppedPersonEntry[] = []
+  const personIdOwner = new Map<string, string>() // person_id (lowercased) -> owning entry key
+  const telegramKeyOwner = new Map<string, string>() // normalized telegram id/username -> owning entry key
+
+  for (const raw of entries) {
+    const key = typeof raw.key === 'string' ? raw.key.trim() : ''
+    const personId = typeof raw.person_id === 'string' ? raw.person_id.trim() : ''
+
+    if (key.length === 0) {
+      dropped.push({ key: raw.key || '(unknown)', reason: 'missing users: map key', reasonClass: 'missing users: map key' })
+      continue
+    }
+    if (personId.length === 0) {
+      dropped.push({ key, reason: 'empty or missing person_id', reasonClass: 'empty or missing person_id' })
+      continue
+    }
+    if (!Array.isArray(raw.telegram_ids) || raw.telegram_ids.length === 0) {
+      dropped.push({ key, reason: 'no telegram_ids to resolve against', reasonClass: 'no telegram_ids to resolve against' })
+      continue
+    }
+
+    const personIdLower = personId.toLowerCase()
+    const existingOwner = personIdOwner.get(personIdLower)
+    if (existingOwner != null && existingOwner !== key) {
+      dropped.push({
+        key,
+        // Verbose reason (stderr logLine only — private to the operator):
+        // names the person_id value + the owning config key.
+        reason: `duplicate person_id "${personId}" already claimed by users.${existingOwner}`,
+        // reasonClass (broadcast alertDetail): scrubs the human-name
+        // person_id value; keeps the entry key + collision class. A
+        // config-warning card fans out to every allowFrom chat, so the
+        // name must not travel further than the display path allows.
+        reasonClass: `duplicate person_id already claimed by users.${existingOwner}`,
+      })
+      continue
+    }
+    personIdOwner.set(personIdLower, key)
+
+    const telegramKeys = [...new Set(raw.telegram_ids.map(normalizeTelegramKey).filter((k) => k.length > 0))]
+    if (telegramKeys.length === 0) {
+      dropped.push({ key, reason: 'telegram_ids contained no usable id/username', reasonClass: 'telegram_ids contained no usable id/username' })
+      personIdOwner.delete(personIdLower)
+      continue
+    }
+
+    const collidingTelegramKey = telegramKeys.find((tk) => {
+      const existingTkOwner = telegramKeyOwner.get(tk)
+      return existingTkOwner != null && existingTkOwner !== key
+    })
+    if (collidingTelegramKey != null) {
+      const existingTkOwner = telegramKeyOwner.get(collidingTelegramKey)
+      dropped.push({
+        key,
+        reason: `duplicate telegram_id "${collidingTelegramKey}" already claimed by users.${existingTkOwner}`,
+        // Scrub the colliding telegram id/username from the broadcast
+        // reason; keep the owning config key (operator-chosen slug).
+        reasonClass: `duplicate telegram_id already claimed by users.${existingTkOwner}`,
+      })
+      personIdOwner.delete(personIdLower)
+      continue
+    }
+
+    const entry: PersonDirectoryEntry = { key, personId, telegramKeys }
+    for (const tk of telegramKeys) {
+      telegramKeyOwner.set(tk, key)
+      byTelegramKey[tk] = entry
+    }
+  }
+
+  return { directory: { byTelegramKey }, dropped }
+}
+
+export interface PersonDirectoryBootResult {
+  directory: PersonDirectory
+  /** Non-null when the caller should route an alert through the fleet
+   * alert path (`emitGatewayOperatorEvent`, kind: 'config-warning'). */
+  alertDetail: string | null
+  /** Always present — one human-readable line for stderr. */
+  logLine: string
+}
+
+/**
+ * Orchestrate the ONE-TIME boot-time check (requirement: boot-time-only,
+ * NOT periodic — call this exactly once, at gateway boot, never on a
+ * timer/interval). Extracted as a pure(ish) function — taking the file
+ * read as an injected dependency and RETURNING what to log/alert rather
+ * than performing the I/O itself — so it's unit-testable without booting
+ * the real gateway process.
+ *
+ * Dead-man's-switch: wraps the whole check in try/catch. If anything
+ * throws before completing (including `readEntries` itself), that failure
+ * is ALSO surfaced via `alertDetail` — mirrors a past incident where
+ * `access.json` validation failed silently in the wrong (fail-open)
+ * direction, undetected for hours. `PERSON_DIRECTORY` falls back to an
+ * empty directory on crash (fail-open: raw ids/usernames keep showing).
+ */
+export function runPersonDirectoryBootCheck(readEntries: () => RawPersonEntry[]): PersonDirectoryBootResult {
+  try {
+    const rawEntries = readEntries()
+    const { directory, dropped } = buildPersonDirectory(rawEntries)
+
+    if (dropped.length > 0) {
+      // Broadcast-safe summary for `alertDetail` (fans out to EVERY
+      // allowFrom chat via emitGatewayOperatorEvent, including group chats
+      // where the named person may not be a member): built from
+      // `reasonClass`, which scrubs the embedded person_id human-name
+      // value and the colliding telegram id. The verbose `reason`
+      // (names the values) is kept for the operator's own stderr
+      // `logLine` — private, never broadcast.
+      const alertSummary = dropped.map((d) => `${d.key} (${d.reasonClass})`).join('; ')
+      const logSummary = dropped.map((d) => `${d.key} (${d.reason})`).join('; ')
+      const plural = dropped.length === 1 ? 'y' : 'ies'
+      return {
+        directory,
+        alertDetail: `person_id: dropped ${dropped.length} malformed users: entr${plural} at boot — ${alertSummary}`,
+        logLine: `telegram gateway: person_id boot validation dropped ${dropped.length} entr${plural}: ${logSummary}`,
+      }
+    }
+
+    return {
+      directory,
+      alertDetail: null,
+      logLine: rawEntries.length > 0
+        ? `telegram gateway: person_id boot validation ok — ${Object.keys(directory.byTelegramKey).length} telegram id/username(s) resolved`
+        : `telegram gateway: person_id boot validation ok — no person_id entries configured`,
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return {
+      directory: { byTelegramKey: {} },
+      // Crash alertDetail scrubs the raw error message too — it can
+      // carry a filesystem path or other host detail that shouldn't fan
+      // out to every allowFrom chat. The full message stays in logLine.
+      alertDetail: `person_id boot validation crashed — name resolution disabled this boot (fail-open, raw ids/usernames will show); see gateway stderr for detail`,
+      logLine: `telegram gateway: person_id boot validation CRASHED (name resolution disabled this boot, raw ids will show — fail-open): ${msg}`,
+    }
+  }
+}
+
+export interface ResolvePersonOptions {
+  telegramId: string
+  username?: string | undefined
+  isDm: boolean
+  /** That chat's/group's configured allowFrom, if any (from access.json). */
+  groupAllowFrom?: readonly string[] | undefined
+}
+
+/**
+ * Resolve a sender's display name for THIS chat, chat-scoped per the
+ * module doc above. Returns undefined (fall back to raw id/username) when
+ * unresolved OR when membership in a group chat can't be positively
+ * confirmed.
+ */
+export function resolvePersonName(directory: PersonDirectory, opts: ResolvePersonOptions): string | undefined {
+  const idKey = normalizeTelegramKey(opts.telegramId)
+  const usernameKey = opts.username ? normalizeTelegramKey(opts.username) : undefined
+
+  const entry = directory.byTelegramKey[idKey] ?? (usernameKey ? directory.byTelegramKey[usernameKey] : undefined)
+  if (!entry) return undefined
+
+  // DM: the chat IS the sender, so resolution always applies.
+  if (opts.isDm) return entry.personId
+
+  // Group: only resolve if the sender is explicitly present in that
+  // chat's allowFrom (the existing membership source) — conservative
+  // fallback (undefined) otherwise, since we can't positively confirm
+  // membership from an empty/unset list.
+  const allowFrom = opts.groupAllowFrom ?? []
+  const allowFromNormalized = allowFrom.map(normalizeTelegramKey)
+  const memberConfirmed =
+    allowFromNormalized.includes(idKey) || (usernameKey != null && allowFromNormalized.includes(usernameKey))
+  return memberConfirmed ? entry.personId : undefined
+}
+
+/**
+ * Fail-open call-site wrapper around `resolvePersonName`, for use at the
+ * `handleInbound` call site (gateway.ts). This feature's whole design
+ * point is "never blocks or denies anything" (module doc above) — a throw
+ * from resolution must fall back to the raw id/username, not abort message
+ * handling. Mirrors the same defensive pattern already used for
+ * `readPeopleFile` (gateway.ts) and `runPersonDirectoryBootCheck` (this
+ * file): catch, fall back, never propagate.
+ */
+export function safeResolvePersonName(
+  directory: PersonDirectory,
+  opts: ResolvePersonOptions,
+  rawFallback: string,
+): string {
+  try {
+    return resolvePersonName(directory, opts) ?? rawFallback
+  } catch {
+    return rawFallback
+  }
+}