switchroom 0.14.60 → 0.14.62

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)
+}

package/telegram-plugin/gateway/obligation-ledger.ts

@@ -38,6 +38,12 @@ export interface Obligation {
   readonly openedAt: number
   /** How many times it has been re-presented (0 on first open). */
   representCount: number
+  /** How many times the operator-escalation send has been ATTEMPTED (0 until
+   *  the represent ladder is exhausted). Bounds escalation so a permanently-
+   *  undeliverable nudge (dead/renumbered topic → Telegram 400, blocked bot)
+   *  can't loop forever — and, because it is part of the durable snapshot,
+   *  can't become a boot-surviving poison record either. */
+  escalateAttempts?: number
 }
 
 /** What the gateway should do for the oldest open obligation at an idle boundary. */
@@ -57,14 +63,33 @@ export interface ObligationInput {
   openedAt: number
 }
 
+/** Side-effect hooks the gateway injects. Kept out of the pure decision logic
+ *  so the ledger stays unit-testable (a capturing `onChange` in tests). */
+export interface ObligationLedgerHooks {
+  /** Called after EVERY state mutation (open/close/represent/escalate-attempt)
+   *  with the full open snapshot, so the gateway can durably persist it. NOT
+   *  called by hydrate() — that IS the restoration of persisted state. */
+  onChange?: (snapshot: Obligation[]) => void
+}
+
 export class ObligationLedger {
   private readonly open = new Map<string, Obligation>()
 
   /**
    * @param maxRepresents max re-presentations before escalating to an
    *   operator-visible nudge instead of re-asking again. Default 2.
+   * @param hooks optional side-effect hooks (durable persistence). Omitted in
+   *   pure unit tests; the gateway wires `onChange` to the snapshot store.
    */
-  constructor(private readonly maxRepresents = 2) {}
+  constructor(
+    private readonly maxRepresents = 2,
+    private readonly hooks: ObligationLedgerHooks = {},
+  ) {}
+
+  /** Persist the current open set via the injected hook (no-op if unwired). */
+  private persist(): void {
+    this.hooks.onChange?.(this.list())
+  }
 
   /**
    * Open an obligation if not already tracked. Idempotent on originTurnId — a
@@ -75,13 +100,33 @@ export class ObligationLedger {
   openIfAbsent(input: ObligationInput): boolean {
     if (this.open.has(input.originTurnId)) return false
     this.open.set(input.originTurnId, { ...input, representCount: 0 })
+    this.persist()
     return true
   }
 
   /** Close by origin id. Returns true if an obligation was open and is now closed. */
   close(originTurnId: string | null | undefined): boolean {
     if (originTurnId == null) return false
-    return this.open.delete(originTurnId)
+    const closed = this.open.delete(originTurnId)
+    if (closed) this.persist()
+    return closed
+  }
+
+  /**
+   * Re-populate from a persisted snapshot at boot — the restart-durability seam.
+   * Open obligations (with their representCount + escalateAttempts intact)
+   * survive a gateway/container restart, so the next idle sweep re-presents or
+   * re-escalates them rather than silently losing a delivered-but-unanswered
+   * message. Replaces current contents; does NOT fire onChange (this state is
+   * already what's on disk). Tolerates a malformed snapshot (skips bad rows).
+   */
+  hydrate(snapshot: readonly Obligation[]): void {
+    this.open.clear()
+    for (const o of snapshot) {
+      if (o != null && typeof o.originTurnId === 'string' && o.originTurnId.length > 0) {
+        this.open.set(o.originTurnId, { ...o })
+      }
+    }
   }
 
   isOpen(originTurnId: string): boolean {
@@ -156,8 +201,26 @@ export class ObligationLedger {
     const o = this.open.get(originTurnId)
     if (o === undefined) return 0
     o.representCount += 1
+    this.persist()
     return o.representCount
   }
+
+  /**
+   * Record an operator-escalation SEND attempt (bumps escalateAttempts).
+   * Returns the new count. The gateway calls this immediately before each
+   * escalation send and uses the count to bound retries: a transient send
+   * failure leaves the obligation OPEN and is retried next sweep, but after
+   * the bound the gateway closes best-effort so a permanently-undeliverable
+   * nudge can neither loop forever nor (now that the count is durable) re-enter
+   * the loop on every boot.
+   */
+  markEscalateAttempt(originTurnId: string): number {
+    const o = this.open.get(originTurnId)
+    if (o === undefined) return 0
+    o.escalateAttempts = (o.escalateAttempts ?? 0) + 1
+    this.persist()
+    return o.escalateAttempts
+  }
 }
 
 /** Original message preview length for re-presentation (mirrors resume builder). */

package/telegram-plugin/gateway/obligation-store.ts

@@ -0,0 +1,107 @@
+/**
+ * obligation-store.ts — durable snapshot for the obligation ledger.
+ *
+ * Why this exists: `ObligationLedger` is an in-memory Map. A gateway/container
+ * restart (switchroom update, agent restart, self-restart, OOM) empties it, so
+ * an inbound that was OPEN-but-unanswered when the process died loses its
+ * answer-obligation. The inbound-spool redelivers the MESSAGE on boot, but its
+ * replay bypasses `handleInbound` (the only place obligations OPEN), so the
+ * obligation is never reborn and a post-restart deferral is silently dropped —
+ * the determinism hole the systems analysis flagged.
+ *
+ * This makes the obligation guarantee SELF-CONTAINED across restart: every
+ * ledger mutation persists the full open set here; on boot the gateway hydrates
+ * the ledger from it, so OPEN/ESCALATING obligations survive WITH their
+ * representCount + escalateAttempts intact (the latter so a permanently-
+ * undeliverable escalation can't re-enter its retry loop on every boot).
+ *
+ * Shape choice — SNAPSHOT, not append-log. The open set is tiny and bounded
+ * (the count of currently-unanswered messages — normally 0–3), so rewriting the
+ * whole set on each change is trivially cheap and needs NO compaction,
+ * tombstones, or torn-tail replay. Crash-safety is a single write-tmp +
+ * atomic rename: a crash leaves EITHER the prior complete snapshot OR the new
+ * complete one — never a torn file. This is strictly simpler than the spool's
+ * append+ack+compact idiom, which that file needs only because its set is
+ * unbounded. PURE w.r.t. the injected fs seam ⇒ unit-testable.
+ */
+
+import type { Obligation } from './obligation-ledger.js'
+
+export interface ObligationStoreFsSeam {
+  readFileSync: (path: string) => string
+  writeFileSync: (path: string, data: string) => void
+  /** Atomic same-dir replace (POSIX rename) so a crash mid-write can't tear
+   *  the snapshot. */
+  renameSync: (from: string, to: string) => void
+  existsSync: (path: string) => boolean
+}
+
+interface SnapshotEnvelope {
+  v: 1
+  obligations: Obligation[]
+}
+
+function isObligationRow(x: unknown): x is Obligation {
+  if (x == null || typeof x !== 'object') return false
+  const o = x as Record<string, unknown>
+  return (
+    typeof o.originTurnId === 'string' &&
+    o.originTurnId.length > 0 &&
+    typeof o.chatId === 'string' &&
+    typeof o.messageId === 'number' &&
+    typeof o.text === 'string' &&
+    typeof o.openedAt === 'number' &&
+    typeof o.representCount === 'number'
+  )
+}
+
+/**
+ * Load the persisted open set. Returns [] on a missing, unreadable, or
+ * malformed file (fail-open to empty: a corrupt snapshot must never crash boot;
+ * worst case we lose the cross-restart obligation guarantee for that boot and
+ * fall back to the spool's message redelivery — strictly no worse than today).
+ */
+export function loadObligations(path: string, fs: ObligationStoreFsSeam): Obligation[] {
+  if (!fs.existsSync(path)) return []
+  let raw = ''
+  try {
+    raw = fs.readFileSync(path)
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (parsed == null || typeof parsed !== 'object') return []
+  const env = parsed as Record<string, unknown>
+  if (env.v !== 1 || !Array.isArray(env.obligations)) return []
+  return env.obligations.filter(isObligationRow)
+}
+
+/**
+ * Persist the open set atomically (write sibling tmp → rename over the real
+ * path). Best-effort relative to fs availability: a write failure is logged but
+ * never thrown — a failing store degrades to in-memory-only (today's behaviour),
+ * it must not break live delivery.
+ */
+export function persistObligations(
+  path: string,
+  fs: ObligationStoreFsSeam,
+  snapshot: readonly Obligation[],
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const env: SnapshotEnvelope = { v: 1, obligations: [...snapshot] }
+  const tmp = path + '.tmp'
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(env))
+    fs.renameSync(tmp, path)
+  } catch (err) {
+    log(
+      `obligation-store: persist FAILED path=${path}: ${(err as Error).message} — ` +
+        `durability degraded to in-memory\n`,
+    )
+  }
+}

