switchroom 0.14.61 → 0.14.62

package/telegram-plugin/gateway/auth-broker-client.ts

@@ -11,6 +11,7 @@
  */
 
 import { AuthBrokerClient as BrokerClient, type AddAccountCredentials } from '../../src/auth/broker/client.js'
+import type { ProviderName } from '../../src/auth/broker/protocol.js'
 import type { AuthBrokerClient } from './auth-command.js'
 
 /**
@@ -56,21 +57,30 @@ export async function getAuthBrokerClient(
 }
 
 /**
- * Add an account via the broker. Used exclusively by the `/auth add`
- * chat flow — the narrow {@link AuthBrokerClient} surface in
- * `auth-command.ts` deliberately omits `addAccount` because the verb
- * is gateway-routed (not handler-routed). Constructs and closes a
- * one-shot {@link BrokerClient} so the gateway doesn't need a
- * long-lived handle just for this verb.
+ * Add an account via the broker. Used by the `/auth add` chat flow
+ * (Anthropic) and the `/connect microsoft` device-code flow — the narrow
+ * {@link AuthBrokerClient} surface in `auth-command.ts` deliberately
+ * omits `addAccount` because the verb is gateway-routed (not
+ * handler-routed). Constructs and closes a one-shot {@link BrokerClient}
+ * so the gateway doesn't need a long-lived handle just for this verb.
+ *
+ * `provider` defaults to Anthropic (back-compat with the `/auth add`
+ * caller, which omits it). The device-code flow passes `"microsoft"`
+ * with a `MicrosoftAddAccountCredentials` payload.
  */
 export async function addAccountViaBroker(
   label: string,
   credentials: AddAccountCredentials,
-  opts: { replace?: boolean } = {},
+  opts: { replace?: boolean; provider?: ProviderName } = {},
 ): Promise<{ label: string; expiresAt?: number }> {
   const broker = new BrokerClient()
   try {
-    return await broker.addAccount(label, credentials, opts.replace)
+    return await broker.addAccount(
+      label,
+      credentials,
+      opts.replace,
+      opts.provider,
+    )
   } finally {
     await broker.close()
   }

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 {
@@ -284,6 +289,7 @@ import {
   obligationEscalationText,
 } from './obligation-ledger.js'
 import { loadObligations, persistObligations } from './obligation-store.js'
+import { withDeadline } from './with-deadline.js'
 import { createInboundSpool } from './inbound-spool.js'
 import { purgeStaleTurnsForChat } from './turn-state-purge.js'
 import { decideInboundDelivery } from './inbound-delivery-gate.js'
@@ -1406,6 +1412,17 @@ 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
 // 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
@@ -3745,6 +3762,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 +4902,39 @@ 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()
   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(
@@ -4909,13 +4960,22 @@ function obligationSweep(): void {
   // 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' },
+  // withDeadline: grammy/fetch impose no request timeout and `.finally` (which
+  // clears the in-flight flag) only runs on settle — so a hung send would leak
+  // the flag forever and wedge this obligation OPEN. Racing against a deadline
+  // guarantees the chain settles, the flag always clears, and a hang becomes a
+  // bounded reject handled exactly like any other failed attempt.
+  void withDeadline(
+    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' },
+    ),
+    OBLIGATION_ESCALATE_SEND_DEADLINE_MS,
+    'obligation escalation send timed out',
   )
     .then(() => {
       obligationLedger.close(escId)
@@ -14385,6 +14445,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 +17410,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

package/telegram-plugin/gateway/microsoft-connect-flow.ts

@@ -0,0 +1,226 @@
+/**
+ * Telegram-native Microsoft connect — device-code flow (RFC #1873 /
+ * out-of-box, Phase 2).
+ *
+ * The headline "connect from your phone" path: a user runs
+ * `/connect microsoft`, the gateway shows a card with a Microsoft
+ * sign-in link + a short code, the user approves on their phone, and the
+ * gateway registers the resulting account with the auth-broker — no host
+ * shell, no Azure portal (the shipped default app is used unless the
+ * operator BYO'd one).
+ *
+ * This module is the framework-agnostic core: it talks to Microsoft's
+ * device-code endpoints (RFC 8628, engine in `src/microsoft/oauth.ts`)
+ * and the auth-broker, and returns plain data. The gateway owns the
+ * Telegram surface (card rendering, edits, callbacks). All network +
+ * broker boundaries are injectable so the flow is testable without
+ * hitting Microsoft or a live broker, and it contains NO raw bot.api
+ * calls (the bot-api-wrapping lint trap lives only in the gateway).
+ *
+ * Mirrors `auth-add-flow.ts` (the Anthropic `/auth add` template) but
+ * needs no child subprocess and no pasted code: device-code consent
+ * happens entirely on Microsoft's domain, so nothing secret is ever
+ * pasted into chat (strictly better than paste-back — no redaction
+ * needed). Personal Microsoft accounts (outlook.com/hotmail) are the
+ * clean case at `/common`; a work/school account that fails device-code
+ * at `/common` surfaces a clear "use the host CLI" error (the documented
+ * "personal-first, work best-effort" boundary).
+ */
+
+import {
+  requestDeviceCode as realRequestDeviceCode,
+  pollDeviceToken as realPollDeviceToken,
+  type MicrosoftDeviceCodeResponse,
+  type MicrosoftOAuthClientConfig,
+} from '../../src/microsoft/oauth.js'
+import { selectMicrosoftScopes } from '../../src/microsoft/scopes.js'
+import { buildMicrosoftCredentials } from '../../src/microsoft/credentials.js'
+import { resolveMicrosoftClientId } from '../../src/auth/default-oauth-clients.js'
+import { isVaultReference } from '../../src/vault/resolver.js'
+import { addAccountViaBroker } from './auth-broker-client.js'
+import type { MicrosoftAddAccountCredentials } from '../../src/auth/broker/client.js'
+
+/** A connect flow in flight, keyed by `chatKey(chatId, threadId)`. */
+export interface PendingMicrosoftConnectFlow {
+  /** Telegram user id that started the flow (consent owner; Phase 3). */
+  initiatedBy: string
+  /** Card we posted, so the poll loop can edit it on completion. */
+  cardChatId: number | string
+  cardMessageId: number
+  device: MicrosoftDeviceCodeResponse
+  clientId: string
+  scopes: string[]
+  startedAt: number
+  /** Flipped by cancel so the in-flight poll bails without writing. */
+  cancelled: boolean
+}
+
+export const pendingMicrosoftConnectFlows = new Map<
+  string,
+  PendingMicrosoftConnectFlow
+>()
+
+export interface MicrosoftConnectDeps {
+  /** `config.microsoft_workspace?.microsoft_client_id` (may be a vault: ref). */
+  configClientId?: string
+  orgMode?: boolean
+  requestDeviceCode?: (
+    cfg: MicrosoftOAuthClientConfig,
+  ) => Promise<MicrosoftDeviceCodeResponse>
+  pollDeviceToken?: typeof realPollDeviceToken
+  addAccount?: (
+    label: string,
+    credentials: MicrosoftAddAccountCredentials,
+    opts: { replace?: boolean; provider: 'microsoft' },
+  ) => Promise<{ label: string; expiresAt?: number }>
+  now?: () => number
+}
+
+export type StartResult =
+  | {
+      kind: 'started'
+      device: MicrosoftDeviceCodeResponse
+      clientId: string
+      scopes: string[]
+      /** 'default' = shipped app; 'config'/'env' = BYO. */
+      source: 'env' | 'config' | 'default'
+    }
+  | {
+      // The operator BYO'd a Microsoft client via a vault: reference,
+      // which the gateway can't resolve in-process — host CLI only.
+      kind: 'byo-vault'
+      ref: string
+    }
+  | { kind: 'error'; message: string }
+
+/**
+ * Request a device code and return the data the gateway needs to render
+ * the connect card. Does NOT mutate the pending map — the gateway stores
+ * the pending entry (with the card message id) after it posts the card.
+ */
+export async function startMicrosoftConnect(
+  deps: MicrosoftConnectDeps = {},
+): Promise<StartResult> {
+  const resolved = resolveMicrosoftClientId(deps.configClientId)
+
+  // A vaulted BYO client_id can't be resolved from the gateway process
+  // (the gateway has no passphrase / vault-broker read path here). The
+  // shipped default and literal config values are fine.
+  if (isVaultReference(resolved.clientId)) {
+    return { kind: 'byo-vault', ref: resolved.clientId }
+  }
+
+  const scopes = selectMicrosoftScopes(deps.orgMode ?? false)
+  const cfg: MicrosoftOAuthClientConfig = {
+    client_id: resolved.clientId,
+    scopes,
+  }
+  try {
+    const device = await (deps.requestDeviceCode ?? realRequestDeviceCode)(cfg)
+    return {
+      kind: 'started',
+      device,
+      clientId: resolved.clientId,
+      scopes,
+      source: resolved.source,
+    }
+  } catch (err) {
+    return { kind: 'error', message: (err as Error).message }
+  }
+}
+
+export type PollResult =
+  | {
+      kind: 'connected'
+      account: string
+      accountType: 'personal' | 'work'
+      expiresAt: number
+    }
+  | { kind: 'cancelled' }
+  | { kind: 'no-refresh-token' }
+  | { kind: 'failed'; message: string }
+
+/**
+ * Poll Microsoft for consent completion, then register the account with
+ * the broker. Blocks (with the device-code `interval`) up to the
+ * device's `expires_in`. Returns a discriminated result the gateway
+ * turns into a card edit. Reads `flow.cancelled` after the (potentially
+ * long) poll so a `/connect cancel` between consent and write is
+ * honored.
+ */
+export async function runMicrosoftConnectPoll(
+  flow: Pick<
+    PendingMicrosoftConnectFlow,
+    'device' | 'clientId' | 'scopes' | 'cancelled'
+  >,
+  deps: MicrosoftConnectDeps = {},
+): Promise<PollResult> {
+  const now = deps.now ?? Date.now
+  const cfg: MicrosoftOAuthClientConfig = {
+    client_id: flow.clientId,
+    scopes: flow.scopes,
+  }
+
+  let tokens
+  try {
+    tokens = await (deps.pollDeviceToken ?? realPollDeviceToken)(
+      cfg,
+      flow.device,
+      { now },
+    )
+  } catch (err) {
+    return { kind: 'failed', message: (err as Error).message }
+  }
+
+  if (flow.cancelled) return { kind: 'cancelled' }
+
+  const built = buildMicrosoftCredentials({
+    tokens,
+    clientId: flow.clientId,
+    accountEmail: '', // device-code learns the email from the id_token
+    fallbackScope: flow.scopes.join(' '),
+    now,
+  })
+
+  // offline_access is requested, so a refresh token is expected; without
+  // one the account dies at the first access-token expiry — fail loud
+  // rather than register an un-refreshable account.
+  if (!built.credentials.microsoftOauth.refreshToken) {
+    return { kind: 'no-refresh-token' }
+  }
+
+  const account = built.resolvedEmail
+  if (!account) {
+    return {
+      kind: 'failed',
+      message: 'Microsoft did not return an account identity (no id_token).',
+    }
+  }
+
+  const addAccount = deps.addAccount ?? defaultAddAccount
+  try {
+    await addAccount(account, built.credentials as MicrosoftAddAccountCredentials, {
+      provider: 'microsoft',
+      // replace:true so reconnecting an already-linked account just
+      // refreshes its tokens rather than erroring.
+      replace: true,
+    })
+  } catch (err) {
+    return { kind: 'failed', message: (err as Error).message }
+  }
+
+  return {
+    kind: 'connected',
+    account,
+    accountType: built.credentials.microsoftOauth.accountType,
+    expiresAt: built.credentials.microsoftOauth.expiresAt,
+  }
+}
+
+function defaultAddAccount(
+  label: string,
+  credentials: MicrosoftAddAccountCredentials,
+  opts: { replace?: boolean; provider: 'microsoft' },
+): Promise<{ label: string; expiresAt?: number }> {
+  return addAccountViaBroker(label, credentials, opts)
+}