@oxygen-agent/cli 1.575.19 → 1.591.1

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.575.19
+Version: 1.591.1

package/dist/help.js

@@ -137,6 +137,7 @@ export function applyOxygenHelp(program, binaryName) {
         // first-touch surface names the skill that teaches the GTM loops.
         `  2. ${binaryName} skills install --json      load the skills that teach the GTM loops (automatic after login)`,
         `  3. ${binaryName} commands --json            full machine-readable command grammar (this CLI's self-index)`,
+        `  Recurring monitors: use a shareable Blueprint; start with ${binaryName} blueprints list --json.`,
         "",
         "Conventions:",
         "  --json prints a stable envelope {ok, data|error, meta}; errors always print it.",

package/dist/index.js

@@ -639,99 +639,217 @@ function readJsonFileValue(path, inputName) {
 /**
  * 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 hypertide so the server applies
- * the encrypted transfer-vault contract.
+ * inline path: the caller must choose --from credentials (or the Hypertide
+ * shortcut) so the server applies the encrypted transfer-vault contract.
  */
-function normalizeMailboxImportFile(value, source) {
+function normalizeMailboxImportFile(value, mode) {
     if (!Array.isArray(value) || value.length === 0) {
         throw new OxygenError("invalid_request", "--file must contain a non-empty mailboxes array.", { exitCode: 1 });
     }
-    return value.map((entry, index) => {
+    const rows = value.map((entry, index) => {
         if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
             throw new OxygenError("invalid_request", `mailboxes[${index}] must be an object.`, { exitCode: 1 });
         }
-        const rawRow = entry;
-        const row = source === "hypertide"
-            ? normalizeHypertideMailboxExportRow(rawRow, index)
-            : rawRow;
-        const hasCredential = typeof row.app_password === "string" || typeof row.password === "string";
-        if (source === "inline" && hasCredential) {
-            throw new OxygenError("invalid_request", "Mailbox credentials require --from hypertide; the ordinary inline import never accepts or forwards passwords.", { exitCode: 1 });
-        }
-        return {
-            ...(typeof row.email_address === "string"
-                ? { email_address: row.email_address }
-                : {}),
-            ...(typeof row.provider === "string" ? { provider: row.provider } : {}),
-            ...(typeof row.workspace_external_id === "string"
-                ? { workspace_external_id: row.workspace_external_id }
-                : {}),
-            ...(source === "hypertide" && typeof row.app_password === "string"
-                ? { app_password: row.app_password }
-                : {}),
-        };
+        return normalizeMailboxExportRow(entry, index, mode);
     });
+    return dedupeMailboxImportRows(rows);
+}
+function summarizeMailboxImportValidation(mailboxes, input) {
+    const providers = { google: 0, microsoft: 0 };
+    const infrastructurePlatforms = {};
+    let credentialRows = 0;
+    for (const mailbox of mailboxes) {
+        if (mailbox.provider === "google")
+            providers.google += 1;
+        if (mailbox.provider === "microsoft")
+            providers.microsoft += 1;
+        if (typeof mailbox.infrastructure_platform === "string") {
+            const platform = mailbox.infrastructure_platform;
+            infrastructurePlatforms[platform] =
+                (infrastructurePlatforms[platform] ?? 0) + 1;
+        }
+        if (typeof mailbox.app_password === "string")
+            credentialRows += 1;
+    }
+    return {
+        valid: true,
+        source: input.source,
+        ...(input.sourceProvider
+            ? { source_provider: input.sourceProvider }
+            : {}),
+        rows: mailboxes.length,
+        providers,
+        infrastructure_platforms: infrastructurePlatforms,
+        credential_rows: credentialRows,
+        identity_only_rows: mailboxes.length - credentialRows,
+        limits: {
+            max_rows: MAILBOX_IMPORT_ROW_LIMIT,
+            max_file_bytes: MAILBOX_IMPORT_FILE_MAX_BYTES,
+        },
+        mutation: false,
+        network_request: false,
+        provider_call: false,
+        credits_used: 0,
+        next_action: "Re-run the same command without --validate-only to register these mailboxes.",
+    };
 }
-const HYPERTIDE_EMAIL_HEADERS = new Set([
+const MAILBOX_EMAIL_HEADERS = new Set([
     "address",
     "email",
     "emailaddress",
+    "fromemail",
     "mailbox",
     "mailboxaddress",
     "mailboxemail",
 ]);
-const HYPERTIDE_PROVIDER_HEADERS = new Set([
+const MAILBOX_PROVIDER_HEADERS = new Set([
     "emailprovider",
+    "esp",
     "mailboxprovider",
     "platform",
     "provider",
     "serviceprovider",
     "type",
 ]);
-const HYPERTIDE_PASSWORD_HEADERS = new Set([
+const MAILBOX_PASSWORD_HEADERS = new Set([
     "apppassword",
+    "applicationpassword",
+    "googleapppassword",
     "imappassword",
     "mailboxpassword",
     "password",
     "smtppassword",
 ]);
-const HYPERTIDE_WORKSPACE_HEADERS = new Set([
+const MAILBOX_WORKSPACE_HEADERS = new Set([
     "externalaccountid",
+    "mailboxid",
+    "mailboxuid",
+    "sourceaccountid",
+    "sourcemailboxid",
+    "uid",
     "workspaceexternalid",
 ]);
+const MAILBOX_PLATFORM_HEADERS = new Set([
+    "infrastructure",
+    "infrastructureplatform",
+    "infraplatform",
+]);
+const MAILBOX_TENANT_HEADERS = new Set([
+    "azuretenantid",
+    "entratenantid",
+    "microsofttenantid",
+    "tenantid",
+]);
+const MAILBOX_NON_TRANSFERABLE_SECRET_HEADERS = new Set([
+    "accesstoken",
+    "applicationsecret",
+    "authenticatorsecret",
+    "authorization",
+    "authorizationcode",
+    "bearertoken",
+    "clientsecret",
+    "clientprivatekey",
+    "delegationkey",
+    "idtoken",
+    "mfacode",
+    "mfasecret",
+    "oauthaccesstoken",
+    "oauthcode",
+    "oauthrefreshtoken",
+    "oauthtoken",
+    "onetimepassword",
+    "otp",
+    "otpsecret",
+    "privatekey",
+    "refreshtoken",
+    "serviceaccountkey",
+    "serviceaccountjson",
+    "serviceaccountprivatekey",
+    "totp",
+    "totpsecret",
+]);
 const MAILBOX_IMPORT_FILE_MAX_BYTES = 5 * 1024 * 1024;
 const MAILBOX_IMPORT_ROW_LIMIT = 500;
 /**
- * Hypertide's public contract promises a CSV carrying mailbox addresses,
- * app-password/OAuth credentials, and SMTP/IMAP host information, but it does
- * not publish one canonical header spelling. Normalize the common export
- * labels locally, then send only Oxygen's canonical fields. Microsoft passwords
- * are intentionally dropped because tenant consent is its only warmup path.
- * Host/DNS columns are useful for provider inference but never cross the request
- * boundary; Oxygen derives the standard Google/Microsoft endpoints itself.
+ * Normalize common mailbox-vendor export labels locally, then send only
+ * Oxygen's canonical fields. Passwords are accepted only in credential mode
+ * and only become Google app passwords; Microsoft passwords are dropped because
+ * tenant consent is its only warmup path. OAuth grants, MFA/TOTP seeds, and
+ * delegation keys are rejected in every mode. Host columns may prove the
+ * provider but never cross the request boundary.
  */
-function normalizeHypertideMailboxExportRow(row, index) {
+function normalizeMailboxExportRow(row, index, mode) {
     const byHeader = new Map();
     for (const [header, value] of Object.entries(row)) {
-        byHeader.set(normalizeMailboxExportHeader(header), value);
+        const normalizedHeader = normalizeMailboxExportHeader(header);
+        const existing = byHeader.get(normalizedHeader);
+        if (existing !== undefined &&
+            String(existing).trim() !== String(value ?? "").trim()) {
+            throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting columns that normalize to ${normalizedHeader}.`, { exitCode: 1 });
+        }
+        byHeader.set(normalizedHeader, value);
+    }
+    const email = readUniqueMailboxExportString(byHeader, MAILBOX_EMAIL_HEADERS, index, "email_address", (value) => value.trim().toLowerCase()) ?? readEmailShapedMailboxUsername(byHeader);
+    const providerValues = readMailboxExportStrings(byHeader, MAILBOX_PROVIDER_HEADERS);
+    const provider = normalizeMailboxProvider(providerValues, byHeader, index);
+    if (!email ||
+        email.length > 320 ||
+        !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].email_address must be a valid address of at most 320 characters.`, { exitCode: 1 });
+    }
+    if (!provider) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].provider could not be inferred. Oxygen imports Google Workspace and Microsoft 365/Entra identities; generic SMTP credentials are not transferable yet.`, { exitCode: 1 });
     }
-    const email = readMailboxExportString(byHeader, HYPERTIDE_EMAIL_HEADERS) ??
-        readEmailShapedMailboxUsername(byHeader);
-    const providerRaw = readMailboxExportString(byHeader, HYPERTIDE_PROVIDER_HEADERS);
-    const provider = normalizeHypertideMailboxProvider(providerRaw, byHeader, index);
-    const passwords = readMailboxExportStrings(byHeader, HYPERTIDE_PASSWORD_HEADERS);
+    if (hasMailboxExportValue(byHeader, MAILBOX_NON_TRANSFERABLE_SECRET_HEADERS) ||
+        hasNonTransferableMailboxAuthLikeValue(byHeader)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains OAuth, MFA/TOTP, client-secret, or delegation material. Those credentials are never transferable; import the mailbox identity and complete the provider's administrator consent flow.`, { exitCode: 1 });
+    }
+    const passwords = readMailboxExportStrings(byHeader, MAILBOX_PASSWORD_HEADERS);
     const distinctPasswords = [...new Set(passwords)];
+    if (distinctPasswords.some((password) => password.length > 1024)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].app_password must be at most 1024 characters.`, { exitCode: 1 });
+    }
+    if (mode === "identity" && distinctPasswords.length > 0) {
+        throw new OxygenError("invalid_request", "Mailbox credentials require --from credentials --vendor <source> (or --from hypertide for a Hypertide export); keep --validate-only for a no-network preflight. An identity import never accepts or forwards passwords.", { exitCode: 1 });
+    }
     if (provider !== "microsoft" && distinctPasswords.length > 1) {
         throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting SMTP/IMAP/app-password values.`, { exitCode: 1 });
     }
-    const workspaceExternalId = readMailboxExportString(byHeader, HYPERTIDE_WORKSPACE_HEADERS);
+    if (mode === "credential" &&
+        provider === "google" &&
+        distinctPasswords.length === 0) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] needs a Google app password for credential import. OAuth tokens and an ordinary account password are not portable.`, { exitCode: 1 });
+    }
+    const workspaceExternalId = readUniqueMailboxExportString(byHeader, MAILBOX_WORKSPACE_HEADERS, index, "workspace_external_id", (value) => value.trim());
+    if (workspaceExternalId && workspaceExternalId.length > 512) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].workspace_external_id must be at most 512 characters.`, { exitCode: 1 });
+    }
+    const tenantId = readUniqueMailboxExportString(byHeader, MAILBOX_TENANT_HEADERS, index, "tenant_id", (value) => value.trim().toLowerCase());
+    if (tenantId && provider !== "microsoft") {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].tenant_id applies only to Microsoft mailboxes.`, { exitCode: 1 });
+    }
+    if (tenantId &&
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(tenantId.trim())) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].tenant_id must be a Microsoft Entra tenant GUID.`, { exitCode: 1 });
+    }
+    const infrastructurePlatformRaw = readUniqueMailboxExportString(byHeader, MAILBOX_PLATFORM_HEADERS, index, "infrastructure_platform", (value) => normalizeMailboxExportHeader(value)) ??
+        (providerValues.some((value) => ["azure", "entra", "microsoftazure"].includes(normalizeMailboxExportHeader(value)))
+            ? "microsoft_azure"
+            : null);
+    const infrastructurePlatform = normalizeMailboxInfrastructurePlatform(infrastructurePlatformRaw, provider, index);
     return {
-        ...(email !== null ? { email_address: email } : {}),
-        ...(provider !== null ? { provider } : {}),
+        email_address: email.trim().toLowerCase(),
+        provider,
         ...(workspaceExternalId !== null
-            ? { workspace_external_id: workspaceExternalId }
+            ? { workspace_external_id: workspaceExternalId.trim() }
+            : {}),
+        ...(infrastructurePlatformRaw
+            ? { infrastructure_platform: infrastructurePlatform }
             : {}),
-        ...(provider !== "microsoft" && distinctPasswords[0] !== undefined
+        ...(tenantId ? { tenant_id: tenantId.trim().toLowerCase() } : {}),
+        ...(mode === "credential" &&
+            provider === "google" &&
+            distinctPasswords[0] !== undefined
             ? { app_password: distinctPasswords[0] }
             : {}),
     };
@@ -752,6 +870,16 @@ function readMailboxExportString(byHeader, headers) {
     }
     return null;
 }
+function readUniqueMailboxExportString(byHeader, headers, index, field, normalize) {
+    const values = readMailboxExportStrings(byHeader, headers);
+    if (values.length === 0)
+        return null;
+    const normalized = [...new Set(values.map(normalize))];
+    if (normalized.length > 1) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting ${field} aliases.`, { exitCode: 1 });
+    }
+    return normalized[0] ?? null;
+}
 function readMailboxExportStrings(byHeader, headers) {
     const values = [];
     for (const header of headers) {
@@ -761,24 +889,115 @@ function readMailboxExportStrings(byHeader, headers) {
     }
     return values;
 }
+function hasMailboxExportValue(byHeader, headers) {
+    for (const header of headers) {
+        const value = byHeader.get(header);
+        if (value !== undefined && value !== null && String(value).trim()) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasNonTransferableMailboxAuthLikeValue(byHeader) {
+    for (const [header, value] of byHeader) {
+        if (/(?:token|secret|privatekey|totp|passcode|authorization)/.test(header) &&
+            value !== undefined &&
+            value !== null &&
+            String(value).trim()) {
+            return true;
+        }
+    }
+    return false;
+}
 function readEmailShapedMailboxUsername(byHeader) {
     for (const header of ["username", "imapusername", "smtpusername"]) {
         const value = byHeader.get(header);
         if (typeof value === "string" && value.includes("@"))
-            return value;
+            return value.trim().toLowerCase();
     }
     return null;
 }
-function normalizeHypertideMailboxProvider(providerRaw, byHeader, index) {
-    const normalized = providerRaw
-        ? normalizeMailboxExportHeader(providerRaw)
-        : "";
-    if (["google", "googleworkspace", "gmail", "gsuite"].includes(normalized)) {
-        return "google";
+function normalizeMailboxProvider(providerValues, byHeader, index) {
+    const explicit = providerValues.map((value) => {
+        const normalized = normalizeMailboxExportHeader(value);
+        if (["google", "googleworkspace", "gmail", "gsuite"].includes(normalized)) {
+            return "google";
+        }
+        if ([
+            "azure",
+            "entra",
+            "m365",
+            "microsoft",
+            "microsoft365",
+            "microsoftazure",
+            "ms365",
+            "o365",
+            "office365",
+            "outlook",
+        ].includes(normalized)) {
+            return "microsoft";
+        }
+        throw new OxygenError("invalid_request", `mailboxes[${index}].provider is unsupported; expected Google/Gmail/Workspace or Microsoft/Outlook/Office 365/Entra.`, { exitCode: 1 });
+    });
+    const explicitKinds = [...new Set(explicit)];
+    if (explicitKinds.length > 1) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting provider aliases.`, { exitCode: 1 });
+    }
+    const hostValues = [
+        byHeader.get("imaphost"),
+        byHeader.get("imaphostname"),
+        byHeader.get("imapserver"),
+        byHeader.get("smtphost"),
+        byHeader.get("smtphostname"),
+        byHeader.get("smtpserver"),
+    ].filter((value) => typeof value === "string" && Boolean(value.trim()));
+    const hostKinds = hostValues.map((value) => {
+        const hostname = normalizeMailboxHost(value);
+        if (hostname === "smtp.gmail.com" || hostname === "imap.gmail.com") {
+            return "google";
+        }
+        if (hostname === "smtp.office365.com" ||
+            hostname === "outlook.office365.com") {
+            return "microsoft";
+        }
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains a non-standard SMTP/IMAP host. Oxygen imports Google Workspace and Microsoft 365/Entra identities; generic SMTP credential transport is not supported.`, { exitCode: 1 });
+    });
+    const inferredKinds = [...new Set(hostKinds)];
+    if (inferredKinds.length > 1) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting Google and Microsoft mail hosts.`, { exitCode: 1 });
+    }
+    const explicitKind = explicitKinds[0];
+    const inferredKind = inferredKinds[0];
+    if (explicitKind && inferredKind && explicitKind !== inferredKind) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] has conflicting provider and SMTP/IMAP host evidence.`, { exitCode: 1 });
+    }
+    return explicitKind ?? inferredKind ?? null;
+}
+function normalizeMailboxHost(value) {
+    const withoutScheme = value
+        .trim()
+        .toLowerCase()
+        .replace(/^[a-z]+:\/\//, "");
+    return withoutScheme.split(/[/:]/, 1)[0] ?? "";
+}
+function normalizeMailboxInfrastructurePlatform(raw, provider, index) {
+    if (!raw) {
+        return provider === "google" ? "google_workspace" : "microsoft_365";
+    }
+    const normalized = normalizeMailboxExportHeader(raw);
+    if (["google", "googleworkspace", "gmail", "gsuite", "workspace"].includes(normalized)) {
+        if (provider !== "google") {
+            throw mailboxPlatformConflict(index, provider);
+        }
+        return "google_workspace";
+    }
+    if (["azure", "entra", "microsoftazure"].includes(normalized)) {
+        if (provider !== "microsoft") {
+            throw mailboxPlatformConflict(index, provider);
+        }
+        return "microsoft_azure";
     }
     if ([
-        "azure",
-        "entra",
         "m365",
         "microsoft",
         "microsoft365",
@@ -787,25 +1006,50 @@ function normalizeHypertideMailboxProvider(providerRaw, byHeader, index) {
         "office365",
         "outlook",
     ].includes(normalized)) {
-        return "microsoft";
+        if (provider !== "microsoft") {
+            throw mailboxPlatformConflict(index, provider);
+        }
+        return "microsoft_365";
     }
-    const hostEvidence = [
-        byHeader.get("imaphost"),
-        byHeader.get("imapserver"),
-        byHeader.get("smtphost"),
-        byHeader.get("smtpserver"),
-    ]
-        .filter((value) => typeof value === "string")
-        .join(" ")
-        .toLowerCase();
-    if (/(?:gmail|google)/.test(hostEvidence))
-        return "google";
-    if (/(?:microsoft|office365|outlook)/.test(hostEvidence)) {
-        return "microsoft";
-    }
-    if (!providerRaw)
+    throw new OxygenError("invalid_request", `mailboxes[${index}].infrastructure_platform is unsupported; expected Google Workspace, Microsoft 365, Azure, or Entra.`, { exitCode: 1 });
+}
+function mailboxPlatformConflict(index, provider) {
+    return new OxygenError("invalid_request", `mailboxes[${index}].infrastructure_platform conflicts with provider=${provider}.`, { exitCode: 1 });
+}
+function dedupeMailboxImportRows(rows) {
+    const unique = new Map();
+    for (const row of rows) {
+        const address = String(row.email_address).toLowerCase();
+        const existing = unique.get(address);
+        if (!existing) {
+            unique.set(address, row);
+            continue;
+        }
+        if (JSON.stringify(existing) !== JSON.stringify(row)) {
+            throw new OxygenError("invalid_request", `Duplicate mailbox ${address} has conflicting provider, platform, tenant, external id, or credential fields.`, { exitCode: 1 });
+        }
+    }
+    return [...unique.values()];
+}
+function normalizeMailboxImportVendor(raw, from) {
+    if (from === "hypertide") {
+        if (raw && raw.trim().toLowerCase() !== "hypertide") {
+            throw new OxygenError("invalid_request", "--from hypertide is fixed to --vendor hypertide.", { exitCode: 1 });
+        }
+        return null;
+    }
+    if (from === "credentials" && !raw) {
+        throw new OxygenError("invalid_request", "--vendor <source> is required with --from credentials so the imported mailbox keeps its provenance.", { exitCode: 1 });
+    }
+    if (!raw)
         return null;
-    throw new OxygenError("invalid_request", `mailboxes[${index}].provider is unsupported; expected Google/Gmail/Workspace or Microsoft/Outlook/Office 365/Entra.`, { exitCode: 1 });
+    const normalized = raw.trim().toLowerCase();
+    if (normalized.length < 1 ||
+        normalized.length > 64 ||
+        !/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(normalized)) {
+        throw new OxygenError("invalid_request", "--vendor must be 1-64 lowercase letters, digits, dots, underscores, or hyphens.", { exitCode: 1 });
+    }
+    return normalized;
 }
 async function readMailboxImportFile(path) {
     let buffer;
@@ -813,7 +1057,7 @@ async function readMailboxImportFile(path) {
         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. Ordinary JSON accepts [{"email_address":"ada@send.acme.com","provider":"google"}] or {"mailboxes":[...]}; credential exports require --from hypertide. See https://oxygen-agent.com/docs/providers/mailbox-compatibility.`, { exitCode: 1 });
+        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 (or --from hypertide). See https://oxygen-agent.com/docs/providers/mailbox-compatibility.`, { exitCode: 1 });
     }
     if (buffer.byteLength > MAILBOX_IMPORT_FILE_MAX_BYTES) {
         throw new OxygenError("invalid_request", `Mailbox import files must be ${MAILBOX_IMPORT_FILE_MAX_BYTES / 1024 / 1024} MB or smaller.`, { exitCode: 1 });
@@ -821,7 +1065,13 @@ async function readMailboxImportFile(path) {
     const format = inferRowsFileFormat(path);
     let rows;
     if (format === "json") {
-        const parsed = parseJsonValue(buffer.toString("utf8"), "--file");
+        let parsed;
+        try {
+            parsed = JSON.parse(buffer.toString("utf8"));
+        }
+        catch {
+            throw new OxygenError("invalid_json", "--file must contain valid JSON. File contents are omitted from this error because mailbox imports may contain credentials.", { exitCode: 1 });
+        }
         if (Array.isArray(parsed)) {
             rows = parsed;
         }
@@ -836,7 +1086,12 @@ async function readMailboxImportFile(path) {
         }
     }
     else {
-        rows = await parseRowsFileBuffer(buffer, format);
+        try {
+            rows = await parseRowsFileBuffer(buffer, format);
+        }
+        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 });
+        }
     }
     if (rows.length > MAILBOX_IMPORT_ROW_LIMIT) {
         throw new OxygenError("invalid_request", `Mailbox imports are limited to ${MAILBOX_IMPORT_ROW_LIMIT} rows per request.`, { exitCode: 1 });
@@ -1233,7 +1488,10 @@ function readCrmEnrichmentMaxCredits(value) {
     return credits === undefined ? {} : { max_credits: credits };
 }
 function buildCrmSearchBody(query, options) {
-    const objects = readCsvOption(options.objects);
+    // `crm search` is the only command in the family that took the plural, which
+    // cost a failed invocation every time an agent reached for the sibling
+    // spelling. Both are accepted; the plural still wins if somebody passes both.
+    const objects = readCsvOption(options.objects ?? options.object);
     const limit = readPositiveInt(options.limit);
     return {
         query,
@@ -3405,6 +3663,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Search CRM records by identity or record label.")
         .argument("<query>", "Domain, email, LinkedIn URL, or record name to search for.")
         .option("--objects <objects>", "Comma-separated CRM object slugs to search. Defaults to all configured objects.")
+        .option("--object <object>", "Alias for --objects; every sibling crm command spells it singular.")
         .option("--limit <limit>", "Maximum records to return.")
         .option("--json", "Print a JSON envelope.")
         .action(async (query, options) => {
@@ -3545,9 +3804,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("timeline")
-        .description("Show a CRM record's activity timeline, newest first.")
+        .description("Show a CRM record's activity timeline, newest first. Address the record by row id OR by any of the object's identities \u2014 a company domain, a person's email or LinkedIn URL.")
         .argument("<object>", "CRM object slug, such as companies or people.")
-        .argument("<row_id>", "CRM record row id.")
+        .argument("<record>", "CRM record row id, or an identity value such as acme.com or sarah@acme.com.")
         .option("--limit <limit>", "Maximum activities to return.")
         .option("--cursor <cursor>", "Pagination cursor from a previous page.")
         .option("--json", "Print a JSON envelope.")
@@ -5581,13 +5840,13 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("apply")
-        .description("Apply a blueprint to this workspace. Creates tables, columns, prompts, and a disabled workflow.")
+        .description("Apply a blueprint: 0 credits and no provider calls or external writes, but creates workspace tables, columns, prompts, and a disabled workflow. It does not enable or run the workflow.")
         .argument("[slug]", "Blueprint slug (for stored or seed blueprints).")
         .option("--file <path>", "Read a blueprint envelope from a local JSON file.")
         .option("--from-url <url>", "Fetch a shared blueprint envelope from a public Oxygen share URL.")
         .option("--input-json <json>", "Seed blueprint input (parameters) as JSON.")
         .option("--table-ref <ref=id...>", "Reuse an existing table for a blueprint ref (repeatable).", collectMultiple, [])
-        .option("--workflow-id <id>", "Override the resulting workflow id.")
+        .option("--workflow-id <id>", "Set the new workflow's manifest id/slug; this does not update or reuse an existing workflow.")
         .option("--workflow-name <name>", "Override the resulting workflow name.")
         .option("--json", "Print a JSON envelope.")
         .action(async (slug, options) => {
@@ -5723,7 +5982,17 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             const qs = params.toString() ? `?${params.toString()}` : "";
             return requestOxygen(`/api/blueprints/marketplace${qs}`, { requireAuth: false });
         });
-    }));
+    }))
+        .addHelpText("after", [
+        "",
+        "Safety:",
+        "  list, describe, and preflight use 0 credits, make no provider calls, and do not change workspace state.",
+        "  export has the same workspace safety; --out only writes the named local file.",
+        "  apply also uses 0 credits and makes no provider calls or external writes, but it creates workspace",
+        "  tables, prompts, and a disabled workflow. Its response reports future per-run credit ceilings.",
+        "  save, archive, tag, share, publish, and their inverse commands change workspace or publication state.",
+        "",
+    ].join("\n"));
     program
         .command("recipes")
         .description("Business-case GTM playbooks: proven plays with prerequisites, credit posture, and approval gates spelled out.")