package/telegram-plugin/gateway/with-deadline.ts

@@ -0,0 +1,43 @@
+/**
+ * withDeadline — bound a promise so the chain off it ALWAYS settles within `ms`.
+ *
+ * Why this exists (the obligation-ledger determinism hole): the escalation send
+ * in `obligationSweep` is fire-and-forget and clears its in-flight guard
+ * (`obligationEscalateInFlight`) only in a `.finally` — which runs only if the
+ * awaited promise SETTLES. grammy's `bot.api` has no request timeout
+ * (`new Bot(TOKEN)`, no `client.timeoutSeconds`) and `retryApiCall`'s `await
+ * fn()` does not bound a hang (its retry cap applies to rejections, not to a
+ * promise that never resolves). So a stalled send (half-open TCP, unresponsive
+ * Telegram) would never settle → `.finally` never fires → the in-flight id is
+ * leaked forever → every later sweep early-returns at the guard → the
+ * obligation is stuck OPEN: never re-presented, never escalated, never closed.
+ * That is a silent loss of the "every inbound is answered-or-escalated"
+ * guarantee — the one liveness hole a total state-machine proof surfaced (a
+ * sampling test cannot, because its model never includes "send never settles").
+ *
+ * Racing the send against a deadline makes the wait bounded BY CONSTRUCTION:
+ * the returned promise settles in ≤ `ms`, so the caller's `.then/.catch/.finally`
+ * always run and the in-flight flag always clears. A hang becomes a bounded
+ * rejection that feeds the already-bounded escalate ladder
+ * (`escalateAttempts → OBLIGATION_ESCALATE_MAX`) to a terminal. The losing
+ * (still-pending) promise is given a no-op `.catch` so its eventual rejection
+ * is not an unhandled rejection, and the timer is cleared + unref'd so it
+ * neither leaks nor keeps the event loop alive.
+ *
+ * Pure (no gateway/Telegram coupling) ⇒ unit-testable; see
+ * tests/with-deadline.test.ts.
+ */
+export function withDeadline<T>(p: Promise<T>, ms: number, timeoutMessage: string): Promise<T> {
+  // Swallow a late rejection from the loser after the race has already settled,
+  // so a hung-then-eventually-rejected send is never an unhandled rejection.
+  p.catch(() => {})
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(timeoutMessage)), ms)
+    // Don't keep the process alive solely for this timer.
+    ;(timer as unknown as { unref?: () => void }).unref?.()
+  })
+  return Promise.race([p, deadline]).finally(() => {
+    if (timer !== undefined) clearTimeout(timer)
+  }) as Promise<T>
+}

