@bobfrankston/rmfmail 1.2.50 → 1.2.66

package/packages/mailx-imap/index.js

@@ -11,6 +11,7 @@ import { EventEmitter } from "node:events";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { GmailApiProvider } from "./providers/gmail-api.js";
+import { OutlookApiProvider } from "./providers/outlook-api.js";
 import { SmtpClient } from "@bobfrankston/smtp-direct";
 import * as os from "node:os";
 import { fileURLToPath } from "node:url";
@@ -180,6 +181,16 @@ async function withTimeout(promise, ms, client, label) {
         clearTimeout(timer);
     }
 }
+/** Outlook.com / Microsoft 365 detection from an account config (host or email
+ *  domain). Shared by the addAccount tokenProvider branch and isOutlookAccount
+ *  so the credential/scope choice and the provider-routing choice agree. */
+function isOutlookCfg(account) {
+    const host = account.imap?.host?.toLowerCase() || "";
+    const email = account.email?.toLowerCase() || "";
+    if (/outlook\.|office365|hotmail|\.live\.com/.test(host))
+        return true;
+    return /@(outlook|hotmail|live|msn)\.com$/.test(email);
+}
 export class ImapManager extends EventEmitter {
     configs = new Map();
     watchers = new Map();
@@ -454,6 +465,98 @@ export class ImapManager extends EventEmitter {
             catch { /* */ }
         }
     }