@@ -5856,7 +6125,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .command("columns")
         .description("Workspace table column commands.")
         .addCommand(new Command("add")
-        .description("Add a nullable column to a workspace table.")
+        .description("Add a nullable column to a workspace table. Writes the definition only — this never runs the column and never spends credits; use `columns run` for that, with --dry-run first to see the cost.")
         .argument("<table>", "Table id or slug.")
         .option("--label <label>", "Display label for the new column. Required unless --prompt-key supplies a default title.")
         .option("--key <key>", "Optional stable column key. Defaults to a normalized label.")
@@ -6017,7 +6286,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Run an executable AI, tool, formula, enrichment, bind, lookup, or local custom HTTP column for one row or a bounded batch. Paid server-side columns always run durably in the background. Bind create-mode (onNoMatch=create) needs --approved.")
         .argument("<table>", "Table id or slug.")
         .argument("<column>", "Column id or key.")
-        .option("--row-id <row_id>", "Workspace row id to run.")
+        .option("--row-id <row_id>", "Workspace row id to run. Get one from `oxygen tables query <table> --limit 1 --json` — the field is `_row_id`, not `id`.")
         .option("--limit <n>", "Run the next N rows whose target cell is still empty (--force runs the first N regardless). Repeat until rowCount is 0 to page through a table. Defaults to 10; inline deterministic runs have a hard cap of 25.")
         .option("--all", "Run all rows. Requires --background.")
         .option("--filter-json <json>", "Row selector filter object or array for background runs. Do not combine with --all, --limit, or --row-id.")
@@ -7108,7 +7377,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     })));
     program
         .command("billing")