package/telegram-plugin/tests/microsoft-connect-flow.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  startMicrosoftConnect,
+  runMicrosoftConnectPoll,
+} from '../gateway/microsoft-connect-flow.js'
+import { DEFAULT_MICROSOFT_CLIENT_ID } from '../../src/auth/default-oauth-clients.js'
+import type {
+  MicrosoftDeviceCodeResponse,
+  MicrosoftOAuthClientConfig,
+  MicrosoftTokenResponse,
+} from '../../src/microsoft/oauth.js'
+
+const PERSONAL_MSA_TID = '9188040d-6c67-4c5b-b112-36a304b66dad'
+
+const DEVICE: MicrosoftDeviceCodeResponse = {
+  device_code: 'dc-abc',
+  user_code: 'ABCD-EFGH',
+  verification_uri: 'https://microsoft.com/devicelogin',
+  expires_in: 900,
+  interval: 5,
+}
+
+function fakeIdToken(payload: Record<string, unknown>): string {
+  const b64 = (o: unknown) => Buffer.from(JSON.stringify(o)).toString('base64url')
+  return `${b64({ alg: 'none' })}.${b64(payload)}.sig`
+}
+
+describe('startMicrosoftConnect', () => {
+  it('uses the shipped default client_id + default scopes when there is no config', async () => {
+    let seen: MicrosoftOAuthClientConfig | undefined
+    const res = await startMicrosoftConnect({
+      requestDeviceCode: async (cfg) => {
+        seen = cfg
+        return DEVICE
+      },
+    })
+    expect(res.kind).toBe('started')
+    if (res.kind === 'started') {
+      expect(res.source).toBe('default')
+      expect(res.clientId).toBe(DEFAULT_MICROSOFT_CLIENT_ID)
+      expect(res.scopes).toContain('offline_access')
+      expect(res.device.user_code).toBe('ABCD-EFGH')
+    }
+    expect(seen?.client_id).toBe(DEFAULT_MICROSOFT_CLIENT_ID)
+  })
+
+  it('refuses a vaulted BYO client (gateway can\'t resolve vault refs)', async () => {
+    const res = await startMicrosoftConnect({
+      configClientId: 'vault:microsoft-oauth-client-id',
+      requestDeviceCode: async () => DEVICE,
+    })
+    expect(res.kind).toBe('byo-vault')
+    if (res.kind === 'byo-vault') {
+      expect(res.ref).toBe('vault:microsoft-oauth-client-id')
+    }
+  })
+
+  it('uses a literal BYO config client_id (source=config)', async () => {
+    const res = await startMicrosoftConnect({
+      configClientId: 'byo-literal-123',
+      requestDeviceCode: async () => DEVICE,
+    })
+    expect(res.kind).toBe('started')
+    if (res.kind === 'started') {
+      expect(res.source).toBe('config')
+      expect(res.clientId).toBe('byo-literal-123')
+    }
+  })
+
+  it('returns an error when the device-code request fails', async () => {
+    const res = await startMicrosoftConnect({
+      requestDeviceCode: async () => {
+        throw new Error('device_code request failed (400): boom')
+      },
+    })
+    expect(res.kind).toBe('error')
+    if (res.kind === 'error') expect(res.message).toContain('boom')
+  })
+})
+
+describe('runMicrosoftConnectPoll', () => {
+  const flow = {
+    device: DEVICE,
+    clientId: 'client-1',
+    scopes: ['offline_access', 'Mail.ReadWrite'],
+    cancelled: false,
+  }
+
+  function tokens(o: Partial<MicrosoftTokenResponse> = {}): MicrosoftTokenResponse {
+    return {
+      access_token: 'at',
+      refresh_token: 'rt',
+      expires_in: 3600,
+      token_type: 'Bearer',
+      scope: 'Mail.ReadWrite',
+      ...o,
+    }
+  }
+
+  it('connects: registers the account via the broker keyed by the authenticated email', async () => {
+    const id_token = fakeIdToken({
+      tid: PERSONAL_MSA_TID,
+      oid: 'oid-1',
+      preferred_username: 'Lisa@Outlook.com',
+    })
+    const calls: Array<{ label: string; opts: unknown; refreshToken: string }> = []
+    const res = await runMicrosoftConnectPoll(flow, {
+      pollDeviceToken: async () => tokens({ id_token }),
+      addAccount: async (label, creds, opts) => {
+        calls.push({
+          label,
+          opts,
+          refreshToken: creds.microsoftOauth.refreshToken,
+        })
+        return { label }
+      },
+    })
+    expect(res.kind).toBe('connected')
+    if (res.kind === 'connected') {
+      expect(res.account).toBe('lisa@outlook.com')
+      expect(res.accountType).toBe('personal')
+    }
+    expect(calls).toHaveLength(1)
+    expect(calls[0].label).toBe('lisa@outlook.com')
+    expect(calls[0].opts).toEqual({ provider: 'microsoft', replace: true })
+    expect(calls[0].refreshToken).toBe('rt')
+  })
+
+  it('cancelled: does NOT register if the flow was cancelled during the poll', async () => {
+    let added = false
+    const res = await runMicrosoftConnectPoll(
+      { ...flow, cancelled: true },
+      {
+        pollDeviceToken: async () => tokens(),
+        addAccount: async () => {
+          added = true
+          return { label: 'x' }
+        },
+      },
+    )
+    expect(res.kind).toBe('cancelled')
+    expect(added).toBe(false)
+  })
+
+  it('no-refresh-token: refuses to register an un-refreshable account', async () => {
+    let added = false
+    const res = await runMicrosoftConnectPoll(flow, {
+      pollDeviceToken: async () => tokens({ refresh_token: undefined }),
+      addAccount: async () => {
+        added = true
+        return { label: 'x' }
+      },
+    })
+    expect(res.kind).toBe('no-refresh-token')
+    expect(added).toBe(false)
+  })
+
+  it('failed: surfaces a poll error (e.g. a work account rejected at /common)', async () => {
+    const res = await runMicrosoftConnectPoll(flow, {
+      pollDeviceToken: async () => {
+        throw new Error('Token poll failed: AADSTS9001023 work account')
+      },
+      addAccount: async () => ({ label: 'x' }),
+    })
+    expect(res.kind).toBe('failed')
+    if (res.kind === 'failed') expect(res.message).toContain('AADSTS9001023')
+  })
+
+  it('failed: refuses to register when Microsoft returns no id_token (no account identity)', async () => {
+    let added = false
+    const res = await runMicrosoftConnectPoll(flow, {
+      // Has a refresh token but no id_token → no resolvable email to key
+      // the broker account by; must NOT register a label-less account.
+      pollDeviceToken: async () => tokens({ id_token: undefined }),
+      addAccount: async () => {
+        added = true
+        return { label: 'x' }
+      },
+    })
+    expect(res.kind).toBe('failed')
+    if (res.kind === 'failed') expect(res.message).toContain('account identity')
+    expect(added).toBe(false)
+  })
+})