+    /** Special-use roles a folder may NOT be renamed/reparented out of. Renaming
+     *  INBOX/Sent/Drafts/Trash/Junk/Archive would break the special-folder
+     *  mapping (compose's draft auto-save, the trash target, sent-copy append),
+     *  and most servers reject it outright — so we refuse before touching the
+     *  server. */
+    static PROTECTED_ROLES = new Set(["inbox", "sent", "drafts", "trash", "junk", "archive"]);
+    /** Rename and/or reparent a folder. Both operations are a single server-side
+     *  mailbox rename (IMAP RENAME / Gmail label PATCH / Graph move+patch) —
+     *  messages never move, no copy-and-delete. Mirrors moveMessage's plumbing:
+     *  validate + branch API-vs-IMAP + commit locally.
+     *
+     *  - `newName` is the new LEAF name.
+     *  - `newParentId` (optional) reparents under that folder; omit for an
+     *    in-place rename. Reparenting and renaming share one path computation:
+     *    newPath = (newParent ? newParent.path + delim : oldParentPrefix) + newName.
+     *
+     *  Guard rails (all throw a UI-surfaced error): protected special-use
+     *  folders, empty/whitespace names, names containing the hierarchy
+     *  delimiter, a destination that already exists, and reparenting a folder
+     *  under itself or its own descendant (which would orphan the subtree). */
+    async renameFolder(accountId, folderId, newName, newParentId) {
+        const folders = this.db.getFolders(accountId);
+        const folder = folders.find(f => f.id === folderId);
+        if (!folder)
+            throw new Error("Folder not found");
+        // Use the folder's OWN delimiter — never borrow folders[0]'s (a
+        // different-delimiter folder would build a wrong newPath).
+        const delimiter = folder.delimiter || "/";
+        // ── Guard rails ──────────────────────────────────────────────────────
+        if (folder.specialUse && ImapManager.PROTECTED_ROLES.has(folder.specialUse)) {
+            throw new Error(`"${folder.name}" is a special folder (${folder.specialUse}) and can't be renamed.`);
+        }
+        const leaf = (newName || "").trim();
+        if (!leaf)
+            throw new Error("Folder name can't be empty.");
+        if (leaf.includes(delimiter)) {
+            throw new Error(`Folder name can't contain the "${delimiter}" hierarchy separator.`);
+        }
+        // Resolve the destination parent (reparent) or keep the existing parent
+        // prefix (in-place rename).
+        let newPath;
+        let parent;
+        if (newParentId != null) {
+            parent = folders.find(f => f.id === newParentId);
+            if (!parent)
+                throw new Error("Target parent folder not found");
+            if (parent.id === folder.id)
+                throw new Error("Can't move a folder into itself.");
+            // Reparenting under a descendant would orphan the moved subtree.
+            if (parent.path === folder.path || parent.path.startsWith(folder.path + delimiter)) {
+                throw new Error("Can't move a folder into one of its own subfolders.");
+            }
+            newPath = parent.path + delimiter + leaf;
+        }
+        else {
+            const idx = folder.path.lastIndexOf(delimiter);
+            const parentPrefix = idx >= 0 ? folder.path.slice(0, idx + delimiter.length) : "";
+            newPath = parentPrefix + leaf;
+        }
+        if (newPath === folder.path)
+            return; // no-op (same name + same parent)
+        if (folders.some(f => f.path === newPath)) {
+            throw new Error(`A folder named "${leaf}" already exists here.`);
+        }
+        // ── Server op ────────────────────────────────────────────────────────
+        // API accounts (Gmail labels / Outlook Graph folders) have native
+        // rename; IMAP accounts use RFC 3501 RENAME, which renames the whole
+        // subtree server-side in one command.
+        if (this.isApiAccount(accountId)) {
+            const api = this.getApiProvider(accountId);
+            if (!api.renameFolder) {
+                throw new Error("This account's provider doesn't support folder rename.");
+            }
+            // Gmail wants the parent label PATH; Outlook wants the parent Graph
+            // id — both are the parent folder's `path` in our model.
+            await api.renameFolder(folder.path, leaf, parent?.path);
+        }
+        else {
+            await this.renameFolderViaServer(accountId, folder.path, newPath);
+        }
+        // ── Local commit ─────────────────────────────────────────────────────
+        // All providers now use a HIERARCHICAL display path:
+        //   - IMAP: server mailbox path (renameFolderViaServer also resyncs).
+        //   - Gmail: label name (which is the slash-path).
+        //   - Outlook: display-name path — the provider keeps a path↔Graph-id
+        //     map internally, so renaming the path is safe (Graph ops resolve
+        //     the id from the new path on the next list-sync).
+        // So the predicted newPath matches the server result; rewrite the row +
+        // descendant prefixes for an immediate tree update.
+        this.db.renameFolderPath(accountId, folder.path, newPath, leaf, delimiter);
+        this.emit("folderCountsChanged", accountId, {});
+    }
     /** Delete `path` on the server (tolerating already-gone). Local folder-row
      *  removal stays with the caller (it knows the folderId). */
     async deleteFolderViaServer(accountId, path) {
@@ -928,25 +1031,56 @@ export class ImapManager extends EventEmitter {
         // createAutoImapConfig auto-detects Gmail from server/username and sets up OAuth
         // For OAuth accounts, provide a tokenProvider using oauthsupport
         let tokenProvider;
-        if (account.imap.auth === "oauth2" || (!account.imap.password && account.imap.host?.includes("gmail"))) {
-            // Find Google OAuth credentials — check ~/.mailx first, then iflow-direct package
-            let credPath = path.join(getConfigDir(), "google-credentials.json");
-            if (!fs.existsSync(credPath)) {
-                try {
-                    // Use fileURLToPath, NOT string-replace on "file://" — on Linux,
-                    // file:///usr/local/... loses its leading slash via .replace("file:///",
-                    // "") and becomes relative, so fs.existsSync silently fails.
-                    const pkgDir = path.dirname(fileURLToPath(import.meta.resolve("@bobfrankston/iflow-direct")));
-                    for (const name of ["iflow-credentials.json"]) {
-                        const p = path.join(pkgDir, name);
-                        if (fs.existsSync(p)) {
-                            credPath = p;
-                            break;
+        if (account.imap.auth === "oauth2" || (!account.imap.password && account.imap.host?.includes("gmail")) || (!account.imap.password && isOutlookCfg(account))) {
+            // Pick the OAuth provider by account kind. Outlook accounts use
+            // Microsoft Graph credentials + scopes; everything else is Google.
+            // Both flow through the same provider-agnostic oauthsupport code —
+            // only the creds file and scope string differ (see docs/outlook.md).
+            const outlook = isOutlookCfg(account);
+            let credPath;
+            if (outlook) {
+                // Microsoft app registration creds. Check the per-machine
+                // override (~/.rmfmail) first, then fall back to the file
+                // BUNDLED IN THIS PACKAGE — same model as Google's creds
+                // shipping inside iflow-direct. Because the client is PUBLIC
+                // (PKCE, no secret), the bundled file holds only the public
+                // client_id and is safe to commit/ship. So a fresh install
+                // needs NO manual creds placement (see docs/outlook.md §A/B).
+                credPath = path.join(getConfigDir(), "microsoft-credentials.json");
+                if (!fs.existsSync(credPath)) {
+                    const bundled = path.join(path.dirname(fileURLToPath(import.meta.url)), "microsoft-credentials.json");
+                    if (fs.existsSync(bundled))
+                        credPath = bundled;
+                }
+            }
+            else {
+                // Find Google OAuth credentials — check ~/.rmfmail first, then iflow-direct package
+                credPath = path.join(getConfigDir(), "google-credentials.json");
+                if (!fs.existsSync(credPath)) {
+                    try {
+                        // Use fileURLToPath, NOT string-replace on "file://" — on Linux,
+                        // file:///usr/local/... loses its leading slash via .replace("file:///",
+                        // "") and becomes relative, so fs.existsSync silently fails.
+                        const pkgDir = path.dirname(fileURLToPath(import.meta.resolve("@bobfrankston/iflow-direct")));
+                        for (const name of ["iflow-credentials.json"]) {
+                            const p = path.join(pkgDir, name);
+                            if (fs.existsSync(p)) {
+                                credPath = p;
+                                break;
+                            }
                         }
                     }
+                    catch { /* iflow-direct not resolvable */ }
                 }
-                catch { /* iflow-direct not resolvable */ }
             }
+            // Scope set by provider. Google: full two-way sync of all
+            // mailx-managed stores. Microsoft Graph: mail read/write + send +
+            // offline refresh. (Graph and Outlook-IMAP scopes are DIFFERENT
+            // audiences — we mint Graph because Outlook syncs/sends via Graph,
+            // not IMAP/SMTP. See docs/outlook.md "Decision".)
+            const oauthScope = outlook
+                ? "https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/Mail.Send offline_access openid profile"
+                : "https://mail.google.com/ https://www.googleapis.com/auth/contacts https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/tasks https://www.googleapis.com/auth/drive";
             const tokenDir = path.join(getConfigDir(), "tokens", tokenDirName(account.imap.user));
             tokenProvider = async () => {
                 // Wall-clock timeout on OAuth. Use a longer timeout when no
@@ -955,11 +1089,9 @@ export class ImapManager extends EventEmitter {
                 const hasToken = fs.existsSync(path.join(tokenDir, "oauth-token.json"));
                 const TOKEN_FETCH_TIMEOUT_MS = hasToken ? 30_000 : 120_000;
                 const authPromise = authenticateOAuth(credPath, {
-                    // Scope set covers two-way sync of all mailx-managed local
-                    // stores: mail (mail.google.com), contacts (full, not
-                    // readonly — we write edits back), calendar (full), tasks
-                    // (full), drive (for shared accounts.jsonc).
-                    scope: "https://mail.google.com/ https://www.googleapis.com/auth/contacts https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/tasks https://www.googleapis.com/auth/drive",
+                    // Scope set chosen per provider above (Google full-store
+                    // sync, or Microsoft Graph mail).
+                    scope: oauthScope,
                     tokenDirectory: tokenDir,
                     credentialsKey: "installed",
                     loginHint: account.imap.user,
@@ -1004,6 +1136,15 @@ export class ImapManager extends EventEmitter {
             // Gmail-via-IMAP responds instantly, no need to bump it there.
             greetingTimeout: isGmail ? 10000 : 30000,
         });
+        // createAutoImapConfig only threads the tokenProvider through for GMAIL
+        // hosts — its non-Gmail branch drops it (it assumes non-Gmail == password
+        // IMAP). Outlook is OAuth-but-not-Gmail: it never opens IMAP (it syncs via
+        // Graph), but getOutlookProvider reads config.tokenProvider. So re-attach
+        // it here for any OAuth account whose host createAutoImapConfig didn't
+        // recognize. Without this, an Outlook account silently has no provider →
+        // "No tokenProvider for outlook" on every sync (Bob 2026-06-21).
+        if (tokenProvider && !config.tokenProvider)
+            config.tokenProvider = tokenProvider;
         this.configs.set(account.id, config);
         // Register account in DB
         this.db.upsertAccount(account.id, account.name, account.email, JSON.stringify(account));
@@ -1043,6 +1184,38 @@ export class ImapManager extends EventEmitter {
             throw new Error(`No tokenProvider for ${accountId}`);
         return new GmailApiProvider(config.tokenProvider);
     }
+    /** Check if an account is Outlook.com / Microsoft 365 (should use Graph API
+     *  instead of IMAP). Detection mirrors isGmailAccount: host or email domain.
+     *  office365 IMAP front-ends and consumer outlook.com both route here. */
+    isOutlookAccount(accountId) {
+        const settings = loadSettings();
+        const account = settings.accounts.find(a => a.id === accountId);
+        if (!account)
+            return false;
+        return isOutlookCfg(account);
+    }
+    /** True for any account that syncs via a REST provider (Gmail or Outlook)
+     *  rather than IMAP. The branch points that used to ask isGmailAccount to
+     *  mean "API, not IMAP" ask this instead. */
+    isApiAccount(accountId) {
+        return this.isGmailAccount(accountId) || this.isOutlookAccount(accountId);
+    }
+    /** Get a Microsoft Graph provider for an account (reuses the tokenProvider —
+     *  which mints Graph-scoped tokens for Outlook accounts, see addAccount). */
+    getOutlookProvider(accountId) {
+        const config = this.configs.get(accountId);
+        if (!config?.tokenProvider)
+            throw new Error(`No tokenProvider for ${accountId}`);
+        return new OutlookApiProvider(config.tokenProvider);
+    }
+    /** Get the right REST provider (Gmail or Outlook) for an API account.
+     *  Both implement MailProvider plus the setFlags/trashMessage/moveMessage/
+     *  fetchBodiesBatch surface the dispatcher uses, so callers stay generic. */
+    getApiProvider(accountId) {
+        if (this.isOutlookAccount(accountId))
+            return this.getOutlookProvider(accountId);
+        return this.getGmailProvider(accountId);
+    }
     /** Convert ProviderMessage to the shape expected by storeMessages/upsertMessage */
     providerMsgToLocal(msg) {
         return {
@@ -2067,8 +2240,8 @@ export class ImapManager extends EventEmitter {
     }
     /** Sync a single account — manages its own connection lifecycle */
     async syncAccount(accountId, priorityOrder) {
-        // Gmail: use REST API instead of IMAP
-        if (this.isGmailAccount(accountId)) {
+        // Gmail / Outlook: use REST API instead of IMAP
+        if (this.isApiAccount(accountId)) {
             return this.syncAccountViaApi(accountId, priorityOrder);
         }
         try {
@@ -2277,19 +2450,40 @@ export class ImapManager extends EventEmitter {
             this.handleSyncError(accountId, errMsg);
         }
     }
-    /** Sync a Gmail account via REST API — no IMAP connections */
+    /** Sync a Gmail or Outlook account via REST API — no IMAP connections */
     async syncAccountViaApi(accountId, priorityOrder) {
         try {
-            const api = this.getGmailProvider(accountId);
+            const api = this.getApiProvider(accountId);
             const t0 = Date.now();
             // Step 1: Sync folder list via API
             console.log(`  [api] ${accountId}: listing labels...`);
             const apiFolders = await api.listFolders();
             console.log(`  [api] ${accountId}: ${apiFolders.length} labels in ${Date.now() - t0}ms`);
             // Store folders in DB (same as IMAP path)
+            const serverPaths = new Set();
             for (const f of apiFolders) {
                 const specialUse = f.specialUse || "";
                 this.db.upsertFolder(accountId, f.path, f.name, specialUse, f.delimiter);
+                serverPaths.add(f.path);
+            }
+            // Prune local folders the provider no longer returns. The IMAP path
+            // (syncFolders) already does this; the API path didn't, so a folder
+            // deleted on the server — OR whose path SCHEME changed (e.g. the
+            // Outlook id→hierarchical-path migration) — lingered forever as a
+            // stale/duplicate row. Same guards as syncFolders: only prune on a
+            // non-empty list (empty == transient error, not "all gone") and
+            // never drop INBOX.
+            if (apiFolders.length > 0) {
+                const stale = this.db.getFolders(accountId).filter(f => !serverPaths.has(f.path) && f.specialUse !== "inbox");
+                for (const f of stale) {
+                    console.log(`  [api] ${accountId}: pruning stale folder "${f.path}" (id=${f.id}) — not in provider list`);
+                    try {
+                        this.db.deleteFolder(f.id);
+                    }
+                    catch (e) {
+                        console.error(`  [api] ${accountId}: prune failed for "${f.path}": ${e.message}`);
+                    }
+                }
             }
             this.emit("folderCountsChanged", accountId, {});
             const dbFolders = this.db.getFolders(accountId);
@@ -2562,8 +2756,8 @@ export class ImapManager extends EventEmitter {
      *  on a large mailbox). The 5-minute STATUS poll path still runs full
      *  `syncFolder` so deletions and gaps eventually reconcile. */
     async syncInboxNewOnly(accountId) {
-        if (this.isGmailAccount(accountId))
-            return; // IDLE is IMAP-only
+        if (this.isApiAccount(accountId))
+            return; // IDLE is IMAP-only (Gmail/Outlook poll via API)
         const inbox = this.db.getFolders(accountId).find(f => f.specialUse === "inbox");
         if (!inbox)
             return;
@@ -2611,8 +2805,8 @@ export class ImapManager extends EventEmitter {
                     // mismatch — API uses hashed IDs, IMAP uses server-assigned
                     // UIDs. The IMAP reconcile then deletes every API-synced
                     // message because their UIDs don't appear in the IMAP list.
-                    if (this.isGmailAccount(accountId)) {
-                        const api = this.getGmailProvider(accountId);
+                    if (this.isApiAccount(accountId)) {
+                        const api = this.getApiProvider(accountId);
                         try {
                             await this.syncFolderViaApi(accountId, inbox, api);
                         }
@@ -2676,8 +2870,31 @@ export class ImapManager extends EventEmitter {
     async quickInboxCheckAccount(accountId) {
         if (this.isGmailAccount(accountId))
             return this.quickGmailCheck(accountId);
+        if (this.isOutlookAccount(accountId))
+            return this.quickApiCheck(accountId);
         return this.quickImapCheck(accountId);
     }
+    /** Lightweight inbox refresh for a generic API account (Outlook). Unlike
+     *  quickGmailCheck there's no cheap "top message id" probe — a single
+     *  incremental syncFolderViaApi is itself cheap (Graph delta-ish page), so
+     *  we just run it and recalc counts. */
+    async quickApiCheck(accountId) {
+        const inbox = this.db.getFolders(accountId).find(f => f.specialUse === "inbox");
+        if (!inbox)
+            return;
+        const api = this.getApiProvider(accountId);
+        try {
+            await this.syncFolderViaApi(accountId, inbox, api);
+            this.db.recalcFolderCounts(inbox.id);
+            this.emit("folderCountsChanged", accountId, {});
+        }
+        finally {
+            try {
+                await api.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
     async quickImapCheck(accountId) {
         const inbox = this.db.getFolders(accountId).find(f => f.specialUse === "inbox");
         if (!inbox)
@@ -2749,21 +2966,21 @@ export class ImapManager extends EventEmitter {
             // Gmail uses API sync, not IMAP STATUS. IMAP accounts use IDLE
             // which gives instant push — the STATUS poll is just a fallback
             // in case IDLE silently dropped.
-            const isGmail = this.isGmailAccount(accountId);
+            const isApi = this.isApiAccount(accountId);
             // IMAP accounts: IDLE gives instant push; STATUS poll is just a
             // safety net for silent IDLE drops — keep it infrequent.
-            // Gmail accounts: no IDLE (Gmail API doesn't expose it), so the
-            // quick poll IS the primary path to new-mail latency. Drop to 30s
-            // so Gmail mail appears in ~15s average. Gmail quota budget is
-            // huge (250 units/sec per user, 1.2B/day) — 120 polls/hour × 5
-            // units ≈ 600/hour, trivial. Dovecot accounts stay at 5min to
-            // respect connection limits (each poll = fresh connection).
-            const interval = isGmail ? 30000 : 300000; // Gmail: 30s; IMAP: 5min
+            // API accounts (Gmail/Outlook): no IDLE, so the quick poll IS the
+            // primary path to new-mail latency. Drop to 30s so mail appears in
+            // ~15s average. Both providers have ample request budget and their
+            // own rate-limiters, so a fresh poll is cheap. Dovecot accounts
+            // stay at 5min to respect connection limits (each poll = fresh
+            // connection).
+            const interval = isApi ? 30000 : 300000; // API: 30s; IMAP: 5min
             const timer = setInterval(() => {
                 this.quickInboxCheckAccount(accountId).catch(() => { });
             }, interval);
             this.syncIntervals.set(`quick:${accountId}`, timer);
-            console.log(`  [periodic] ${accountId}: STATUS check every ${interval / 1000}s (${isGmail ? "API" : "IMAP+IDLE"})`);
+            console.log(`  [periodic] ${accountId}: STATUS check every ${interval / 1000}s (${isApi ? "API" : "IMAP+IDLE"})`);
         }
         // DEADMAN: IDLE silently dropped on 2026-05-27 at 10:07 (empty
         // error message swallowed the cause) and 90 minutes of new mail
@@ -2776,8 +2993,8 @@ export class ImapManager extends EventEmitter {
         // the log.
         const deadmanInterval = setInterval(() => {
             for (const [accountId] of this.configs) {
-                if (this.isGmailAccount(accountId))
-                    continue; // Gmail = API, no IDLE
+                if (this.isApiAccount(accountId))
+                    continue; // Gmail/Outlook = API, no IDLE
                 if (this.watchers.has(accountId))
                     continue;
                 console.log(`  [idle-deadman] ${accountId}: no IDLE watcher — attempting restart`);
@@ -3144,8 +3361,8 @@ export class ImapManager extends EventEmitter {
         const folder = this.db.getFolders(accountId).find(f => f.id === folderId);
         if (!folder)
             return null;
-        // Gmail: REST API, no IMAP connection involved.
-        if (this.isGmailAccount(accountId)) {
+        // Gmail / Outlook: REST API, no IMAP connection involved.
+        if (this.isApiAccount(accountId)) {
             return this.fetchMessageBodyViaApi(accountId, folderId, uid, folder.path);
         }
         // IMAP: fast lane on the ops queue. One try; if the socket is stale,
@@ -3189,7 +3406,7 @@ export class ImapManager extends EventEmitter {
      *  delete the stale row locally instead of showing a generic error. */
     async fetchMessageBodyViaApi(accountId, folderId, uid, folderPath) {
         try {
-            const api = this.getGmailProvider(accountId);
+            const api = this.getApiProvider(accountId);
             // Read provider_id from the local row so fetchOne can skip the
             // listMessageIds pagination (the dominant Gmail rate-limit cost).
             const env = this.db.getMessageByUid(accountId, uid, folderId);
@@ -3341,7 +3558,7 @@ export class ImapManager extends EventEmitter {
         const ERROR_BUDGET = 20;
         const RATE_LIMIT_PAUSE_MS = 30000;
         const BATCH_SIZE = 100;
-        const isGmail = this.isGmailAccount(accountId);
+        const isApi = this.isApiAccount(accountId);
         // Gmail still uses per-message fetch (HTTP /batch is a separate TODO in this file's
         // governing unit). IMAP uses the batched `fetchBodiesBatch` path via iflow-direct —
         // one SELECT + one UID FETCH per folder per tick instead of N round trips.
@@ -3378,13 +3595,13 @@ export class ImapManager extends EventEmitter {
                 announced = true;
             }
             let madeProgress = false;
-            if (isGmail) {
-                // Gmail batch path: group by label (what mailx calls "folder"),
-                // list once per label, bounded-concurrency fetch. Far fewer
-                // HTTP round trips than the old one-listMessageIds-per-body path.
-                // Note on the model: Gmail has labels, not folders. A message in
-                // multiple labels gets fetched twice under current grouping. A
-                // deeper label-native redesign is tracked as a separate TODO.
+            if (isApi) {
+                // API batch path (Gmail/Outlook): group by folder/label, list
+                // once per folder, bounded-concurrency fetch. Far fewer HTTP
+                // round trips than the old one-list-per-body path.
+                // Note on the Gmail model: Gmail has labels, not folders. A
+                // message in multiple labels gets fetched twice under current
+                // grouping. A deeper label-native redesign is a separate TODO.
                 const byFolder = new Map();
                 for (const m of missing) {
                     let arr = byFolder.get(m.folderId);
@@ -3395,7 +3612,7 @@ export class ImapManager extends EventEmitter {
                     arr.push(m.uid);
                 }
                 const folders = this.db.getFolders(accountId);
-                const api = this.getGmailProvider(accountId);
+                const api = this.getApiProvider(accountId);
                 try {
                     for (const [folderId, uidsInFolder] of byFolder) {
                         const folder = folders.find(f => f.id === folderId);
@@ -3796,8 +4013,8 @@ export class ImapManager extends EventEmitter {
         // through withConnection → IMAP, which silently no-op'd for Gmail
         // accounts (REST-only, no IMAP connection) and left local-only stars
         // that vanished on the next full sync.
-        if (this.isGmailAccount(accountId)) {
-            const api = this.getGmailProvider(accountId);
+        if (this.isApiAccount(accountId)) {
+            const api = this.getApiProvider(accountId);
             try {
                 for (const action of actions) {
                     const folder = folders.find(f => f.id === action.folderId);
@@ -3933,16 +4150,33 @@ export class ImapManager extends EventEmitter {
                             console.log(`  [sync] Moved UID ${action.uid}: ${folder.path} → ${target.path}`);
                             break;
                         }
-                        case "flags":
-                            if (action.flags.length > 0) {
-                                await client.addFlags(folder.path, action.uid, action.flags.filter(f => !f.startsWith("-")));
-                                const toRemove = action.flags.filter(f => f.startsWith("-")).map(f => f.slice(1));
-                                if (toRemove.length > 0) {
-                                    await client.removeFlags(folder.path, action.uid, toRemove);
-                                }
-                                console.log(`  [sync] Updated flags UID ${action.uid}`);
+                        case "flags": {
+                            // action.flags is the ABSOLUTE desired flag set: the UI
+                            // sends the whole array with the toggled flag added or
+                            // simply OMITTED — it does NOT use the `-remove` convention.
+                            // The old code only ever called addFlags (additive), so
+                            // CLEARING a star never reached the server and the flag came
+                            // back on the next sync — "I shut off the stars and they
+                            // suddenly come back, still flagged on the server" (Bob
+                            // 2026-06-26). The old `length > 0` guard also made clearing
+                            // the last remaining flag a complete no-op. Reconcile to the
+                            // absolute state instead: add the desired flags, and remove
+                            // any flag mailx manages (\Seen / \Flagged) that's no longer
+                            // present. Mirrors the Gmail provider's add+remove approach.
+                            const desired = action.flags.filter(f => !f.startsWith("-"));
+                            const explicitRemove = action.flags.filter(f => f.startsWith("-")).map(f => f.slice(1));
+                            const MANAGED = ["\\Seen", "\\Flagged"];
+                            const impliedRemove = MANAGED.filter(f => !desired.includes(f));
+                            const toRemove = [...new Set([...explicitRemove, ...impliedRemove])];
+                            if (desired.length > 0) {
+                                await client.addFlags(folder.path, action.uid, desired);
+                            }
+                            if (toRemove.length > 0) {
+                                await client.removeFlags(folder.path, action.uid, toRemove);
                             }
+                            console.log(`  [sync] Updated flags UID ${action.uid} (+[${desired.join(",")}] -[${toRemove.join(",")}])`);
                             break;
+                        }
                         case "append": {
                             if (action.rawMessage) {
                                 await client.appendMessage(folder.path, action.rawMessage, action.flags);
@@ -4674,10 +4908,13 @@ export class ImapManager extends EventEmitter {
         }
         if (filesToSend.length === 0)
             return;
-        // Gmail/API accounts: send directly via SMTP from local queue (no IMAP outbox)
+        // API accounts (Gmail/Outlook): send directly from the local queue (no
+        // IMAP outbox). Gmail goes via SMTP+XOAUTH2 (mail.google.com scope
+        // covers SMTP); Outlook goes via Graph /sendMail (its token is Graph-
+        // scoped, not SMTP) — sendRawForAccount picks the right transport.
         const sentDir = path.join(getConfigDir(), "sending", accountId, "sent");
         fs.mkdirSync(sentDir, { recursive: true });
-        if (this.isGmailAccount(accountId)) {
+        if (this.isApiAccount(accountId)) {
             const nowMs = Date.now();
             for (const { dir, file } of filesToSend) {
                 const filePath = path.join(dir, file);
@@ -4718,9 +4955,9 @@ export class ImapManager extends EventEmitter {
                 raw = insertHeaderBeforeBody(raw, `X-Mailx-Retry: ${attempt} ${new Date().toISOString()}`);
                 fs.writeFileSync(claimedPath, raw, "utf-8");
                 try {
-                    await this.sendRawViaSMTP(accountId, raw);
+                    await this.sendRawForAccount(accountId, raw);
                     fs.renameSync(claimedPath, path.join(sentDir, file));
-                    console.log(`  [outbox] Sent ${file} via SMTP → sent/ (attempt ${attempt})`);
+                    console.log(`  [outbox] Sent ${file} → sent/ (attempt ${attempt})`);
                 }
                 catch (e) {
                     // Persist a next-attempt timestamp and release the claim so the
@@ -4816,6 +5053,20 @@ export class ImapManager extends EventEmitter {
             // IMAP still unreachable — leave files for next attempt
         }
     }
+    /** Send a raw RFC 2822 message for an account, choosing the transport by
+     *  provider. Outlook accounts have a Graph-scoped OAuth token (no SMTP
+     *  audience), so they send via Graph POST /sendMail; Gmail and IMAP
+     *  accounts send via SMTP (Gmail's mail.google.com token covers XOAUTH2
+     *  SMTP). Graph /sendMail auto-files a copy in Sent, so no append needed. */
+    async sendRawForAccount(accountId, raw) {
+        if (this.isOutlookAccount(accountId)) {
+            const api = this.getOutlookProvider(accountId);
+            await api.sendRaw(raw);
+            console.log(`  [graph] ${accountId}: sent via /sendMail`);
+            return;
+        }
+        await this.sendRawViaSMTP(accountId, raw);
+    }
     /** Send a raw RFC 2822 message via SMTP for a given account.
      *  Uses @bobfrankston/smtp-direct with the same TransportFactory as IMAP —
      *  same TCP byte-stream interface, no nodemailer dependency. */
@@ -4901,8 +5152,9 @@ export class ImapManager extends EventEmitter {
         const outboxFolder = this.findFolder(accountId, "outbox");
         if (!outboxFolder)
             return;
-        // Gmail: skip IMAP outbox check — sending handled by processLocalQueue which sends directly via SMTP
-        if (this.isGmailAccount(accountId))
+        // Gmail/Outlook: skip IMAP outbox — sending handled by processLocalQueue
+        // (Gmail via SMTP, Outlook via Graph /sendMail).
+        if (this.isApiAccount(accountId))
             return;
         const settings = loadSettings();
         const account = settings.accounts.find(a => a.id === accountId);
@@ -5249,7 +5501,7 @@ export class ImapManager extends EventEmitter {
             return;
         const tick = async () => {
             for (const [accountId] of this.configs) {
-                if (this.isGmailAccount(accountId))
+                if (this.isApiAccount(accountId))
                     continue;
                 try {
                     await this.sweepSentOnce(accountId);