-        .description("Plan and managed credit commands. Spend splits into FLEXIBLE (ad-hoc: enrichment, AI, automation — drawn from your free-to-spend balance) and FIXED recurring per-resource monthly commitments blocked out of it; see `billing commitments`.")
+        .description("Plan and managed credit commands. Spend splits into FLEXIBLE (ad-hoc: enrichment, AI, automation — drawn from your free-to-spend balance) and FIXED recurring per-resource monthly commitments blocked out of it; see `billing commitments`. THREE CLOCKS, deliberately different: the CREDIT CYCLE that `billing allowance` reports against (your plan's monthly grant window); each resource's own COMMITMENT RENEWAL, anchored to the day you connected it, so `billing commitments --json` next_due_at rarely matches the cycle end; and your SUBSCRIPTION PERIOD in `billing balance` (annual plans span many credit cycles). A number from one clock will not reconcile against another.")
         .addCommand(new Command("change")
         .description("Preview an upgrade or downgrade and return a Stripe confirmation link. Nothing changes until confirmed in Stripe.")
         .requiredOption("--to <tier>", "Target plan: starter, pro, or team.")
@@ -7126,13 +7395,13 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("billing balance", options, () => requestOxygen("/api/cli/billing/balance"));
     }))
         .addCommand(new Command("commitments")
-        .description("List the fixed monthly credit commitments blocked at your subscription renewal — per connected sending mailbox, OXYGEN-sold mailbox, warm-up, deliverability, and connected LinkedIn account — with unit price, quantity, and next-due date. Read-only, 0 Oxygen credits.")
+        .description("List the fixed monthly credit commitments blocked at your subscription renewal — per connected sending mailbox, OXYGEN-sold mailbox, warm-up, deliverability, and connected LinkedIn account — with unit price, quantity, and next-due date. This is the FORWARD run-rate: what your currently-connected resources will cost at their next renewal. It is NOT this cycle's charges — compare `billing allowance` fixed_spent_credits for that, and expect the two to differ. Each resource renews on its OWN anchor (the day it was connected), so next_due_at is per-resource and rarely lines up with the credit cycle. Read-only, 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing commitments", options, () => requestOxygen("/api/cli/billing/commitments"));
     }))
         .addCommand(new Command("allowance")
-        .description("Show this billing cycle's credit pool as one breakdown: fixed spend, flexible spend, credits committed to the next renewal, and what is free to spend — the numbers behind the bar on the credit-usage page. The parts always sum to the total. Read-only, 0 Oxygen credits.")
+        .description("Show this billing cycle's credit pool as one breakdown: fixed spend, flexible spend, credits committed to the next renewal, and what is free to spend — the numbers behind the bar on the credit-usage page. The parts always sum to the total. fixed_spent_credits is what has ALREADY been charged this cycle, NOT your monthly run-rate — for the forward figure billed at the next renewal see `billing commitments`, which is normally much larger. reserved_credits is in-flight spend already carved out of free_to_spend_credits, so treat free_to_spend as the ceiling and free_to_spend minus reserved as what is genuinely uncommitted. Every segment carries region=fixed|flexible. Read-only, 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing allowance", options, () => requestOxygen("/api/cli/billing/allowance"));
@@ -7504,6 +7773,19 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     program
         .command("admin")
         .description("Staff-only commands.")
+        .addCommand(new Command("kpis")
+        .description("Show company acquisition, matured seven-day trial conversion, MRR/ARR, and churn. OXYGEN staff only; workspace admin role alone does not grant access.")
+        .addOption(new Option("--range <range>", "Range for acquisition, seven-day trial cohorts, and churn; current MRR/ARR remain point-in-time.")
+        .choices(["7d", "30d", "90d"])
+        .default("30d"))
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin kpis", options, () => {
+            const range = readOption(options.range);
+            const suffix = range && range !== "30d" ? `?range=${encodeURIComponent(range)}` : "";
+            return requestOxygen(`/api/cli/admin/kpis${suffix}`);
+        });
+    }))
         .addCommand(new Command("costs")
         .description("Show provider costs (COGS) per workspace. Staff only.")
         .option("--top <n>", "Limit number of workspace columns. Defaults to all.")
@@ -9377,7 +9659,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("engagement")
-        .description("Harvest a LinkedIn post's engagers (reactors + commenters) into an enrollable workspace table. The harvest runs as a slow, durable background drip under a dedicated conservative read budget — it never bursts and never starves the sequencer's own reads.")
+        .description("Capture LinkedIn intent from one known post (harvest needs its public URL or the composite social_id from `oxygen posts get`) or from your connected account's viewers, followers, and connections. For recurring competitor-profile monitoring that discovers future posts, start with `oxygen recipes list competitor --json`. Harvests run as a slow, durable drip under a conservative read budget.")
         .addCommand(new Command("harvest")
         .description("Start (or re-arm) a harvest of a post's engagers into a workspace table you can enroll into a sequence. Engagers drip into the table over many ticks; poll `engagement status` to watch it fill. No messages are sent. Cookieless harvests spend Oxygen credits per scraper page and require --max-credits.")
         .requiredOption("--post <social_id_or_url>", "Composite post social_id from `oxygen posts get` (NOT the activity URN), or the public LinkedIn post URL for cookieless.")
@@ -9493,6 +9775,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     }))
         .addCommand(new Command("watch")
         .description("Declarative engagement watches (the signals wedge): stand up a watch on a post's engagers, 'who viewed my profile', or the sender's inbound network (new followers / new connections) that harvests people into a table and, under a standing approval, auto-enrolls them into a sequence. The watch materializes the harvest drip and enrolls newly-harvested people each cycle — the sequence still gates its own sends.")
+        .addHelpText("after", "\nScope: this watches one known post or one connected-account signal. For daily discovery across one or more public profiles' recent posts, use `oxygen blueprints describe linkedin-profile-engager-monitor --json`.\n")
         .addCommand(new Command("create")
         .description("Arm an engagement watch. `--kind post` watches a post's reactors + commenters (needs --post social_id; a cookieless post also needs --post-url); `--kind profile_viewers` watches 'who viewed my profile' (source unipile); `--kind followers` / `--kind connections` watch the sender's inbound network — people NEW to the org's orbit stream into the watch table as they follow/connect (source unipile, no credits, reads metered against the account's daily ingest budget). With --auto-enroll it enrolls harvested people into --sequence, capped by --max-enrolls-per-day — the inbound-led-outbound loop. --max-credits-per-cycle is the standing per-cycle spend cap (required for --auto-enroll and cookieless). No messages are sent by the watch itself.")
         .requiredOption("--kind <kind>", "post | profile_viewers | followers | connections.")
@@ -11697,7 +11980,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("mailboxes")
-        .description("Native email sending pool: register/refresh Google/Microsoft mailboxes (including secure local Hypertide transfer), pause/disable inboxes, connect EmailGuard monitoring, and run managed TrulyInbox warmup with explicit plans and credit caps.")
+        .description("Native email sending pool: register/refresh Google/Microsoft mailboxes (including secure local Hypertide transfer), pause/disable inboxes, connect EmailGuard monitoring, and run managed TrulyInbox warmup with explicit plans and credit caps. 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, and a pool overview.")
         .option("--status <status>", "Filter by status: active, paused, or disabled.")
@@ -11726,13 +12009,20 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("mailboxes health", options, () => requestOxygen("/api/cli/mailboxes/health"));
     }))
         .addCommand(new Command("compatibility")
-        .description("Read-only compatibility report for every selected mailbox: origin vendor, real infrastructure tier (including InboxKit Azure), mailbox auth, TrulyInbox warmup path, EmailGuard monitoring path, and the exact next action. JSON data.compatibility contains checked mailbox rows; data.provider_matrix always contains the complete current 13-pair product matrix even when mailboxes are filtered; data.summary rolls up states; data.web_url opens the pool. States distinguish credential_required, consent_required, and vendor_blocked. Never decrypts a credential or calls a downstream provider.")
+        .description("Read-only compatibility report for every selected mailbox: origin vendor, real infrastructure tier (including InboxKit Azure), mailbox auth, TrulyInbox warmup path, EmailGuard monitoring path, and the exact next action. Use --catalog-only for the compact, workspace-independent import contract with no mailbox rows. JSON data.compatibility contains checked mailbox rows; data.provider_matrix always contains the complete current 18-pair product matrix even when mailboxes are filtered; data.import_methods and data.import_fields describe every supported ingestion path; data.non_transferable_auth names credentials that must be reconnected; data.summary rolls up states; data.web_url opens the pool. 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 18-pair 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(","));
             }
@@ -11741,38 +12031,54 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("import")
-        .description("Register (or refresh) sending mailboxes in bulk. This is a 0-credit state mutation with no dry-run; the complete file is validated locally before the first request and the upsert is idempotent by mailbox address. Provide --file for identities, --from hypertide --file for a local secure CSV/JSON/JSONL/XLSX credential transfer, or --from zapmail to pull the connected workspace. A Hypertide app_password is Google-only: Microsoft password fields are discarded locally and Microsoft warmup uses Entra tenant-admin consent later; continuous EmailGuard monitoring remains vendor_blocked for Microsoft. Google passwords are sent only in the request body, encrypted server-side, and never returned.")
+        .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>; --from hypertide remains a shortcut. 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: Microsoft warmup requires Entra tenant-admin consent and EmailGuard remains vendor_blocked for Microsoft. Google app passwords are sent only in the request body, encrypted server-side, and never returned.")
         .addHelpText("after", [
         "",
-        "Ordinary identity file contract:",
-        '  JSON: [{"email_address":"ada@send-acme.com","provider":"google","workspace_external_id":"optional"}] or {"mailboxes":[...]}. Credentials are rejected.',
+        "Ordinary identity file contract (CSV / JSON / JSONL / XLSX):",
+        "  Canonical fields: email_address, provider, workspace_external_id?, infrastructure_platform?, tenant_id?. Common vendor aliases such as Email, From Email, ESP, Mailbox ID, and Entra Tenant ID are mapped locally. Credentials are rejected.",
         "",
-        "Hypertide file contract:",
-        "  Limits: 500 rows / 5 MB.",
+        "All local file imports:",
+        "  Limits: 500 rows / 5 MB for identity, credential, and Hypertide files.",
+        "",
+        "Credential file contract:",
         '  JSON: {"mailboxes":[{"email_address":"ada@send-acme.com","provider":"google","app_password":"<Google mailbox app password>"}]}',
-        "  Validation: any parse, shape, provider, or credential-conflict error rejects the entire file before the first mailbox write and names mailboxes[index]. A later infrastructure failure may interrupt the upsert; re-run the same file because import is idempotent by address.",
+        "  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 without authentication, a network request, or a workspace write. 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/mailbox-compatibility",
         "  Skill: oxygen-email-infra (`oxygen skills install --skill oxygen-email-infra`).",
         "",
     ].join("\n"))
-        .option("--file <path>", "Local JSON file for ordinary identity import. With --from hypertide, accepts the provider's CSV/JSON/JSONL/XLSX export and maps common Email Address, Provider, and App Password headers locally.")
-        .option("--from <source>", "Import source: 'hypertide' with --file for encrypted local credential transfer, or 'zapmail' to pull a connected workspace.")
+        .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, 'hypertide' as its provider shortcut, 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("--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);
-            if (from && from !== "zapmail" && from !== "hypertide") {
-                throw new Error("--from must be hypertide or zapmail.");
+            const validateOnly = options.validateOnly === true;
+            if (from &&
+                from !== "zapmail" &&
+                from !== "hypertide" &&
+                from !== "credentials") {
+                throw new Error("--from must be credentials, hypertide, 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: {
@@ -11784,13 +12090,36 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             }
             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 hypertide --file <path>, or --from zapmail.");
-            const mailboxes = normalizeMailboxImportFile(await readMailboxImportFile(resolve(filePath)), from === "hypertide" ? "hypertide" : "inline");
+                throw new Error("Provide --file <path>, --from credentials --vendor <source> --file <path>, --from hypertide --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,
+                });
+            }
             return requestOxygen("/api/cli/mailboxes", {
                 method: "POST",
                 body: {
-                    ...(from === "hypertide" ? { source: "hypertide" } : {}),
+                    ...(from === "hypertide"
+                        ? { source: "hypertide" }
+                        : from === "credentials"
+                            ? { source: "credential_file" }
+                            : {}),
+                    ...(sourceProvider
+                        ? { source_provider: sourceProvider }
+                        : {}),
                     mailboxes,
                 },
             });
@@ -11913,40 +12242,60 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("connect-oauth")
-        .description("Zapmail-provisioned pools only — not Hypertide imports. Provision Zapmail Custom OAuth for Google/Microsoft mailboxes so native send needs no per-Workspace delegation. BYOK — Zapmail bills your account, 0 Oxygen credits. Pass --status <export_id> to poll.")
+        .description("Zapmail- or InboxKit-provisioned pools — not Hypertide imports. Preview native OAuth provisioning by default; pass --approved after reviewing the mailbox/domain scope to start external vendor writes. A successful preview describes the requested scope and safety envelope; it can still contain zero eligible mailboxes or only already-authorized no-ops. For InboxKit, first confirm mailboxes oauth-health returns remedy connect_oauth_inboxkit, then use mailboxes compatibility --mailboxes <list> to verify origin and auth state. --vendor zapmail (default) hands the pool to Zapmail's Custom OAuth export; --vendor inboxkit requests Workspace-admin consent per mailbox, but only for domains where Oxygen's OAuth client id is already approved — an unapproved domain sends no mailbox consent, and a domain that has never connected a mailbox fires one canary until it lands (--no-canary to fan out immediately). Manual InboxKit live requests are capped at 10 potential mailbox consent writes; use --mailboxes to split wider proven-domain or no-canary scopes. Newly provisioned InboxKit mailboxes are retried by the durable worker. This authorization action uses 0 Oxygen credits; existing vendor or subscription billing is unchanged. Pass --status <id> to poll.")
         .option("--provider <provider>", "Mailbox provider to provision: google or microsoft.")
-        .option("--mailboxes <list>", "Comma-separated mailbox addresses to provision. Omit to provision the whole pool for the provider.")
+        .option("--vendor <vendor>", "Which provisioning path to use: zapmail (default) or inboxkit.")
+        .option("--mailboxes <list>", "Comma-separated mailbox addresses to provision. Omit for the whole pool; manual InboxKit live runs must resolve to at most 10 potential consent writes.")
+        .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 <export_id>", "Poll a previously started Custom OAuth export instead of starting a new one.")
+        .option("--status <id>", "Poll a previously started run (Zapmail export id or InboxKit run id) instead of starting a new one.")
+        .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 live vendor OAuth provisioning after inspecting the dry-run preview.")
         .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 <export_id> to poll a run).");
+                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);
             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 } : {}),
                     ...(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 the delegation-stuck sending mailboxes: Zapmail-linked google inboxes still on auth_mode=delegation with no OAuth grant, each with its Custom OAuth budget (attempts in the last 7 days, remaining re-export posts before Zapmail's 3-per-mailbox-per-7-day cap, last error, and next safe retry time). Read-only — 0 Oxygen credits.")
+        .description("Show the delegation-stuck sending mailboxes across both transports (google and microsoft): every inbox still on auth_mode=delegation with no OAuth grant, each naming the remedy that applies (connect_oauth for Zapmail-linked rows, connect_oauth_inboxkit for InboxKit-provisioned ones, domain_delegation for the rest) and, for Zapmail rows, its Custom OAuth budget (attempts in the last 7 days, remaining re-export posts before Zapmail's 3-per-mailbox-per-7-day cap, last error, and next safe retry time). Read-only — 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes oauth-health", options, () => requestOxygen("/api/cli/mailboxes/oauth-health"));
@@ -12774,7 +13123,7 @@ Run completion:
         .description("Deprecated alias for `oxygen blueprints apply`. Creates a disabled workflow (plus its tables, columns, and prompts) from a blueprint.")
         .argument("<template_id>", "Blueprint slug (formerly workflow template id).")
         .requiredOption("--input-json <json>", "Blueprint input as a JSON object.")
-        .option("--workflow-id <workflow_id>", "Override the resulting workflow id.")
+        .option("--workflow-id <workflow_id>", "Set the new workflow's manifest id/slug; this does not update or reuse an existing workflow.")
         .option("--workflow-name <workflow_name>", "Override the resulting workflow name.")
         .option("--mode <mode>", "Deprecated and ignored: the workflow is created disabled.")
         .option("--max-credits <credits>", "Credit ceiling; folded into inputs.max_credits.")
@@ -13400,7 +13749,7 @@ Run completion:
         await handleAsyncAction("skills doctor", options, () => doctorAgentSkills(options));
     }))
         .addCommand(new Command("install")
-        .description("Install Oxygen agent skills into local agent skill directories.")
+        .description("Install Oxygen agent skills into local agent skill directories only; uses 0 credits and does not change the Oxygen workspace or call a provider.")
         .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
         .option("--agents <agents...>", "Space or comma separated agents. Defaults to codex, claude-code, and cursor.")
         .option("--skill <skill>", "Skill name or '*'. Defaults to '*'.")

package/node_modules/@oxygen/shared/dist/file-import.js

@@ -66,8 +66,9 @@ export function parseRowsText(text, format) {
     if (format === "jsonl") {
         return normalizeRowObjects(text
             .split(/\r?\n/)
-            .filter((line) => line.trim())
-            .map((line) => JSON.parse(line)));
+            .map((line, index) => ({ line, lineNumber: index + 1 }))
+            .filter(({ line }) => line.trim())
+            .map(({ line, lineNumber }) => parseJsonImportLine(line, lineNumber)));
     }
     return parseCsvRows(text);
 }
