@oxygen-agent/cli 1.1014.1600 → 1.1014.1696

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.1014.1600
+Version: 1.1014.1696

package/dist/command-manifest.js

@@ -180,6 +180,8 @@ const MUTATING_COMMANDS = new Set([
 // mode, but a small number of approved operations are explicitly
 // zero-credit. Keep those exceptions exact so discovery never invents spend.
 const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
+    "custom-integrations remove",
+    "integrations disconnect",
     // Native deliverability tests send approved real email without buying provider credits.
     "deliverability workspace-test run",
     "deliverability workspace-test bulk run",
@@ -270,6 +272,7 @@ const READ_ONLY_COMMANDS = new Set([
 // invocation still previews, so machine-readable discovery must not imply that
 // calling the command without its confirmation flag writes anything.
 const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
+    "custom-integrations remove",
     // A bare call validates and names what would be sent; --approved submits.
     "voice verification submit",
     "domains dns apply",
@@ -491,7 +494,7 @@ function toManifestEntry(command, path) {
             && (MUTATING_COMMANDS.has(commandName)
                 || MUTATING_VERBS.has(leafVerb)
                 || MUTATING_VERBS.has(verbPrefix))),
-        destructive: operations.some((spec) => spec.mcp.annotations?.destructiveHint === true),
+        destructive: commandName === "custom-integrations remove" || commandName === "integrations disconnect" || operations.some((spec) => spec.mcp.annotations?.destructiveHint === true),
         preview_by_default: flagStrings.some((flags) => flags.includes("--live")) ||
             PREVIEW_BY_DEFAULT_COMMANDS.has(commandName),
         json_supported: flagStrings.some((flags) => flags.includes("--json")),

package/dist/commands/custom-integrations.js

@@ -123,6 +123,19 @@ export function registerCustomIntegrationsFamily(program, handleAsyncAction) {
                 body: { slug, api_key: apiKey },
             });
         });
+    }))
+        .addCommand(new Command("remove")
+        .description("Preview removal of a custom HTTP integration and its tools. Confirm with --approved --plan <plan_hash>; saved columns, workflows and run history remain.")
+        .argument("[slug]", "Custom HTTP integration slug.")
+        .option("--connection-id <id>", "Select an exact connection, including when a slug is ambiguous.")
+        .option("--approved", "Approve the exact removal preview.")
+        .option("--plan <plan_hash>", "Hash returned by the removal preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("custom-integrations remove", options, () => requestOxygen("/api/cli/custom-integrations/remove", {
+            method: "POST",
+            body: { slug, connection_id: readOption(options.connectionId), approved: options.approved ?? false, plan_hash: readOption(options.plan) },
+        }));
     }))
         .addCommand(new Command("list")
         .description("List custom HTTP integrations for the active organization.")

package/dist/commands/inbox.js

@@ -336,7 +336,7 @@ export function registerInboxFamily(program, handleAsyncAction) {
         });
     }))
         .addCommand(new Command("analyze")
-        .description("Run analysis on a conversation now: status + a drafted reply (Oxygen's default model). The worker also does this automatically on inbound conversations.")
+        .description("Run analysis on a conversation now: status + a drafted reply (Oxygen's default model). The worker also does this automatically on inbound conversations inside each mailbox's classification scope (`mailboxes update --classify`).")
         .argument("<conversation>", "Conversation id, Unipile chat id, or (email) Zapbox thread id.")
         .option("--channel <channel>", "Inbox channel: email (default), linkedin, or whatsapp.")
         .option("--force", "Re-analyze even if the conversation was already classified (an explicit paid re-classification; spends one managed credit). Without it, an already-analyzed email is a free no-op. DMs always re-analyze.")

package/dist/commands/integrations.js

@@ -206,9 +206,11 @@ export function registerIntegrationsFamily(program, handleAsyncAction) {
         }));
     }))
         .addCommand(new Command("disconnect")
-        .description("Disconnect an integration. LinkedIn and WhatsApp remove the connected account; pass --connection-id when more than one is connected.")
+        .description("Disconnect an integration. Custom HTTP previews removal first; confirm with --approved --plan <plan_hash>. LinkedIn and WhatsApp remove the connected account.")
         .argument("<integration_id>", "Integration id, such as 'slack'.")
         .option("--connection-id <id>", "Disconnect a specific connected account when multiple exist.")
+        .option("--approved", "Approve the custom HTTP removal preview.")
+        .option("--plan <plan_hash>", "Custom HTTP removal preview hash.")
         .option("--json", "Print a JSON envelope.")
         .action(async (integrationId, options) => {
         const connectionId = readOption(options.connectionId)?.trim();
@@ -217,6 +219,8 @@ export function registerIntegrationsFamily(program, handleAsyncAction) {
             body: {
                 integration_id: integrationId,
                 ...(connectionId ? { connection_id: connectionId } : {}),
+                ...(options.approved !== undefined ? { approved: options.approved } : {}),
+                ...(readOption(options.plan) ? { plan_hash: readOption(options.plan) } : {}),
             },
         }));
     }))

