@oxygen-agent/cli 1.1014.136 → 1.1014.618

package/dist/commands/mailboxes.js

@@ -0,0 +1,1290 @@
+import { emitCliFailure, emitSuccess, writeBillingNotices } from "../cli-output.js";
+import { readNonNegativeInt, readPositiveInt } from "../cli-values.js";
+import { readCsvOption, readNonNegativeNumber, splitCommaList } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { inferRowsFileFormat, parseXlsxWorkbookBuffer } from "@oxygen/shared/file-import";
+import { MAILBOX_IMPORT_FILE_MAX_BYTES as SHARED_MAILBOX_IMPORT_FILE_MAX_BYTES, MAILBOX_IMPORT_ROW_LIMIT as SHARED_MAILBOX_IMPORT_ROW_LIMIT, normalizeMailboxImportFile as normalizeSharedMailboxImportFile, normalizeMailboxImportVendor as normalizeSharedMailboxImportVendor, normalizeMailboxWorkbookRows, parseMailboxImportText, summarizeMailboxImportValidation as summarizeSharedMailboxImportValidation } from "@oxygen/shared/mailbox-import";
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+/**
+ * The active warm-up filter as the flags that produced it, or null for a
+ * pool-wide read.
+ *
+ * The server's echo wins because it is what was actually applied; the flags this
+ * CLI sent are the fallback for a server too old to echo anything. Neither path
+ * invents a number — the choice here is only about WORDING, because the counts
+ * are already scoped to the matches and printing them bare reads as the whole
+ * workspace.
+ */
+function describeMailboxFilters(echo, filterFlags) {
+    const parts = [];
+    if (echo) {
+        // Query order, so the line reads back as the command that produced it.
+        if (typeof echo.status === "string" && echo.status.length > 0) {
+            parts.push(`--status ${echo.status}`);
+        }
+        if (Array.isArray(echo.tag) && echo.tag.length > 0)
+            parts.push(`--tag ${echo.tag.join(",")}`);
+        if (Array.isArray(echo.warmup) && echo.warmup.length > 0) {
+            parts.push(`--warmup ${echo.warmup.join(",")}`);
+        }
+        if (Array.isArray(echo.next_action) && echo.next_action.length > 0) {
+            parts.push(`--next-action ${echo.next_action.join(",")}`);
+        }
+        if (echo.stalled === true)
+            parts.push("--stalled");
+    }
+    if (parts.length === 0)
+        parts.push(...filterFlags);
+    return parts.length > 0 ? parts.join(" ") : null;
+}
+const MAILBOX_POOL_COLUMNS = 80;
+/**
+ * How many mailboxes may owe an action before a block each stops being a list
+ * and becomes a wall. Measured on dev's eval workspace: 223 of 224 mailboxes
+ * needed one, and a block each printed ~1,100 lines in which the same four
+ * sentences repeated 93 times and the single unusual seat was buried in the
+ * middle of them. Under this limit the per-mailbox detail IS the value, so it
+ * stays exactly as it is; over it, the same rows are grouped by the step they
+ * need and the filter that selects each group is printed instead.
+ */
+const MAILBOX_POOL_DETAIL_LIMIT = 12;
+/** Example addresses per group, and rows sampled from a long settled list. */
+const MAILBOX_POOL_SAMPLES = 3;
+/** Distinct cause sentences named before the rest are counted off. */
+const MAILBOX_POOL_CAUSE_SAMPLES = 3;
+/**
+ * Wrap prose under a label, hanging-indented to the label's width. Commands are
+ * never passed through here.
+ */
+function writeWrappedPoolProse(out, prefix, text, 
+// Defaults to the label's own width; the headline overrides it, because a
+// continuation starting at column 0 with `--next-action` reads as a separate
+// command rather than the rest of a sentence.
+hangingIndent) {
+    const [first, ...rest] = text.split(/\s+/).filter(Boolean);
+    if (!first)
+        return;
+    const indent = hangingIndent ?? " ".repeat(prefix.length);
+    let line = `${prefix}${first}`;
+    for (const word of rest) {
+        if (line.length + 1 + word.length > MAILBOX_POOL_COLUMNS) {
+            out(line);
+            line = `${indent}${word}`;
+            continue;
+        }
+        line = `${line} ${word}`;
+    }
+    out(line);
+}
+/**
+ * `warmupNeedsAction`, read off the wire instead of recomputed: the server
+ * publishes the code, the CLI only compares it. A row from a server that sends no
+ * warmupTruth cannot owe an action this renderer could name, so it reads as
+ * settled rather than being invented into the urgent list.
+ */
+function mailboxNeedsWarmupAction(row) {
+    const code = row.warmupTruth?.next_action?.code;
+    return typeof code === "string" && code !== "none";
+}
+function mailboxPoolRow(row) {
+    const address = row.emailAddress ?? row.id ?? "(unnamed mailbox)";
+    const truth = row.warmupTruth;
+    const state = truth?.state ?? row.warmupState ?? "unknown";
+    const dispatch = truth?.dispatch;
+    const facts = [];
+    if (typeof dispatch?.current_day === "number")
+        facts.push(`day ${dispatch.current_day}`);
+    // A measured 0 is the entire story of a billed, silent seat, so it is printed.
+    // A null count was never reported by the rail and must not be shown as zero.
+    if (typeof dispatch?.sent === "number") {
+        facts.push(`${dispatch.sent.toLocaleString("en-US")} sent`);
+    }
+    // Only when it is not the boring answer: a mailbox OXYGEN is not sending from
+    // at all explains a silent warm-up faster than any warm-up field can.
+    if (typeof row.status === "string" && row.status !== "active")
+        facts.push(row.status);
+    return `  ${address.padEnd(34)} ${state.padEnd(12)} ${facts.join("   ")}`.trimEnd();
+}
+/** One mailbox's block: what it is, why, who stopped it, and what to run. */
+function writeMailboxActionDetail(out, row) {
+    out(mailboxPoolRow(row));
+    const truth = row.warmupTruth;
+    if (truth?.label)
+        writeWrappedPoolProse(out, "    Why:  ", truth.label);
+    const pauseLabel = truth?.pause?.paused === true ? truth.pause.label : null;
+    // Who stopped it, when the state sentence did not already say so.
+    if (pauseLabel && !(truth?.label ?? "").includes(pauseLabel)) {
+        writeWrappedPoolProse(out, "    Stop: ", pauseLabel);
+    }
+    const action = truth?.next_action;
+    if (action?.label)
+        writeWrappedPoolProse(out, "    Fix:  ", action.label);
+    if (action?.command)
+        out(`    Run:  ${action.command}`);
+    out();
+}
+/**
+ * One mailbox's next command with its own address replaced by a placeholder, so
+ * 93 rows that differ only by recipient collapse to one printable shape instead
+ * of 93 near-identical lines.
+ */
+function mailboxCommandShape(row) {
+    const command = row.warmupTruth?.next_action?.command;
+    if (typeof command !== "string" || command.length === 0)
+        return null;
+    const address = row.emailAddress;
+    return address ? command.replaceAll(address, "<address>") : command;
+}
+function groupMailboxesByNextAction(rows) {
+    const groups = new Map();
+    for (const row of rows) {
+        const action = row.warmupTruth?.next_action;
+        const code = typeof action?.code === "string" ? action.code : "unknown";
+        const group = groups.get(code) ?? { code, rows: [], causes: [], commands: [] };
+        group.rows.push(row);
+        // Collected, never merged: two mailboxes can need the same step for
+        // different reasons, and printing one of those reasons over both is a lie
+        // the reader would act on.
+        if (action?.label && !group.causes.includes(action.label))
+            group.causes.push(action.label);
+        const shape = mailboxCommandShape(row);
+        if (shape && !group.commands.includes(shape))
+            group.commands.push(shape);
+        groups.set(code, group);
+    }
+    // Biggest first — the wall is what most needs collapsing — and alphabetically
+    // inside a tie so two runs over the same pool read the same way.
+    return [...groups.values()].sort((left, right) => right.rows.length - left.rows.length || left.code.localeCompare(right.code));
+}
+/**
+ * Example addresses, fitted to the line rather than counted out blindly: the
+ * trailing "(+N more)" is part of the budget, so this line cannot be the one
+ * that breaks the 80-column promise.
+ */
+function mailboxSampleLine(rows, prefix) {
+    const addresses = rows.map((row) => row.emailAddress ?? row.id ?? "(unnamed mailbox)");
+    const shown = [];
+    for (const address of addresses.slice(0, MAILBOX_POOL_SAMPLES)) {
+        const remaining = addresses.length - (shown.length + 1);
+        const suffix = remaining > 0 ? `  (+${remaining} more)` : "";
+        const candidate = `${prefix}${[...shown, address].join(", ")}${suffix}`;
+        if (candidate.length > MAILBOX_POOL_COLUMNS && shown.length > 0)
+            break;
+        shown.push(address);
+    }
+    const remaining = addresses.length - shown.length;
+    return `${prefix}${shown.join(", ")}${remaining > 0 ? `  (+${remaining} more)` : ""}`;
+}
+/** The opening sentence, marked as clipped when there was more after it. */
+function firstSentenceOf(text) {
+    const [first] = text.split(/(?<=[.!?])\s+/);
+    if (!first || first.length === text.length)
+        return text;
+    // The clipped sentence keeps its own question or exclamation mark; a full stop
+    // becomes the ellipsis, so the line never reads ". ...".
+    return `${first.replace(/\.$/, "")}\u2026`;
+}
+/**
+ * `listAll` is the other side of the `List:` line this function prints: once the
+ * reader has narrowed to one group, the samples they were given to choose with
+ * are no longer the answer — the addresses are. So a single group states its
+ * shared cause and command once, then lists every member compactly, and drops
+ * the filter line that would only point back at the view they are already in.
+ */
+function writeMailboxActionGroups(out, groups, listAll = false) {
+    for (const group of groups) {
+        const count = group.rows.length;
+        const [only] = group.rows;
+        const noun = `${count} mailbox${count === 1 ? "" : "es"}`;
+        // A group of one is the odd seat in a pool of hundreds — the one thing a
+        // wall of repeated blocks buries. Name it on its own header line.
+        out(count === 1 && only
+            ? `  ${group.code}   ${noun}: ${only.emailAddress ?? only.id ?? "(unnamed mailbox)"}`
+            : `  ${group.code}   ${noun}`);
+        const [firstCause, ...otherCauses] = group.causes;
+        if (firstCause && otherCauses.length === 0) {
+            writeWrappedPoolProse(out, "    Why:  ", firstCause);
+        }
+        else if (firstCause) {
+            out(`    Why:  ${group.causes.length} different causes share this next step:`);
+            for (const cause of group.causes.slice(0, MAILBOX_POOL_CAUSE_SAMPLES)) {
+                // Opening sentence only: what differs between two causes sharing one
+                // next step is stated up front (the domain, the fault), and the rest is
+                // the shared remedy repeated verbatim. The full text is one `List:` line
+                // away, printed directly below.
+                writeWrappedPoolProse(out, "      - ", firstSentenceOf(cause));
+            }
+            if (group.causes.length > MAILBOX_POOL_CAUSE_SAMPLES) {
+                out(`      ... ${group.causes.length - MAILBOX_POOL_CAUSE_SAMPLES} more distinct causes`);
+            }
+        }
+        // One member means the real command; more means the shape, because a
+        // placeholder is honest about the 92 addresses it stands for.
+        const single = count === 1 && only ? only.warmupTruth?.next_action?.command : null;
+        const commands = single ? [single] : group.commands;
+        for (const command of commands.slice(0, 2))
+            out(`    Run:  ${command}`);
+        if (commands.length > 2) {
+            const rest = commands.length - 2;
+            out(`    ...   ${rest} more command ${rest === 1 ? "shape" : "shapes"} in this group`);
+        }
+        if (listAll) {
+            out();
+            for (const row of group.rows)
+                out(mailboxPoolRow(row));
+            out();
+            continue;
+        }
+        if (count > 1)
+            out(mailboxSampleLine(group.rows, "    e.g.  "));
+        // The exact filter that turns this group back into every one of its members.
+        out(`    List: oxygen mailboxes list --next-action ${group.code}`);
+        out();
+    }
+}
+function writeMailboxPoolOverview(data, view) {
+    const out = (line = "") => process.stdout.write(`${line}\n`);
+    const rows = data.mailboxes ?? [];
+    const total = typeof data.count === "number" ? data.count : rows.length;
+    const warmup = data.summary?.warmup;
+    const filterLabel = describeMailboxFilters(data.filters, view.filterFlags);
+    if (filterLabel) {
+        // count, summary.total and summary.warmup are all scoped to what matched, so
+        // the pool-wide headline would be right about the wrong population: "2
+        // mailboxes" to a founder with 224 inboxes is not a smaller number, it is a
+        // false one. Name the filter, count the matches, and say which is which.
+        const stalled = warmup?.stalled;
+        const clause = typeof stalled === "number" && stalled > 0 && stalled < total
+            ? ` — ${stalled} of them have never sent`
+            : "";
+        writeWrappedPoolProse(out, "", `${total} mailbox${total === 1 ? "" : "es"} match${total === 1 ? "es" : ""} ${filterLabel}${clause}`, "  ");
+        out("(a filtered view — not your whole pool; run oxygen mailboxes list for that)");
+    }
+    else {
+        const headline = [`${total} mailbox${total === 1 ? "" : "es"}`];
+        if (typeof warmup?.enrolled === "number")
+            headline.push(`${warmup.enrolled} in warm-up`);
+        if (typeof warmup?.stalled === "number") {
+            headline.push(`${warmup.stalled} enrolled but never sent`);
+        }
+        out(headline.join("   "));
+    }
+    // An older server has no summary.warmup at all. Say that under either
+    // headline, rather than printing a 0 a customer would read as "nothing is
+    // stalled" — or, in the filtered view, silently omitting the one count that
+    // explains why no stalled clause appeared.
+    if (!warmup)
+        out("(this server does not report warm-up pool counts)");
+    // Above the rows, like NEEDS ACTION: mailboxes that stopped sending because
+    // their monthly credits were not covered, and the date they disconnect.
+    if (data.reservations_paused?.message) {
+        out();
+        writeWrappedPoolProse(out, "PAUSED  ", data.reservations_paused.message, "        ");
+    }
+    out();
+    if (rows.length === 0) {
+        out(view.filtered ? "No mailbox matches that filter." : "No mailboxes in this workspace yet.");
+        const emptyLink = data.web_url ?? data.deepLink;
+        if (emptyLink) {
+            out();
+            out(emptyLink);
+        }
+        return;
+    }
+    const needsAction = rows.filter((row) => mailboxNeedsWarmupAction(row));
+    const settled = rows.filter((row) => !mailboxNeedsWarmupAction(row));
+    // First, and never behind the healthy ones: this block is the reason the
+    // command was run.
+    if (needsAction.length > 0 && needsAction.length <= MAILBOX_POOL_DETAIL_LIMIT) {
+        out(`NEEDS ACTION (${needsAction.length})`);
+        out();
+        for (const row of needsAction)
+            writeMailboxActionDetail(out, row);
+    }
+    else if (needsAction.length > 0) {
+        const groups = groupMailboxesByNextAction(needsAction);
+        if (groups.length === 1) {
+            out(`NEEDS ACTION (${needsAction.length}) — all of them need the same next step`);
+            out();
+            writeMailboxActionGroups(out, groups, true);
+        }
+        else {
+            out(`NEEDS ACTION (${needsAction.length}) — grouped by next step, not listed one by one`);
+            out();
+            writeMailboxActionGroups(out, groups);
+            // Nothing is hidden, and the reader should not have to add the groups up
+            // to be sure of it.
+            out(`  All ${needsAction.length} are in a group above. Add --json for every row.`);
+            out();
+        }
+    }
+    if (settled.length > 0) {
+        out(`NOTHING TO DO (${settled.length})`);
+        out();
+        // A healthy mailbox has nothing to say beyond existing, so past the limit a
+        // sample plus the count carries the same information as the whole list.
+        const shown = settled.length <= MAILBOX_POOL_DETAIL_LIMIT
+            ? settled
+            : settled.slice(0, MAILBOX_POOL_SAMPLES);
+        for (const row of shown)
+            out(mailboxPoolRow(row));
+        if (shown.length < settled.length) {
+            out(`  ... ${settled.length - shown.length} more, not listed`);
+        }
+        out();
+    }
+    const link = data.web_url ?? data.deepLink;
+    if (link)
+        out(link);
+    if (!view.filtered && needsAction.length > 0) {
+        out("Narrow it with --stalled, --warmup <state>, or --next-action <code>.");
+    }
+}
+/**
+ * Whitelist mailbox import fields before the local file crosses the network.
+ * In particular, a credential cannot be silently sent through the ordinary
+ * inline path: the caller must choose --from credentials so the server applies
+ * the encrypted transfer-vault contract. Historical aliases remain accepted by
+ * the parser for backward compatibility but are not advertised.
+ */
+function normalizeMailboxImportFile(value, mode) {
+    try {
+        return normalizeSharedMailboxImportFile(value, mode);
+    }
+    catch (error) {
+        if (error instanceof OxygenError &&
+            error.message ===
+                "This identity-only import contains a password. Choose a secure credential import for a compatible Google app-password export.") {
+            throw new OxygenError("invalid_request", "Mailbox credentials require --from credentials --vendor <source>; keep --validate-only for a no-network preflight. An identity import never accepts or forwards passwords.", { exitCode: 1 });
+        }
+        throw error;
+    }
+}
+function summarizeMailboxImportValidation(mailboxes, input) {
+    return {
+        ...summarizeSharedMailboxImportValidation(mailboxes, input),
+        next_action: "Re-run the same command without --validate-only to register these mailboxes.",
+    };
+}
+function normalizeMailboxImportVendor(raw, from) {
+    return normalizeSharedMailboxImportVendor(raw, from);
+}
+async function readMailboxImportFile(path) {
+    let buffer;
+    try {
+        buffer = readFileSync(path);
+    }
+    catch {
+        throw new OxygenError("mailbox_import_file_unreadable", `Couldn't read --file '${basename(path)}'. Check that the path exists and is readable. CSV/JSON/JSONL/XLSX identity files are accepted; credential exports require --from credentials --vendor <source>. See https://oxygen-agent.com/docs/providers/mailboxes.`, { exitCode: 1 });
+    }
+    if (buffer.byteLength > SHARED_MAILBOX_IMPORT_FILE_MAX_BYTES) {
+        throw new OxygenError("invalid_request", `Mailbox import files must be ${SHARED_MAILBOX_IMPORT_FILE_MAX_BYTES / 1024 / 1024} MB or smaller.`, { exitCode: 1 });
+    }
+    const format = inferRowsFileFormat(path);
+    let rows;
+    if (format === "xlsx") {
+        try {
+            rows = normalizeMailboxWorkbookRows(await parseXlsxWorkbookBuffer(buffer));
+        }
+        catch {
+            throw new OxygenError("invalid_mailbox_import_file", `Couldn't parse the ${format.toUpperCase()} mailbox file. File contents are omitted from this error because mailbox imports may contain credentials.`, { exitCode: 1 });
+        }
+    }
+    else {
+        rows = parseMailboxImportText(buffer.toString("utf8"), format);
+    }
+    if (rows.length > SHARED_MAILBOX_IMPORT_ROW_LIMIT) {
+        throw new OxygenError("invalid_request", `Mailbox imports are limited to ${SHARED_MAILBOX_IMPORT_ROW_LIMIT} rows per request.`, { exitCode: 1 });
+    }
+    return rows;
+}
+export function registerMailboxesFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("mailboxes")
+        .description("Connect customer-owned Gmail/Microsoft 365 inboxes with `oxygen mailboxes connect-oauth --vendor composio` for mail history in Unibox and business activity in CRM; read and control progress with `oxygen mailboxes sync`. Also operate the native email sending pool: register/refresh Google/Microsoft mailboxes (including Microsoft SMTP transport and secure local credential-file transfer), pause, disable or delete inboxes, connect EmailGuard monitoring, and inspect/control OXYGEN Warm-up. Fresh managed InboxKit Google/Microsoft/Azure orders activate exact-scope warm-up automatically after provisioning under their approved default-on add-on. Google reuses the managed credential just in time; Microsoft/Azure uses native export. Standalone warm-up plans and credit caps are for BYOK/imported mailboxes, managed opt-outs, or later separate enrollment. OXYGEN Warm-up never owns campaign dispatch. Every inbox here always belongs to a sender profile (the person it sends as) — list, create, and attach those with `oxygen senders profiles`. Safe import preflight: run `oxygen mailboxes compatibility --catalog-only --json`, then `oxygen mailboxes import --file <path> --validate-only --json` (add the credential source flags shown by import help when the file contains credentials).")
+        .addCommand(new Command("list")
+        .description("List the org's sending mailboxes with provider, status, warmup state, source (managed = bought through Oxygen, byok = bring-your-own), worker-owned connectionRepair and warmupRepair state, and a pool overview (including counts by source). Read each mailbox's warmupTruth for warm-up (state, last_send, pause, dispatch, next_action with the exact command); warmupState is only the stored rail token and reads `error` for a provider-paused seat. mode=automatic means OXYGEN owns the next bounded retry — do not ask for browser consent or disable/re-enable an existing warm-up seat. To see only Google/Microsoft mailboxes that still need OAuth connection, including attempt budgets and manual remedies, use `oxygen mailboxes oauth-health --json`. Read the fleet from `summary` — `summary.by_warmup`, `by_status`, `by_provider`, `by_auth_mode`, `by_transport`, and `by_source` already aggregate every mailbox, so you never need to iterate the `mailboxes` array to count them. `summary.warmup` adds the normalized pool counts — by_truth_state, by_next_action, enrolled, stalled (enrolled with a measured zero warm-up sends), and needs_action — and `--warmup <states>`, `--next-action <codes>`, and `--stalled` narrow the list to exactly those mailboxes, so \"which of my inboxes are not sending\" is one command rather than a local transform over every row. Without `--json` this prints a readable pool: the counts, then every mailbox that owes an action with its cause and the exact command to run.")
+        .option("--status <status>", "Filter by status: active, paused, disabled, or provisioning (ordered, still being set up).")
+        .option("--tag <tags>", "Comma-separated workspace tags — matches mailboxes carrying ANY of these tags (see `oxygen tags list`).")
+        .option("--warmup <states>", "Show only mailboxes whose warm-up is in one of these states (comma-separated): warming, active, paused, error, disabled, pending, not_enrolled, unknown.")
+        .option("--next-action <codes>", "Show only mailboxes whose warm-up needs one of these next steps (comma-separated): none, resume_warmup, reconnect_warmup, enable_warmup, connect_oauth, fix_dns, wait, contact_support.")
+        .option("--stalled", "Show only mailboxes enrolled in warm-up with zero recorded sends (warmupTruth.dispatch.sent null or 0) — the seats you are paying for that are silent. In practice these are the `pending` truth state; an `error` seat has usually sent some mail before it stopped, so it is not stalled.")
+        .option("--json", "Print a JSON envelope. The full payload carries per-mailbox daily warm-up metrics, so a large fleet is megabytes — narrow it with --stalled / --warmup / --next-action, or read the default human view, which already aggregates the pool.")
+        .action(async (options) => {
+        const params = new URLSearchParams();
+        const status = readOption(options.status);
+        if (status)
+            params.set("status", status);
+        const tags = splitCommaList(options.tag);
+        if (tags.length > 0)
+            params.set("tag", tags.join(","));
+        const warmupStates = splitCommaList(options.warmup);
+        if (warmupStates.length > 0)
+            params.set("warmup", warmupStates.join(","));
+        const nextActions = splitCommaList(options.nextAction);
+        if (nextActions.length > 0)
+            params.set("next_action", nextActions.join(","));
+        // Only ever sent as `true`. Omitted when the flag is absent so the
+        // server never has to decide what an unasked-for `stalled=false` meant.
+        if (options.stalled)
+            params.set("stalled", "true");
+        const suffix = params.toString();
+        // What this CLI asked for, kept as flags in query order: a server too
+        // old to echo `filters` back still must not let a match count read as
+        // the whole pool. Every facet narrows the same counts, so every facet
+        // is here — status and tag included.
+        const filterFlags = [];
+        if (status)
+            filterFlags.push(`--status ${status}`);
+        if (tags.length > 0)
+            filterFlags.push(`--tag ${tags.join(",")}`);
+        if (warmupStates.length > 0)
+            filterFlags.push(`--warmup ${warmupStates.join(",")}`);
+        if (nextActions.length > 0)
+            filterFlags.push(`--next-action ${nextActions.join(",")}`);
+        if (options.stalled)
+            filterFlags.push("--stalled");
+        // Bypasses handleAsyncAction the way `tables link` does: --json stays
+        // the byte-identical envelope, and a terminal gets a pool a person can
+        // read instead of the raw blob it used to print.
+        const result = await requestOxygen(`/api/cli/mailboxes${suffix ? `?${suffix}` : ""}`).catch((error) => {
+            emitCliFailure("mailboxes list", error);
+            return null;
+        });
+        if (!result)
+            return;
+        if (options.json) {
+            writeBillingNotices("mailboxes list", result);
+            emitSuccess("mailboxes list", result, options);
+            return;
+        }
+        writeMailboxPoolOverview(result, { filtered: suffix.length > 0, filterFlags });
+    }))
+        .addCommand(new Command("get")
+        .description("Get one sending mailbox's configuration/readiness detail (provider, status, daily cap, warmup state, auth mode, and source — managed vs bring-your-own) plus a one-row pool summary. effective_cap comes first: today's campaign limit (effective_daily_cap), the ramp-up mode and its ramp_schedule. This is not sent/replied/bounced performance; use `oxygen sequences analytics` for native Sequence attribution by mailbox/domain. An ineligible native-send transport includes transport_reason + transport_hint; it does not by itself block OXYGEN Warm-up or EmailGuard monitoring. <mailbox> accepts a mailbox id or email address.")
+        .argument("<mailbox>", "Mailbox id or email address.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (mailbox, options) => {
+        await handleAsyncAction("mailboxes get", options, () => requestOxygen(`/api/cli/mailboxes/${encodeURIComponent(mailbox)}`));
+    }))
+        .addCommand(new Command("delete")
+        .description("Preview or approve removal of exact mailboxes from Oxygen at 0 credits. Deletion immediately removes them from sending but never deletes the underlying Google Workspace or Microsoft 365 accounts. It preserves conversation/message/delivery history and stops any separately listed 100-credit connected-mailbox commitment for future renewals; the preview reports whether that commitment is active and any separately billed OXYGEN Warm-up subscription. The current period is not refunded. Listed active/paused sequences keep their status but lose these senders and are not automatically paused. Without --cascade, a mailbox whose own warm-up or deliverability monitoring is still connected fails closed with its exact teardown steps; with --cascade, those add-ons are disconnected as part of the delete (their recurring credits stop too) and nothing is deleted unless every teardown is confirmed. A live managed DOMAIN subscription covers other mailboxes, so it fails closed unless the whole domain goes too: `oxygen domains delete <domain>`, or --include-domains when every inbox on it is selected.")
+        .requiredOption("--mailboxes <list>", "Comma-separated mailbox ids or addresses (maximum 500).")
+        .option("--approved", "Execute the fresh preview. Requires --plan-hash and --confirmation.")
+        .option("--plan-hash <hash>", "Fresh preview plan_hash.")
+        .option("--confirmation <phrase>", "Exact confirmation_phrase returned by the fresh preview.")
+        .option("--cascade", "Disconnect each mailbox's OWN warm-up and deliverability-monitoring add-ons as part of the delete, instead of failing closed until you tear them down by hand. Stops their recurring credits too. Pass it on the preview as well as the approval: the plan hash is bound to it, so an approval cannot turn it on. A live managed domain subscription still fails closed.")
+        .option("--domains <list>", "Exact domains to cancel/archive with this mailbox deletion; included in the preview and approval hash.")
+        .option("--include-domains", "Also delete each domain whose inboxes are ALL selected: an OXYGEN-bought domain is cancelled, your own is archived (DNS and registrar untouched). Partly selected domains are kept and listed in preview.domains_kept. Pass it on the preview as well as the approval.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes delete", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            if (mailboxes.length === 0) {
+                throw new Error("--mailboxes must contain at least one mailbox id or address.");
+            }
+            const planHash = readOption(options.planHash);
+            const confirmation = readOption(options.confirmation);
+            if (options.approved === true && (!planHash || !confirmation)) {
+                throw new Error("--approved requires --plan-hash and --confirmation from a fresh deletion preview.");
+            }
+            return requestOxygen("/api/cli/mailboxes/delete", {
+                method: "POST",
+                body: {
+                    mailboxes,
+                    ...(options.domains !== undefined ? { domains: readCsvOption(options.domains) } : {}),
+                    ...(options.approved === true ? { approved: true } : {}),
+                    ...(options.cascade === true ? { cascade: true } : {}),
+                    ...(options.includeDomains === true ? { include_domains: true } : {}),
+                    ...(planHash ? { plan_hash: planHash } : {}),
+                    ...(confirmation ? { confirmation } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("health")
+        .description("Fleet email-health: the sending pool rolled up by external deliverability reputation (healthy/degraded/critical/unknown), per-mailbox scores, connected health providers, and DIRECTIONAL recommendations — plus OXYGEN's OWN evidence for the last 7 days, which needs no provider connected: the bounce notifications each mailbox received classified as provider rejection / dead address / mailbox full / delay (a Gmail reputation block shows up as provider_rejected), distinct recipients with a hard bounce in the window (legacy facts retain their first observation time), sequence sends OXYGEN logged (source=sequence only), warm-up day, health score and stop cause, each mailbox's configured daily cap, and the same rollup per sending domain ranked worst-first. Notifications whose body was never stored count as signals.dsn7d.unclassified, which means OXYGEN could not look — not that nothing was wrong. Read health_coverage to see how many mailboxes an external provider has actually scored. Start from the fleet read instead of scanning the mailbox array: warmup.byCause (why warm-up stopped, counted once for the whole pool). Every count is scoped, and the scope is stamped into the payload as signals.window (7d) and signals.sendSource (sequence sends only), on the fleet object and on every mailbox: a 0 means nothing was recorded in that window for that send source, NOT that the fleet is un-blocklisted everywhere. Pure read — 0 credits; never pauses a mailbox or changes a cap.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes health", options, () => requestOxygen("/api/cli/mailboxes/health"));
+    }))
+        .addCommand(new Command("compatibility")
+        .description("Read-only compatibility report per mailbox — select with --mailboxes <address,…> (omit for the whole pool; filter here, not in a script): generic origin class, real infrastructure tier (including InboxKit Azure), OXYGEN native-send connection quality, OXYGEN Warm-up path, EmailGuard monitoring path, and exact next actions. Read automatic_repair for native send and warmup_automatic_repair for an existing warm-up seat: mode=automatic means OXYGEN owns the next bounded retry. Native send distinguishes destination-bound OAuth, provider-managed API transport, admin delegation, and authorization_required. Use --catalog-only for the compact workspace-independent import contract. JSON data.compatibility contains checked rows; data.import_methods and data.import_fields describe accepted transfer inputs; data.provider_matrix is the current public product matrix; data.non_transferable_auth names credentials that must be reconnected; data.summary rolls up states; data.web_url opens the pool. Downstream states distinguish credential_required, consent_required, and vendor_blocked. Never decrypts a credential or calls a downstream provider.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
+        .option("--catalog-only", "Return only the bounded import-method, field, auth-boundary, and public provider catalogs; do not read or return workspace mailbox rows.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes compatibility", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            if (options.catalogOnly === true && mailboxes.length > 0) {
+                throw new OxygenError("invalid_scope", "--catalog-only cannot be combined with --mailboxes.", { exitCode: 1 });
+            }
+            const params = new URLSearchParams();
+            if (options.catalogOnly === true) {
+                params.set("catalog_only", "true");
+            }
+            if (mailboxes.length > 0) {
+                params.set("mailboxes", mailboxes.join(","));
+            }
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/mailboxes/compatibility${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("import")
+        .description("Register (or refresh) sending mailboxes in bulk. Use --validate-only with a local file for a non-mutating, no-network preflight; without it, import is a 0-credit state mutation whose upsert is idempotent by mailbox address. CSV/JSON/JSONL/XLSX identity files from any vendor use --file plus optional --vendor. Compatible Google app-password exports use --from credentials --vendor <source>. Connected Zapmail inventories use --from zapmail. In credential files, app_password is Google-only; Microsoft password fields are discarded locally. OAuth grants, MFA/TOTP seeds, and delegation keys never transfer from customer files: fresh managed InboxKit Google orders reuse the vendor-held credential just in time for automatic warmup, while fresh managed Microsoft/Azure orders use native InboxKit Sequencer export; opted-out/separate managed enrollment uses standalone `warmup enable`; eligible non-InboxKit Microsoft warmup uses the Outlook OAuth fallback (`mailboxes warmup microsoft`); EmailGuard remains vendor_blocked for Microsoft. Google app passwords supplied through an authorized credential import are sent only in the request body, encrypted server-side, and never returned. Every imported inbox is attached to a sender profile: --sender <id> names the person, a row's first/last or display name finds or creates them, otherwise OXYGEN creates a profile named from the address for you to correct.")
+        .addHelpText("after", [
+        "",
+        "Ordinary identity file contract (CSV / JSON / JSONL / XLSX):",
+        "  Canonical fields: email_address, provider, workspace_external_id?, infrastructure_platform?, tenant_id?, first_name?, last_name?, display_name?, sender_profile_id?. Common vendor aliases such as Email, From Email, ESP, Mailbox ID, Entra Tenant ID, Given Name, Surname, and From Name are mapped locally. Credentials are rejected.",
+        "",
+        "All local file imports:",
+        "  Limits: 500 rows / 5 MB for identity and credential files.",
+        "",
+        "Credential file contract:",
+        '  JSON: {"mailboxes":[{"email_address":"ada@send-acme.com","provider":"google","app_password":"<Google mailbox app password>"}]}',
+        "  Only Google app passwords enter the encrypted seven-day transfer vault. Microsoft rows remain identity-only. Generic SMTP passwords and OAuth/MFA/delegation secrets are rejected.",
+        "  Validation: add --validate-only to parse the complete real file and return safe aggregate counts plus the provider-specific exact-account OAuth review plan without authentication, a network request, or a workspace write. The plan groups only supplied addresses into reviews of at most 10; it never discovers a domain, and the later online preview may skip existing grants. Any parse, shape, provider, platform, tenant, secret-policy, or duplicate-conflict error rejects the entire file before the first mailbox write and names mailboxes[index]; validation-only never writes. A later import infrastructure failure may interrupt the upsert; re-run the same file because import is idempotent by address.",
+        "  Docs: https://oxygen-agent.com/docs/providers/mailboxes",
+        "  Skill: oxygen-email-infra (`oxygen skills install --skill oxygen-email-infra`).",
+        "",
+    ].join("\n"))
+        .option("--file <path>", "Local CSV/JSON/JSONL/XLSX file. Common mailbox-vendor headers are normalized locally; only canonical allowlisted fields cross the network.")
+        .option("--from <source>", "Import source: 'credentials' for a compatible Google app-password export, or 'zapmail' to pull a connected workspace.")
+        .option("--vendor <slug>", "Non-secret source provenance (for example instantly, mailforge, or smartlead). Required with --from credentials; optional for identity files.")
+        .option("--connection <id>", "Zapmail connection id (--from zapmail). Defaults to the org's active Zapmail connection.")
+        .option("--provider <provider>", "Zapmail pool to pull (--from zapmail): google or microsoft. Zapmail's mailbox list is provider-scoped, so the Microsoft pool is only reachable with --provider microsoft; Microsoft mailboxes get their Entra tenant id stamped on import.")
+        .option("--sender <profileId>", "Sender profile every imported inbox belongs to (`oxygen senders profiles list` for ids, `create` for a new person). A row's own sender_profile_id or first/last name wins over it; without either, OXYGEN creates a profile named from the address.")
+        .option("--validate-only", "Parse, normalize, and policy-check a local file, then return non-secret aggregate counts without authentication, network access, provider calls, or workspace writes.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes import", options, async () => {
+            const from = readOption(options.from);
+            const filePath = readOption(options.file);
+            const vendor = readOption(options.vendor);
+            const connection = readOption(options.connection);
+            const provider = readOption(options.provider);
+            const sender = readOption(options.sender);
+            const validateOnly = options.validateOnly === true;
+            if (from &&
+                from !== "zapmail" &&
+                from !== "hypertide" &&
+                from !== "credentials") {
+                throw new Error("--from must be credentials or zapmail.");
+            }
+            if (from === "zapmail") {
+                if (validateOnly) {
+                    throw new Error("--validate-only applies to local --file imports and cannot be combined with --from zapmail.");
+                }
+                if (filePath) {
+                    throw new Error("--file cannot be combined with --from zapmail.");
+                }
+                if (vendor) {
+                    throw new Error("--vendor cannot be combined with --from zapmail; the connected integration is authoritative.");
+                }
+                return requestOxygen("/api/cli/mailboxes", {
+                    method: "POST",
+                    body: {
+                        source: "zapmail",
+                        ...(connection ? { connection_id: connection } : {}),
+                        ...(provider ? { service_provider: provider } : {}),
+                        ...(sender ? { sender_profile_id: sender } : {}),
+                    },
+                });
+            }
+            if (provider)
+                throw new Error("--provider only applies with --from zapmail (inline files carry a per-mailbox provider).");
+            if (connection) {
+                throw new Error("--connection only applies with --from zapmail.");
+            }
+            const sourceProvider = normalizeMailboxImportVendor(vendor, from);
+            if (!filePath)
+                throw new Error("Provide --file <path>, --from credentials --vendor <source> --file <path>, or --from zapmail.");
+            const mailboxes = normalizeMailboxImportFile(await readMailboxImportFile(resolve(filePath)), from === "hypertide" || from === "credentials"
+                ? "credential"
+                : "identity");
+            if (validateOnly) {
+                return summarizeMailboxImportValidation(mailboxes, {
+                    source: from === "hypertide"
+                        ? "hypertide_file"
+                        : from === "credentials"
+                            ? "credential_file"
+                            : "identity_file",
+                    sourceProvider: from === "hypertide" ? "hypertide" : sourceProvider,
+                });
+            }
+            return requestOxygen("/api/cli/mailboxes", {
+                method: "POST",
+                body: {
+                    ...(from === "hypertide"
+                        ? { source: "hypertide" }
+                        : from === "credentials"
+                            ? { source: "credential_file" }
+                            : {}),
+                    ...(sourceProvider
+                        ? { source_provider: sourceProvider }
+                        : {}),
+                    ...(sender ? { sender_profile_id: sender } : {}),
+                    mailboxes,
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("tag")
+        .description('Replace a sending mailbox\'s workspace tags (whole set; `--tags ""` clears) — e.g. pool the mailboxes behind one campaign tag. See `oxygen tags list` for the vocabulary.')
+        .argument("<mailbox>", "Mailbox id or email address.")
+        .requiredOption("--tags <tags>", "Comma-separated workspace tags (replaces the whole set; empty clears).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (mailbox, options) => {
+        await handleAsyncAction("mailboxes tag", options, () => requestOxygen(`/api/cli/mailboxes/${encodeURIComponent(mailbox)}/tags`, {
+            method: "POST",
+            body: { tags: splitCommaList(options.tags) },
+        }));
+    }))
+        .addCommand(new Command("status")
+        .description("Set a sending mailbox's status. Pausing/disabling takes the inbox out of the rotation pool without losing its warmup state.")
+        .argument("<mailbox>", "Mailbox id or email address.")
+        .requiredOption("--status <status>", "New status: active, paused, or disabled.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (mailbox, options) => {
+        await handleAsyncAction("mailboxes status", options, () => {
+            const status = readOption(options.status);
+            if (!status)
+                throw new Error("--status is required.");
+            return requestOxygen(`/api/cli/mailboxes/${encodeURIComponent(mailbox)}/status`, {
+                method: "POST",
+                body: { status },
+            });
+        });
+    }))
+        .addCommand(new Command("cap")
+        .description("View and adjust a single mailbox's daily send cap (throttle a problem inbox without pausing it). The campaign ramp-up that climbs to it is `mailboxes ramp set`.")
+        .addCommand(new Command("set")
+        .description("Set one sending mailbox's daily send cap (sends per day; new mailboxes get 25). --daily-cap must be a positive whole number; `oxygen limits show` reports the maximum in force. The campaign ramp-up (standard 5, 10, then 20/day over the first nine sending days) climbs to this cap; customize or turn it off with `mailboxes ramp set`. Optional provider warm-up is configured with `mailboxes warmup config`. Consumes no Oxygen credits. <mailbox> accepts a mailbox id or email address.")
+        .argument("<mailbox>", "Mailbox id or email address.")
+        .requiredOption("--daily-cap <n>", "New daily send cap (a positive whole number of sends per day).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (mailbox, options) => {
+        await handleAsyncAction("mailboxes cap set", options, () => {
+            const raw = readOption(options.dailyCap);
+            if (!raw)
+                throw new Error("--daily-cap is required.");
+            return requestOxygen(`/api/cli/mailboxes/${encodeURIComponent(mailbox)}/cap`, {
+                method: "PATCH",
+                body: { daily_cap: Number(raw) },
+            });
+        });
+    })))
+        .addCommand(new Command("ramp")
+        .description("Campaign ramp-up for one mailbox: how much campaign email it may send on each of its first sending days before its daily cap. Standard is 5, 10, then 20 a day over the first nine sending days; set a custom start and increase, or turn it off for an inbox already sending elsewhere. A sending day is a completed UTC day with accepted campaign sends. Provider warm-up is separate (`mailboxes warmup config`).")
+        .addCommand(new Command("set")
+        .description("Set one mailbox's campaign ramp-up: a custom --start-per-day plus --step every --increase-every-days sending days until its daily cap, --off for the full daily cap from the first sending day, or --clear for the standard 5/10/20 ramp. Sending days are completed UTC days with accepted campaign sends. The optional --cap holds a custom ramp lower for good. effective_cap in the response reads back today's limit, the ramp_schedule and full_cap_on_sending_day. Free configuration write.")
+        .argument("<mailbox>", "Mailbox id or email address.")
+        .option("--start-per-day <n>", "Campaign emails allowed on the first sending day (non-negative whole number).")
+        .option("--increase-every-days <n>", "Sending days between increases (whole number >= 1).")
+        .option("--step <n>", "Emails added at each increase (non-negative whole number).")
+        .option("--cap <n>", "Optional permanent ceiling for the ramp; omit it to climb until the daily cap.")
+        .option("--off", "Turn the ramp off: the full daily cap from the first sending day.")
+        .option("--clear", "Restore the standard 5/10/20 ramp.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (mailbox, options) => {
+        await handleAsyncAction("mailboxes ramp set", options, () => {
+            const knobs = [
+                options.startPerDay,
+                options.increaseEveryDays,
+                options.step,
+                options.cap,
+            ].some((value) => value !== undefined);
+            if (options.off && options.clear) {
+                throw new Error("Use --off or --clear, not both.");
+            }
+            if ((options.off || options.clear) && knobs) {
+                throw new Error("--off and --clear take no ramp numbers; drop --start-per-day, --increase-every-days, --step and --cap.");
+            }
+            let rampConfig;
+            if (options.clear) {
+                rampConfig = null;
+            }
+            else if (options.off) {
+                rampConfig = { enabled: false };
+            }
+            else {
+                const startPerDay = readNonNegativeInt(options.startPerDay);
+                const increaseEveryDays = readPositiveInt(options.increaseEveryDays);
+                const step = readNonNegativeInt(options.step);
+                const cap = readNonNegativeInt(options.cap);
+                if (startPerDay === undefined ||
+                    increaseEveryDays === undefined ||
+                    step === undefined) {
+                    throw new Error("Provide --start-per-day, --increase-every-days and --step (--cap is optional), or --off to turn the ramp off, or --clear for the standard ramp.");
+                }
+                rampConfig = {
+                    start_per_day: startPerDay,
+                    increase_every_days: increaseEveryDays,
+                    step,
+                    ...(cap !== undefined ? { cap } : {}),
+                };
+            }
+            return requestOxygen(`/api/cli/mailboxes/${encodeURIComponent(mailbox)}/ramp`, {
+                method: "PATCH",
+                body: { ramp_config: rampConfig },
+            });
+        });
+    })))
+        .addCommand(new Command("update")
+        .description("Update a sending mailbox's rich-content profile: the From display name and/or the HTML signature appended to its sends. An email that already contains the signature gets no second copy. Pass an empty string ('') to clear a field. Consumes no Oxygen credits. <mailbox> accepts a mailbox id or email address.")
+        .argument("<mailbox>", "Mailbox id or email address.")
+        .option("--display-name <name>", "From display name (e.g. \"Ada from Acme\"). Pass '' to clear it.")
+        .option("--signature-html <html>", "HTML signature appended to every send from this mailbox. Pass '' to clear it.")
+        .option("--signature-file <path>", "Read the HTML signature from a file instead of --signature-html.")
+        .option("--bounce-protection <json>", "Mailbox bounce policy (partial updates merge): enabled=true, warning_rate=.02, pause_rate=.03, min_sends=20, window_days=7. Hard bounces / accepted sends in the rolling window; pauses this mailbox. Rates are fractions; sequence protection is separate.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (mailbox, options) => {
+        await handleAsyncAction("mailboxes update", options, () => {
+            // Detect PRESENCE (options.x !== undefined), not truthiness, so passing
+            // an empty string clears the field rather than being dropped.
+            const patch = {};
+            if (options.bounceProtection !== undefined)
+                patch.bounce_protection = JSON.parse(options.bounceProtection);
+            if (options.displayName !== undefined)
+                patch.display_name = options.displayName;
+            if (options.signatureHtml !== undefined) {
+                patch.signature_html = options.signatureHtml;
+            }
+            else if (options.signatureFile) {
+                patch.signature_html = readFileSync(resolve(options.signatureFile), "utf8");
+            }
+            if (Object.keys(patch).length === 0) {
+                throw new Error("Provide --display-name and/or --signature-html (or --signature-file).");
+            }
+            return requestOxygen(`/api/cli/mailboxes/${encodeURIComponent(mailbox)}`, {
+                method: "PATCH",
+                body: patch,
+            });
+        });
+    }))
+        .addCommand(new Command("sync")
+        .description("Read or control full Inbox, Sent and archive import for Gmail or Microsoft 365. History sync and CRM analysis are included in the mailbox’s 100-credit monthly connection. Spam, trash and drafts are excluded. Without --action, this is a free progress read; controls preview until --approved. Disconnect keeps mail and CRM records, stops sync/sends and future mailbox commitment renewals, with no current-period refund. Paid seats and add-ons retain their own billing contracts.")
+        .argument("<mailbox>", "Mailbox ID or exact email address.")
+        .option("--action <action>", "start, pause, resume or disconnect; omit to read progress.")
+        .option("--approved", "Apply the reviewed control; default is preview.")
+        .option("--dry-run", "Preview the control without changing sync.")
+        .option("--json", "Print JSON.")
+        .action(async (mailbox, options) => {
+        await handleAsyncAction("mailboxes sync", options, () => options.action
+            ? requestOxygen("/api/cli/mailboxes/sync", { method: "POST", body: { mailbox, action: options.action, approved: options.approved === true, dry_run: options.dryRun === true } })
+            : requestOxygen(`/api/cli/mailboxes/sync?${new URLSearchParams({ mailbox }).toString()}`));
+    }))
+        .addCommand(new Command("connect-oauth")
+        .description("Connect Gmail/Microsoft 365 with --vendor composio to import all mail into Unibox and business activity into CRM. The listed recurring rate is 100 credits per mailbox per month including history, sync and analysis; previews cost 0, with no extra execution fee. Before consent, inspect current monthly connection prices and first-debit timing with billing commitments --view connection-prices --json. Quote a mailbox count with billing estimate --mailboxes <n> --json; the managed preview shows the listed rate; an unavailable managed Gmail connection directs you to OXYGEN support, and an unavailable managed Microsoft connection offers OXYGEN's own sign-in (--vendor oxygen --authorization-mode individual) as an explicit, sending-only choice. Managed OAuth requires provider rollout readiness and exact registered addresses, max 10. Use mailboxes sync for progress and pause/resume/disconnect. Composio uses individual owner consent only. Native --vendor oxygen retains its existing polling; full history/CRM requires managed reconnection. Warm-up retains its existing eligibility and pricing. Preview by default; pass --approved only after reviewing exact candidates. --vendor oxygen requires an exact address list and never discovers a domain directory. For --vendor oxygen only, Microsoft supports --authorization-mode tenant (one administrator approval, up to 500 exact selected addresses, recommended for dedicated sending tenants) or individual (one account sign-in per mailbox, max 10 per run, recommended for ordinary company/personal mailboxes). For Microsoft's built-in roles, tenant mode requires a Global Administrator or Privileged Role Administrator because it requests the Microsoft Graph application Mail.Send and Mail.Read permissions; Application Administrator and Cloud Application Administrator cannot consent to Microsoft Graph application roles. Microsoft's application grant is tenant-wide at the provider; OXYGEN—not Microsoft—enforces the selected-address boundary at verification and send time unless the tenant separately configures Exchange Application RBAC. For non-managed Microsoft mailboxes, native-send approval does not authorize OXYGEN Warm-up: every mailbox still needs its own `mailboxes warmup microsoft` Outlook consent before standalone enrollment. Connecting authorization does not change whether a mailbox is active or disabled. Google uses individual OAuth. Source tokens, passwords, authenticator seeds, and one-time codes never transfer. Managed authorization paths remain available through their vendor options.")
+        .addHelpText("after", "\nDocs: https://oxygen-agent.com/docs/providers/mailboxes\n")
+        .option("--provider <provider>", "Mailbox provider: google or microsoft.")
+        .option("--vendor <vendor>", "Authorization path: composio for customer-owned Gmail/Microsoft 365 with managed consent, history and CRM; oxygen for native/tenant consent; zapmail (default) or inboxkit for provisioned inboxes.")
+        .option("--mailboxes <list>", "Comma-separated exact mailbox addresses. Required for vendor=composio (max 10) or vendor=oxygen (tenant mode max 500; individual mode max 10).")
+        .option("--authorization-mode <mode>", "vendor=oxygen only: auto, tenant, or individual. Tenant is Microsoft-only and never scans the directory.")
+        .option("--domains <list>", "Comma-separated sending domains to limit an inboxkit run to. Omit to cover every domain in the pool.")
+        .option("--no-canary", "inboxkit only: fan out to every eligible mailbox on a domain that has never connected one, instead of firing a single canary first.")
+        .option("--connection <id>", "Zapmail connection id. Defaults to the org's active Zapmail connection.")
+        .option("--status <id>", "Poll a previously started Zapmail, InboxKit, or OXYGEN direct-consent run.")
+        .option("--dry-run", "Preview the requested mailbox/domain scope and external writes without changing vendor or ledger state. This is the default for starts; a successful preview can still have zero eligible mailboxes, so check InboxKit candidates with oauth-health before approval.")
+        .option("--approved", "Start the reviewed authorization run. Composio creates an individual consent link for each owner, who must open it and approve access with Google or Microsoft. Native vendor=oxygen records expiring browser steps for the selected owner or tenant administrator. Starting a run does not grant mail access.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes connect-oauth", options, () => {
+            const vendor = readOption(options.vendor);
+            const exportId = readOption(options.status);
+            if (exportId) {
+                const params = new URLSearchParams({ export_id: exportId });
+                const pollConnection = readOption(options.connection);
+                if (pollConnection)
+                    params.set("connection_id", pollConnection);
+                // Omitted, the server reads the vendor off the id's shape (numeric
+                // export id vs run uuid); this is the override for the rare id that
+                // does not look like either.
+                if (vendor)
+                    params.set("vendor", vendor);
+                return requestOxygen(`/api/cli/mailboxes/connect-oauth?${params.toString()}`);
+            }
+            const provider = readOption(options.provider);
+            if (!provider) {
+                throw new Error("--provider <google|microsoft> is required (or pass --status <id> to poll a run).");
+            }
+            const mailboxes = readCsvOption(options.mailboxes);
+            const domains = readCsvOption(options.domains);
+            const connection = readOption(options.connection);
+            const authorizationMode = readOption(options.authorizationMode);
+            return requestOxygen("/api/cli/mailboxes/connect-oauth", {
+                method: "POST",
+                body: {
+                    provider,
+                    // Every key stays absent unless it was asked for, so a run
+                    // without the new flags is the request this command has always
+                    // sent — the server reads an absent vendor as zapmail.
+                    ...(vendor ? { vendor } : {}),
+                    ...(authorizationMode
+                        ? { authorization_mode: authorizationMode }
+                        : {}),
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                    ...(domains.length > 0 ? { domains } : {}),
+                    ...(options.canary === false ? { canary: false } : {}),
+                    ...(connection ? { connection_id: connection } : {}),
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("oauth-health")
+        .description("Show every Google/Microsoft inbox with neither a usable per-mailbox OAuth token nor verified delegation/application access. automatic_repair marks Zapmail-linked rows whose safe retries OXYGEN owns in the background; browser-consent rows remain explicit. Results name connect_oauth_oxygen for imported/manual mailboxes and connect_oauth_inboxkit for that managed path. Microsoft can use one-admin tenant authorization for exact selected addresses or individual OAuth. Read-only — 0 Oxygen credits; it can pause no mailbox and sends no email.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes oauth-health", options, () => requestOxygen("/api/cli/mailboxes/oauth-health"));
+    }))
+        .addCommand(new Command("emailguard")
+        .description("Assess every mailbox origin for EmailGuard and connect credential-capable Google Workspace mailboxes from managed, Zapmail, or compatible encrypted external imports. Manual/native Google rows report credential_required; Microsoft 365/Azure reports vendor_blocked. Preview never materializes a password; approved execution fetches it just in time and never prints it.")
+        .addCommand(new Command("connect")
+        .description("Preview or connect selected mailboxes to EmailGuard. Managed mode is 100 credits/inbox-month, with two placement tests per inbox per cycle included; an extra managed test costs 66 credits. The preview shows the price in force. Own-key monitoring has no monthly Oxygen fee; placement tests pay the in-force platform fee and vendor charges separately. Google Workspace requires a real app password, fetched only after approval. Microsoft 365/Azure is explicitly vendor-blocked because EmailGuard exposes neither Microsoft OAuth nor tenant consent; Oxygen never downgrades it to password auth. Starts with a 0-credit, no-provider-write preview. Account connection sends no placement probe.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
+        .option("--approved", "Perform the external EmailGuard account write.")
+        .option("--plan <hash>", "Exact hash from the fresh preview (required with --approved).")
+        .option("--max-credits <n>", "Hard first-cycle credit cap from the preview (required with --approved, including 0 for BYOK).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes emailguard connect", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            const planHash = readOption(options.plan);
+            const maxCredits = options.approved
+                ? readNonNegativeNumber(options.maxCredits)
+                : undefined;
+            if (options.approved && !planHash) {
+                throw new Error("--plan <hash> from the fresh preview is required with --approved.");
+            }
+            if (options.approved && maxCredits === undefined) {
+                throw new Error("--max-credits <n> from the fresh preview is required with --approved.");
+            }
+            return requestOxygen("/api/cli/mailboxes/emailguard", {
+                method: "POST",
+                body: {
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(planHash ? { plan_hash: planHash } : {}),
+                    ...(maxCredits !== undefined
+                        ? { max_credits: maxCredits }
+                        : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("disconnect")
+        .description("Preview or remove selected mailboxes from EmailGuard and cancel their recurring monitoring subscription. Remote absence is confirmed before billing stops.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
+        .option("--approved", "Perform the external EmailGuard account deletion and cancel billing.")
+        .option("--plan <hash>", "Exact hash from the fresh preview (required with --approved).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes emailguard disconnect", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            const planHash = readOption(options.plan);
+            if (options.approved && !planHash) {
+                throw new Error("--plan <hash> from the fresh preview is required with --approved.");
+            }
+            return requestOxygen("/api/cli/mailboxes/emailguard/disconnect", {
+                method: "POST",
+                body: {
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(planHash ? { plan_hash: planHash } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("auto-enroll")
+        .description("Standing permission to connect NEW eligible mailboxes to EmailGuard automatically, so monitoring keeps up with the fleet instead of needing a manual connect per inbox. Enrolment is a RECURRING monthly charge per inbox, so arming is approval-gated and always bounded by a per-cycle credit ceiling. Without --arm/--disarm/--run this reports the current state (0 credits).")
+        .option("--arm", "Arm the standing permission. Requires --max-credits; previews unless --approved.")
+        .option("--disarm", "Turn it off. Existing subscriptions are untouched. 0 credits, no approval needed.")
+        .option("--run", "Enrol one bounded batch now.")
+        .option("--dry-run", "With --run: report what would be enrolled without connecting or charging. Mailboxes held back by OXYGEN's own managed capacity are reported once under platform_condition (owner: oxygen) rather than as per-mailbox skips; skip_summary counts the rest by reason.")
+        .option("--max-credits <n>", "Per-billing-cycle credit ceiling this permission may spend (required with --arm).")
+        .option("--approved", "Actually arm (otherwise --arm returns a preview).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes emailguard auto-enroll", options, () => {
+            const path = "/api/cli/mailboxes/emailguard/auto-enroll";
+            if (options.disarm) {
+                return requestOxygen(path, {
+                    method: "POST",
+                    body: { enabled: false },
+                });
+            }
+            if (options.arm) {
+                const ceiling = readOption(options.maxCredits);
+                if (!ceiling) {
+                    throw new Error("--max-credits <n> is required with --arm: a standing permission without a ceiling would be unlimited recurring spend authority.");
+                }
+                return requestOxygen(path, {
+                    method: "POST",
+                    body: {
+                        enabled: true,
+                        max_credits_per_cycle: Number(ceiling),
+                        ...(options.approved ? { approved: true } : {}),
+                    },
+                });
+            }
+            if (options.run) {
+                return requestOxygen(path, {
+                    method: "POST",
+                    body: {
+                        run: true,
+                        ...(options.dryRun ? { dry_run: true } : {}),
+                    },
+                });
+            }
+            return requestOxygen(path);
+        });
+    })))
+        .addCommand(new Command("delegation")
+        .description("Google sending-domain delegation only — not Microsoft OAuth and not a credential-file handoff to OXYGEN Warm-up or EmailGuard. Reports covered domains plus the exact client id/scopes; --probe mints a real token per mailbox. Read-only, sends no mail, 0 Oxygen credits.")
+        .option("--domain <domain>", "Only report this sending domain.")
+        .option("--probe", "Verify each delegated domain by minting a real delegated token per mailbox. Makes one Google token call per mailbox; still 0 Oxygen credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes delegation", options, () => {
+            const params = new URLSearchParams();
+            const domain = readOption(options.domain);
+            if (domain)
+                params.set("domain", domain);
+            if (options.probe)
+                params.set("probe", "true");
+            const query = params.toString();
+            return requestOxygen(`/api/cli/mailboxes/delegation${query ? `?${query}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("warmup")
+        .description("OXYGEN Warm-up for the sending pool — the weeks of low-volume conversational mail that make a new inbox look trusted before you cold-send from it. It costs 100 credits per warming inbox per month ($1), or nothing once it is included in your own mailbox's 100-credit monthly connection (2026-09 repricing); the preview shows which applies. Fresh managed InboxKit Google/Microsoft/Azure orders with the default-on warm-up add-on activate automatically after provisioning under the approved order quote; do not run a second `warmup enable`. Google reuses the InboxKit-held credential only during activation and never stores or returns it; Microsoft/Azure uses exact native export. Standalone preview → approval is for BYOK/imported mailboxes, a managed opt-out, or later separate enrollment. InboxKit auto-export stays off for Microsoft/Azure because Oxygen submits only the exact authorized UIDs, and any non-cancelled InboxKit warm-up blocks either handoff so one mailbox cannot warm twice. OXYGEN Warm-up never owns campaign dispatch: native OXYGEN Sequences still own campaigns and sends. Eligible non-InboxKit Microsoft mailboxes use the separate `mailboxes warmup microsoft` OAuth fallback. Inboxes already warming on the retired TrulyInbox rail keep reporting and are wound down there with `warmup disable`; they are never silently moved to the current managed rail. On existing active paid seats, Google credential repair uses its own enabled-by-default switch. When the separate worker recovery mode is enforce (the unset default), Microsoft OAuth or tenant-consent seats get a credential-free vendor reactivation, and stalled dispatch or DNS readiness is rechecked. Shadow reports candidates in those enabled lanes without their vendor writes; off skips those lanes. Google credential repair can still run in shadow/off. Correct bad DNS records yourself; an active unpaused paid seat in enforce mode needs no manual resume after that correction. OXYGEN never invents consent, resumes a human or safety pause, starts a new paid enrollment, or blindly repeats an ambiguous provider write. Check `warmup status` and `mailboxes list` for the exact next action.")
+        .addHelpText("after", "\nDocs: https://oxygen-agent.com/docs/providers/mailboxes\n")
+        .addCommand(new Command("enable")
+        .description("Optional provider warm-up defaults to 1/day, +1/day, max 10/day (dedicated-tenant profiles stay stricter); see `mailboxes warmup config` for the effective plan and unsupported OXYGEN Warm-up reply-rate control. This is separate from the 5/10/20 campaign ramp. STANDALONE ENROLLMENT: enroll BYOK/imported mailboxes, a managed order that opted out, or mailboxes being added to warmup later. Fresh managed InboxKit Google/Microsoft/Azure orders whose approved quote included warmup activate automatically after provisioning and do not need this command. Targets the whole pool unless --mailboxes is given; one synchronous preview/approval is capped at 220 mailboxes, so split larger pools into explicit batches. Without --approved this is a 0-credit, no-provider-write priced preview: nothing is handed off, enrolled, or billed. The price is 100 credits per warming mailbox-month, or 0 once warm-up is included in the mailbox's 100-credit monthly connection (2026-09 repricing; the preview's included_in_connection says which, and its max_credits is then 0); the preview returns the exact first-cycle ceiling. Preview one inbox with `oxygen mailboxes warmup enable --mailboxes sender@example.com --json`. Execute by echoing its --plan and --max-credits with --approved. Gmail connected through Composio uses that connection after approval of standard mailbox access (send, read and organize), without a second Google consent. The preview names this access and disabling warm-up revokes it. Existing vendor-consent seats are preserved. Eligible InboxKit-managed Google targets use the InboxKit-held credential just in time without storing or returning it; Microsoft/Azure targets use native InboxKit Sequencer export with exact UIDs and auto-export off. Any non-cancelled InboxKit warmup must be cancelled before either handoff (pausing is not enough). Only eligible non-InboxKit Microsoft mailboxes need `mailboxes warmup microsoft`. OXYGEN Warm-up retains no campaign authority — OXYGEN Sequences own enrollment and dispatch. New enrollments only ever land on the managed OXYGEN rail; the retired TrulyInbox rail is refused here and only accepts teardown.")
+        .addHelpText("after", "\nDocs: https://oxygen-agent.com/docs/providers/mailboxes\n")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to warm. Omit to warm the whole pool.")
+        .option("--approved", "Execute the PRICED enrollment. Without it the response is a priced preview and nothing is enrolled or billed.")
+        .option("--plan <hash>", "Hash from the fresh preview (required with --approved).")
+        .option("--max-credits <n>", "Hard first-cycle credit cap from the preview (required with --approved).")
+        .option("--ramp-weeks <n>", "Weeks the warm-up volume climb is spread over (default 4). A paid enrollment completes its ramp after 28 days with a provider-confirmed warm-up send, then keeps warming at 10 a day until you disable it.")
+        .option("--dry-run", "Simulate without calling the provider (mailboxes marked pending).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup enable", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            const connection = readOption(options.connection);
+            const billingMode = readOption(options.billingMode);
+            const provider = readOption(options.provider);
+            const planHash = readOption(options.plan);
+            const maxCredits = options.approved
+                ? readNonNegativeNumber(options.maxCredits)
+                : undefined;
+            const rampWeeks = readOption(options.rampWeeks);
+            if (options.approved && !planHash) {
+                throw new Error("--plan <hash> from the fresh preview is required with --approved.");
+            }
+            if (options.approved && maxCredits === undefined) {
+                throw new Error("--max-credits <n> from the fresh preview is required with --approved.");
+            }
+            return requestOxygen("/api/cli/mailboxes/warmup", {
+                method: "POST",
+                body: {
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                    ...(connection ? { connection_id: connection } : {}),
+                    ...(billingMode ? { billing_mode: billingMode } : {}),
+                    ...(provider ? { provider } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(planHash ? { plan_hash: planHash } : {}),
+                    ...(maxCredits !== undefined
+                        ? { max_credits: maxCredits }
+                        : {}),
+                    ...(rampWeeks ? { ramp_weeks: Number(rampWeeks) } : {}),
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("google")
+        .description("Legacy Google owner consent for one to ten connected inboxes. Gmail connected through Composio uses warmup enable to review standard mailbox access without a second Google consent. This legacy flow is separate from native sending: no passwords or OXYGEN tokens transfer. Preview costs 0 credits and creates no link. Approve its hash with --max-credits 0, open each consent_url as that exact inbox, then poll --status. Google shows the warm-up provider's consent application. Warmup stays off until a separately approved warmup enable; its fresh preview shows the price, including 0 extra credits when included in the mailbox connection.")
+        .requiredOption("--mailboxes <list>", "Exact Google inbox ids or addresses, comma-separated; maximum ten.")
+        .option("--approved", "Create the previewed authorization links.")
+        .option("--plan <hash>", "Fresh preview hash; required with approval.")
+        .option("--max-credits <n>", "Exactly 0; required with approval.")
+        .option("--status", "Verify completed Google authorizations; never starts warmup.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup google", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            const planHash = readOption(options.plan);
+            const maxCredits = options.maxCredits === undefined ? undefined : readNonNegativeNumber(options.maxCredits);
+            if (options.approved && options.status)
+                throw new Error("Status and approval cannot be combined.");
+            if (options.approved && (!planHash || maxCredits !== 0))
+                throw new Error("Approval requires a fresh --plan and --max-credits 0.");
+            return requestOxygen("/api/cli/mailboxes/warmup/google", { method: "POST", body: {
+                    mailboxes, ...(options.approved ? { approved: true } : {}), ...(options.status ? { status: true } : {}),
+                    ...(planHash ? { plan_hash: planHash } : {}), ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                } });
+        });
+    }))
+        .addCommand(new Command("microsoft")
+        .description("NON-INBOXKIT FALLBACK ONLY: authorize eligible Microsoft/Outlook mailboxes for OXYGEN Warm-up with ONE browser consent PER MAILBOX, never a password or app password. Do not run this for managed InboxKit mailboxes: fresh Microsoft/Azure orders activate native InboxKit warm-up exports automatically when the approved order includes warmup; opted-out or later separate managed enrollment uses standalone `warmup enable`. For the non-InboxKit fallback there is no tenant-admin shortcut: a 40-inbox Microsoft pool means 40 separate authorizations, each opened by whoever can sign in to that mailbox. The preview names the exact fallback mailboxes and outstanding links at 0 credits. Approve that fresh hash with --max-credits 0, open every returned consent_url, then re-run with --status. Warmup itself stays OFF until standalone `warmup enable`.")
+        .addHelpText("after", "\nDocs: https://oxygen-agent.com/docs/providers/mailboxes\n")
+        .option("--mailboxes <list>", "Comma-separated eligible non-InboxKit Microsoft mailbox ids or addresses. Omit to select the pool; the command refuses a scope containing managed InboxKit rows and points to warmup enable.")
+        .option("--tenant <id>", "Deprecated and ignored: OXYGEN Warm-up consent is per mailbox, so there is no tenant-wide scope to bind. Still accepted so older scripts keep running.")
+        .option("--approved", "Mint the per-mailbox consent links for the exact previewed mailbox scope. Still 0 credits — a human then has to open each link.")
+        .option("--plan <hash>", "Fresh setup preview hash (required with --approved).")
+        .option("--max-credits <n>", "Hard Oxygen credit cap; this setup requires exactly 0 (required with --approved).")
+        .option("--status", "Poll the per-mailbox consents instead of creating a new setup preview: reports which mailboxes are authorized and which are still waiting for someone to open their link.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup microsoft", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            const tenantId = readOption(options.tenant);
+            const planHash = readOption(options.plan);
+            const maxCredits = options.approved
+                ? readNonNegativeNumber(options.maxCredits)
+                : undefined;
+            if (options.status && options.approved) {
+                throw new Error("--status cannot be combined with --approved.");
+            }
+            if (options.approved && !planHash) {
+                throw new Error("--plan <hash> from the fresh Microsoft setup preview is required with --approved.");
+            }
+            if (options.approved && maxCredits !== 0) {
+                throw new Error("--max-credits 0 is required with --approved; tenant setup consumes no Oxygen credits.");
+            }
+            return requestOxygen("/api/cli/mailboxes/warmup/microsoft", {
+                method: "POST",
+                body: {
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                    ...(tenantId ? { tenant_id: tenantId } : {}),
+                    ...(options.status ? { status: true } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(planHash ? { plan_hash: planHash } : {}),
+                    ...(maxCredits !== undefined
+                        ? { max_credits: maxCredits }
+                        : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("config")
+        .description("Read or override optional provider warm-up traffic, separate from the campaign ramp. Standard defaults: start 1/day, add 1/day, maximum 10/day; dedicated-tenant profiles stay stricter. No flags reads the effective plan. Override with all four knobs, or --reset for defaults. OXYGEN Warm-up does not support reply-rate control: the value is saved but not applied there. Active warm-up syncs immediately without re-enrollment or rebilling; provider_sync reports the result. 0 Oxygen credits.")
+        .argument("<mailbox>", "Mailbox id or email address.")
+        .option("--initial-per-day <n>", "Warmup emails sent on day one.")
+        .option("--increase-per-day <n>", "Warmup emails added to the daily volume each day.")
+        .option("--max-per-day <n>", "The warmup daily ceiling; climbing stops here.")
+        .option("--reply-rate <percent>", "Requested warm-up reply rate (0-100); saved but unsupported by OXYGEN Warm-up.")
+        .option("--reset", "Drop the override and restore the default provider warm-up plan.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (mailbox, options) => {
+        await handleAsyncAction("mailboxes warmup config", options, () => {
+            const path = `/api/cli/mailboxes/${encodeURIComponent(mailbox)}/warmup-config`;
+            if (options.reset) {
+                return requestOxygen(path, {
+                    method: "PATCH",
+                    body: { warmup_config: null },
+                });
+            }
+            const knobs = {
+                initial_per_day: readOption(options.initialPerDay),
+                increase_per_day: readOption(options.increasePerDay),
+                max_per_day: readOption(options.maxPerDay),
+                reply_rate_percent: readOption(options.replyRate),
+            };
+            const provided = Object.values(knobs).filter((value) => value !== null && value !== undefined);
+            // Reading is a GET on the mailbox: the derived plan is a property
+            // of the mailbox, not of an override that may not exist.
+            if (provided.length === 0) {
+                return requestOxygen(`/api/cli/mailboxes/${encodeURIComponent(mailbox)}`);
+            }
+            if (provided.length < 4) {
+                throw new OxygenError("invalid_request", "Overriding the ramp needs all four knobs: --initial-per-day, --increase-per-day, --max-per-day, --reply-rate. Omit them all to show the derived plan, or pass --reset to clear an override.", { exitCode: 2 });
+            }
+            return requestOxygen(path, {
+                method: "PATCH",
+                body: {
+                    warmup_config: {
+                        initial_per_day: Number(knobs.initial_per_day),
+                        increase_per_day: Number(knobs.increase_per_day),
+                        max_per_day: Number(knobs.max_per_day),
+                        reply_rate_percent: Number(knobs.reply_rate_percent),
+                    },
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("profile")
+        .description("Pin the SENDING ARCHITECTURE a domain is run as, which every inbox on it inherits: `standard` (a few mailboxes on a real business tenant, each climbing to a real number), `dedicated_tenant` (infrastructure tenant, volume from breadth, per-inbox number stays small), or `entry` (first-touch inboxes that need presence, not volume). What you state is the DOMAIN's daily budget; OXYGEN divides it by how many inboxes share that domain, so adding an inbox lowers the others instead of raising the domain's total — the thing a flat per-mailbox cap cannot do. A profile is a CEILING: it never raises a cap above what you configured, and the strictest of {configured cap, per-sequence override, sending-day ramp, profile share} still wins. 0 credits, no provider call. Without --approved this previews the before/after per domain. Omit every selector and profile to list the available profiles.")
+        .addHelpText("after", "\nDocs: https://oxygen-agent.com/docs/providers/mailboxes\n")
+        // NOT --profile: the program declares a GLOBAL --profile (the stored
+        // CLI credential profile), and Commander resolves the value to that
+        // one, so the subcommand's copy silently reads empty. --type is also
+        // the word an operator uses for this ("a specific warm-up type").
+        .option("--type <name>", "Warm-up type to pin: standard, dedicated_tenant, or entry.")
+        .option("--domains <list>", "Comma-separated domains to bind. Every inbox on them inherits the profile.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to override individually — the exception path, not the bulk path.")
+        .option("--all", "Bind every domain that currently holds a mailbox.")
+        .option("--cold-send-per-day <n>", "Override the profile's DOMAIN budget for cold sends per day (not a per-inbox number).")
+        .option("--warmup-per-day <n>", "Override the profile's DOMAIN budget for warm-up emails per day (not a per-inbox number).")
+        .option("--clear", "Remove the profile, restoring inference and the sending-day ramp alone.")
+        .option("--approved", "Apply the previewed change.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup profile", options, () => {
+            const domains = readCsvOption(options.domains);
+            const mailboxes = readCsvOption(options.mailboxes);
+            const all = options.all === true;
+            const clear = options.clear === true;
+            const profile = readOption(options.type);
+            // No selector and no profile is the discovery call: show what
+            // the profiles ARE rather than erroring on a missing flag.
+            if (!all && domains.length === 0 && mailboxes.length === 0 && !profile && !clear) {
+                return requestOxygen("/api/cli/mailboxes/warmup-profile");
+            }
+            if (!profile && !clear) {
+                throw new OxygenError("invalid_request", "Name a --type to pin, or pass --clear to remove one.", { exitCode: 2 });
+            }
+            const coldSend = readOption(options.coldSendPerDay);
+            const warmupPerDay = readOption(options.warmupPerDay);
+            if ((coldSend === null) !== (warmupPerDay === null)) {
+                throw new OxygenError("invalid_request", "A budget override needs BOTH --cold-send-per-day and --warmup-per-day; they are separate budgets and defaulting one silently would misstate the domain's ceiling.", { exitCode: 2 });
+            }
+            return requestOxygen("/api/cli/mailboxes/warmup-profile", {
+                method: "POST",
+                body: {
+                    profile: clear ? null : profile,
+                    ...(coldSend !== null && warmupPerDay !== null
+                        ? {
+                            budget: {
+                                cold_send_per_day: Number(coldSend),
+                                warmup_per_day: Number(warmupPerDay),
+                            },
+                        }
+                        : {}),
+                    ...(domains.length > 0 ? { domains } : {}),
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                    ...(all ? { all: true } : {}),
+                    ...(options.approved === true ? { approved: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("pause")
+        .description("Pause warmup at the rail that actually enrolled each mailbox — OXYGEN Warm-up for current enrollments, TrulyInbox for inboxes still warming there. A mailbox left on a rail Oxygen no longer drives reports unsupported instead of being retargeted, so the reply never claims a pause that did not happen. Targets the whole pool unless --mailboxes is given.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup pause", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            return requestOxygen("/api/cli/mailboxes/warmup/pause", {
+                method: "POST",
+                body: { ...(mailboxes.length > 0 ? { mailboxes } : {}) },
+            });
+        });
+    }))
+        .addCommand(new Command("resume")
+        .description("Resume paused warmup at each mailbox's recorded rail (OXYGEN Warm-up, or TrulyInbox for inboxes still warming there). 0 Oxygen credits; the existing subscription is unchanged. This changes warmup state and uses the last stored analytics snapshot; run warmup status afterward for fresh provider data. Running status alone does not prove a new successful send. A mailbox on a rail Oxygen no longer drives reports unsupported instead of being retargeted. Targets the whole pool unless --mailboxes is given.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup resume", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            return requestOxygen("/api/cli/mailboxes/warmup/resume", {
+                method: "POST",
+                body: { ...(mailboxes.length > 0 ? { mailboxes } : {}) },
+            });
+        });
+    }))
+        .addCommand(new Command("reconnect")
+        .description("Manual repair for an existing live paid seat when automatic credential repair is disabled, exhausted, or needs a new credential: push the mailbox's CURRENT credential to its warmup provider. Use this when a new app password is needed because the old one was rotated or revoked (the provider reporting 'Username and Password not accepted'): re-import the new credential with `mailboxes import`, then run this. It costs 0 credits and leaves your warmup subscription and its renewal date exactly as they are — you do NOT need to disable and re-enable warmup, which would charge a second month. The provider cannot change a stored password in place, so the inbox's warmup history restarts from day 1. Targets the whole pool unless --mailboxes is given.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup reconnect", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            return requestOxygen("/api/cli/mailboxes/warmup/reconnect", {
+                method: "POST",
+                body: {
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("reactivate")
+        .description("Manual reactivation of an existing live paid seat: ask the warm-up provider to re-run the connection check on an inbox it has DISABLED, without touching the credential, subscription, or ramp day. When worker recovery is enforcing, OXYGEN first tries this vendor reactivation automatically for a Microsoft OAuth or tenant-consent seat, without a password or new browser consent. Use this command while recovery is staged in shadow/off, or if `warmup status` still asks you to reactivate after bounded attempts; `warmup reconnect` cannot re-push a password for that consent seat. 0 credits: the subscription, its renewal date, and the ramp day all stay exactly as they are, so it is the free alternative to disable + re-enable (which bills another warm-up month AND restarts the ramp at day 1). Only inboxes with a live warm-up subscription are eligible. IMPORTANT: this forces the provider to re-check; a forced pass is NOT proof the connection works. Confirm recovery from a rising send count with `oxygen mailboxes warmup status` after the provider's next batch, which is hours away, not minutes. Targets the whole pool unless --mailboxes is given.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup reactivate", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            return requestOxygen("/api/cli/mailboxes/warmup/reactivate", {
+                method: "POST",
+                body: {
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("disable")
+        .description("Disable warmup and unenroll each mailbox from the rail that actually enrolled it. On a managed rail — OXYGEN Warm-up today, TrulyInbox for older enrollments — this also cancels that mailbox's warmup subscription, so billing stops with the provider removal. This is how you wind an inbox off the retired TrulyInbox rail. NOT the way to fix a rotated app password — use `mailboxes warmup reconnect` for that, which costs 0 credits instead of a new 100-credit month. Targets the whole pool unless --mailboxes is given.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup disable", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            return requestOxygen("/api/cli/mailboxes/warmup/disable", {
+                method: "POST",
+                body: { ...(mailboxes.length > 0 ? { mailboxes } : {}) },
+            });
+        });
+    }))
+        .addCommand(new Command("status")
+        .description("Read warmup analytics back from the rail each mailbox is enrolled on and refresh each mailbox's warmupTruth (state, last send, pause reason, dispatch counters, next_action). A read: 0 Oxygen credits, no campaign sends, no change to your configuration; the one write OXYGEN may make is its own breaker pausing a mailbox proven to be dispatching far above its ramp. Targets the whole pool unless --mailboxes is given. For a per-mailbox read without a rail sync, use `oxygen mailboxes get <address> --json`.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to sync. Omit to sync the whole pool.")
+        .option("--provider <name>", "Optional machine routing filter. Omit it for OXYGEN Warm-up; pass trulyinbox only to read inboxes still warming on the retired rail.")
+        .option("--dry-run", "Skip the provider call (mailboxes marked pending).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup status", options, () => {
+            const params = new URLSearchParams();
+            const mailboxes = readCsvOption(options.mailboxes);
+            if (mailboxes.length > 0)
+                params.set("mailboxes", mailboxes.join(","));
+            const connection = readOption(options.connection);
+            if (connection)
+                params.set("connection_id", connection);
+            const billingMode = readOption(options.billingMode);
+            if (billingMode)
+                params.set("billing_mode", billingMode);
+            const provider = readOption(options.provider);
+            if (provider)
+                params.set("provider", provider);
+            if (options.dryRun)
+                params.set("dry_run", "true");
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/mailboxes/warmup/status${suffix ? `?${suffix}` : ""}`);
+        });
+    })))
+        .addCommand(new Command("order")
+        .description("RETIRED — managed mailboxes are now purchased as monthly subscriptions via `oxygen managed-inboxes subscribe` (InboxKit-backed). This legacy Zapmail order path was never enabled anywhere and now always fails with code `gone`.")
+        // Swallow the old flags (--provider/--domains/--approved/...) so a
+        // stale invocation reaches the tombstone envelope instead of dying
+        // on commander's unknown-option parse error.
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .action(() => {
+        emitCliFailure("mailboxes order", new OxygenError("gone", "`oxygen mailboxes order` is retired — managed mailboxes are now purchased as monthly subscriptions via `oxygen managed-inboxes subscribe` (InboxKit-backed). Preview a quote, then re-run with --approved --quote <id>. Nothing was ordered or charged.", {
+            details: {
+                replacement: "oxygen managed-inboxes subscribe",
+                deep_link: "https://oxygen-agent.com/billing",
+            },
+        }));
+    })));
+}