switchroom 0.19.2 → 0.19.4

package/telegram-plugin/dist/server.js

@@ -17792,6 +17792,7 @@ function startSessionTail(config2) {
   let stopped = false;
   let pendingPartial = "";
   const fileCursors = new Map;
+  const replayUntilByFile = new Map;
   function readNew() {
     if (stopped || !currentFile)
       return;
@@ -17800,11 +17801,15 @@ function startSessionTail(config2) {
       if (stat.size < cursor) {
         cursor = 0;
         pendingPartial = "";
-        if (currentFile != null)
+        if (currentFile != null) {
           fileCursors.delete(currentFile);
+          replayUntilByFile.delete(currentFile);
+        }
       }
       if (stat.size === cursor)
         return;
+      const chunkStart = cursor;
+      const isReplayChunk = chunkStart < (replayUntilByFile.get(currentFile) ?? 0);
       const buf = Buffer.alloc(stat.size - cursor);
       const fd = openSync(currentFile, "r");
       try {
@@ -17824,7 +17829,7 @@ function startSessionTail(config2) {
         const sid = sessionIdForFile(currentFile);
         for (const ev of events) {
           try {
-            onEvent(decorate(ev, sid));
+            onEvent(decorate(isReplayChunk && ev.kind === "model" ? { ...ev, replayed: true } : ev, sid));
           } catch (err) {
             log?.(`session-tail: onEvent threw: ${err.message}`);
           }
@@ -17877,6 +17882,7 @@ function startSessionTail(config2) {
         const size = statSync4(file).size;
         cursor = computeFirstAttachCursor(file, size);
         if (cursor < size) {
+          replayUntilByFile.set(file, size);
           log?.(`session-tail: attached to ${file} (cursor=${cursor}, replaying in-flight turn from offset; size=${size})`);
         } else {
           log?.(`session-tail: attached to ${file} (cursor=${cursor})`);

package/telegram-plugin/flushed-turn-supersede.ts

@@ -31,7 +31,16 @@
  * `record()` (a much smaller window), `take` finds no record and the duplicate
  * can still slip through. We deliberately trade that residual window for the
  * safety guarantee that we NEVER delete a message we cannot positively attribute
- * to the reply's own turn (identity-only supersede — see `decideSupersede`).
+ * to the reply's own turn (identity-scoped supersede — see `decideSupersede`).
+ *
+ * #3429 content gate: identity is NECESSARY but not sufficient. Because the
+ * flush ends its turn before recording, an async sub-agent handback landing
+ * within the TTL resolves the flush-delivered ENDED turn as its owner too —
+ * same identity as the turn's own late replay. When the caller supplies the
+ * landing reply's text, `decideSupersede` additionally requires it to BE the
+ * flushed answer (`flushedAnswerMatchesReply`); otherwise the decision is
+ * 'new-content' and the gateway sends fresh (a notifying new message) with the
+ * record left intact.
  *
  * Pure module: no I/O, no globals, no clock reads beyond the caller-supplied
  * `now`. Fully unit-testable; the gateway wires the actual delete/send.
@@ -51,9 +60,11 @@ export interface FlushedTurnRecord {
   /** The Telegram message id(s) the flush posted (edit target + any extra
    *  chunk messages). Superseding deletes all of them. */
   messageIds: number[]
-  /** The text the flush delivered — retained for diagnostics/logging only. The
-   *  supersede decision NEVER compares text (that is the whole point: it fires
-   *  even when the flushed text differs from the reply text). */
+  /** The text the flush delivered. Originally diagnostics-only; since #3429 it
+   *  also feeds the new-content gate (`flushedAnswerMatchesReply`): an
+   *  identity-matched reply that is NOT the same answer (neither equal nor a
+   *  bounded containment) is an async handback and must send fresh instead of
+   *  editing/deleting the flushed message. */
   text: string
   /** Wall-clock ms when recorded. */
   ts: number
@@ -71,8 +82,67 @@ export interface SupersedeDecision {
   /** Message ids the gateway must delete before/instead of the fresh send.
    *  Empty when `supersede` is false. */
   deleteMessageIds: number[]
-  /** Machine-readable reason (for logs / tests). */
-  reason: 'supersede' | 'no-record' | 'expired' | 'different-turn'
+  /** Machine-readable reason (for logs / tests). `'new-content'` (#3429): the
+   *  record matched by identity + TTL but the landing reply carries genuinely
+   *  DIFFERENT content than the flushed answer — an async handback attributed
+   *  to the flush-delivered ended turn, NOT that turn's own answer landing
+   *  late. The gateway must send FRESH (a notifying new message), never
+   *  edit/delete the flushed message; the record is NOT consumed. */
+  reason: 'supersede' | 'no-record' | 'expired' | 'different-turn' | 'new-content'
+  /** The matched record's flushed text — populated whenever a fresh record for
+   *  the reply's turn identity was found (`reason` 'supersede' or
+   *  'new-content'). The gateway stashes it on the owner turn atom so the
+   *  answer-delivered latch can make the same content-vs-flush discrimination
+   *  on the no-record retry/race paths (#3429). */
+  recordText?: string
+}
+
+/**
+ * #3429 — minimum length a CONTAINED text must have for a containment match.
+ * The legitimate containment class is a flush that delivered
+ * `narration\n\nanswer` being corrected by the clean `answer`-only reply — the
+ * contained side is a full answer, comfortably long. A trivially short
+ * contained string (e.g. a reply "Done." that happens to appear inside the
+ * flushed blob) is NOT positive evidence of the same answer, and a false match
+ * here silently edits/suppresses genuinely new content — the exact #3429
+ * failure. Below this floor only whitespace-normalized EQUALITY matches; the
+ * worst case of declining is a rare duplicate message, which beats a silent
+ * drop (the #3426/#3428 precedent).
+ */
+export const SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS = 32
+
+/** Collapse whitespace runs so flush-pipeline vs reply-pipeline spacing
+ *  (paragraph spacers, hard-break promotion) never defeats the comparison. */
+function normalizeForMatch(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * #3429 — is the landing reply the SAME ANSWER the flush already delivered
+ * (a late canonical correction), as opposed to genuinely new content (an async
+ * handback that merely resolved the flush-delivered ended turn as its owner)?
+ *
+ * Deterministic string decision, no timing:
+ *   - whitespace-normalized equality → same answer;
+ *   - containment either direction (flush = `narration\n\nanswer` ⊇ reply, or
+ *     reply ⊇ a partially-delivered flush), guarded by
+ *     `SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS` on the CONTAINED side so a short
+ *     coincidental substring can never claim a match.
+ *
+ * A model-REGENERATED paraphrase of the same answer is indistinguishable from
+ * new content and therefore sends fresh — a rare duplicate message, the same
+ * conscious trade #3428 shipped for the reply-armed latch. A silent
+ * drop/edit-in-place of a genuinely new handback is the strictly worse
+ * failure.
+ */
+export function flushedAnswerMatchesReply(flushedText: string, replyText: string): boolean {
+  const flushed = normalizeForMatch(flushedText)
+  const reply = normalizeForMatch(replyText)
+  if (flushed.length === 0 || reply.length === 0) return false
+  if (flushed === reply) return true
+  if (reply.length >= SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS && flushed.includes(reply)) return true
+  if (flushed.length >= SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS && reply.includes(flushed)) return true
+  return false
 }
 
 /**
@@ -93,10 +163,25 @@ export interface SupersedeDecision {
  * now resolves a last-known turnId for the reply before calling in, so the
  * common late-replay case still matches by identity rather than relying on the
  * promiscuous null branch.)
+ *
+ * #3429 content gate: identity alone is NOT sufficient. The flush ends its
+ * turn synchronously BEFORE recording (stream-render `endCurrentTurnAtomic` →
+ * `record`), so EVERY superseding reply is a late reply, and an async
+ * sub-agent handback landing within the TTL with no live gateway turn resolves
+ * the flush-delivered ENDED turn as its owner via the latest-ended tier —
+ * exactly the same identity as the turn's own canonical late replay. The
+ * observed failure (msgs 10482/10486, 2026-07-20): the handback consumed the
+ * record and EDITED the flushed message in place with unrelated new content —
+ * Telegram edits do not re-notify, so the handback never surfaced client-side
+ * AND the flushed answer was destroyed. When the caller supplies `replyText`
+ * and it is NOT the same answer (`flushedAnswerMatchesReply`), the decision is
+ * `'new-content'`: no supersede, record left intact for the genuine replay,
+ * and the gateway sends the reply FRESH. Callers that omit `replyText`
+ * (identity-only legacy shape) keep the pre-#3429 behaviour.
  */
 export function decideSupersede(
   record: FlushedTurnRecord | undefined,
-  args: { liveTurnId: string | null; now: number; ttlMs?: number },
+  args: { liveTurnId: string | null; replyText?: string | null; now: number; ttlMs?: number },
 ): SupersedeDecision {
   const ttlMs = args.ttlMs ?? DEFAULT_SUPERSEDE_TTL_MS
   if (record == null) return { supersede: false, deleteMessageIds: [], reason: 'no-record' }
@@ -110,7 +195,18 @@ export function decideSupersede(
   if (!sameTurn) {
     return { supersede: false, deleteMessageIds: [], reason: 'different-turn' }
   }
-  return { supersede: true, deleteMessageIds: [...record.messageIds], reason: 'supersede' }
+  // #3429 — same turn identity, but genuinely different content: an async
+  // handback attributed to the flush-delivered ended turn, not the turn's own
+  // answer landing late. Never edit/delete the flushed message for it.
+  if (args.replyText != null && !flushedAnswerMatchesReply(record.text, args.replyText)) {
+    return { supersede: false, deleteMessageIds: [], reason: 'new-content', recordText: record.text }
+  }
+  return {
+    supersede: true,
+    deleteMessageIds: [...record.messageIds],
+    reason: 'supersede',
+    recordText: record.text,
+  }
 }
 
 /**
@@ -225,23 +321,31 @@ export class FlushedTurnSupersedeRegistry {
 
   /** Decide supersede for a landing reply WITHOUT consuming the record. Selects
    *  the record whose turnId matches the reply's resolved `liveTurnId` (or the
-   *  null-turnId record when `liveTurnId == null`). */
+   *  null-turnId record when `liveTurnId == null`). `replyText` (#3429) enables
+   *  the new-content gate; omitting it keeps the identity-only legacy shape. */
   peek(
     chatId: string,
     threadId: number | undefined,
-    args: { liveTurnId: string | null; now: number },
+    args: { liveTurnId: string | null; replyText?: string | null; now: number },
   ): SupersedeDecision {
     const rec = this.entries.get(makeKey(chatId, threadId))?.get(turnKey(args.liveTurnId))
-    return decideSupersede(rec, { liveTurnId: args.liveTurnId, now: args.now, ttlMs: this.ttlMs })
+    return decideSupersede(rec, {
+      liveTurnId: args.liveTurnId,
+      replyText: args.replyText,
+      now: args.now,
+      ttlMs: this.ttlMs,
+    })
   }
 
   /** Decide supersede AND, on a supersede, consume the matched record (so a
    *  second replay of the same reply doesn't try to delete the same — now gone —
-   *  messages again). Returns the same decision `peek` would. */
+   *  messages again). A `'new-content'` decision (#3429) does NOT consume: the
+   *  record stays live for the turn's own canonical replay until the TTL.
+   *  Returns the same decision `peek` would. */
   take(
     chatId: string,
     threadId: number | undefined,
-    args: { liveTurnId: string | null; now: number },
+    args: { liveTurnId: string | null; replyText?: string | null; now: number },
   ): SupersedeDecision {
     const lane = makeKey(chatId, threadId)
     const decision = this.peek(chatId, threadId, args)

package/telegram-plugin/gateway/auth-add-flow.ts

@@ -67,10 +67,15 @@ import {
   parseSetupTokenUrl,
   readTokenFromCredentialsFile,
 } from '../../src/auth/manager.js'
+import { PRE_PASTE_RULES } from '../../src/auth/via-claude.js'
 import type {
   AddAccountCredentials,
   AnthropicAddAccountCredentials,
 } from '../../src/auth/broker/client.js'
+import { isAuthAdmin, runReaddPrecheck } from './auth-command.js'
+import type { ParsedAuthCommand } from './auth-command.js'
+import { getAuthBrokerClient } from './auth-broker-client.js'
+import { chatKey } from './chat-key.js'
 
 /* ── Injectable tmux ops (mirrors makeTmuxRunner in src/agents/inject.ts) ─── */
 
@@ -103,6 +108,19 @@ export interface AuthAddTmuxOps {
    * the session has ended.
    */
   send(socket: string, session: string, text: string): void
+  /**
+   * `tmux -L <socket> send-keys -t <session> <key>` — a SINGLE key-name
+   * dispatch (e.g. `Enter`), with NO `-l` literal prefix and NO pane
+   * capture. Used for:
+   *   - pre-paste picker choreography (theme / login-method Enters) during
+   *     the URL-poll phase, before any secret is on the pane; and
+   *   - blind post-paste Enter dispatches to advance past Enter-gated
+   *     "Logged in / Security notes" screens in the via-claude picker flow.
+   * It reads nothing from the pane, so it can never leak the echoed code —
+   * this is the deterministic replacement for via-claude's capture-driven
+   * post-paste dispatch (see prb-safety.md).
+   */
+  sendKey(socket: string, session: string, key: string): void
   /** `tmux -L <socket> has-session -t <session>` — returns true if alive. */
   hasSession(socket: string, session: string): boolean
   /** `tmux -L <socket> kill-session -t <session>` — best-effort. */
@@ -151,6 +169,12 @@ export function makeAuthAddTmuxOps(tmuxBin = 'tmux'): AuthAddTmuxOps {
         stdio: ['pipe', 'pipe', 'pipe'],
       })
     },
+    sendKey(socket, session, key) {
+      // Single key-name dispatch, no -l literal prefix, no capture.
+      execFileSync(tmuxBin, ['-L', socket, 'send-keys', '-t', session, key], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+    },
     hasSession(socket, session) {
       try {
         execFileSync(tmuxBin, ['-L', socket, 'has-session', '-t', session], {
@@ -184,6 +208,20 @@ export function makeAuthAddTmuxOps(tmuxBin = 'tmux'): AuthAddTmuxOps {
  * TTL matches `REAUTH_INTERCEPT_TTL_MS` (10 minutes); the reaper sweep
  * in gateway.ts walks both maps each minute.
  */
+/**
+ * Which credential minter drives the flow.
+ *
+ *   - `'via-claude'` (DEFAULT): spawn the bare `claude` login picker, which
+ *     mints the broad scope set (`org:create_api_key user:profile
+ *     user:inference user:sessions:claude_code user:mcp_servers
+ *     user:file_upload`) that `server:` mode agents require at boot. This is
+ *     the default because `claude setup-token` tokens carry only
+ *     `user:inference` and are REFUSED by server: agents (via-claude.ts:9-17).
+ *   - `'setup-token'`: spawn `claude setup-token` (narrow `user:inference`).
+ *     Kept for completeness / legacy narrow-scope adds.
+ */
+export type AuthAddMode = 'via-claude' | 'setup-token'
+
 export interface PendingAuthAddFlow {
   label: string
   scratchDir: string
@@ -192,6 +230,21 @@ export interface PendingAuthAddFlow {
   /** tmux session name (`auth-add-<label>-<hex>`). */
   tmuxSession: string
   startedAt: number
+  /**
+   * True when this flow re-authenticates an EXISTING account label in place
+   * (`/auth readd`) — threaded to `addAccountViaBroker(..., { replace: true })`
+   * so the broker overwrites the stored credentials instead of rejecting the
+   * duplicate. Absent/false is a fresh add. Set by the gateway dispatch.
+   */
+  replace?: boolean
+  /**
+   * Minter mode this flow was started in. `submitAccountAuthCode` reads it to
+   * decide whether to dispatch blind post-paste Enter key-presses (via-claude
+   * picker screens) — setup-token exits after the code so needs none.
+   * Optional for back-compat with callers/tests that construct flows directly;
+   * absent is treated as `'via-claude'` (the default minter).
+   */
+  mode?: AuthAddMode
 }
 export const pendingAuthAddFlows = new Map<string, PendingAuthAddFlow>()
 
@@ -299,6 +352,8 @@ export interface StartAccountAuthSessionResult {
   scratchDir: string
   tmuxSocket: string
   tmuxSession: string
+  /** The minter mode the session was started in. */
+  mode: AuthAddMode
 }
 
 /**
@@ -343,6 +398,11 @@ export async function startAccountAuthSession(
     agentName?: string
     /** Override the claude binary name (tests). */
     claudeBinary?: string
+    /**
+     * Credential minter. Defaults to `'via-claude'` (broad scope) — see
+     * {@link AuthAddMode}. Pass `'setup-token'` for the narrow-scope minter.
+     */
+    mode?: AuthAddMode
   } = {},
 ): Promise<StartAccountAuthSessionResult> {
   if (process.env.SWITCHROOM_TMUX_SUPERVISOR !== '1' && !opts.tmuxOps) {
@@ -353,10 +413,14 @@ export async function startAccountAuthSession(
   }
 
   const home = opts.home ?? homedir()
-  const urlTimeoutMs = opts.urlTimeoutMs ?? 12_000
+  // 30s (was 12s): the via-claude login picker adds keystroke-choreography
+  // latency (theme + login-method Enters) before the URL renders, and an
+  // unloaded VM can be slow. via-claude's own default is 20s; 30s is generous.
+  const urlTimeoutMs = opts.urlTimeoutMs ?? 30_000
   const agentName = opts.agentName ?? process.env.SWITCHROOM_AGENT_NAME ?? 'gateway'
   const tmux = opts.tmuxOps ?? makeAuthAddTmuxOps(opts.tmuxBin)
   const binary = opts.claudeBinary ?? 'claude'
+  const mode: AuthAddMode = opts.mode ?? 'via-claude'
 
   const scratchDir = pickScratchDir(label, home)
   mkdirSync(scratchDir, { recursive: true, mode: 0o700 })
@@ -391,20 +455,31 @@ export async function startAccountAuthSession(
   if (process.env.CLAUDE_CONFIG_DIR) sessionEnv['CLAUDE_CONFIG_DIR'] = scratchDir // always override
   if (process.env.XDG_CONFIG_HOME) sessionEnv['XDG_CONFIG_HOME'] = process.env.XDG_CONFIG_HOME
 
+  // Command: bare `claude` for the broad-scope login picker (via-claude), or
+  // `claude setup-token` for the narrow-scope minter.
+  const sessionCmd = mode === 'via-claude' ? binary : binary + ' setup-token'
+  const minterLabel = mode === 'via-claude' ? 'claude login' : 'claude setup-token'
   try {
-    tmux.newSession(tmuxSocket, tmuxSession, sessionEnv, binary + ' setup-token')
+    tmux.newSession(tmuxSocket, tmuxSession, sessionEnv, sessionCmd)
   } catch (err) {
     cleanScratchDir(scratchDir)
-    throw new Error(`Failed to start tmux session for claude setup-token: ${(err as Error).message}`)
+    throw new Error(`Failed to start tmux session for ${minterLabel}: ${(err as Error).message}`)
   }
 
   // Poll capture-pane every 500ms up to the URL timeout.
+  //
+  // In via-claude mode we ALSO dispatch the pre-paste picker choreography
+  // (theme picker → Enter, login-method picker → Enter) each tick, at most
+  // once per rule. This runs BEFORE any secret is on the pane, so capturing
+  // here is safe. parseSetupTokenUrl matches both the claude.ai/oauth and
+  // claude.com/cai/oauth shapes, which is exactly the URL the picker renders.
+  const preFired = new Set<string>()
   const loginUrl = await new Promise<string>((resolve, reject) => {
     const deadline = setTimeout(() => {
       clearInterval(ticker)
       tmux.killSession(tmuxSocket, tmuxSession)
       cleanScratchDir(scratchDir)
-      reject(new Error(`claude setup-token did not print an OAuth URL within ${urlTimeoutMs}ms`))
+      reject(new Error(`${minterLabel} did not print an OAuth URL within ${urlTimeoutMs}ms`))
     }, urlTimeoutMs)
 
     const ticker = setInterval(() => {
@@ -414,9 +489,20 @@ export async function startAccountAuthSession(
         clearTimeout(deadline)
         clearInterval(ticker)
         cleanScratchDir(scratchDir)
-        reject(new Error('claude setup-token exited before printing OAuth URL'))
+        reject(new Error(`${minterLabel} exited before printing OAuth URL`))
         return
       }
+      if (mode === 'via-claude') {
+        for (const rule of PRE_PASTE_RULES) {
+          if (preFired.has(rule.name)) continue
+          if (rule.match.test(pane)) {
+            preFired.add(rule.name)
+            // The pre-paste rules dispatch bare key-names (Enter); use the
+            // single-key primitive, not the literal-code `send`.
+            for (const key of rule.keys) tmux.sendKey(tmuxSocket, tmuxSession, key)
+          }
+        }
+      }
       const url = parseSetupTokenUrl(pane)
       if (url) {
         clearTimeout(deadline)
@@ -427,7 +513,7 @@ export async function startAccountAuthSession(
     }, 500)
   })
 
-  return { loginUrl, scratchDir, tmuxSocket, tmuxSession }
+  return { loginUrl, scratchDir, tmuxSocket, tmuxSession, mode }
 }
 
 /**
@@ -456,11 +542,24 @@ export async function submitAccountAuthCode(
     pollIntervalMs?: number
     pollTimeoutMs?: number
     tmuxOps?: AuthAddTmuxOps
+    /**
+     * Blind post-paste Enter schedule (ms after the code paste) for the
+     * via-claude picker flow: advances past the Enter-gated "Logged in /
+     * Security notes" screens WITHOUT ever capturing the pane (the echoed
+     * code is a secret — see prb-safety.md). Defaults derive from
+     * `flow.mode`: via-claude → `[1500, 3000, 5000]`, setup-token → `[]`
+     * (setup-token exits after the code, so no screens to dismiss). Pass an
+     * explicit array to override (tests use tight schedules).
+     */
+    blindEnterDelaysMs?: number[]
   } = {},
 ): Promise<AddAccountCredentials> {
   const pollIntervalMs = opts.pollIntervalMs ?? 250
   const pollTimeoutMs = opts.pollTimeoutMs ?? 300_000
   const tmux = opts.tmuxOps ?? makeAuthAddTmuxOps()
+  const mode: AuthAddMode = flow.mode ?? 'via-claude'
+  const blindEnterDelaysMs =
+    opts.blindEnterDelaysMs ?? (mode === 'via-claude' ? [1500, 3000, 5000] : [])
 
   const credentialsPath = join(flow.scratchDir, '.credentials.json')
 
@@ -475,11 +574,29 @@ export async function submitAccountAuthCode(
     )
   }
 
+  // Blind post-paste Enter schedule (via-claude picker). Absolute deadlines;
+  // each fires at most once. NEVER reads the pane — sendKey only writes.
+  const pasteAt = Date.now()
+  const blindEnters = blindEnterDelaysMs.map((d) => ({ at: pasteAt + d, fired: false }))
+
   // Poll filesystem + session liveness only — no capture-pane.
   const deadline = Date.now() + pollTimeoutMs
   while (Date.now() < deadline) {
     await new Promise((r) => setTimeout(r, pollIntervalMs))
 
+    // Dispatch any due blind Enters (best-effort; a dead session just throws
+    // and we swallow it — the fs poll below is the real success signal).
+    for (const be of blindEnters) {
+      if (!be.fired && Date.now() >= be.at) {
+        be.fired = true
+        try {
+          tmux.sendKey(flow.tmuxSocket, flow.tmuxSession, 'Enter')
+        } catch {
+          // best-effort — session may have already exited on success
+        }
+      }
+    }
+
     if (existsSync(credentialsPath)) {
       const token = readTokenFromCredentialsFile(credentialsPath)
       if (token) {
@@ -529,3 +646,95 @@ export function cancelAccountAuthSession(
   tmux.killSession(flow.tmuxSocket, flow.tmuxSession)
   cleanScratchDir(flow.scratchDir)
 }
+
+/**
+ * `/auth add`, `/auth readd`, `/auth add --replace`, and `/auth cancel`
+ * dispatch. Extracted verbatim from gateway.ts (switchroom#2996 ratchet) —
+ * behavior identical. Gateway-routed because it drives a scratch-dir-backed
+ * `claude setup-token` tmux/OAuth lifecycle the broker client can't model.
+ *
+ * `reply` sends an HTML message to the originating chat; `escapeHtml` is the
+ * gateway's Telegram-HTML escaper. Admin authority is passed through as
+ * `isAdmin` (the gateway sources it from the agent's own `admin`/`root` flag).
+ */
+export async function handleAuthAddOrCancel(opts: {
+  parsed: Extract<ParsedAuthCommand, { kind: 'add' | 'cancel' }>
+  isAdmin: boolean
+  currentAgent: string
+  chatId: string
+  threadId: number | null
+  reply: (text: string) => Promise<unknown>
+  escapeHtml: (text: string) => string
+}): Promise<void> {
+  const { parsed, isAdmin, currentAgent, chatId, threadId, reply, escapeHtml } = opts
+  if (!isAuthAdmin({ isAdmin })) {
+    await reply(
+      `**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.).`,
+    )
+    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, threadId) as string
+  if (parsed.kind === 'cancel') {
+    const existing = pendingAuthAddFlows.get(authAddKey)
+    if (!existing) {
+      await reply("_No pending \`/auth add\` flow in this chat._")
+      return
+    }
+    cancelAccountAuthSession(existing)
+    pendingAuthAddFlows.delete(authAddKey)
+    await reply("Cancelled.")
+    return
+  }
+  // parsed.kind === 'add'
+  if (pendingAuthAddFlows.has(authAddKey)) {
+    await reply(
+      "_An \`/auth add\` flow is already in progress for this chat. " +
+        "Finish the paste, or send \`/auth cancel\` to abort._",
+    )
+    return
+  }
+  // Precheck against broker state (readd requires the label to exist; a
+  // fresh add requires it NOT to): fail fast before spinning up a tmux/OAuth
+  // flow. Best-effort — a broker-unreachable case returns null and
+  // addAccountViaBroker enforces.
+  const precheckErr = await runReaddPrecheck(
+    () => getAuthBrokerClient(currentAgent),
+    parsed.label,
+    parsed.replace,
+  )
+  if (precheckErr) {
+    await reply(precheckErr)
+    return
+  }
+  try {
+    const { loginUrl, scratchDir, tmuxSocket, tmuxSession, mode } = await startAccountAuthSession(parsed.label)
+    pendingAuthAddFlows.set(authAddKey, {
+      label: parsed.label,
+      scratchDir,
+      tmuxSocket,
+      tmuxSession,
+      startedAt: Date.now(),
+      replace: parsed.replace,
+      mode,
+    })
+    const verbNoun = parsed.replace ? 'Re-authenticating account' : 'Adding account'
+    await reply(
+      `**${verbNoun}** \`${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.`,
+    )
+  } catch (err) {
+    await reply(
+      `**/auth ${parsed.replace ? 'readd' : 'add'} failed:** ${escapeHtml((err as Error)?.message ?? String(err))}`,
+    )
+  }
+}