package/dist/commands/mailboxes.js

@@ -553,15 +553,23 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
     }))
         .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 Google receiving-server policy rejection 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). Per-mailbox warmup.state and fleet warmup.byState are stored rail telemetry; use `oxygen mailboxes list --json` warmupTruth for enrollment state and next actions. The rolling window is signals.window (7d). Delivery notifications include all send sources, including warm-up and manual mail; signals.sendSource=sequence restricts only coldSends7d. Identified warm-up rejections are reported separately, and other notifications have no verified send-source attribution. Rejections alone do not establish that prospect mail was rejected or that a whole domain is blocked. A zero means no such evidence was recorded in the stated window, not that the fleet is un-blocklisted everywhere. Pure read — 0 credits; never pauses a mailbox or changes a cap.")
-        .addOption(new Option("--view <view>", "Summary: complete compact roster (default); fleet: domain, DSN and warm-up totals without rows; full: all inbox evidence.").choices(["summary", "fleet", "full"]))
+        .addOption(new Option("--view <view>", "Start with --view fleet for totals; summary: complete compact roster (default); full: per-inbox evidence.").choices(["summary", "fleet", "full"]))
+        .option("--mailboxes <list>", "Inspect 1–100 mailbox ids or addresses, comma-separated (defaults to full evidence). Fleet totals remain unfiltered.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleReadActionWithLens("mailboxes health", options, () => requestOxygen(`/api/cli/mailboxes/health?view=${encodeURIComponent(options.view ?? "summary")}`), formatMailboxFleetHealth);
+        const query = new URLSearchParams({ view: options.view ?? (options.mailboxes !== undefined ? "full" : "summary") });
+        if (options.mailboxes !== undefined)
+            query.set("mailboxes", options.mailboxes);
+        await handleReadActionWithLens("mailboxes health", options, () => requestOxygen(`/api/cli/mailboxes/health?${query}`), formatMailboxFleetHealth);
     }))
         .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, OXYGEN deliverability 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.")
+        .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, OXYGEN deliverability 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 credentials or writes provider state. The full report may read InboxKit source-warmup status; --remedy oauth uses stored authorization only with no provider calls and leaves warm-up and deliverability unchecked.")
         .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("--vendor <origin>", "Filter the canonical mailbox origin, for example inboxkit, zapmail or native.")
+        .option("--provider <provider>", "Filter google or microsoft.")
+        .option("--remedy <remedy>", "Filter a native-send remedy code; oauth reports stored authorization only without provider calls.")
+        .option("--summary-only", "Return counts without individual mailbox rows.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes compatibility", options, () => {
@@ -576,6 +584,13 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
             if (mailboxes.length > 0) {
                 params.set("mailboxes", mailboxes.join(","));
             }
+            for (const key of ["vendor", "provider", "remedy"]) {
+                const value = readOption(options[key]);
+                if (value)
+                    params.set(key, value);
+            }
+            if (options.summaryOnly)
+                params.set("summary_only", "true");
             const suffix = params.toString();
             return requestOxygen(`/api/cli/mailboxes/compatibility${suffix ? `?${suffix}` : ""}`);
         });
@@ -781,12 +796,13 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
         });
     })))
         .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.")
