switchroom 0.19.1 → 0.19.3

package/telegram-plugin/gateway/gateway.ts

@@ -42,6 +42,7 @@ import {
   resolveSafeBoundaryEnabled,
 } from './interrupt-defer.js'
 import { parseStopKeyword, buildStopReply } from './stop-command.js'
+import { shouldMaskUsageLabels } from './usage-mask.js'
 import { shouldPostBusyAck, formatBusyAckText, BUSY_ACK_STEP_AGE_THRESHOLD_MS } from './busy-ack.js'
 import {
   resolveStickerSendArgs,
@@ -365,10 +366,10 @@ import { createFleetFallbackResumeGate } from '../fleet-fallback-resume.js'
 import { resolveExhaustUntil } from './exhaust-until.js'
 import {
   pendingAuthAddFlows,
-  startAccountAuthSession,
   submitAccountAuthCode,
   cancelAccountAuthSession,
   cleanScratchDir as cleanAuthAddScratchDir,
+  handleAuthAddOrCancel,
 } from './auth-add-flow.js'
 import {
   pendingLoopbackFlows,
@@ -482,6 +483,7 @@ import {
 } from '../turn-flush-safety.js'
 import {
   resolveReplyOwnerTurnId,
+  type AnswerDeliveredLatch,
 } from '../reply-owner-resolve.js'
 // PR A — deterministic answer-ready quiescence flush (late-delivery fix).
 import {
@@ -537,6 +539,11 @@ import {
   modelCommandReceiptLine,
   handleModelCommand,
   classifyModelSwitchConfirmation,
+  formatModelRelaunchDiagLog,
+  servedModelMatchesRequested,
+  buildServedModelDivergenceHandler,
+  deliverModelSwitchBootNotice,
+  type ModelBootCardDeps,
   buildModelMenu,
   handleModelMenuCallback,
   isValidModelArg,
@@ -651,6 +658,7 @@ import {
   mutateStatusPinRow,
   reconcileAndPersistStatusPin,
   runStatusPinBootCleanup,
+  withPinReconcileLock,
   type PersistedStatusPin,
   type StatusPinPersistOp,
 } from './status-pin-store.js'
@@ -877,7 +885,7 @@ import {
   decideAnnouncementDelivery,
   foldAnnouncementIntoCard,
 } from '../fallback-card-collapse.js'
-import { buildSnapshotsFromState, buildSnapshotsFromCachedState, zipProbeResults } from '../auth-snapshot-format.js'
+import { buildSnapshotsFromState, buildSnapshotsFromCachedState, zipProbeResults, deriveUsageFooterFreshness } from '../auth-snapshot-format.js'
 import { maskUsername } from '../demo-mask.js'
 import {
   writeTurnActiveMarker,
@@ -3407,18 +3415,33 @@ export type CurrentTurn = {
   // false ONLY at turn start, mirroring `activityEverOpened`'s sticky-true
   // contract.
   finalAnswerEverDelivered: boolean
-  // 2026-07 double-reply-on-DM fix (Part 2 — race backstop). Set true
-  // SYNCHRONOUSLY at turn-flush FIRE time (before the ~500 ms async send and
-  // before `flushedTurnSupersede.record`) when the flush delivers a SUBSTANTIVE
-  // (≥`FLUSH_SUBSTANTIVE_MIN_CHARS`) terminal answer, and also set when a
-  // substantive `reply` sends. It persists on the ended turn in
+  // 2026-07 double-reply-on-DM fix (Part 2 — race backstop), SOURCE-TAGGED
+  // since #3426. Set to 'flush' SYNCHRONOUSLY at turn-flush FIRE time (before
+  // the ~500 ms async send and before `flushedTurnSupersede.record`) and at
+  // supersede-record consumption (the resurrection window); set to 'reply'
+  // when a substantive `reply` sends. It persists on the ended turn in
   // `recentTurnsById`, so a LATE reply landing in the flush's post-fire
   // pre-record race window (where `flushedTurnSupersede` finds no record to
   // delete yet) resolves this turn via the unified owner resolver, sees the
-  // latch already set, and suppresses itself — closing the residual window Part
-  // 1's supersede cannot reach. Scoped to the substantive floor so an interim
-  // sub-floor ack NEITHER sets nor trips it. Reset false at turn start.
-  answerDelivered: boolean
+  // 'flush' latch already set, and suppresses itself — closing the residual
+  // window Part 1's supersede cannot reach. The 'reply' tag deliberately does
+  // NOT suppress a late reply (#3426): a substantive interim ack followed by
+  // an async sub-agent handback (which lands with NO live gateway turn and
+  // resolves this ended turn as owner via the latest-ended tier) must deliver,
+  // not silently drop. Scoped to the substantive floor so an interim sub-floor
+  // ack NEITHER sets nor trips it. Reset false at turn start.
+  answerDelivered: AnswerDeliveredLatch
+  // #3429 — the text the turn-flush backstop delivered (or is mid-delivering)
+  // as this turn's answer. Stamped SYNCHRONOUSLY alongside the 'flush' latch
+  // arm (stream-render fire site; outbound-send-path supersede-consumption
+  // resurrection site) and cleared wherever that latch is reset. Lets the
+  // late-reply suppression discriminate BY CONTENT between the flushed answer
+  // landing again (suppress — the flush race) and a genuinely new async
+  // handback attributed to this flush-delivered ended turn (deliver fresh —
+  // suppressing/editing it is the #3429 silent client-side drop), including in
+  // the post-fire pre-record window where no supersede record exists yet.
+  // Null when no flush armed this turn. Reset null at turn start.
+  flushedAnswerText: string | null
   // 2026-07 double-reply-on-DM fix (F2 — recency bound). Wall-clock ms the turn
   // ENDED (stamped once by `endCurrentTurnAtomic`), or null while still live.
   // The `findLatestEndedTurnForChat` supersede tier carries DESTRUCTIVE
@@ -3668,8 +3691,9 @@ const currentTurnMap = new CurrentTurnMap<CurrentTurn>()
 // is seq-stamped and `resolve()` prefers the NEWER observation, so neither
 // source can go stale behind the other (session-model-source.ts, pinned by
 // tests/session-model-source.test.ts). buildAgentMetadata reads resolve();
-// the /model command paths write via setOverride.
-const sessionModelSource = createSessionModelSource()
+// the /model command paths write via setOverride. The comparator arms the
+// #3427 requested-vs-served tripwire (handler registered at boot rehydration).
+const sessionModelSource = createSessionModelSource({ servedMatchesRequested: servedModelMatchesRequested })
 // Captures the most-recently-started turn's sessionChatId. Unlike currentTurn,
 // this is NOT cleared by the silence poke (firePoke/clearTurnStarted). It lets
 // the Bug B fallback in executeReply route to the correct chat even when the
@@ -8440,6 +8464,10 @@ const PIN_STATUS_WHILE_WORKING = (() => {
 // handlers unconditionally unpinning on every send) and runs NO polling
 // watchdog / getChat().pinned_message reconciler.
 const statusPinState = new Map<string, PinState>()
+// F2 serialization: same-pinKey reconciles run one-at-a-time via
+// `withPinReconcileLock` (status-pin-store.ts — kept there so it's
+// unit-testable) so each reads a fresh `prev`; see its doc for the stale-`prev`
+// race it closes. Adds zero Telegram API calls (a serialized noop still no-ops).
 // Companion registry: pinKey → chatId, so the pre-restart sweep can unpin
 // owned pins without threading the chat id through every call site. Written on
 // every desired-pinned reconcile, cleared alongside the state on unpin.
@@ -9023,7 +9051,10 @@ async function reconcileStatusPin(
   // absorbed. (The `pin_message` MCP tool still surfaces failures to the agent
   // as a normal tool-error — that path is `executePinMessage`, not this one.)
   try {
-    await reconcileStatusPinInner(pinKey, chatId, desired)
+    // Serialize per pinKey (F2): reconcileStatusPinInner reads `prev` from the
+    // in-memory claim map at its top, so overlapping same-key reconciles must
+    // run one-at-a-time or a stale `prev` clears the disk row under a live pin.
+    await withPinReconcileLock(pinKey, () => reconcileStatusPinInner(pinKey, chatId, desired))
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
     process.stderr.write(
@@ -9040,14 +9071,11 @@ async function reconcileStatusPinInner(
 ): Promise<void> {
   if (!PIN_STATUS_WHILE_WORKING) return
   if (chatId.length === 0) return
-  // NOTE (invisible-worker-cards review, intentionally left): this reconcile is
-  // NOT serialized per pinKey — it snapshots `prev` then awaits. Two edits that
-  // fire `syncPin` in the same microtask window after a dropped claim can both
-  // read `prev=null` and both issue a `pinChatMessage` for the SAME id. That is
-  // benign and self-healing: re-pinning an already-pinned id is idempotent on
-  // Telegram, and the first reconcile to set the claim makes every subsequent
-  // edit a no-op — it converges in one round, never a storm. A per-key mutex
-  // would remove the duplicate pin but adds lock complexity for zero UX gain.
+  // Serialized per pinKey by `withPinReconcileLock` at the caller (F2), so this
+  // `prev` snapshot is taken only after any prior same-key reconcile fully
+  // settled — always the true current claim. Closes the stale-`prev` race (a
+  // turn-end clear dropping the disk row under a flood-delayed open-pin) and the
+  // older duplicate-pin concern (two edits both reading prev=null).
   const prev = statusPinState.get(pinKey) ?? null
 
   const runReconcile = () =>
@@ -14333,6 +14361,26 @@ function isAuthorizedSender(ctx: Context): boolean {
   return false
 }
 
+// Adversarial-review F4 — a group configured with an EMPTY `allowFrom`
+// authorizes every member (isAuthorizedSender returns true for any sender in
+// that group). That's an intentional "whole-group" access mode, but it means
+// `/usage` would expose per-account email labels + quota headroom to every
+// member of a broadly-shared group. Harden minimally: for the quota-bearing
+// card in a non-private chat, mask account labels (reusing the demo-mask
+// machinery) UNLESS the group pinned a non-empty `allowFrom` — i.e. an
+// explicit operator-curated member list is treated as trusted enough to see
+// the real labels. Private (operator DM) chats are never masked. This changes
+// only what /usage REVEALS, not who may run it. The pure decision lives in
+// ./usage-mask.ts (shouldMaskUsageLabels) so it is unit-testable without
+// importing the whole gateway module.
+function shouldMaskAccountLabels(ctx: Context): boolean {
+  const groupAllowFrom =
+    ctx.chat?.type === 'group' || ctx.chat?.type === 'supergroup'
+      ? loadAccess().groups[String(ctx.chat.id)]?.allowFrom
+      : undefined
+  return shouldMaskUsageLabels(ctx.chat?.type, groupAllowFrom)
+}
+
 // safeName moved to ./media-message-handlers.ts (switchroom#2996 P6 cluster A);
 // imported above and shared with the attachment handlers still inline here.
 
@@ -20830,68 +20878,17 @@ bot.command("auth", async ctx => {
   // handleAuthCommand which only needs the narrow broker surface.
   const chatId = String(ctx.chat?.id ?? '')
   if (parsed.kind === 'add' || parsed.kind === 'cancel') {
-    if (!isAuthAdmin({ isAdmin })) {
-      await switchroomReply(
-        ctx,
-        `**Not authorized.** \`/auth ${parsed.kind}\` is admin-only.\n` +
-          `Set \`admin: true\` on this agent in switchroom.yaml to unlock ` +
-          `(the same flag that gates \`/agents\`, \`/restart\`, ` +
-          `\`/update\` etc.).`,
-        { html: true },
-      )
-      return
-    }
-    // PR3 supergroup-mode: key auth-add flows by (chat, thread) so
-    // separate flows in two topics of one supergroup can't collide.
-    // In DM chats message_thread_id is undefined → key collapses to
-    // `chatId:_`, identical to today's behavior.
-    const authAddKey = chatKey(chatId, ctx.message?.message_thread_id ?? null) as string
-    if (parsed.kind === 'cancel') {
-      const existing = pendingAuthAddFlows.get(authAddKey)
-      if (!existing) {
-        await switchroomReply(ctx, "_No pending \`/auth add\` flow in this chat._", { html: true })
-        return
-      }
-      cancelAccountAuthSession(existing)
-      pendingAuthAddFlows.delete(authAddKey)
-      await switchroomReply(ctx, "Cancelled.", { html: true })
-      return
-    }
-    // parsed.kind === 'add'
-    if (pendingAuthAddFlows.has(authAddKey)) {
-      await switchroomReply(
-        ctx,
-        "_An \`/auth add\` flow is already in progress for this chat. " +
-          "Finish the paste, or send \`/auth cancel\` to abort._",
-        { html: true },
-      )
-      return
-    }
-    try {
-      const { loginUrl, scratchDir, tmuxSocket, tmuxSession } = await startAccountAuthSession(parsed.label)
-      pendingAuthAddFlows.set(authAddKey, {
-        label: parsed.label,
-        scratchDir,
-        tmuxSocket,
-        tmuxSession,
-        startedAt: Date.now(),
-      })
-      await switchroomReply(
-        ctx,
-        `**Adding account** \`${parsed.label}\`\n\n` +
-          `1. Open this URL on your phone:\n${loginUrl}\n\n` +
-          `2. Log into Anthropic, copy the code Claude shows.\n` +
-          `3. Paste it back here.\n\n` +
-          `Send \`/auth cancel\` to abort.`,
-        { html: true },
-      )
-    } catch (err) {
-      await switchroomReply(
-        ctx,
-        `**/auth add failed:** ${escapeHtmlForTg((err as Error)?.message ?? String(err))}`,
-        { html: true },
-      )
-    }
+    // Gateway-routed `/auth add|readd|cancel` — extracted to
+    // handleAuthAddOrCancel in auth-add-flow.ts (switchroom#2996 ratchet).
+    await handleAuthAddOrCancel({
+      parsed,
+      isAdmin,
+      currentAgent,
+      chatId,
+      threadId: ctx.message?.message_thread_id ?? null,
+      reply: (text: string) => switchroomReply(ctx, text, { html: true }),
+      escapeHtml: escapeHtmlForTg,
+    })
     return
   }
 
@@ -21444,7 +21441,12 @@ bot.command('issues', async ctx => {
 })
 bot.command('usage', async ctx => {
   if (!isAuthorizedSender(ctx)) return
-  const demo = hasDemoFlag(getCommandArgs(ctx))
+  // `demo` is the explicit `/usage demo` opt-in mask. F4 additionally masks
+  // account labels for a non-private chat whose group has no pinned
+  // `allowFrom` (open-membership group) — see shouldMaskAccountLabels. The
+  // effective mask feeds the label-rendering paths (renderUsageCard,
+  // buildSnapshotKeyboard) exactly as `demo` did.
+  const demo = hasDemoFlag(getCommandArgs(ctx)) || shouldMaskAccountLabels(ctx)
   // Format 2 path: enumerate every account in the broker's known set,
   // probe live quota in parallel, render the health-grouped snapshot.
   // Falls back to the legacy single-agent shape when the broker is
@@ -21484,26 +21486,34 @@ bot.command('usage', async ctx => {
         // segment, just relative instead of absolute — no info lost; the
         // recommendation + cached/live footer the table used to carry are
         // preserved by renderUsageCard.
+        // External OpenRouter/$ block (layout B) — best-effort; omitted when
+        // LiteLLM admin key is unavailable or the spend endpoint fails.
+        const { fetchExternalSpendSummary } = await import('../external-spend.js')
+        const externalSpend = await fetchExternalSpendSummary(renderNow).catch(() => null)
         const exhaustedByLabel = new Map<string, boolean>(
           state.accounts.map((a) => [a.label, a.exhausted]),
         )
         const text = renderUsageCard(snapshots, exhaustedByLabel, {
           now: renderNow,
           demo,
+          externalSpend,
           // #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 }),
+          // "Live" stamp next to "⚠️ no data" rows (#2959 review finding).
+          // Honesty invariant (adversarial-review F1): the live stamp is
+          // derived from whether ANY row carries usable data, NOT from the
+          // array length — a failed live probe against an empty cache returns
+          // a non-empty results array of all-`ok:false` rows. Full rationale
+          // in deriveUsageFooterFreshness (auth-snapshot-format.ts).
+          ...deriveUsageFooterFreshness(
+            probeResp.results,
+            staleCachedAtMs,
+            renderNow.getTime(),
+          ),
         })
         // Preserve the Switch/Refresh/usage/Add inline keyboard on the
         // rich-message render — the table card carries the same actions the
@@ -23867,75 +23877,48 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 // real post-boot signal (`.active-session-model`), never from a
                 // scraped pane or an optimistic record.
                 const isApplyBoot = launched.length > 0 && launched !== configured
-                sessionModelSource.setOverride(isApplyBoot ? launched : null)
-                // Diagnosability (rev 5): the applied model is now always
-                // greppable — `grep 'gw /model relaunch applied'`. F4 note:
-                // `launched` is the REQUESTED token start.sh wrote before `exec
-                // claude` (it is NOT a post-launch confirmation). If a shape-valid
-                // but unknown Claude id was requested, `--fallback-model` may mask
-                // it: claude serves a fallback while this records the requested
-                // token. That divergence is NOT a persistent lie — the transcript's
-                // `message.model` (noteTranscriptModel) reclaims the source from
-                // this override on the first assistant line, correcting /status to
-                // the model actually serving calls. The pre-first-assistant window
-                // is the only optimistic window (G2), and it is bounded and
-                // self-healing; it is documented, not silently asserted as success.
+                // { verify: true } (#3427 item 4 / H1): ONLY this site arms the
+                // requested-vs-served tripwire — `launched` IS the token of the
+                // session now serving. Command-time setOverride never arms.
+                sessionModelSource.setOverride(isApplyBoot ? launched : null, { verify: true })
+                // Boot /model cards (#3427): the divergence tripwire warn and
+                // the switch confirmation share one deps surface; the card
+                // logic lives in model-command.ts (#2996 ratchet).
+                const modelBootCardDeps: ModelBootCardDeps = {
+                  agent: getMyAgentName(),
+                  chat: modelSwitchMarkerChat,
+                  log: (line) => process.stderr.write(line),
+                  // allow-raw-bot-api: one-shot boot /model cards (divergence warn + switch confirmation), same shape as the session-model alert relay below
+                  sendCard: (chatId, body, opts) => lockedBot.api.sendMessage(chatId, body, opts),
+                }
+                if (isApplyBoot) {
+                  sessionModelSource.setDivergenceHandler(buildServedModelDivergenceHandler(modelBootCardDeps))
+                }
+                // F1/N4: classify + log + one confirmation card. Formatters live
+                // in model-command.ts so this file does not inflate (#2996 ratchet).
+                const confirmation = modelSwitchReason != null
+                  ? classifyModelSwitchConfirmation({
+                      reason: modelSwitchReason,
+                      launched,
+                      configured,
+                    })
+                  : null
                 process.stderr.write(
-                  `telegram gateway: gw /model relaunch applied agent=${getMyAgentName()} launched=${launched || '(none)'} configured=${configured} override=${isApplyBoot ? 'set' : 'cleared'}\n`,
-                )
-                // Switch-confirmation (F1 / PLAN §4 step 2): on a /model apply-boot
-                // with a known initiating chat, send ONE confirmation built from the
-                // ACTUAL launched model — never optimistic. Keyed on the DETERMINISTIC
-                // /model switch reason (from the clean-shutdown marker), not on
-                // `launched !== configured`, so it ALSO fires when a switch landed on
-                // the configured default (`/model default`, or `/model <configured>`)
-                // — N4. The generic boot card is suppressed for this boot (N3), so
-                // this is the single card the operator sees for the switch.
-                if (modelSwitchReason != null && modelSwitchMarkerChat) {
-                  const chat = modelSwitchMarkerChat
-                  // Derive the confirmation from the DETERMINISTIC post-boot
-                  // signals. A non-default switch that reverted to the configured
-                  // default (a wedged/consumed apply-boot — the silent-revert bug)
-                  // must WARN, not print a misleading green "✅ Now running
-                  // <default>" card. `applied` / `default` keep the honest green
-                  // card (N4: the default/revert case still confirms).
-                  const confirmation = classifyModelSwitchConfirmation({
-                    reason: modelSwitchReason,
+                  formatModelRelaunchDiagLog({
+                    agent: getMyAgentName(),
                     launched,
                     configured,
+                    confirmation,
+                    isApplyBoot,
+                  }),
+                )
+                if (confirmation != null) {
+                  // #3427 item 2: card-vs-suppress decision is pure + behaviorally tested.
+                  deliverModelSwitchBootNotice({
+                    ...modelBootCardDeps,
+                    confirmation,
+                    hasSessionModelAlert: existsSync(join(smAgentDir, '.session-model-alert')),
                   })
-                  // LOW-2 dedup: the config-default-changed / proxy-down revert
-                  // paths in start.sh write a TAILORED `.session-model-alert`
-                  // (relayed to operators below) that already explains why the
-                  // switch didn't apply and how to re-issue it. Suppress the
-                  // generic not-applied card when such an alert is present for
-                  // this boot so the operator isn't double-warned — the alert is
-                  // the more specific message. The not-applied card still fires
-                  // for the plain wedge/revert case (no alert on disk).
-                  const hasSessionModelAlert = existsSync(join(smAgentDir, '.session-model-alert'))
-                  if (confirmation.kind === 'not-applied' && hasSessionModelAlert) {
-                    process.stderr.write(
-                      `telegram gateway: gw /model relaunch applied — suppressing not-applied confirmation (a .session-model-alert is present and will be relayed) agent=${getMyAgentName()} target=${confirmation.target}\n`,
-                    )
-                  } else {
-                    const body =
-                      confirmation.kind === 'applied'
-                        ? `✅ Now running \`${confirmation.launched}\` — session-only, reverts to the configured model on the next restart. Fresh session; memory and the handoff briefing carry the context.`
-                        : confirmation.kind === 'not-applied'
-                          ? `⚠️ Your switch to \`${confirmation.target}\` didn't apply — the agent reverted to \`${confirmation.revertedTo}\` (the apply-boot didn't complete). Re-issue \`/model ${confirmation.target}\` to try again.`
-                          : `✅ Now running \`${confirmation.launched}\` (the configured default) — fresh session; memory and the handoff briefing carry the context.`
-                    // allow-raw-bot-api: one-shot boot confirmation, same shape as the session-model alert relay below
-                    void lockedBot.api
-                      .sendMessage(chat.chatId, body, {
-                        parse_mode: 'Markdown',
-                        ...(chat.threadId != null ? { message_thread_id: chat.threadId } : {}),
-                      })
-                      .catch((err: unknown) =>
-                        process.stderr.write(
-                          `telegram gateway: model-switch confirmation send failed: ${(err as Error)?.message ?? String(err)}\n`,
-                        ),
-                      )
-                  }
                 }
               } catch { /* leave override as-is on a bad read */ }
             }

package/telegram-plugin/gateway/inbound-interceptors.ts

@@ -18,6 +18,7 @@
 import type { Context } from 'grammy'
 import type { ReactionTypeEmoji } from 'grammy/types'
 import { parseStopKeyword, buildStopReply } from './stop-command.js'
+import { formatGrantedScopesReply } from './auth-command.js'
 import { decideInterruptTiming, resolveSafeBoundaryEnabled } from './interrupt-defer.js'
 import { naturalAction } from '../permission-title.js'
 import { richMessage } from '../rich-send.js'
@@ -463,15 +464,24 @@ export async function interceptAuthAdd(
     deps.pendingAuthAddFlows.delete(p.interceptKey)
     try {
       const credentials = await deps.submitAccountAuthCode(pendingAdd, p.text.trim())
+      const replace = pendingAdd.replace === true
       try {
-        await deps.addAccountViaBroker(pendingAdd.label, credentials, { replace: false })
+        await deps.addAccountViaBroker(pendingAdd.label, credentials, { replace })
         // success — wipe scratch dir now that the broker owns the creds
         deps.cleanAuthAddScratchDir(pendingAdd.scratchDir)
+        // Read the minted scopes STRUCTURALLY (never scraped) and surface
+        // them so a scope regression (missing user:profile) is caught at add
+        // time, not at /usage time.
+        const scopeReply = formatGrantedScopesReply(
+          (credentials as { claudeAiOauth?: { scopes?: string[] } }).claudeAiOauth?.scopes,
+        )
+        const verb = replace ? 're-authenticated' : 'added'
         await deps.switchroomReply(
           p.ctx,
-          `✓ Account \`${pendingAdd.label}\` added.\n` +
+          `✓ Account \`${pendingAdd.label}\` ${verb}.\n` +
             `The fleet's active account hasn't changed. Send ` +
-            `\`/auth use ${deps.escapeHtmlForTg(pendingAdd.label)}\` to switch to it.`,
+            `\`/auth use ${deps.escapeHtmlForTg(pendingAdd.label)}\` to switch to it.` +
+            scopeReply.text,
           { html: true },
         )
       } catch (brokerErr) {