switchroom 0.14.61 → 0.14.63

package/telegram-plugin/gateway/gateway.ts

@@ -116,6 +116,11 @@ import {
 import type { AuthBrokerClient } from './auth-command.js'
 import type { ListStateData } from './auth-line.js'
 import { getAuthBrokerClient, addAccountViaBroker } from './auth-broker-client.js'
+import {
+  pendingMicrosoftConnectFlows,
+  startMicrosoftConnect,
+  runMicrosoftConnectPoll,
+} from './microsoft-connect-flow.js'
 import { resolveAuthBrokerSocketPath } from '../../src/auth/broker/client.js'
 import { createFleetFallbackGate } from '../fleet-fallback-gate.js'
 import {
@@ -137,6 +142,7 @@ import {
   resolveRetentionDays as resolveRegistryRetentionDays,
 } from '../registry/reaper.js'
 import { parseQueuePrefix, parseSteerPrefix, formatPriorAssistantPreview, formatReplyToText } from '../steering.js'
+import { autoClassifyMidTurnInbound } from './auto-classify-mid-turn.js'
 import {
   renderOperatorEvent,
   shouldEmitOperatorEvent,
@@ -284,6 +290,7 @@ import {
   obligationEscalationText,
 } from './obligation-ledger.js'
 import { loadObligations, persistObligations } from './obligation-store.js'
+import { driveEscalation } from './escalation-drive.js'
 import { createInboundSpool } from './inbound-spool.js'
 import { purgeStaleTurnsForChat } from './turn-state-purge.js'
 import { decideInboundDelivery } from './inbound-delivery-gate.js'
@@ -1406,6 +1413,58 @@ const OBLIGATION_SWEEP_MS = 5_000
 // attempts the gateway closes best-effort (loud log): the user is genuinely
 // unreachable, so a bounded give-up beats an infinite/poison loop.
 const OBLIGATION_ESCALATE_MAX = 3
+// Deadline for a single escalation send. grammy/fetch impose NO request timeout,
+// and the in-flight guard (obligationEscalateInFlight) is cleared only in the
+// send's `.finally` — which never runs if the send hangs. Without a bound, one
+// stalled send leaks the in-flight flag forever and the obligation is stuck OPEN
+// (never re-escalated, never closed) — the sole liveness hole a total proof
+// found. Racing the send against this deadline makes the wait bounded BY
+// CONSTRUCTION (see with-deadline.ts): the chain always settles, `.finally`
+// always clears the flag, and a hang becomes a bounded reject that feeds the
+// bounded escalate ladder to a terminal. 45s comfortably exceeds robustApiCall's
+// 3-attempt network backoff so a legitimate slow send isn't cut short.
+const OBLIGATION_ESCALATE_SEND_DEADLINE_MS = 45_000
+// Escalate-grace window. A slow / background-worker / multi-segment turn ends
+// (the in-flight gate clears) BEFORE its trailing answer's reply lands, and the
+// 5s sweep would re-present/escalate in that gap — a false "⚠️ I may have missed
+// this" on a message that's actively being answered (fuzz-confirmed on v0.14.62:
+// ~14% of marko's no-reply turn-ends had the answer in flight). An obligation
+// whose handling turn ended < this ago is skipped by decideAtIdle, giving the
+// trailing answer's close a beat to fire. Bounded: each re-present is itself a
+// turn that re-stamps once, representCount is capped → the ladder still
+// terminates. 45s > the observed "answer lands within ~60s, usually <40s" gap.
+// Kill switch: SWITCHROOM_OBLIGATION_ESCALATE_GRACE_MS=0 → pre-grace behaviour.
+const OBLIGATION_ESCALATE_GRACE_MS = (() => {
+  const raw = process.env.SWITCHROOM_OBLIGATION_ESCALATE_GRACE_MS
+  if (raw == null || raw === '') return 45_000
+  const n = Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : 45_000
+})()
+
+// ─── Mid-turn auto-classify (steer-vs-queue), SHADOW mode ─────────────────────
+// Today a no-prefix mid-turn message always QUEUES. autoClassifyMidTurnInbound
+// (auto-classify-mid-turn.ts) is the basis for a smarter default using
+// topic-vs-active-turn + reply-recency. Phase 1 ships SHADOW-ONLY: when this
+// flag is on we COMPUTE + LOG what we'd decide (decision/reason/same_topic/
+// ms_since_out) but the behaviour is UNCHANGED (still queue) — to gather the
+// real-world distribution (how often mid-turn messages are same-topic
+// continuations vs cross-topic, and the recency spread) before any action flips
+// on. Default OFF → zero overhead. The action windows below stay 0 in shadow.
+const AUTOCLASSIFY_MIDTURN_SHADOW = process.env.SWITCHROOM_AUTOCLASSIFY_MIDTURN_SHADOW === '1'
+// Per-(chat,thread) wall-clock ms of the agent's LAST visible output — the
+// recency clock the classifier uses (NOT turn age: a long actively-narrating
+// worker turn must not read "stale"). Stamped beside signalTracker.noteOutbound.
+// LRU-bounded so a long-lived gateway with many topics can't grow unboundedly.
+const lastAgentOutputAt = new Map<string, number>()
+const LAST_OUTPUT_MAX_KEYS = 512
+function noteAgentOutputAt(key: string, ts: number): void {
+  lastAgentOutputAt.delete(key) // re-insert → most-recently-used at the tail
+  lastAgentOutputAt.set(key, ts)
+  if (lastAgentOutputAt.size > LAST_OUTPUT_MAX_KEYS) {
+    const oldest = lastAgentOutputAt.keys().next().value
+    if (oldest !== undefined) lastAgentOutputAt.delete(oldest)
+  }
+}
 // Durable snapshot of the open obligation set on the persistent per-agent
 // volume (STATE_DIR = /state/agent/telegram in prod). Closes the restart hole:
 // the in-memory ledger alone empties on restart and the spool's boot-replay
@@ -1982,6 +2041,29 @@ let pendingDeferredInterrupt: PendingDeferredInterrupt | null = null
  * Idempotent: nulls the slot and clears the timer before doing any work so a
  * boundary event and the timeout can't double-fire.
  */
+/**
+ * An `!` interrupt SIGINT-kills the in-flight turn. That turn was handling a
+ * user message with an open obligation, and the killed turn does NOT reliably
+ * emit turn_end (so endCurrentTurnAtomic never closes it) — so without this the
+ * obligation survives and the idle sweep later re-presents/escalates "you have
+ * an earlier message you never answered" for a question the user EXPLICITLY
+ * cancelled. An interrupt is a deliberate redirect, so closing that obligation
+ * is the correct terminal (the user chose to interrupt; they can re-ask). Only
+ * the interrupted turn's OWN obligation is closed — queued siblings (other open
+ * obligations) are untouched. No-op when the flag is off, no turn is in flight,
+ * or the turn isn't a tracked obligation (synthetic / already closed).
+ */
+function cancelInterruptedObligation(): void {
+  if (!OBLIGATION_LEDGER_ENABLED) return
+  const turn = currentTurn
+  if (turn == null) return
+  if (obligationLedger.close(turn.turnId)) {
+    process.stderr.write(
+      `telegram gateway: obligation cancelled by interrupt origin=${turn.turnId}\n`,
+    )
+  }
+}
+
 async function fireDeferredInterrupt(reason: 'boundary' | 'timeout'): Promise<void> {
   const pending = pendingDeferredInterrupt
   if (pending == null) return
@@ -2010,6 +2092,10 @@ async function fireDeferredInterrupt(reason: 'boundary' | 'timeout'): Promise<vo
     process.stderr.write(`telegram gateway: deferred-interrupt SIGINT failed: ${(err as Error).message}\n`)
   }
 
+  // The SIGINT just killed the in-flight turn — cancel its obligation so the
+  // interrupted (user-redirected) question isn't re-presented/escalated later.
+  cancelInterruptedObligation()
+
   // Deliver the replacement body as a fresh turn to the freshly-killed
   // bridge — same sendToAgent + buffer-on-miss primitive the synchronous
   // interrupt carve-out uses at the handleInbound delivery site.
@@ -2409,8 +2495,17 @@ function endCurrentTurnAtomic(turn: CurrentTurn): void {
   // finalAnswerDelivered===false → stays open → re-presented (the intended
   // catch). close() is a no-op for synthetic turns (turnId not in the ledger).
   // No-op when the flag is off.
-  if (OBLIGATION_LEDGER_ENABLED && turn.finalAnswerDelivered) {
-    obligationLedger.close(turn.turnId)
+  if (OBLIGATION_LEDGER_ENABLED) {
+    if (turn.finalAnswerDelivered) {
+      obligationLedger.close(turn.turnId)
+    } else {
+      // Turn ended WITHOUT a final answer. If this turn was handling an open
+      // obligation, stamp its grace clock so the idle sweep waits before
+      // re-presenting/escalating — a slow/worker answer may still be in flight
+      // (the over-escalation fix). No-op when turn.turnId isn't an open
+      // obligation (synthetic / already-closed turn).
+      obligationLedger.noteTurnEnded(turn.turnId, Date.now())
+    }
   }
   // Component 2 — clear any prior no-reply drain timer for this turn; a
   // fresh end re-evaluates below. (Idempotent — null when never armed.)
@@ -3745,6 +3840,17 @@ const pendingStateReaper = setInterval(() => {
   for (const [k, v] of awaitingAuthCodeAt) {
     if (now - v > AUTH_CODE_CONTEXT_TTL_MS) awaitingAuthCodeAt.delete(k)
   }
+  // Microsoft connect flows self-expire at the device code's own expiry
+  // (~15 min) — sweep past that + grace so an abandoned card doesn't pin
+  // its key. Setting cancelled makes any still-running poll bail. Placed
+  // AFTER the OAuth-code cluster above, which secret-detect-oauth-code.
+  // test.ts pins as contiguous within the first 800 chars of the reaper.
+  for (const [k, v] of pendingMicrosoftConnectFlows) {
+    if (now - v.startedAt > v.device.expires_in * 1000 + 30_000) {
+      v.cancelled = true
+      pendingMicrosoftConnectFlows.delete(k)
+    }
+  }
   // Auth-refresh throttle entries decay quickly (5s window); sweep
   // anything older than 60s so abandoned snapshot messages don't pin
   // their key forever.
@@ -4874,16 +4980,45 @@ const pendingInboundBuffer = createPendingInboundBuffer({ spool: inboundSpool })
 // OPEN via meta.source; reuses tested delivery). Bounded: after maxRepresents,
 // escalate to ONE operator-visible "did I miss this?" and close — no loop.
 // No-op unless the flag is on; gated on the same idle predicate as the drains.
+// DETERMINISM (closed-form, not sampled). The obligation ledger itself
+// (obligation-ledger.ts) is a finite FSM with a total transition function and a
+// strictly-decreasing measure μ = (REPRESENT_MAX - representCount) +
+// (ESCALATE_MAX - escalateAttempts): every markRepresented/markEscalateAttempt
+// decreases μ, both terms are bounded below, and at the floor the only move is
+// close → terminal. So on the FSM, every OPEN reaches answered | escalation-
+// delivered | bounded give-up (no cycle re-increments a counter). This sweep is
+// the FSM's driver; its termination rests on three liveness facts, all bounded:
+//   (1) the 5s setInterval keeps firing;
+//   (2) the gate (turnInFlightForGate) opens — claudeBusyKeys is cleared at
+//       turn-end (purgeReactionTracking / releaseTurnBufferGate), on bridge
+//       disconnect (disconnect-flush.ts), and by the 300s silence-poke watchdog;
+//   (3) the escalation send settles — bounded BY CONSTRUCTION via withDeadline
+//       below (grammy has no request timeout, so an unbounded send was the one
+//       way an obligation could get stuck OPEN forever — now closed).
+// The only residual liveness assumption is the bridge eventually reconnecting /
+// the process restarting, which the entire gateway's inbound delivery already
+// depends on and which durable spool + boot-replay make self-healing.
 function obligationSweep(): void {
   if (!OBLIGATION_LEDGER_ENABLED) return
   if (!obligationLedger.hasOpen()) return
   if (turnInFlightForGate()) return // a turn is running — let it finish/answer
   const agent = process.env.SWITCHROOM_AGENT_NAME ?? ''
-  if (pendingInboundBuffer.depth(agent) > 0) return // existing drain runs first; avoids double-present
-  const decision = obligationLedger.decideAtIdle()
+  // Grace window: skip an obligation whose handling turn ended < grace ago — its
+  // trailing slow/worker answer may still be landing (over-escalation fix).
+  const decision = obligationLedger.decideAtIdle(
+    OBLIGATION_ESCALATE_GRACE_MS > 0
+      ? { now: Date.now(), graceMs: OBLIGATION_ESCALATE_GRACE_MS }
+      : undefined,
+  )
   const o = decision.obligation
   if (decision.action === 'none' || o == null) return
   if (decision.action === 'represent') {
+    // Re-present goes through the bridge → buffer. Only the represent path is
+    // gated on an empty buffer (let the existing drain run first, avoid
+    // double-presenting). Escalation below is NOT gated on the buffer — it is a
+    // direct Telegram send, independent of the bridge, so a represent stranded
+    // behind a dead bridge can never block the operator nudge.
+    if (pendingInboundBuffer.depth(agent) > 0) return
     pendingInboundBuffer.push(agent, buildObligationRepresentInbound(o, Date.now()))
     const attempt = obligationLedger.markRepresented(o.originTurnId)
     process.stderr.write(
@@ -4899,45 +5034,30 @@ function obligationSweep(): void {
   // (dead topic even after thread-fallback, blocked bot) is bounded by
   // OBLIGATION_ESCALATE_MAX → close best-effort (the user is unreachable, so a
   // bounded give-up beats an infinite loop / a boot-surviving poison record).
-  if (obligationEscalateInFlight.has(o.originTurnId)) return // a send is already awaiting
-  const escId = o.originTurnId
-  const attempt = obligationLedger.markEscalateAttempt(escId)
-  obligationEscalateInFlight.add(escId)
-  process.stderr.write(
-    `telegram gateway: obligation escalating (exhausted ${OBLIGATION_REPRESENT_MAX} re-presents) origin=${escId} attempt=${attempt}/${OBLIGATION_ESCALATE_MAX}\n`,
-  )
-  // retryWithThreadFallback: a stale/renumbered topic returns THREAD_NOT_FOUND;
-  // retry WITHOUT the thread so the nudge still lands in the chat (the #2096
-  // pattern) instead of being permanently undeliverable to a dead topic.
-  void retryWithThreadFallback(
-    robustApiCall,
-    (tid) =>
-      bot.api.sendMessage(o.chatId, obligationEscalationText(o), {
-        ...(tid != null ? { message_thread_id: tid } : {}),
-      }),
-    { threadId: o.threadId, chat_id: o.chatId, verb: 'obligation.escalate' },
-  )
-    .then(() => {
-      obligationLedger.close(escId)
-      process.stderr.write(
-        `telegram gateway: obligation escalation delivered + closed origin=${escId}\n`,
-      )
-    })
-    .catch((err) => {
-      if (attempt >= OBLIGATION_ESCALATE_MAX) {
-        obligationLedger.close(escId)
-        process.stderr.write(
-          `telegram gateway: obligation escalation PERMANENTLY undeliverable after ${attempt} attempts — closing best-effort origin=${escId}: ${err}\n`,
-        )
-      } else {
-        process.stderr.write(
-          `telegram gateway: obligation escalation send failed (attempt ${attempt}/${OBLIGATION_ESCALATE_MAX}), retrying next sweep origin=${escId}: ${err}\n`,
-        )
-      }
-    })
-    .finally(() => {
-      obligationEscalateInFlight.delete(escId)
-    })
+  // Drive one escalation attempt. The send is a direct Telegram nudge
+  // (retryWithThreadFallback: a stale/renumbered topic → THREAD_NOT_FOUND retries
+  // thread-less, the #2096 pattern). driveEscalation guards against concurrent
+  // sends, bounds the send with withDeadline (so a hung send can't leak the
+  // in-flight flag and wedge the obligation OPEN), closes only after a successful
+  // send, and bounds permanent failures to a best-effort close. Extracted so the
+  // hang → bounded → terminal path is executable in escalation-drive.test.ts —
+  // the path neither mtcute (can't hang Telegram) nor a synchronous test reaches.
+  void driveEscalation({
+    escId: o.originTurnId,
+    inFlight: obligationEscalateInFlight,
+    ledger: obligationLedger,
+    send: () =>
+      retryWithThreadFallback(
+        robustApiCall,
+        (tid) =>
+          bot.api.sendMessage(o.chatId, obligationEscalationText(o), {
+            ...(tid != null ? { message_thread_id: tid } : {}),
+          }),
+        { threadId: o.threadId, chat_id: o.chatId, verb: 'obligation.escalate' },
+      ),
+    maxAttempts: OBLIGATION_ESCALATE_MAX,
+    deadlineMs: OBLIGATION_ESCALATE_SEND_DEADLINE_MS,
+  })
 }
 if (!STATIC && OBLIGATION_LEDGER_ENABLED) {
   setInterval(obligationSweep, OBLIGATION_SWEEP_MS).unref()
@@ -6443,6 +6563,10 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   // silence-poke clock so the next poke is measured from this send.
   signalTracker.noteOutbound(statusKey(chat_id, threadId), Date.now())
   silencePoke.noteOutbound(statusKey(chat_id, threadId), Date.now())
+  // Mid-turn auto-classify recency clock: the agent just produced visible output
+  // in this chat/thread (cross-turn, unlike silencePoke's per-turn lastOutboundAt).
+  // Only maintained when the shadow flag is on → truly zero overhead by default.
+  if (AUTOCLASSIFY_MIDTURN_SHADOW) noteAgentOutputAt(statusKey(chat_id, threadId), Date.now())
   // PR3b-cutover: feed lastOutboundAt to the delivery machine so its
   // TTL `tick` suppresses the fallback for a long-but-active turn
   // (model streaming past 5 min) — parity with silencePoke's own
@@ -10748,6 +10872,9 @@ async function handleInbound(
       } catch (err) {
         process.stderr.write(`telegram gateway: interrupt-marker SIGINT failed: ${(err as Error).message}\n`)
       }
+      // The SIGINT just killed the in-flight turn — cancel its obligation so the
+      // interrupted (user-redirected) question isn't re-presented/escalated later.
+      cancelInterruptedObligation()
     }
     if (interrupt.emptyBody) {
       // #1075: thread-id-bearing — route through swallowingApiCall so
@@ -11354,6 +11481,33 @@ async function handleInbound(
     isSteering = priorTurnInFlight && isSteerPrefix
     if (priorTurnInFlight) priorTurnStartedAt = activeTurnStartedAt.get(key)
 
+    // Mid-turn auto-classify SHADOW: compute what a topic+recency classifier
+    // WOULD decide and log it — behaviour is UNCHANGED (isSteering above is
+    // untouched). Gathers the real-world distribution (same-topic continuation
+    // vs cross-topic, recency spread) to tune auto-steer before it ever acts.
+    // No-op unless the shadow flag is on AND a turn is in flight (the only case
+    // a steer-vs-queue decision is meaningful).
+    if (AUTOCLASSIFY_MIDTURN_SHADOW && priorTurnInFlight) {
+      const lastOut = lastAgentOutputAt.get(key)
+      const msSinceOut = lastOut != null ? Date.now() - lastOut : null
+      const shadow = autoClassifyMidTurnInbound({
+        isSteerPrefix,
+        isQueuePrefix: isQueuedPrefix,
+        priorTurnInFlight,
+        isDm: isDmChatId(chat_id),
+        incomingThreadId: messageThreadId ?? null,
+        activeTurnThreadId: currentTurn?.sessionThreadId ?? null,
+        msSinceLastAgentOutput: msSinceOut,
+        dmSteerWindowMs: 0, // DM auto-steer stays off (the April regime)
+        topicSteerWindowMs: 8_000, // candidate window — what we're tuning
+      })
+      process.stderr.write(
+        `telegram gateway: autoclassify-shadow chat_id=${chat_id} ` +
+        `would=${shadow.decision} reason=${shadow.reason} same_topic=${shadow.sameTopic ?? '-'} ` +
+        `ms_since_out=${msSinceOut ?? '-'} actual=${isSteering ? 'steer' : 'queue'}\n`,
+      )
+    }
+
     if (access.statusReactions !== false) {
       if (isSteering) {
         // Explicit steer: mark with 🤝 on the inbound message; leave the
@@ -14385,6 +14539,226 @@ async function runQuotaWatch(): Promise<void> {
   }
 }
 
+/**
+ * Edit a Microsoft connect card from the BACKGROUND device-code poll
+ * (no `ctx` — we hold the chat+message id). Wrapped in robustApiCall;
+ * swallows failures (a deleted card / closed topic must not crash the
+ * poll). RFC #1873 Phase 2.
+ */
+async function editMicrosoftConnectCard(
+  chatId: number | string,
+  messageId: number,
+  html: string,
+): Promise<void> {
+  await robustApiCall(
+    // allow-raw-bot-api: background connect-card edit by message id (no thread_id; not the reply chunk loop)
+    () => bot.api.editMessageText(chatId, messageId, html, {
+      parse_mode: 'HTML',
+      link_preview_options: { is_disabled: true },
+    }),
+    { chat_id: String(chatId), verb: 'microsoftConnectCard' },
+  ).catch(() => {})
+}
+
+/**
+ * Background half of `/connect microsoft`: poll Microsoft for consent,
+ * register the account with the broker, then edit the card to the
+ * outcome. Fire-and-forget from the command handler.
+ */
+async function finalizeMicrosoftConnect(key: string): Promise<void> {
+  const flow = pendingMicrosoftConnectFlows.get(key)
+  if (!flow) return
+  const agentName = getMyAgentName()
+  const result = await runMicrosoftConnectPoll(flow)
+  // A `/connect cancel` (command or button) between consent and write
+  // already edited the card and dropped the entry — don't clobber it.
+  if (result.kind === 'cancelled' || !pendingMicrosoftConnectFlows.has(key)) {
+    pendingMicrosoftConnectFlows.delete(key)
+    return
+  }
+  pendingMicrosoftConnectFlows.delete(key)
+
+  let html: string
+  if (result.kind === 'connected') {
+    html =
+      `✅ <b>Connected</b> <code>${escapeHtmlForTg(result.account)}</code> ` +
+      `(${result.accountType}).\n\n` +
+      `To let <b>${escapeHtmlForTg(agentName)}</b> use it, run on the host:\n` +
+      `<code>switchroom auth microsoft enable ${escapeHtmlForTg(result.account)} ${escapeHtmlForTg(agentName)}</code>\n` +
+      `then restart ${escapeHtmlForTg(agentName)}.`
+  } else if (result.kind === 'no-refresh-token') {
+    html =
+      `⚠ Microsoft returned no refresh token (the account would expire in ~1h), ` +
+      `so it was not registered. Try <code>/connect microsoft</code> again, or ` +
+      `connect from the host CLI.`
+  } else {
+    html =
+      `❌ <b>Connect failed:</b> ${escapeHtmlForTg(result.message)}\n\n` +
+      `<i>Work/school accounts can't use the phone flow at /common — connect those ` +
+      `from the host: <code>switchroom auth microsoft account add &lt;email&gt;</code>.</i>`
+  }
+  await editMicrosoftConnectCard(flow.cardChatId, flow.cardMessageId, html)
+}
+
+/**
+ * `/connect microsoft` — Telegram-native device-code connect for a
+ * Microsoft account (RFC #1873 Phase 2). The user signs in on their
+ * phone; we register the account with the auth-broker (shipped default
+ * app unless the operator BYO'd one). Admin-gated like `/auth add`.
+ * `/connect cancel` aborts a pending flow. Google stays host-CLI.
+ */
+bot.command('connect', async ctx => {
+  // Credential-plane admin is OPERATOR-PRIVATE (WS7-F2 / #1408), exactly
+  // like `/auth`: honor `/connect` ONLY in a private chat from a strict
+  // `access.allowFrom` sender — never the group-permissive
+  // `isAuthorizedSender` (an empty group `allowFrom` = allow-all, so a
+  // forum member could otherwise bind THEIR OWN Microsoft account as the
+  // agent's credential). The agent-`admin:true` flag check below is
+  // orthogonal and the broker enforces it server-side on add-account.
+  const senderId = String(ctx.from?.id ?? '')
+  const operatorPrivate =
+    ctx.chat?.type === 'private' && loadAccess().allowFrom.includes(senderId)
+  if (!operatorPrivate) {
+    if (ctx.chat?.type !== 'private') {
+      process.stderr.write(
+        `telegram gateway: /connect refused (not operator-private) agent=${process.env.SWITCHROOM_AGENT_NAME ?? '-'} chat=${ctx.chat?.type ?? '?'} sender=${senderId}\n`,
+      )
+      await switchroomReply(
+        ctx,
+        `⚠️ <code>/connect</code> links account credentials — it is <b>operator-private</b>. ` +
+          `Send it as a direct message to me from your operator account (a private chat where ` +
+          `your Telegram ID is on the access allowlist), not in a group or forum.`,
+        { html: true },
+      ).catch(() => {})
+    }
+    return
+  }
+
+  const arg = String(ctx.match ?? '').trim().toLowerCase()
+  const chatId = String(ctx.chat?.id ?? '')
+  const key = chatKey(chatId, ctx.message?.message_thread_id ?? null) as string
+
+  // Agent-`admin:true` gate (orthogonal to operator-private above; same
+  // source as /auth + the broker's server-side add-account enforcement).
+  let isAdmin = false
+  try {
+    const cfg = loadSwitchroomConfig()
+    const me = (cfg as unknown as { agents?: Record<string, { admin?: boolean }> })
+      ?.agents?.[getMyAgentName()]
+    isAdmin = me?.admin === true
+  } catch { /* non-admin is the safe default */ }
+  if (!isAuthAdmin({ isAdmin })) {
+    await switchroomReply(
+      ctx,
+      `<b>Not authorized.</b> <code>/connect</code> requires this agent to have ` +
+        `<code>admin: true</code> in switchroom.yaml.`,
+      { html: true },
+    )
+    return
+  }
+
+  if (arg === 'cancel') {
+    const existing = pendingMicrosoftConnectFlows.get(key)
+    if (!existing) {
+      await switchroomReply(ctx, '<i>No pending connect flow in this chat.</i>', { html: true })
+      return
+    }
+    existing.cancelled = true
+    pendingMicrosoftConnectFlows.delete(key)
+    await switchroomReply(ctx, 'Cancelled.', { html: true })
+    return
+  }
+
+  if (arg !== '' && arg !== 'microsoft' && arg !== 'ms') {
+    await switchroomReply(
+      ctx,
+      `<b>Usage:</b> <code>/connect microsoft</code> to link a Microsoft account ` +
+        `(Outlook / Office 365), or <code>/connect cancel</code>.\n` +
+        `<i>Google accounts are connected from the host CLI.</i>`,
+      { html: true },
+    )
+    return
+  }
+
+  if (pendingMicrosoftConnectFlows.has(key)) {
+    await switchroomReply(
+      ctx,
+      '<i>A Microsoft connect flow is already in progress here. Finish it on your phone, ' +
+        'or send <code>/connect cancel</code>.</i>',
+      { html: true },
+    )
+    return
+  }
+
+  let configClientId: string | undefined
+  let orgMode = false
+  try {
+    const cfg = loadSwitchroomConfig() as unknown as {
+      microsoft_workspace?: { microsoft_client_id?: string; org_mode?: boolean }
+    }
+    configClientId = cfg?.microsoft_workspace?.microsoft_client_id
+    orgMode = cfg?.microsoft_workspace?.org_mode === true
+  } catch { /* fall back to the shipped default */ }
+
+  const started = await startMicrosoftConnect({ configClientId, orgMode })
+  if (started.kind === 'byo-vault') {
+    await switchroomReply(
+      ctx,
+      `<b>Can't connect from chat:</b> this install uses a vaulted custom Microsoft ` +
+        `app (<code>${escapeHtmlForTg(started.ref)}</code>) only the host CLI can read. ` +
+        `Run <code>switchroom auth microsoft account add &lt;email&gt;</code> on the host.`,
+      { html: true },
+    )
+    return
+  }
+  if (started.kind === 'error') {
+    await switchroomReply(
+      ctx,
+      `<b>/connect failed:</b> ${escapeHtmlForTg(started.message)}`,
+      { html: true },
+    )
+    return
+  }
+
+  const appNote =
+    started.source === 'default'
+      ? "<i>Using switchroom's shipped Microsoft app.</i>"
+      : '<i>Using your configured Microsoft app.</i>'
+  const keyboard = new InlineKeyboard()
+    .url('🔐 Sign in to Microsoft', started.device.verification_uri)
+    .row()
+    .text('✖ Cancel', `cn:cancel:${key}`)
+  const sent = await ctx.reply(
+    `🔗 <b>Connect a Microsoft account</b>\n\n` +
+      `1. Tap <b>Sign in to Microsoft</b> below.\n` +
+      `2. Enter this code: <code>${escapeHtmlForTg(started.device.user_code)}</code>\n` +
+      `3. Approve the requested permissions (Mail, Calendar, Files).\n\n` +
+      `I'll confirm here once it's connected (within ~15 min).\n${appNote}`,
+    {
+      parse_mode: 'HTML',
+      link_preview_options: { is_disabled: true },
+      reply_markup: keyboard,
+      ...(ctx.message?.message_thread_id != null
+        ? { message_thread_id: ctx.message.message_thread_id }
+        : {}),
+    },
+  )
+
+  pendingMicrosoftConnectFlows.set(key, {
+    initiatedBy: String(ctx.from?.id ?? ''),
+    cardChatId: ctx.chat!.id,
+    cardMessageId: sent.message_id,
+    device: started.device,
+    clientId: started.clientId,
+    scopes: started.scopes,
+    startedAt: Date.now(),
+    cancelled: false,
+  })
+
+  // Background: poll Microsoft, register the account, edit the card.
+  void finalizeMicrosoftConnect(key)
+})
+
 bot.command("auth", async ctx => {
   // sec WS7-F2b (#1394): `/auth` drives the auth-broker credential
   // lifecycle (`/auth add` mints/attaches an Anthropic account token,
@@ -17130,6 +17504,37 @@ bot.on('callback_query:data', async ctx => {
     return
   }
 
+  // `cn:cancel:<key>` — cancel a pending Microsoft connect flow (the
+  // Cancel button on the /connect card). RFC #1873 Phase 2.
+  if (data.startsWith('cn:')) {
+    const access = loadAccess()
+    const senderId = String(ctx.from?.id ?? '')
+    if (!access.allowFrom.includes(senderId)) {
+      await ctx.answerCallbackQuery({ text: 'Not authorized.' })
+      return
+    }
+    const rest = data.slice('cn:'.length)
+    const sep = rest.indexOf(':')
+    const action = sep >= 0 ? rest.slice(0, sep) : rest
+    const flowKey = sep >= 0 ? rest.slice(sep + 1) : ''
+    if (action === 'cancel') {
+      const pending = pendingMicrosoftConnectFlows.get(flowKey)
+      if (pending) {
+        pending.cancelled = true
+        pendingMicrosoftConnectFlows.delete(flowKey)
+      }
+      await ctx.answerCallbackQuery({ text: 'Connect cancelled.' })
+      await ctx
+        .editMessageText('Microsoft connect cancelled.', {
+          reply_markup: { inline_keyboard: [] },
+        })
+        .catch(() => {})
+    } else {
+      await ctx.answerCallbackQuery()
+    }
+    return
+  }
+
   // RFC B §6.1: apv:<request_id>:<choice>[:<param>] — approval kernel taps.
   // Routed through the generic kernel handler so any surface that uses
   // buildApprovalCard inherits consume → record → confirmation UX without