+        .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. Also sets its bounce protection and which inbound mail AI reply classification triages (--classify). 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("--classify <scope>", "Which inbound conversations AI reply classification triages (each one uses credits): replies (Sequence threads and threads you wrote in; other mail, such as newsletters and notifications, stays in Unibox unclassified at no cost) or all (every inbound conversation). Default: replies for a Google mailbox you added yourself, all for every other mailbox. Applies to new mail; `mailboxes get` shows the current scope.")
         .option("--json", "Print a JSON envelope.")
         .action(async (mailbox, options) => {
         await handleAsyncAction("mailboxes update", options, () => {
@@ -795,6 +811,8 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
             const patch = {};
             if (options.bounceProtection !== undefined)
                 patch.bounce_protection = JSON.parse(options.bounceProtection);
+            if (options.classify !== undefined)
+                patch.classification_scope = options.classify;
             if (options.displayName !== undefined)
                 patch.display_name = options.displayName;
             if (options.signatureHtml !== undefined) {
@@ -804,7 +822,7 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
                 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).");
+                throw new Error("Provide --display-name, --signature-html (or --signature-file), --bounce-protection or --classify.");
             }
             return requestOxygen(`/api/cli/mailboxes/${encodeURIComponent(mailbox)}`, {
                 method: "PATCH",
@@ -836,8 +854,9 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
         .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("--dry-run", "Preview the requested mailbox/domain scope and external writes without changing vendor or ledger state. InboxKit enumerates consent candidates, skipped reasons, domain approvals and exact external writes; approve its fresh plan hash. This is the default for starts.")
         .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("--plan-hash <hash>", "InboxKit: exact fresh eligibility/approval preview hash; required with --approved.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes connect-oauth", options, () => {
@@ -867,6 +886,7 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
                 method: "POST",
                 body: {
                     provider,
+                    ...(readOption(options.planHash) ? { plan_hash: readOption(options.planHash) } : {}),
                     ...(options.googleSmtp === true ? { google_smtp: true } : {}),
                     // Every key stays absent unless it was asked for, so a run
                     // without the new flags is the request this command has always

package/dist/commands/managed-inboxes.js

@@ -126,8 +126,8 @@ export function registerManagedInboxesFamily(program, handleAsyncAction) {
         .addOption(new Option("--preview", "Explicit read-only quote: connects nothing, buys nothing and charges nothing. Cannot be combined with purchase or DNS cleanup approval.").conflicts(["approved", "dnsCleanupApproved"]))
         .option("--existing-domain", "Use an existing Cloudflare domain from oxygen domains list; never register or transfer it.")
         .option("--max-per-domain <n>", "Save a stricter mailbox limit with the approved order, including existing addresses (e.g. 2). Preview does not save it.")
-        .option("--dns-cleanup-records <ids>", "Preview deletion of these comma-separated exact email DNS record IDs on an existing domain; connects and buys nothing.")
-        .addOption(new Option("--dns-cleanup-approved", "Delete only the reviewed email records; requires --dns-cleanup-records and --dns-cleanup-hash. Request a fresh purchase quote afterward.").conflicts("approved"))
+        .option("--dns-cleanup-records <ids>", "Optional standalone cleanup: preview deletion of these comma-separated email DNS record IDs; buys nothing. An approved existing-domain order already removes the records its preview lists.")
+        .addOption(new Option("--dns-cleanup-approved", "Delete only the reviewed email records without buying; requires --dns-cleanup-records and --dns-cleanup-hash. Request a fresh purchase quote afterward.").conflicts("approved"))
         .option("--dns-cleanup-hash <hash>", "The plan_hash from the exact DNS cleanup preview, required to delete records.")
         .option("--years <n>", "Years to register a new domain for (1-10). Omit for existing domains.")
         .option("--redirect-url <url>", "Where the domain's web root redirects. Defaults to your workspace's company website; editable later with `oxygen domains forwarding set`.")

package/dist/commands/senders.js

@@ -203,15 +203,15 @@ export function registerSendersFamily(program, handleAsyncAction) {
         .description("Show current limits, overrides, working hours (timezone, days, start, end), defaults, hard maximums, and the caution levels above which LinkedIn restriction risk rises, for an account. <id> accepts a sender account id, connection id, or Unipile account id.")
         .argument("<id>", "Sender account id, connection id, or Unipile account id.")
         .option("--json", "Print a JSON envelope.")
-        .action(async (id, options) => {
-        await handleAsyncAction("senders limits get", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/limits`));
+        .action(async (id, options, command) => {
+        await handleAsyncAction("senders limits get", { ...options, json: command.optsWithGlobals().json === true }, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/limits`));
     }))
         .addCommand(addContractFlags(new Command(SENDER_LIMITS_SET_OPERATION.cli.path.at(-1) ?? "set")
         .description(SENDER_LIMITS_SET_OPERATION.cli.summary)
         .argument("<id>", SENDER_LIMITS_SET_OPERATION.cli.argument?.description), SENDER_LIMITS_SET_OPERATION.contract, SENDER_LIMITS_FLAG_OVERLAY)
         .option("--json", "Print a JSON envelope.")
-        .action(async (id, options) => {
-        await handleAsyncAction("senders limits set", options, () => {
+        .action(async (id, options, command) => {
+        await handleAsyncAction("senders limits set", { ...options, json: command.optsWithGlobals().json === true }, () => {
             const body = buildSenderLimitsBody(options);
             return requestOxygen(operationPath(SENDER_LIMITS_SET_OPERATION, { id }), {
                 method: SENDER_LIMITS_SET_OPERATION.method,

package/dist/credential-storage/store.d.ts

@@ -0,0 +1,10 @@
+/** The CLI's per-user config directory; `OXYGEN_CONFIG_DIR` overrides it. */
+export declare function resolveConfigDir(env?: NodeJS.ProcessEnv): string;
+/** Own raw credential IO. The same live environment is read at every original
+ * operation boundary; the application still owns documents and profiles.
+ * Construct once at the application's original promisify initialization point. */
+export declare function createCredentialStorage(): {
+    readSystemCredentialPayload: (env: NodeJS.ProcessEnv) => Promise<string | null>;
+    writeSystemCredentialPayload: (payload: string, env: NodeJS.ProcessEnv) => Promise<void>;
+    deleteSystemCredentialPayload: (env: NodeJS.ProcessEnv) => Promise<void>;
+};

package/dist/credential-storage/store.js

@@ -0,0 +1,282 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { OxygenError } from "@oxygen/shared/cli-result";
+const SERVICE_NAME = "oxygen-cli";
+const ACCOUNT_NAME = "default";
+const WINDOWS_CREDENTIAL_PAYLOAD_ENV = "OXYGEN_CLI_WINDOWS_CREDENTIAL_PAYLOAD";
+/** The CLI's per-user config directory; `OXYGEN_CONFIG_DIR` overrides it. */
+export function resolveConfigDir(env = process.env) {
+    return env.OXYGEN_CONFIG_DIR?.trim()
+        || (process.platform === "win32"
+            ? join(env.APPDATA || join(homedir(), "AppData", "Roaming"), "oxygen")
+            : join(homedir(), ".config", "oxygen"));
+}
+/** Own raw credential IO. The same live environment is read at every original
+ * operation boundary; the application still owns documents and profiles.
+ * Construct once at the application's original promisify initialization point. */
+export function createCredentialStorage() {
+    const execFileAsync = promisify(execFile);
+    async function readSystemCredentialPayload(env) {
+        const store = credentialStore(env);
+        if (store === "keychain")
+            return readMacOSKeychainPayload(env);
+        if (store === "credential-manager")
+            return readWindowsCredentialManagerPayload(env);
+        return readFileCredentialPayload(env);
+    }
+    async function writeSystemCredentialPayload(payload, env) {
+        const store = credentialStore(env);
+        if (store === "keychain") {
+            await writeMacOSKeychainPayload(payload, env);
+            return;
+        }
+        if (store === "credential-manager") {
+            await writeWindowsCredentialManagerPayload(payload, env);
+            return;
+        }
+        writeFileCredentialPayload(payload, env);
+    }
+    async function deleteSystemCredentialPayload(env) {
+        const store = credentialStore(env);
+        if (store === "keychain") {
+            await deleteMacOSKeychain(env);
+            return;
+        }
+        if (store === "credential-manager") {
+            await deleteWindowsCredentialManager(env);
+            return;
+        }
+        deleteFileCredentials(env);
+    }
+    function credentialStore(env) {
+        const forced = env.OXYGEN_CREDENTIAL_STORE?.trim().toLowerCase();
+        if (forced === "file")
+            return "file";
+        if (forced === "keychain")
+            return "keychain";
+        if (forced === "credential-manager")
+            return "credential-manager";
+        if (process.platform === "darwin")
+            return "keychain";
+        if (process.platform === "win32")
+            return "credential-manager";
+        return "file";
+    }
+    function credentialsPath(env) {
+        return join(resolveConfigDir(env), "credentials.json");
+    }
+    function readFileCredentialPayload(env) {
+        const path = credentialsPath(env);
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, "utf8");
+    }
+    function writeFileCredentialPayload(payload, env) {
+        const path = credentialsPath(env);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const tempPath = `${path}.${process.pid}.tmp`;
+        writeFileSync(tempPath, payload, { mode: 0o600 });
+        chmodSync(tempPath, 0o600);
+        renameSync(tempPath, path);
+        chmodSync(path, 0o600);
+    }
+    function deleteFileCredentials(env) {
+        const path = credentialsPath(env);
+        rmSync(path, { force: true });
+    }
+    async function readMacOSKeychainPayload(env) {
+        try {
+            const { stdout } = await execFileAsync(macOSSecurityCommand(env), [
+                "find-generic-password",
+                "-a",
+                ACCOUNT_NAME,
+                "-s",
+                SERVICE_NAME,
+                "-w",
+            ], { env });
+            return stdout;
+        }
+        catch {
+            return null;
+        }
+    }
+    // `security -i` reads commands with a line buffer that traditionally caps at
+    // 4096 bytes. Beyond that, the input is silently truncated, which would
+    // corrupt the stored credential and break re-auth. Reject early with a clear
+    // error so a user with too many profiles gets actionable feedback instead of
+    // a partial-write that only surfaces on the next CLI invocation.
+    const MACOS_SECURITY_LINE_LIMIT_BYTES = 4096;
+    async function writeMacOSKeychainPayload(payload, env) {
+        // `security add-generic-password -w PAYLOAD` would put the token in argv
+        // (visible to any same-UID `ps`). Use `security -i` instead: the subcommand
+        // is written on stdin, so the only argv `ps` ever sees is `security -i`.
+        const command = macOSSecurityCommand(env);
+        const escaped = payload.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+        const line = `add-generic-password -a "${ACCOUNT_NAME}" -s "${SERVICE_NAME}" -w "${escaped}" -U\n`;
+        const lineBytes = Buffer.byteLength(line, "utf8");
+        if (lineBytes >= MACOS_SECURITY_LINE_LIMIT_BYTES) {
+            throw credentialStoreError("write", "macOS Keychain", {
+                code: "payload_too_large",
+                stderr: `Credential document is ${lineBytes} bytes; \`security -i\` truncates lines at ${MACOS_SECURITY_LINE_LIMIT_BYTES} bytes. Reduce stored profiles (oxygen logout <profile>) and retry.`,
+            });
+        }
+        await new Promise((resolve, reject) => {
+            const child = spawn(command, ["-i"], { env, stdio: ["pipe", "pipe", "pipe"] });
+            let stderr = "";
+            child.stderr.on("data", (chunk) => {
+                stderr += chunk.toString("utf8");
+            });
+            child.once("error", (error) => {
+                reject(credentialStoreError("write", "macOS Keychain", error));
+            });
+            child.once("close", (code, signal) => {
+                const trimmedStderr = stderr.trim();
+                if (code === 0 && !trimmedStderr) {
+                    resolve();
+                    return;
+                }
+                reject(credentialStoreError("write", "macOS Keychain", { code, signal, stderr: trimmedStderr }));
+            });
+            child.stdin.end(line);
+        });
+    }
+    async function deleteMacOSKeychain(env) {
+        await execFileAsync(macOSSecurityCommand(env), [
+            "delete-generic-password",
+            "-a",
+            ACCOUNT_NAME,
+            "-s",
+            SERVICE_NAME,
+        ], { env }).catch(() => undefined);
+    }
+    async function readWindowsCredentialManagerPayload(env) {
+        try {
+            const { stdout } = await runPowerShell(`${windowsCredentialManagerScript()}
+$ptr = [IntPtr]::Zero
+try {
+  if (-not [OxygenCredMan]::CredRead("${SERVICE_NAME}", 1, 0, [ref]$ptr)) { exit 2 }
+  $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][OxygenCredMan+CREDENTIAL])
+  $secret = [Runtime.InteropServices.Marshal]::PtrToStringUni($cred.CredentialBlob, [int]($cred.CredentialBlobSize / 2))
+  [Console]::Out.Write($secret)
+} finally {
+  if ($ptr -ne [IntPtr]::Zero) { [OxygenCredMan]::CredFree($ptr) }
+}
+`, env);
+            return stdout;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function writeWindowsCredentialManagerPayload(value, env) {
+        const payload = Buffer.from(value, "utf16le").toString("base64");
+        try {
+            await runPowerShell(`${windowsCredentialManagerScript()}
+$payload = $env:${WINDOWS_CREDENTIAL_PAYLOAD_ENV}
+if ([string]::IsNullOrWhiteSpace($payload)) { exit 1 }
+$secret = [Text.Encoding]::Unicode.GetString([Convert]::FromBase64String($payload))
+$bytes = [Text.Encoding]::Unicode.GetBytes($secret)
+$blob = [Runtime.InteropServices.Marshal]::StringToCoTaskMemUni($secret)
+try {
+  $cred = New-Object OxygenCredMan+CREDENTIAL
+  $cred.Type = 1
+  $cred.TargetName = "${SERVICE_NAME}"
+  $cred.UserName = "${ACCOUNT_NAME}"
+  $cred.CredentialBlob = $blob
+  $cred.CredentialBlobSize = $bytes.Length
+  $cred.Persist = 2
+  if (-not [OxygenCredMan]::CredWrite([ref]$cred, 0)) { exit 1 }
+} finally {
+  [Runtime.InteropServices.Marshal]::FreeCoTaskMem($blob)
+}
+`, {
+                ...env,
+                [WINDOWS_CREDENTIAL_PAYLOAD_ENV]: payload,
+            });
+        }
+        catch (error) {
+            throw credentialStoreError("write", "Windows Credential Manager", error);
+        }
+    }
+    async function deleteWindowsCredentialManager(env) {
+        await runPowerShell(`${windowsCredentialManagerScript()}
+[void][OxygenCredMan]::CredDelete("${SERVICE_NAME}", 1, 0)
+`, env).catch(() => undefined);
+    }
+    function runPowerShell(script, env) {
+        const encodedCommand = Buffer.from(script, "utf16le").toString("base64");
+        return execFileAsync(windowsPowerShellCommand(env), [
+            "-NoProfile",
+            "-NonInteractive",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-EncodedCommand",
+            encodedCommand,
+        ], { env });
+    }
+    function credentialStoreError(operation, store, error) {
+        const child = error;
+        const details = {
+            operation,
+            store,
+        };
+        if (typeof child.code === "number") {
+            details.exit_code = child.code;
+        }
+        else if (typeof child.code === "string") {
+            details.reason = child.code;
+        }
+        if (typeof child.signal === "string")
+            details.signal = child.signal;
+        if (typeof child.stderr === "string" && child.stderr.trim()) {
+            details.stderr = sanitizeCredentialErrorText(child.stderr.trim()).slice(0, 4000);
+        }
+        return new OxygenError("credential_store_failed", `Unable to ${operation} Oxygen CLI credentials in ${store}.`, { details, exitCode: 1 });
+    }
+    function sanitizeCredentialErrorText(value) {
+        return value.replace(/\boxy_(?:live|user)_[A-Za-z0-9_-]+\b/g, "[redacted_token]");
+    }
+    function macOSSecurityCommand(env) {
+        return env.OXYGEN_SECURITY_COMMAND?.trim() || "security";
+    }
+    function windowsPowerShellCommand(env) {
+        return env.OXYGEN_POWERSHELL_COMMAND?.trim() || "powershell.exe";
+    }
+    function windowsCredentialManagerScript() {
+        return `
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public static class OxygenCredMan {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  public struct CREDENTIAL {
+    public UInt32 Flags;
+    public UInt32 Type;
+    public string TargetName;
+    public string Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public UInt32 CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public UInt32 Persist;
+    public UInt32 AttributeCount;
+    public IntPtr Attributes;
+    public string TargetAlias;
+    public string UserName;
+  }
+  [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern bool CredWrite([In] ref CREDENTIAL userCredential, UInt32 flags);
+  [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern bool CredRead(string target, UInt32 type, UInt32 reservedFlag, out IntPtr credentialPtr);
+  [DllImport("advapi32.dll", SetLastError = true)]
+  public static extern bool CredDelete(string target, UInt32 type, UInt32 flags);
+  [DllImport("advapi32.dll", SetLastError = true)]
+  public static extern void CredFree([In] IntPtr cred);
+}
+"@
+`;
+    }
+    return { readSystemCredentialPayload, writeSystemCredentialPayload, deleteSystemCredentialPayload };
+}

package/dist/credentials.d.ts

@@ -1,3 +1,4 @@
+export { resolveConfigDir } from "./credential-storage/store.js";
 export type StoredProfileIdentity = {
     organization: StoredOrganization | null;
     user: {
@@ -77,7 +78,4 @@ export declare function pickProfileNameForUserSession(userId: string, candidateS
 export declare function switchCredentialProfile(profile: string, env?: NodeJS.ProcessEnv): Promise<CredentialProfile>;
 export declare function updateActiveOrganizationForProfile(profile: string, organization: StoredOrganization, env?: NodeJS.ProcessEnv): Promise<CredentialProfile>;
 export declare function normalizeApiUrl(value: string): string;
-/** The CLI's per-user config directory; `OXYGEN_CONFIG_DIR` overrides it. */
-export declare function resolveConfigDir(env?: NodeJS.ProcessEnv): string;
 export declare function readEnvToken(env?: NodeJS.ProcessEnv): string | null;
-export {};