@@ -162,12 +163,26 @@ function normalizeXlsxImportCell(value) {
     return String(value);
 }
 function parseJsonArray(text) {
-    const parsed = JSON.parse(text);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new OxygenError("invalid_json", "Import file must contain valid JSON. Input contents are omitted from this error.", { exitCode: 1 });
+    }
     if (!Array.isArray(parsed)) {
         throw new OxygenError("invalid_json", "Expected a JSON array.", { exitCode: 1 });
     }
     return parsed;
 }
+function parseJsonImportLine(line, lineNumber) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        throw new OxygenError("invalid_jsonl", `Import file contains invalid JSON on line ${lineNumber}. Input contents are omitted from this error.`, { exitCode: 1 });
+    }
+}
 function normalizeRowObjects(rows) {
     return rows.map((row) => normalizeRowObject(row));
 }
@@ -182,6 +197,7 @@ function parseCsvRows(text) {
     const [header, ...rows] = records;
     if (!header || header.length === 0)
         return [];
+    assertUniqueCsvHeaders(header);
     return rows
         .filter((row) => row.some((cell) => cell.trim()))
         .map((row) => Object.fromEntries(header.map((key, index) => [key, normalizeCsvImportCell(row[index])])));
@@ -209,6 +225,8 @@ function* iterateCsvRowBatches(text, batchSize) {
         if (ready)
             yield ready;
     }
+    if (state.inQuotes)
+        throw unterminatedCsvError();
     if (state.field || state.record.length > 0) {
         const ready = appendCsvRecordToBatch(state, finishCsvRecord(state), batchSize);
         if (ready)
@@ -249,6 +267,8 @@ async function* iterateCsvRowStreamBatches(chunks, batchSize) {
         if (ready.batch)
             yield ready.batch;
     }
+    if (state.inQuotes)
+        throw unterminatedCsvError();
     if (state.field || state.record.length > 0) {
         const ready = appendCsvRecordToBatch(state, finishCsvRecord(state), batchSize);
         if (ready)
@@ -313,8 +333,10 @@ function finishCsvRecord(state) {
 }
 function appendCsvRecordToBatch(state, record, batchSize) {
     const row = csvRecordToRow(record, state.header);
-    if (state.header === null)
+    if (state.header === null) {
+        assertUniqueCsvHeaders(record);
         state.header = record;
+    }
     if (row)
         state.batch.push(row);
     if (state.batch.length < batchSize)
@@ -333,22 +355,27 @@ function csvRecordToRow(record, header) {
 function* iterateJsonlRowBatches(text, batchSize) {
     let batch = [];
     let lineStart = 0;
+    let lineNumber = 1;
     for (let index = 0; index < text.length; index += 1) {
         if (text.charAt(index) !== "\n")
             continue;
         const line = text.slice(lineStart, index).replace(/\r$/, "").trim();
         lineStart = index + 1;
+        if (line) {
+            batch.push(normalizeRowObject(parseJsonImportLine(line, lineNumber)));
+        }
+        lineNumber += 1;
         if (!line)
             continue;
-        batch.push(normalizeRowObject(JSON.parse(line)));
         if (batch.length >= batchSize) {
             yield batch;
             batch = [];
         }
     }
     const trailingLine = text.slice(lineStart).replace(/\r$/, "").trim();
-    if (trailingLine)
-        batch.push(normalizeRowObject(JSON.parse(trailingLine)));
+    if (trailingLine) {
+        batch.push(normalizeRowObject(parseJsonImportLine(trailingLine, lineNumber)));
+    }
     if (batch.length > 0)
         yield batch;
 }
@@ -356,14 +383,17 @@ async function* iterateJsonlRowStreamBatches(chunks, batchSize) {
     const decoder = new TextDecoder();
     let pending = "";
     let batch = [];
+    let lineNumber = 1;
     for await (const chunk of chunks) {
         pending += decoder.decode(toUint8Array(chunk), { stream: true });
         let newline = pending.indexOf("\n");
         while (newline >= 0) {
             const line = pending.slice(0, newline).replace(/\r$/, "").trim();
             pending = pending.slice(newline + 1);
-            if (line)
-                batch.push(normalizeRowObject(JSON.parse(line)));
+            if (line) {
+                batch.push(normalizeRowObject(parseJsonImportLine(line, lineNumber)));
+            }
+            lineNumber += 1;
             if (batch.length >= batchSize) {
                 yield batch;
                 batch = [];
@@ -372,8 +402,9 @@ async function* iterateJsonlRowStreamBatches(chunks, batchSize) {
         }
     }
     const tail = (pending + decoder.decode()).replace(/\r$/, "").trim();
-    if (tail)
-        batch.push(normalizeRowObject(JSON.parse(tail)));
+    if (tail) {
+        batch.push(normalizeRowObject(parseJsonImportLine(tail, lineNumber)));
+    }
     if (batch.length > 0)
         yield batch;
 }
@@ -459,12 +490,28 @@ function parseCsvRecords(text) {
             field += char;
         }
     }
+    if (inQuotes) {
+        throw unterminatedCsvError();
+    }
     if (field || record.length > 0) {
         record.push(field);
         records.push(record);
     }
     return records;
 }
+function unterminatedCsvError() {
+    return new OxygenError("invalid_csv", "CSV contains an unterminated quoted field.", { exitCode: 1 });
+}
+function assertUniqueCsvHeaders(header) {
+    const seen = new Set();
+    for (const value of header) {
+        const normalized = value.normalize("NFKC").trim().toLowerCase();
+        if (!normalized || seen.has(normalized)) {
+            throw new OxygenError("invalid_csv", "CSV headers must be non-empty and unique (case-insensitive).", { exitCode: 1 });
+        }
+        seen.add(normalized);
+    }
+}
 function makeUniqueImportKey(label, taken) {
     return makeUniqueIdentifier(label, taken, {
         exhaustedMessage: "Unable to create a unique column key.",

package/node_modules/@oxygen/shared/dist/version.d.ts

@@ -1,3 +1,3 @@
-export declare const OXYGEN_VERSION = "1.575.19";
+export declare const OXYGEN_VERSION = "1.591.1";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";

package/node_modules/@oxygen/shared/dist/version.js

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.575.19";
+export const OXYGEN_VERSION = "1.591.1";
 // The GLOBAL CLI compatibility floor: the oldest CLI allowed to call any
 // operational route. Raising it hard-rejects every older CLI from the entire
 // product, so it obeys one law, enforced by scripts/ci/cli-min-version-gate.mjs:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.575.19",
+  "version": "1.591.1",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",