@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/sequences.js

@@ -0,0 +1,2322 @@
+import { asPayloadRecord, emitCliFailure, emitSuccess, writeBillingNotices, writeCreditsReceipt, writeJson } from "../cli-output.js";
+import { parseJsonObject, readNonNegativeInt, readPositiveInt } from "../cli-values.js";
+import { ansi, collectRepeatable, handleReadActionWithLens, parseJsonValue, readCreditCeilingOrZero, readCsvOption, readJsonFileValue, readPositiveNumber, readPublishingPostText, renderTextTable, splitCommaList } from "../command-support.js";
+import { addContractFlags, readContractFlags } from "../contract-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { parseWorkingDaysOption } from "../sender-limits-flags.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError, success } from "@oxygen/shared/cli-result";
+import { COMPANY_REPLY_PAUSE_DEFAULT_STATUSES, COMPANY_REPLY_PAUSE_LEGACY_STATUSES, COMPANY_REPLY_PAUSE_STATUS_KEY_PATTERN } from "@oxygen/shared/company-reply-pause";
+import { SEQUENCE_ANALYTICS_READ_CONTRACT } from "@oxygen/shared/contracts/sequence-analytics-read";
+import { SEQUENCE_LIST_PROJECTION_CONTRACT } from "@oxygen/shared/contracts/sequence-list";
+import { SEQUENCE_LIFECYCLES, sequenceDisplayStatus } from "@oxygen/shared/sequence-lifecycle";
+import { Command, Option } from "commander";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { stdout as output } from "node:process";
+// `--suppress-list <comma ids or @file>`: a comma-separated list of lead provider
+// ids, or `@<path>` to a file of ids (comma/newline/whitespace separated). Returns
+// the trimmed, de-duplicated, blank-free ids; an absent value yields an empty list.
+function parseSuppressListOption(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return [];
+    const text = raw.startsWith("@") ? readFileSync(resolve(raw.slice(1)), "utf8") : raw;
+    return [
+        ...new Set(text
+            .split(/[\s,]+/)
+            .map((id) => id.trim())
+            .filter((id) => id.length > 0)),
+    ];
+}
+function buildSequenceDraftBody(options) {
+    const goal = readOption(options.goal);
+    if (!goal)
+        throw new Error("--goal is required.");
+    const name = readOption(options.name);
+    const slug = readOption(options.slug);
+    if (options.create && (!name || !slug)) {
+        throw new Error("--create requires --name and --slug.");
+    }
+    const audience = readOption(options.audience);
+    const table = readOption(options.table);
+    const steps = readPositiveInt(options.steps);
+    const variants = readPositiveInt(options.variants);
+    return {
+        goal,
+        max_credits: readPositiveNumber(options.maxCredits),
+        ...(audience ? { audience } : {}),
+        ...(table ? { source_table: table } : {}),
+        ...(steps !== undefined ? { steps } : {}),
+        ...(variants !== undefined ? { variants } : {}),
+        ...(options.create ? { create: true } : {}),
+        ...(name ? { name } : {}),
+        ...(slug ? { slug } : {}),
+    };
+}
+// Human-legible preview for `sequences draft` (stdout stays the machine JSON, like
+// every other command): the drafted emails with their subjects + wait gaps, the
+// Knowledge Graph pages that grounded the copy, and the next step. Written to
+// stderr (the same lane as the credits receipt) so scripts still parse stdout.
+function writeSequenceDraftPreview(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const record = data;
+    const definition = record.definition;
+    const steps = Array.isArray(record.steps)
+        ? record.steps
+        : Array.isArray(definition?.steps)
+            ? definition.steps
+            : [];
+    const sequence = record.sequence;
+    const lines = [];
+    if (record.created && sequence) {
+        lines.push(`Saved draft sequence "${String(sequence.name ?? "")}" (${String(sequence.slug ?? "")}).`);
+    }
+    else {
+        lines.push("Drafted email sequence (preview — not saved):");
+    }
+    let emailNumber = 0;
+    // The subject the next threaded email continues under. A drafted follow-up
+    // deliberately has no subject of its own — that is what keeps it in the first
+    // email's thread — so show what it actually goes out under rather than the
+    // "(no subject)" that reads like a drafting failure.
+    let threadSubject = null;
+    for (const step of steps) {
+        if (!step || typeof step !== "object" || Array.isArray(step))
+            continue;
+        const entry = step;
+        if (entry.kind === "email_send") {
+            emailNumber += 1;
+            const own = typeof entry.subject_template === "string" && entry.subject_template.trim()
+                ? entry.subject_template.trim()
+                : null;
+            if (own)
+                threadSubject = own;
+            const subject = own ?? (threadSubject ? `Re: ${threadSubject} (same thread)` : "(no subject)");
+            const variantCount = Array.isArray(entry.variants) ? entry.variants.length : 0;
+            lines.push(`  Email ${emailNumber}: ${subject}${variantCount > 0 ? ` (+${variantCount} A/B variant${variantCount === 1 ? "" : "s"})` : ""}`);
+        }
+        else if (entry.kind === "wait") {
+            const days = typeof entry.days === "number" ? entry.days : 0;
+            lines.push(`  wait ${days} day${days === 1 ? "" : "s"}`);
+        }
+    }
+    const provenance = record.provenance;
+    const pages = Array.isArray(provenance?.pages) ? provenance.pages : [];
+    if (pages.length > 0) {
+        const names = pages
+            .map((page) => (typeof page.title === "string" && page.title.trim() ? page.title.trim() : typeof page.slug === "string" ? page.slug : ""))
+            .filter((name) => name.length > 0)
+            .slice(0, 5);
+        lines.push(`  Grounded on ${pages.length} Knowledge Graph page${pages.length === 1 ? "" : "s"}${names.length > 0 ? `: ${names.join(", ")}` : ""}.`);
+    }
+    else {
+        lines.push("  Grounded on the workspace voice (no Knowledge Graph pages retrieved).");
+    }
+    if (!record.created) {
+        lines.push("  Re-run with --create --name <name> --slug <slug> to save it as a draft sequence.");
+    }
+    process.stderr.write(`${lines.join("\n")}\n`);
+}
+// `sequences duplicate` is deliberately CLIENT-SIDE composition (get + create):
+// it adds a real workflow convenience (Instantly/Lemlist/HeyReach all have
+// campaign duplication) without growing the API/MCP surface — an MCP agent
+// composes the same two calls, and the tools/list payload is at its size
+// budget. The Instantly email BINDING is never copied: two campaigns must not
+// share one provider campaign id; the create-side validation tells the user
+// exactly that if the copied steps require a binding.
+async function handleSequenceDuplicateAction(sequence, options) {
+    try {
+        const name = readOption(options.name);
+        const slug = readOption(options.slug);
+        const created = await requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/duplicate`, {
+            method: "POST",
+            body: {
+                ...(name ? { name } : {}),
+                ...(slug ? { slug } : {}),
+                ...(options.senders === false ? { include_senders: false } : {}),
+            },
+        });
+        if (options.json) {
+            writeJson(success("sequences duplicate", created));
+            return;
+        }
+        const link = created.deepLink ?? created.web_url;
+        const notCopied = created.not_copied?.length ? ` Not copied: ${created.not_copied.join("; ")}.` : "";
+        process.stdout.write(`Duplicated '${sequence}' as draft '${created.sequence?.slug ?? slug ?? "copy"}'.${notCopied}${link ? ` ${link}` : ""}\n`);
+    }
+    catch (error) {
+        emitCliFailure("sequences duplicate", error);
+    }
+}
+async function handleSequenceRenderAction(sequence, options) {
+    try {
+        const params = new URLSearchParams();
+        const step = readOption(options.step);
+        if (step)
+            params.set("step", step);
+        const variant = readOption(options.variant);
+        if (variant)
+            params.set("variant", variant);
+        const rows = readCsvOption(options.row);
+        if (rows.length > 0)
+            params.set("row", rows.join(","));
+        const sender = readOption(options.sender);
+        if (sender)
+            params.set("sender", sender);
+        const limit = readPositiveInt(options.limit);
+        if (limit !== undefined)
+            params.set("limit", String(limit));
+        const query = params.toString();
+        const data = await requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/render${query ? `?${query}` : ""}`);
+        if (options.json) {
+            writeJson(success("sequences render", data));
+            return;
+        }
+        process.stdout.write(formatSequenceRender(data));
+    }
+    catch (error) {
+        emitCliFailure("sequences render", error);
+    }
+}
+function formatSequenceRender(data) {
+    const lines = [];
+    for (const step of data.steps ?? []) {
+        const signer = step.sender ? ` · from ${step.sender.name}` : "";
+        lines.push(`Step ${step.step_index + 1} ${step.step_id} (${step.kind}${step.threaded ? ", continues the thread" : ""})${signer}`);
+        if (step.note)
+            lines.push(`  ${step.note}`);
+        for (const variant of step.variants) {
+            lines.push(`  Variant ${variant.variant_id}${variant.status === "paused" ? " (paused)" : ""}`);
+            for (const render of variant.renders) {
+                lines.push(`    ${render.lead}`);
+                for (const field of render.fields) {
+                    const limit = field.character_limit !== null && field.character_count > field.character_limit
+                        ? ` [${field.character_count}/${field.character_limit} characters]`
+                        : "";
+                    const missing = field.missing_variables.length > 0
+                        ? ` [missing ${field.missing_variables.map((key) => `{{${key}}}`).join(", ")}]`
+                        : "";
+                    const text = field.text.replace(/\n/g, "\n        ") || "(empty)";
+                    lines.push(`      ${field.key}: ${text}${limit}${missing}`);
+                }
+            }
+        }
+    }
+    if (lines.length === 0)
+        lines.push("No step has copy to render.");
+    if (data.note)
+        lines.push("", data.note);
+    const link = data.deepLink ?? data.web_url;
+    if (link)
+        lines.push(link);
+    return `${lines.join("\n")}\n`;
+}
+async function handleSequenceSignalAction(sequence, options) {
+    try {
+        const signal = readOption(options.signal);
+        if (!signal)
+            throw new Error("--signal is required.");
+        const enrollmentId = readOption(options.enrollment);
+        const leadProviderId = readOption(options.lead);
+        if (!enrollmentId && !leadProviderId) {
+            throw new Error("Provide a target enrollment with --enrollment <id> and/or --lead <provider_id>.");
+        }
+        const data = await requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/signal`, {
+            method: "POST",
+            body: {
+                signal,
+                ...(enrollmentId ? { enrollment_id: enrollmentId } : {}),
+                ...(leadProviderId ? { lead_provider_id: leadProviderId } : {}),
+            },
+        });
+        if (options.json) {
+            writeJson(success("sequences signal", data));
+            return;
+        }
+        const updated = typeof data.enrollments_updated === "number" ? data.enrollments_updated : 0;
+        const recordedSignal = data.signal ?? signal;
+        const link = data.deepLink ?? data.web_url;
+        process.stdout.write(`Recorded ${recordedSignal} on ${updated} enrollment(s).${link ? ` ${link}` : ""}\n`);
+    }
+    catch (error) {
+        emitCliFailure("sequences signal", error);
+    }
+}
+// `sequences events` reads the per-sequence activity feed (Instantly "Sending
+// Activities" parity). Read-only: it forwards the filters as query params and
+// renders one line per event, with a keyset `next:` hint when a further page
+// exists.
+async function handleSequenceEventsAction(sequence, options) {
+    try {
+        const params = new URLSearchParams();
+        const enrollment = readOption(options.enrollment);
+        if (enrollment)
+            params.set("enrollment", enrollment);
+        const kinds = readCsvOption(options.kind);
+        if (kinds.length > 0)
+            params.set("kinds", kinds.join(","));
+        if (options.includeBots)
+            params.set("include_bots", "true");
+        const limit = readOption(options.limit);
+        if (limit)
+            params.set("limit", limit);
+        const before = readOption(options.before);
+        if (before)
+            params.set("before", before);
+        const suffix = params.toString();
+        const data = await requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/events${suffix ? `?${suffix}` : ""}`);
+        if (options.json) {
+            writeJson(success("sequences events", data));
+            return;
+        }
+        process.stdout.write(formatSequenceEvents(data));
+    }
+    catch (error) {
+        emitCliFailure("sequences events", error);
+    }
+}
+const SEQUENCE_EVENT_KIND_WIDTH = 12;
+// Render occurred_at as a compact minute-precision UTC stamp for the terminal
+// (the full-precision ISO stays in the JSON envelope and the --before cursor).
+function formatEventTime(iso) {
+    if (!iso)
+        return "—";
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime()))
+        return iso;
+    return `${date.toISOString().slice(0, 16)}Z`;
+}
+function formatSequenceEvents(data) {
+    const events = Array.isArray(data.events) ? data.events : [];
+    if (events.length === 0)
+        return "No events yet.\n";
+    const lines = events.map((event) => {
+        const time = formatEventTime(event.occurredAt);
+        const kind = (event.kind ?? "—").padEnd(SEQUENCE_EVENT_KIND_WIDTH);
+        const segments = [];
+        if (event.stepIndex != null) {
+            segments.push(`step ${event.stepIndex}${event.variantId ? ` (${event.variantId})` : ""}`);
+        }
+        if (event.actionKind)
+            segments.push(event.actionKind);
+        if (event.mailboxEmail)
+            segments.push(`via ${event.mailboxEmail}`);
+        else if (event.mailboxId)
+            segments.push(`via mailbox ${event.mailboxId}`);
+        if (event.url)
+            segments.push(event.url);
+        if (event.detail)
+            segments.push(`— ${event.detail}`);
+        const tail = segments.join("  ");
+        return [time, kind, tail].filter((part) => part.trim().length > 0).join("  ").replace(/\s+$/, "");
+    });
+    if (data.next_before)
+        lines.push(`next: --before ${data.next_before}`);
+    return `${lines.join("\n")}\n`;
+}
+async function handleSequenceVariantsAction(sequence, options) {
+    try {
+        const path = `/api/cli/sequences/${encodeURIComponent(sequence)}/variants`;
+        // One change per call: extra flags used to be dropped without a word, and a
+        // lone --step read the whole scoreboard.
+        const actions = [
+            options.autoOptimize ? "--auto-optimize" : null,
+            options.pause !== undefined ? "--pause" : null,
+            options.activate !== undefined ? "--activate" : null,
+            options.reset !== undefined ? "--reset" : null,
+        ].filter((flag) => flag !== null);
+        if (actions.length > 1) {
+            throw new OxygenError("invalid_request", `Pass one of ${actions.join(", ")} per call.`, { details: { flags: actions }, exitCode: 2 });
+        }
+        if (options.step && (actions.length === 0 || options.autoOptimize)) {
+            throw new OxygenError("invalid_request", options.autoOptimize
+                ? "--auto-optimize runs on the whole sequence; drop --step."
+                : "--step scopes --pause, --activate or --reset; add one of them.", { details: { step: options.step }, exitCode: 2 });
+        }
+        let body = null;
+        if (options.autoOptimize)
+            body = { action: "auto_optimize" };
+        else if (options.pause !== undefined)
+            body = { action: "pause", step_id: options.step, variant: options.pause };
+        else if (options.activate !== undefined)
+            body = { action: "activate", step_id: options.step, variant: options.activate };
+        else if (options.reset !== undefined)
+            body = {
+                action: "reset",
+                ...(options.step ? { step_id: options.step } : {}),
+                ...(typeof options.reset === "string" ? { variant: options.reset } : {}),
+            };
+        const data = body
+            ? await requestOxygen(path, { method: "POST", body })
+            : await requestOxygen(path);
+        if (options.json) {
+            writeJson(success("sequences variants", data));
+            return;
+        }
+        if (body) {
+            const link = data.deepLink ?? data.web_url;
+            process.stdout.write(`${data.note ?? "Done."}${link ? ` ${link}` : ""}\n`);
+            return;
+        }
+        process.stdout.write(formatSequenceVariants(data));
+    }
+    catch (error) {
+        emitCliFailure("sequences variants", error);
+    }
+}
+function formatVariantCell(value) {
+    if (value === null || value === undefined)
+        return "—";
+    return String(value);
+}
+function formatRatePercent(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "—";
+    // Rates arrive as a 0–1 fraction; render as a one-decimal percentage.
+    return `${(value * 100).toFixed(1)}%`;
+}
+function formatReplyTypes(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return "—";
+    const entries = Object.entries(value)
+        .map(([key, count]) => [key, Number(count)])
+        .filter(([, count]) => Number.isFinite(count) && count > 0)
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+    return entries.length > 0 ? entries.map(([key, count]) => `${key}:${count}`).join(", ") : "—";
+}
+// Sequence state is derived only by the shared API. These helpers render those
+// facts; they never infer flowing/blocked/live client-side. The one label drawn
+// from them, completed, is the server's `lifecycle` (the shared helper covers a
+// server that predates it). JSON remains the untouched API data inside the
+// standard CLI envelope.
+const SEQUENCE_OPERATIONAL_STATE_ORDER = ["empty", "drained", "never_started", "blocked", "degraded", "flowing", "paced", "paused"];
+/**
+ * A state-changing sequencer command that prints a readable block instead of the
+ * raw envelope. Same shape as `handleReadActionWithLens`, plus the billing
+ * notices every write path owes the operator.
+ */
+async function handleSequenceWriteAction(command, options, action, render) {
+    try {
+        const data = await action();
+        writeBillingNotices(command, data);
+        if (options.json) {
+            writeJson(success(command, data));
+            return;
+        }
+        process.stdout.write(isRecord(data) ? render(data) : `${JSON.stringify(data, null, 2)}\n`);
+        writeCreditsReceipt(data);
+    }
+    catch (error) {
+        emitCliFailure(command, error);
+    }
+}
+/**
+ * The external-campaign push, in the shape an operator reads before approving:
+ * what campaign it resolved, what is mapped onto which column, how many rows
+ * each gate drops, and — when something is in the way — the one command that
+ * clears it. A dry run that is blocked still prints the row counts, because
+ * "you are not connected" and "your table has no emails" are different problems
+ * and the operator should learn both in one pass.
+ */
+function formatSequencePushExternal(data) {
+    const lines = [];
+    const provider = stringValue(data.provider) ?? "provider";
+    const campaign = recordValue(data.campaign);
+    const resolved = recordValue(campaign.resolved);
+    const table = recordValue(data.table);
+    const rows = recordValue(data.rows);
+    const live = stringValue(data.mode) === "live";
+    const campaignName = stringValue(resolved.name) ?? stringValue(campaign.name);
+    const campaignId = stringValue(resolved.id) ?? stringValue(campaign.id);
+    lines.push(campaignName
+        ? `${live ? "Pushing to" : "Preview: push to"} ${provider} campaign "${campaignName}"${campaignId ? ` (${campaignId})` : ""}`
+        : `${live ? "Pushing to" : "Preview: push to"} ${provider} campaign "${stringValue(campaign.requested) ?? "?"}" — NOT RESOLVED (${stringValue(campaign.reason) ?? "unknown"})`);
+    lines.push(`Table: ${stringValue(table.display_name) ?? stringValue(table.slug) ?? stringValue(table.id) ?? "?"}`);
+    const connection = recordValue(data.connection);
+    if (stringValue(connection.status) === "missing") {
+        lines.push(`Connection: NOT CONNECTED — ${stringValue(connection.connect_command) ?? `oxygen integrations connect ${provider} --api-key <key>`}`);
+    }
+    else if (stringValue(connection.connection_id)) {
+        lines.push(`Connection: ${stringValue(connection.connection_id)}`);
+    }
+    const identityField = stringValue(rows.identity_field) ?? "email";
+    lines.push([
+        `Rows: ${numericValue(rows.scoped) ?? 0} scoped`,
+        `${numericValue(rows.with_identity) ?? 0} with ${identityField}`,
+        `${numericValue(rows.missing_identity) ?? 0} missing ${identityField}`,
+        `${numericValue(rows.duplicate_identity) ?? 0} duplicate`,
+        `${numericValue(rows.already_pushed) ?? 0} already pushed`,
+        `${numericValue(rows.to_push) ?? 0} to push`,
+    ].join(" | "));
+    if (rows.has_more === true) {
+        lines.push("More rows match than one push covers — re-run after this one to continue.");
+    }
+    const mapping = recordValue(data.field_mapping);
+    const mapped = Object.entries(mapping).map(([field, column]) => `${field}=${String(column)}`);
+    lines.push(`Mapping: ${mapped.length > 0 ? mapped.join(", ") : "none detected"}`);
+    const column = recordValue(data.column);
+    if (stringValue(column.key)) {
+        lines.push(`Provenance column: ${stringValue(column.key)}${column.exists === true ? "" : " (will be created)"}`);
+    }
+    const samples = Array.isArray(data.sample_leads) ? data.sample_leads : [];
+    if (samples.length > 0) {
+        lines.push("Sample leads (exactly as they will be sent):");
+        for (const sample of samples)
+            lines.push(`  ${JSON.stringify(sample)}`);
+    }
+    if (stringValue(data.dedupe))
+        lines.push(`Dedupe: ${stringValue(data.dedupe)}`);
+    const candidates = Array.isArray(campaign.candidates) ? campaign.candidates.filter(isRecord) : [];
+    if (candidates.length > 0) {
+        lines.push("Campaigns on this connection:");
+        for (const entry of candidates) {
+            lines.push(`  ${stringValue(entry.name) ?? "?"} (${stringValue(entry.id) ?? "?"}${stringValue(entry.status) ? `, ${stringValue(entry.status)}` : ""})`);
+        }
+    }
+    const blockedBy = Array.isArray(data.blocked_by) ? data.blocked_by.filter((entry) => typeof entry === "string") : [];
+    if (blockedBy.length > 0)
+        lines.push(`Blocked: ${blockedBy.join(", ")}`);
+    if (stringValue(data.note))
+        lines.push(stringValue(data.note));
+    const run = recordValue(data.run);
+    if (stringValue(run.id))
+        lines.push(`Run: ${stringValue(run.id)} (${stringValue(run.status) ?? "queued"})`);
+    if (stringValue(data.next_action))
+        lines.push(`Next: ${stringValue(data.next_action)}`);
+    const link = stringValue(data.web_url) ?? stringValue(data.deepLink);
+    if (link)
+        lines.push(link);
+    return `${lines.join("\n")}\n`;
+}
+function formatSequenceListHealth(data) {
+    const sequences = Array.isArray(data.sequences) ? data.sequences.filter(isRecord) : [];
+    const lines = [...formatSequenceFleetSummary(data.fleet), ""];
+    if (sequences.length === 0) {
+        lines.push("No sequences match these filters.");
+    }
+    else {
+        lines.push(...renderTextTable(["SEQUENCE", "PERSISTED", "OPERATIONAL", "OPEN WORK", "SENT / FAILED", "REASONS"], sequences.map((sequence) => {
+            // Warnings print below the table, so the row points at them: a reader
+            // skimming the rows missed the deleted-row warning (T-220 acceptance).
+            const row = sequenceHealthRow(sequence);
+            const warningCount = sequenceRowWarnings([sequence]).length;
+            if (warningCount > 0)
+                row[row.length - 1] = `${row[row.length - 1]}; ${warningCount} warning${warningCount === 1 ? "" : "s"} below`;
+            return row;
+        })));
+        const warnings = sequenceRowWarnings(sequences);
+        if (warnings.length > 0)
+            lines.push("", ...warnings);
+        lines.push("", ...sequenceInspectionLinks(sequences));
+    }
+    const listLink = stringValue(data.web_url) ?? stringValue(data.deepLink);
+    if (listLink)
+        lines.push(listLink);
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Render one funnel metric.
+ *
+ * `numberText` defaults a missing value to "0", which is exactly the lie this
+ * whole contract exists to stop: a campaign whose workspace has no verified
+ * tracking domain would print "0" opens, indistinguishable from "nobody opened
+ * it". An unmeasured metric carries a coverage entry and prints what it is.
+ */
+function funnelMetricText(funnel, metric) {
+    const value = numericValue(funnel[metric]);
+    if (value !== null)
+        return String(value);
+    const coverage = recordValue(recordValue(funnel.coverage)[metric]);
+    const state = stringValue(coverage.state);
+    if (state === "not_supported")
+        return "n/a";
+    if (state)
+        return "not tracked";
+    return "—";
+}
+function funnelRateText(funnel, rate, metric) {
+    const value = numericValue(funnel[rate]);
+    if (value !== null)
+        return `${(value * 100).toFixed(1)}%`;
+    const coverage = recordValue(recordValue(funnel.coverage)[metric]);
+    const state = stringValue(coverage.state);
+    if (state === "not_supported")
+        return "n/a";
+    if (state)
+        return "not tracked";
+    return "—";
+}
+/**
+ * The per-channel funnel block, shared by `sequences stats` and `sequences
+ * analytics`.
+ *
+ * `sequences analytics` printed no funnel at all before this, only operational
+ * health. A blind user eval run against dev asked exactly the question this
+ * answers -- "which channel got the most replies, and what is my reply rate on
+ * each" -- and had to open every campaign's stats block one by one and hand-sum
+ * the channels in prose, because no command grouped them.
+ */
+function formatSequenceChannelFunnels(funnels, replies) {
+    const byChannel = recordValue(funnels);
+    const channels = ["linkedin", "email", "whatsapp"].filter((channel) => isRecord(byChannel[channel]));
+    if (channels.length === 0)
+        return [];
+    const rows = channels.map((channel) => {
+        const funnel = recordValue(byChannel[channel]);
+        const invites = recordValue(funnel.invites);
+        return [
+            channel,
+            numberText(funnel.recipients),
+            numberText(funnel.sends),
+            numericValue(invites.sent) === null ? "n/a" : `${numberText(invites.accepted)}/${numberText(invites.sent)}`,
+            funnelMetricText(funnel, "delivered"),
+            funnelMetricText(funnel, "opened"),
+            funnelMetricText(funnel, "replied"),
+            funnelRateText(funnel, "replyRate", "replied"),
+            funnelMetricText(funnel, "positiveReplied"),
+        ];
+    });
+    const lines = ["", ...renderTextTable(["CHANNEL", "PEOPLE", "SENDS", "ACCEPTED", "DELIVERED", "OPENED", "REPLIED", "REPLY RATE", "POSITIVE"], rows)];
+    // Name the remedy once per distinct gap rather than once per row.
+    const remedies = new Map();
+    for (const channel of channels) {
+        const coverage = recordValue(recordValue(byChannel[channel]).coverage);
+        for (const entry of Object.values(coverage)) {
+            const record = recordValue(entry);
+            if (stringValue(record.state) === "not_supported")
+                continue;
+            const detail = stringValue(record.detail);
+            const command = stringValue(recordValue(record.remedy).command);
+            if (detail)
+                remedies.set(detail, command ?? "");
+        }
+    }
+    for (const [detail, command] of remedies) {
+        lines.push(command ? `Not tracked: ${detail} Turn it on with: ${command}` : `Not tracked: ${detail}`);
+    }
+    // A reply can exist on a channel the table has no row for: an invite-only
+    // campaign whose lead answered the invite note replied on LinkedIn without ever
+    // being MESSAGED, so it is not in that channel's rate denominator. Left
+    // unexplained, the headline ("linkedin 19") disagrees with the table (18) and
+    // the reader has to guess -- a blind user eval hit exactly this and recorded it
+    // as plausible but unverified.
+    const byChannelReplies = recordValue(recordValue(replies).byChannel);
+    for (const channel of ["linkedin", "email", "whatsapp"]) {
+        const counted = numericValue(byChannelReplies[channel]) ?? 0;
+        const inTable = numericValue(recordValue(byChannel[channel]).replied) ?? 0;
+        const outside = counted - inTable;
+        if (outside <= 0)
+            continue;
+        lines.push(`${channel}: ${outside} more ${outside === 1 ? "reply" : "replies"} came from a campaign with no message step `
+            + "(an invite note, say), so they are counted in the total above but have no reply rate here.");
+    }
+    return lines;
+}
+/** `Replies: 4 (linkedin 2 · email 1 · unattributed 1)` -- the one-line answer. */
+function formatSequenceReplyRollup(replies) {
+    const rollup = recordValue(replies);
+    const total = numericValue(rollup.total);
+    if (total === null)
+        return null;
+    const byChannel = recordValue(rollup.byChannel);
+    const parts = ["linkedin", "email", "whatsapp"]
+        .map((channel) => [channel, numericValue(byChannel[channel])])
+        .filter((entry) => entry[1] !== null && entry[1] > 0)
+        .map(([channel, value]) => `${channel} ${value}`);
+    const unattributed = numericValue(rollup.unattributed) ?? 0;
+    // An unattributed reply is a recording gap made visible, never folded into a
+    // channel and never dropped.
+    if (unattributed > 0)
+        parts.push(`unattributed ${unattributed}`);
+    return parts.length > 0 ? `Replies: ${total} (${parts.join(" · ")})` : `Replies: ${total}`;
+}
+function formatSequenceStatsHealth(data) {
+    const stats = recordValue(data.stats);
+    const operational = recordValue(stats.operational);
+    const budget = recordValue(data.daily_budget);
+    const lines = [
+        stringValue(data.name) ?? stringValue(data.sequence_id) ?? "Sequence",
+        `Persisted status: ${stringValue(data.status) ?? "unknown"}`,
+        `Operational state: ${operationalStateText(data, operational) ?? "unknown (legacy response)"}`,
+        `Open work: ${formatSequenceOpenWork(operational.openWork)}`,
+        `Reasons: ${formatSequenceReasons(operational)}`,
+        `${formatFailureWindow(operational.failureAnalytics)} outcomes: ${formatSequenceFailureTotals(operational.failureAnalytics)}`,
+    ];
+    const sentToday = numericValue(budget.sends_used);
+    if (sentToday !== null) {
+        const reserved = numericValue(budget.sends_reserved);
+        const remaining = numericValue(budget.sends_remaining);
+        lines.push(`Today${stringValue(budget.day) ? ` (${budget.day} UTC)` : ""}: ${sentToday} sent`
+            + (reserved === null ? "" : ` · ${reserved} reserved`)
+            + ` · ${remaining === null ? "unlimited" : remaining} available`);
+    }
+    const failureMix = formatCountRecord(recordValue(recordValue(operational.failureAnalytics).byFailureClass));
+    if (failureMix !== "—")
+        lines.push(`Failure mix: ${failureMix}`);
+    lines.push(...formatActionKindBreakdown(operational.failureAnalytics));
+    // Every lead ever enrolled, removed and finished included, so name the split
+    // beside it: "Enrolled: 6" next to 4 in progress read as a miscount (T-220 acceptance).
+    const byStatus = formatCountRecord(recordValue(stats.byStatus));
+    lines.push("", `Enrolled (all time): ${numberText(stats.enrolled)}${byStatus === "—" ? "" : ` — ${byStatus}`}`);
+    const replyLine = formatSequenceReplyRollup(stats.replies);
+    if (replyLine)
+        lines.push(replyLine);
+    const funnelLines = formatSequenceChannelFunnels(stats.funnels, stats.replies);
+    if (funnelLines.length > 0) {
+        lines.push(...funnelLines);
+    }
+    else {
+        lines.push("", ...renderTextTable(["FUNNEL", "COUNT"], [
+            ["Invites sent", numberText(stats.invitesSent ?? stats.connectionRequestsSent)],
+            ["Connected", numberText(stats.connected ?? stats.connectionRequestsAccepted)],
+            ["Messages sent", numberText(stats.messagesSent)],
+            ["Replies", numberText(stats.totalReplies ?? stats.replied)],
+        ]));
+    }
+    const link = stringValue(data.web_url) ?? stringValue(data.deepLink);
+    if (link)
+        lines.push("", link);
+    return `${lines.join("\n")}\n`;
+}
+function formatSequenceAnalyticsHealth(data) {
+    const analytics = recordValue(data.analytics);
+    const summary = recordValue(analytics.operationalSummary);
+    const failureAnalytics = summary.failureAnalytics;
+    const sequences = Array.isArray(analytics.sequences) ? analytics.sequences.filter(isRecord) : [];
+    const range = recordValue(analytics.range);
+    const from = stringValue(range.from);
+    const to = stringValue(range.to);
+    const rangeLabel = from || to ? `${from ?? "start"} → ${to ?? "now"}` : stringValue(range.preset) ?? "selected window";
+    const senderOptions = Array.isArray(analytics.senders) ? analytics.senders.filter(isRecord) : [];
+    const senderFilter = Array.isArray(analytics.senderFilter)
+        ? analytics.senderFilter.filter((key) => typeof key === "string")
+        : null;
+    const senderName = (key) => stringValue(senderOptions.find((option) => option.key === key)?.name) ?? key;
+    const lines = [
+        `Sequencer analytics (${rangeLabel})`,
+        ...(senderFilter ? [`Senders: ${senderFilter.map(senderName).join(", ")}`] : []),
+        ...formatSequenceFleetSummary(analytics.fleet),
+        `Open work: ${formatSequenceOpenWork(summary.openWork)}`,
+        `Selected-window outcomes: ${formatSequenceFailureTotals(failureAnalytics)}`,
+        `Failure mix: ${formatCountRecord(recordValue(recordValue(failureAnalytics).byFailureClass))}`,
+        ...formatActionKindBreakdown(failureAnalytics),
+    ];
+    const totals = recordValue(analytics.totals);
+    const replyLine = formatSequenceReplyRollup(totals.replies);
+    if (replyLine)
+        lines.push(replyLine);
+    lines.push(...formatSequenceChannelFunnels(totals.funnels, totals.replies));
+    lines.push("");
+    if (sequences.length === 0) {
+        lines.push("No sequences in this analytics scope.");
+    }
+    else {
+        lines.push(...renderTextTable(["SEQUENCE", "PERSISTED", "OPERATIONAL", "OPEN WORK", "SENT / FAILED", "REASONS"], sequences.map((sequence) => sequenceHealthRow(sequence))));
+        lines.push("", ...sequenceInspectionLinks(sequences));
+    }
+    const link = stringValue(data.web_url) ?? stringValue(data.deepLink);
+    if (link)
+        lines.push(link);
+    const firstSender = stringValue(senderOptions[0]?.key);
+    if (!senderFilter && senderOptions.length > 1 && firstSender) {
+        lines.push(`Scope to one sender: add --sender ${firstSender} (${senderName(firstSender)}); all ${senderOptions.length} are under analytics.senders with --json.`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function sequenceHealthRow(sequence) {
+    const operational = recordValue(sequence.operational);
+    return [
+        stringValue(sequence.name) ?? stringValue(sequence.slug) ?? "—",
+        stringValue(sequence.status) ?? "unknown",
+        operationalStateText(sequence, operational) ?? "unknown",
+        formatSequenceOpenWork(operational.openWork),
+        formatSequenceFailureTotals(operational.failureAnalytics),
+        formatSequenceReasons(operational),
+    ];
+}
+/**
+ * The operational state, naming the lifecycle a person reads when the two
+ * disagree. A campaign that contacted every lead keeps its persisted `active`,
+ * and a blind user eval (2026-09-29) had to infer it was done from `drained`
+ * plus zero open work. The web lists the same Sequence as Completed.
+ */
+function operationalStateText(sequence, operational) {
+    const state = stringValue(operational.operationalState);
+    if (!state)
+        return null;
+    // The server's own `lifecycle`; the shared helper covers a server that predates it.
+    const lifecycle = stringValue(sequence.lifecycle) ?? sequenceDisplayStatus(stringValue(sequence.status) ?? "", state);
+    return lifecycle === "completed" ? `${state} (completed)` : state;
+}
+/** A listed Sequence's launch warnings (e.g. two sending schedules), one line each. */
+function sequenceRowWarnings(sequences) {
+    return sequences.flatMap((sequence) => {
+        const label = stringValue(sequence.name) ?? stringValue(sequence.slug) ?? "Sequence";
+        const warnings = Array.isArray(sequence.warnings) ? sequence.warnings.filter(isRecord) : [];
+        return warnings.flatMap((warning) => {
+            const message = stringValue(warning.message);
+            return message ? [`Warning (${label}): ${message}`] : [];
+        });
+    });
+}
+function sequenceInspectionLinks(sequences) {
+    return sequences.flatMap((sequence) => {
+        const exactLink = stringValue(sequence.web_url) ?? stringValue(sequence.deepLink);
+        return exactLink ? [`Inspect ${stringValue(sequence.name) ?? stringValue(sequence.slug) ?? "Sequence"}: ${exactLink}`] : [];
+    });
+}
+function formatSequenceFleetSummary(value) {
+    const fleet = recordValue(value);
+    if (Object.keys(fleet).length === 0)
+        return ["Fleet counts: unavailable (legacy API response)"];
+    const states = recordValue(fleet.byOperationalState);
+    // Only when there is something to act on: a workspace with no parked drafts
+    // should not read a line of zeroes every time it lists its sequences.
+    const neverStarted = typeof fleet.neverStarted === "number" ? fleet.neverStarted : 0;
+    const parkedLeads = typeof fleet.neverStartedEnrollments === "number" ? fleet.neverStartedEnrollments : 0;
+    const completed = recordValue(fleet.byLifecycle).completed;
+    const completedText = typeof completed === "number" ? ` · ${numberText(completed)} completed` : "";
+    return [
+        `Fleet: ${numberText(fleet.markedActive)} marked active · ${numberText(fleet.operationallyLive)} operationally live${completedText} · ${numberText(fleet.total)} total`,
+        `States: ${SEQUENCE_OPERATIONAL_STATE_ORDER.map((state) => `${state} ${numberText(states[state])}`).join(" · ")}`,
+        ...(neverStarted > 0
+            ? [`Never started: ${numberText(neverStarted)} draft${neverStarted === 1 ? "" : "s"} holding ${numberText(parkedLeads)} enrolled lead${parkedLeads === 1 ? "" : "s"} — these send nothing until launched. List them with \`oxygen sequences list --operational-state never_started\`, then check one with \`oxygen sequences get <sequence> --readiness\` (read-only).`]
+            : []),
+    ];
+}
+/**
+ * Spelled out because a blind user eval (2026-09-29) read `enr 352` as 352
+ * enrolled when it meant 352 leads still in progress, and told the founder the
+ * wrong count. Only the first two counts have a unit: ready, in flight, paced
+ * and blocked add leads with no open action to open actions.
+ */
+function formatSequenceOpenWork(value) {
+    const work = recordValue(value);
+    if (Object.keys(work).length === 0)
+        return "unknown";
+    const counts = [
+        ["leads in progress", work.enrollments],
+        ["open actions", work.actions],
+        ["ready now", work.actionableNow],
+        ["in flight", work.inFlight],
+        ["paced", work.paced],
+        ["blocked", work.blocked],
+        ["unresolved failures", work.unresolvedFailures],
+    ];
+    if (counts.every(([, count]) => count === 0))
+        return "none";
+    return counts.map(([label, count]) => `${label} ${numberText(count)}`).join(" · ");
+}
+function formatSequenceFailureTotals(value) {
+    const analytics = recordValue(value);
+    if (Object.keys(analytics).length === 0)
+        return "unknown";
+    return `sent ${numberText(analytics.sent)} · failed ${numberText(analytics.terminalFailed)} · deferred ${numberText(analytics.deferrals)}`;
+}
+function formatFailureWindow(value) {
+    const windowValue = recordValue(recordValue(value).window);
+    const from = stringValue(windowValue.from);
+    const to = stringValue(windowValue.to);
+    return from || to ? `Selected-window ${from ?? "start"} → ${to ?? "now"}` : "Lifetime";
+}
+function formatSequenceReasons(operational) {
+    const reasonCodes = Array.isArray(operational.reasonCodes)
+        ? operational.reasonCodes.filter((reason) => typeof reason === "string")
+        : [];
+    if (reasonCodes.length > 0)
+        return reasonCodes.join(", ");
+    return stringValue(operational.operationalState) ? "none reported" : "unknown";
+}
+function formatActionKindBreakdown(value) {
+    const byActionKind = recordValue(recordValue(value).byActionKind);
+    const entries = Object.entries(byActionKind).filter((entry) => isRecord(entry[1])).sort(([left], [right]) => left.localeCompare(right));
+    if (entries.length === 0)
+        return [];
+    return ["By action kind:", ...entries.map(([kind, bucket]) => {
+            const mix = formatCountRecord(recordValue(bucket.byFailureClass));
+            return `  ${kind}: ${formatSequenceFailureTotals(bucket)}${mix === "—" ? "" : ` · failures ${mix}`}`;
+        })];
+}
+function formatCountRecord(value) {
+    const entries = Object.entries(value)
+        .map(([key, count]) => [key, numericValue(count)])
+        .filter((entry) => entry[1] !== null && entry[1] > 0)
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+    return entries.length > 0 ? entries.map(([key, count]) => `${key} ${count}`).join(" · ") : "—";
+}
+function recordValue(value) {
+    return isRecord(value) ? value : {};
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function numericValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function numberText(value) {
+    return String(numericValue(value) ?? 0);
+}
+function formatSequenceVariants(data) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const byVariant = Array.isArray(data.by_variant) ? data.by_variant : [];
+    const byMailbox = Array.isArray(data.by_mailbox) ? data.by_mailbox : [];
+    const byDomain = Array.isArray(data.by_domain) ? data.by_domain : [];
+    const unattributed = data.unattributed;
+    const lines = ["", styles.bold("By variant")];
+    if (byVariant.length === 0) {
+        lines.push(`  ${styles.dim("No variant analytics yet.")}`);
+    }
+    else {
+        const headers = ["STEP", "VARIANT", "SENT", "REPLIED", "REPLY RATE", "BOUNCED", "CREDITS"];
+        const rows = byVariant.map((row) => [
+            formatVariantCell(row.step_index),
+            formatVariantCell(row.variant_id),
+            formatVariantCell(row.sent),
+            formatVariantCell(row.replied),
+            formatRatePercent(row.reply_rate),
+            formatVariantCell(row.bounced),
+            formatVariantCell(row.credits_used),
+        ]);
+        lines.push(...renderTextTable(headers, rows));
+    }
+    lines.push("", styles.bold("By mailbox"));
+    if (byMailbox.length === 0) {
+        lines.push(`  ${styles.dim("No mailbox analytics yet.")}`);
+    }
+    else {
+        const headers = ["MAILBOX", "CAMPAIGNS", "SENT", "REPLIED", "REPLY RATE", "BOUNCED", "BOUNCE RATE", "REPLY TYPES", "FAILED"];
+        const rows = byMailbox.map((row) => [
+            formatVariantCell(row.email_address ?? row.emailAddress),
+            formatVariantCell(row.campaign_count ?? row.campaignCount),
+            formatVariantCell(row.sent),
+            formatVariantCell(row.replied),
+            formatRatePercent(row.reply_rate ?? row.replyRate),
+            formatVariantCell(row.bounced),
+            formatRatePercent(row.bounce_rate ?? row.bounceRate),
+            formatReplyTypes(row.reply_types ?? row.replyTypes),
+            formatVariantCell(row.failed),
+        ]);
+        lines.push(...renderTextTable(headers, rows));
+    }
+    lines.push("", styles.bold("By sending domain"));
+    if (byDomain.length === 0) {
+        lines.push(`  ${styles.dim("No sending-domain analytics yet.")}`);
+    }
+    else {
+        const headers = ["DOMAIN", "MAILBOXES", "CAMPAIGNS", "SENT", "REPLIED", "REPLY RATE", "BOUNCED", "BOUNCE RATE", "REPLY TYPES"];
+        const rows = byDomain.map((row) => [
+            formatVariantCell(row.sending_domain ?? row.sendingDomain),
+            formatVariantCell(row.mailbox_count ?? row.mailboxCount),
+            formatVariantCell(row.campaign_count ?? row.campaignCount),
+            formatVariantCell(row.sent),
+            formatVariantCell(row.replied),
+            formatRatePercent(row.reply_rate ?? row.replyRate),
+            formatVariantCell(row.bounced),
+            formatRatePercent(row.bounce_rate ?? row.bounceRate),
+            formatReplyTypes(row.reply_types ?? row.replyTypes),
+        ]);
+        lines.push(...renderTextTable(headers, rows));
+    }
+    const hasUnattributed = unattributed
+        && [unattributed.sent, unattributed.replied, unattributed.bounced, unattributed.failed]
+            .some((value) => typeof value === "number" && value > 0);
+    if (hasUnattributed && unattributed) {
+        lines.push("", styles.bold("Unattributed sending identity"));
+        lines.push(...renderTextTable(["SENT", "REPLIED", "POSITIVE", "BOUNCED", "FAILED", "REPLY TYPES"], [[
+                formatVariantCell(unattributed.sent),
+                formatVariantCell(unattributed.replied),
+                formatVariantCell(unattributed.positive_replies ?? unattributed.positiveReplies),
+                formatVariantCell(unattributed.bounced),
+                formatVariantCell(unattributed.failed),
+                formatReplyTypes(unattributed.reply_types ?? unattributed.replyTypes),
+            ]]));
+        lines.push(`  ${styles.dim("Campaign attribution is preserved; mailbox/domain is left unassigned instead of guessed.")}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+// Assemble the optional campaign email binding from the --email-* flags. The
+// content spec (--email-definition-file) is the author-provided email sequence
+// that the API compiles to an Instantly campaign on start; provider/connection
+// pick which Instantly account to bind. Returns undefined when no email flags
+// are set (a LinkedIn-only campaign).
+function readCampaignEmailBinding(options) {
+    const provider = readOption(options.emailProvider);
+    const connectionId = readOption(options.emailConnection);
+    const definitionPath = readOption(options.emailDefinitionFile);
+    if (!provider && !connectionId && !definitionPath)
+        return undefined;
+    const definition = definitionPath
+        ? readJsonFileValue(resolve(definitionPath), "--email-definition-file")
+        : undefined;
+    return {
+        ...(provider ? { provider } : {}),
+        ...(connectionId ? { connection_id: connectionId } : {}),
+        ...(definition !== undefined ? { definition } : {}),
+    };
+}
+// The four --linkedin-* flags write settings.schedule, the per-sequence window
+// the LinkedIn/WhatsApp dispatcher enforces on top of each sender's working
+// hours. The server stores the window whole, so the four flags go together.
+function readLinkedinScheduleOptions(options) {
+    const timezone = readOption(options.linkedinTimezone);
+    const days = readOption(options.linkedinDays);
+    const start = readOption(options.linkedinHoursStart);
+    const end = readOption(options.linkedinHoursEnd);
+    if (!timezone && !days && !start && !end)
+        return undefined;
+    if (!timezone || !days || !start || !end) {
+        throw new OxygenError("invalid_linkedin_schedule", "Set the LinkedIn sending schedule with all four flags: --linkedin-timezone, --linkedin-days, --linkedin-hours-start and --linkedin-hours-end.", { exitCode: 1 });
+    }
+    return { timezone, days: parseWorkingDaysOption(days), start, end };
+}
+// Launch's one sending schedule and one unsubscribe switch. The server writes
+// `sending_schedule` to the email window and the LinkedIn/WhatsApp window, and
+// `include_unsubscribe` to the visible link and the one-click headers.
+function readUnifiedSequenceBody(options) {
+    const timezone = readOption(options.scheduleTimezone);
+    const days = readOption(options.scheduleDays);
+    const start = readOption(options.scheduleHoursStart);
+    const end = readOption(options.scheduleHoursEnd);
+    const body = {};
+    if (timezone || days || start || end) {
+        if (!timezone || !days || !start || !end) {
+            throw new OxygenError("invalid_sending_schedule", "Set the sending schedule with all four flags: --schedule-timezone, --schedule-days, --schedule-hours-start and --schedule-hours-end.", { exitCode: 1 });
+        }
+        body.sending_schedule = { timezone, days: parseWorkingDaysOption(days), start, end };
+    }
+    if (options.includeUnsubscribe !== undefined)
+        body.include_unsubscribe = options.includeUnsubscribe;
+    return body;
+}
+function countCompanyIdentityOptions(options) {
+    return [options.domain, options.email, options.linkedinCompany, options.record]
+        .filter((value) => readOption(value) !== null)
+        .length;
+}
+// Exactly one company identity flag, mapped onto the route's body fields. The
+// server re-checks (and resolves record ids); refusing locally names the flags.
+function readCompanyIdentityOptions(options, verb) {
+    const fields = [
+        ["domain", readOption(options.domain)],
+        ["email", readOption(options.email)],
+        ["linkedin_company_url", readOption(options.linkedinCompany)],
+        ["record_id", readOption(options.record)],
+    ];
+    const provided = fields.filter((entry) => entry[1] !== null);
+    if (provided.length !== 1) {
+        const which = verb === "resume" ? "--hold, or exactly one of " : "exactly one of ";
+        throw new OxygenError(provided.length === 0 ? "company_identity_required" : "company_identity_ambiguous", `Name the company with ${which}--domain, --email, --linkedin-company, or --record.`, { exitCode: 2 });
+    }
+    return Object.fromEntries(provided);
+}
+function readRepeatableIds(values) {
+    return [...new Set((values ?? []).flatMap((value) => readCsvOption(value)))];
+}
+// `sequences contacts-remove` for a human reader: what the call selects, the
+// people it names (a --missing-source-rows preview exists so nobody approves a
+// removal by UUID), and the next step. stderr, like the other summaries.
+function writeContactsRemoveSummary(data) {
+    const payload = asPayloadRecord(data);
+    if (!payload)
+        return;
+    const count = (value) => (typeof value === "number" ? value : 0);
+    const lines = [];
+    const leads = asPayloadRecord(payload.leads);
+    const approved = payload.approved === true;
+    if (payload.mode === "missing_source_rows") {
+        const total = count(leads?.total);
+        // Counts recorded deletions only, so zero is never read as "none deleted".
+        lines.push(`${total} enrolled lead${total === 1 ? " has" : "s have"} a recorded deletion from this campaign's source table.`);
+    }
+    lines.push(approved
+        ? `Removed ${count(payload.removed)} from the campaign.`
+        : `Preview: ${count(payload.removable)} removable, ${count(payload.contacted)} already contacted, ${count(payload.skippedTerminal)} already finished.`);
+    // What approving costs and touches, stated where the reader decides; with
+    // nothing removable there is nothing to approve, so no line invites it.
+    if (!approved && count(payload.removable) > 0 && typeof payload.credits_used === "number") {
+        lines.push(`Cost: ${payload.credits_used} credits. Approving stops only these campaign enrollments: nothing is sent, and table rows are kept.`);
+    }
+    const items = Array.isArray(leads?.items) ? leads.items : [];
+    for (const entry of items) {
+        const lead = asPayloadRecord(entry);
+        if (!lead)
+            continue;
+        const name = typeof lead.name === "string" && lead.name.trim() ? lead.name.trim() : "(unnamed lead)";
+        // After approval the server reports each lead's new state; "stopped" is this removal.
+        const state = approved
+            ? lead.status === "stopped" ? "removed" : `not removed (${String(lead.status ?? "unknown")})`
+            : String(lead.status ?? "unknown");
+        lines.push(`  ${name} — ${state}${lead.contacted === true ? ", already contacted" : ""}`);
+    }
+    // One call covers at most per_call_limit leads (the oldest); the server's
+    // next_step says to repeat for the rest, so count the unnamed ones in this call.
+    const total = count(leads?.total);
+    const covered = typeof payload.per_call_limit === "number" ? Math.min(total, payload.per_call_limit) : total;
+    const unnamed = covered - items.length;
+    if (unnamed > 0)
+        lines.push(`  …and ${unnamed} more${covered < total ? " in this call" : ""}`);
+    if (typeof payload.next_step === "string")
+        lines.push(payload.next_step);
+    if (typeof payload.web_url === "string")
+        lines.push(`Open: ${payload.web_url}`);
+    process.stderr.write(`${lines.join("\n")}\n`);
+}
+// Human-mode summary of a company pause/resume/list on stderr (stdout keeps the
+// machine-readable envelope): what was held or resumed, per campaign, and where
+// to see it.
+function writeCompanyPauseSummary(data) {
+    const payload = asPayloadRecord(data);
+    if (!payload)
+        return;
+    const lines = [];
+    if (typeof payload.message === "string")
+        lines.push(payload.message);
+    const affected = Array.isArray(payload.affected) ? payload.affected : [];
+    for (const entry of affected) {
+        const record = asPayloadRecord(entry);
+        if (!record)
+            continue;
+        const count = typeof record.enrollments === "number" ? record.enrollments : 0;
+        lines.push(`  ${String(record.sequence_name ?? record.sequence_id)}: ${count} lead${count === 1 ? "" : "s"}`);
+    }
+    // A pause reaching a campaign whose email is sent by Instantly does not stop
+    // those emails; the route says which campaigns, and a human reader must see it.
+    const warnings = Array.isArray(payload.warnings) ? payload.warnings : [];
+    for (const entry of warnings) {
+        const warning = asPayloadRecord(entry);
+        if (warning && typeof warning.message === "string")
+            lines.push(`Warning: ${warning.message}`);
+    }
+    const holds = Array.isArray(payload.holds) && typeof payload.message !== "string" ? payload.holds : [];
+    if (Array.isArray(payload.holds) && typeof payload.message !== "string" && holds.length === 0) {
+        lines.push("No companies are paused.");
+    }
+    for (const entry of holds) {
+        const hold = asPayloadRecord(entry);
+        if (!hold)
+            continue;
+        const scope = typeof hold.sequence_name === "string" ? hold.sequence_name : hold.sequence_id ? String(hold.sequence_id) : "every campaign";
+        const held = typeof hold.held_enrollments === "number" ? hold.held_enrollments : 0;
+        lines.push(`  ${String(hold.display_name)} — ${scope} — ${String(hold.state)} — ${held} lead${held === 1 ? "" : "s"} held (hold ${String(hold.id)})`);
+    }
+    if (typeof payload.next_step === "string")
+        lines.push(payload.next_step);
+    if (typeof payload.web_url === "string")
+        lines.push(`Open: ${payload.web_url}`);
+    if (lines.length > 0)
+        process.stderr.write(`${lines.join("\n")}\n`);
+}
+// `--company-reply-pause` (and its deprecated alias `--stop-on-reply-scope`) as
+// the `settings.company_reply_pause` object the server stores. `default` names
+// the statuses a new campaign gets; the alias maps `company_domain` to exactly
+// what the legacy scope always stopped on and `lead` to off, so an old script
+// keeps its behavior while the server stores one key.
+function readCompanyReplyPauseOption(value, legacyScope) {
+    const raw = readOption(value);
+    const legacy = readOption(legacyScope);
+    if (raw && legacy) {
+        throw new OxygenError("invalid_company_reply_pause", "Pass --company-reply-pause only; --stop-on-reply-scope is its deprecated alias.", { exitCode: 2 });
+    }
+    if (legacy) {
+        if (legacy === "company_domain")
+            return { enabled: true, statuses: [...COMPANY_REPLY_PAUSE_LEGACY_STATUSES] };
+        if (legacy === "lead")
+            return { enabled: false, statuses: [] };
+        throw new OxygenError("invalid_company_reply_pause", "--stop-on-reply-scope must be lead or company_domain (deprecated: use --company-reply-pause).", { details: { value: legacy }, exitCode: 2 });
+    }
+    if (!raw)
+        return undefined;
+    const normalized = raw.toLowerCase();
+    if (normalized === "off")
+        return { enabled: false, statuses: [] };
+    if (normalized === "default" || normalized === "on") {
+        return { enabled: true, statuses: [...COMPANY_REPLY_PAUSE_DEFAULT_STATUSES] };
+    }
+    const statuses = [...new Set(readCsvOption(normalized))];
+    const invalid = statuses.filter((status) => !COMPANY_REPLY_PAUSE_STATUS_KEY_PATTERN.test(status));
+    if (statuses.length === 0 || invalid.length > 0) {
+        throw new OxygenError("invalid_company_reply_pause", "--company-reply-pause takes off, default, or comma-separated Inbox status keys such as interested,not_now.", { details: { invalid }, exitCode: 2 });
+    }
+    return { enabled: true, statuses };
+}
+// Folds the sequence-level email send controls (--max-emails-per-mailbox-per-day,
+// --send-window-file) into a partial `settings` object. Returns undefined when
+// neither flag is set so the field is omitted from the request body entirely.
+// The server shallow-merges this fragment over the sequence's current settings
+// (apps/web .../sequences/[sequenceId]/route.ts), so a throttle-only PATCH
+// preserves other settings the server already holds, e.g. dispatch_mode/schedule.
+/**
+ * A sequence daily cap flag: a whole number (0 is a real cap) or `none`, which
+ * sends null to remove the cap, as clearing the web's Sends per day field does.
+ */
+function readDailyCapOption(value, flag) {
+    const trimmed = value?.trim();
+    if (trimmed === undefined || trimmed === "")
+        return undefined;
+    if (trimmed.toLowerCase() === "none")
+        return null;
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) {
+        throw new OxygenError("invalid_number", `${flag} takes a whole number (0 or more) or none.`, {
+            details: { flag, value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+function readSequenceSettings(options) {
+    const settings = {};
+    // 0 is a real cap, as on the web's Sending limits (0-50).
+    const maxPerMailbox = readNonNegativeInt(options.maxEmailsPerMailboxPerDay);
+    if (maxPerMailbox !== undefined) {
+        settings.max_emails_per_mailbox_per_day = maxPerMailbox;
+    }
+    const windowPath = readOption(options.sendWindowFile);
+    if (windowPath) {
+        settings.email_send_window = readJsonFileValue(resolve(windowPath), "--send-window-file");
+    }
+    const linkedinSchedule = readLinkedinScheduleOptions(options);
+    if (linkedinSchedule) {
+        settings.schedule = linkedinSchedule;
+    }
+    if (options.linkedinInviteSchedule !== undefined)
+        settings.linkedin_invite_schedule = parseJsonValue(options.linkedinInviteSchedule, "--linkedin-invite-schedule");
+    if (options.linkedinMessageSchedule !== undefined)
+        settings.linkedin_message_schedule = parseJsonValue(options.linkedinMessageSchedule, "--linkedin-message-schedule");
+    // Tri-state: `--no-whatsapp-cold-initiate` (update) turns the opt-in off.
+    if (options.whatsappColdInitiate !== undefined) {
+        settings.whatsapp_cold_initiate = options.whatsappColdInitiate;
+    }
+    const whatsappDuplicateScope = readOption(options.whatsappDuplicateScope);
+    if (whatsappDuplicateScope)
+        settings.whatsapp_duplicate_scope = whatsappDuplicateScope;
+    // "" is sent as "": back to auto-detect, as the web's Lead identifiers save it.
+    if (options.phoneColumnKey !== undefined)
+        settings.phone_column_key = options.phoneColumnKey.trim();
+    if (options.emailColumnKey !== undefined)
+        settings.email_column_key = options.emailColumnKey.trim();
+    // stop_on_bounce defaults ON server-side; commander's `--no-stop-on-bounce`
+    // sets this to false, so only send the key when the user explicitly opts OUT.
+    // Leaving it absent keeps the safe default and a settings PATCH clean.
+    if (options.stopOnBounce === false) {
+        settings.stop_on_bounce = false;
+    }
+    // exclude_contacted: sequence-level cross-campaign exclusion default. Tri-state
+    // (--exclude-contacted / --no-exclude-contacted); undefined leaves it unset so a
+    // settings PATCH stays clean and enroll keeps today's per-call-only behavior.
+    if (options.excludeContacted !== undefined) {
+        settings.exclude_contacted = options.excludeContacted;
+    }
+    // A visible footer mutates outbound copy, so it is opt-in and tri-state:
+    // absent leaves the stored value alone; either explicit flag persists the
+    // chosen boolean. Missing/false is interpreted as OFF by the dispatcher.
+    if (options.autoOptimize !== undefined)
+        settings.auto_optimize = options.autoOptimize;
+    if (options.bounceProtection !== undefined)
+        settings.bounce_protection = JSON.parse(options.bounceProtection);
+    if (options.includeUnsubscribeHeaders !== undefined)
+        settings.include_unsubscribe_headers = options.includeUnsubscribeHeaders;
+    if (options.includeUnsubscribeLink !== undefined) {
+        settings.include_unsubscribe_link = options.includeUnsubscribeLink;
+    }
+    const companyReplyPause = readCompanyReplyPauseOption(options.companyReplyPause, options.stopOnReplyScope);
+    if (companyReplyPause)
+        settings.company_reply_pause = companyReplyPause;
+    const maxEmailsPerDay = readDailyCapOption(options.maxEmailsPerDay, "--max-emails-per-day");
+    if (maxEmailsPerDay !== undefined)
+        settings.max_emails_per_day = maxEmailsPerDay;
+    const maxNewEnrollmentsPerDay = readDailyCapOption(options.maxNewEnrollmentsPerDay, "--max-new-enrollments-per-day");
+    if (maxNewEnrollmentsPerDay !== undefined)
+        settings.max_new_enrollments_per_day = maxNewEnrollmentsPerDay;
+    const prioritization = readOption(options.sequencePrioritization);
+    if (prioritization)
+        settings.sequence_prioritization = prioritization;
+    const espMatching = readOption(options.espMatching);
+    if (espMatching)
+        settings.esp_matching = espMatching;
+    // The file is the whole policy: settings merge by top-level key, so a partial
+    // document would silently drop the routes or exclusions it omits.
+    const espRoutingPath = readOption(options.espRoutingFile);
+    if (espRoutingPath) {
+        settings.esp_matching = readJsonFileValue(resolve(espRoutingPath), "--esp-routing-file");
+    }
+    const senderFailover = readOption(options.senderFailover);
+    if (senderFailover)
+        settings.sender_failover = senderFailover;
+    // email_min_gap_minutes accepts 0 ("no extra humanization gap"), which
+    // readPositiveInt rejects (it requires >= 1); treat a literal 0 as valid and
+    // defer any other value to readPositiveInt's positive-integer validation. The
+    // server enforces the 0-720 range (validateSequenceSettings).
+    const emailMinGapRaw = readOption(options.emailMinGapMinutes);
+    if (emailMinGapRaw !== null) {
+        const emailMinGap = Number(emailMinGapRaw) === 0 ? 0 : readPositiveInt(emailMinGapRaw);
+        if (emailMinGap !== undefined)
+            settings.email_min_gap_minutes = emailMinGap;
+    }
+    // opportunity_value is a non-negative dollar amount (may be fractional and may be
+    // 0), so it is parsed as a plain finite number rather than a positive integer;
+    // the server enforces the >= 0 rule (validateSequenceSettings) and reports a clear
+    // error for a negative value, so send any finite number through.
+    const opportunityValueRaw = readOption(options.opportunityValue);
+    if (opportunityValueRaw !== null) {
+        const opportunityValue = Number(opportunityValueRaw);
+        if (Number.isFinite(opportunityValue))
+            settings.opportunity_value = opportunityValue;
+    }
+    // Per-sequence sending-account allowlist (--mailboxes id1,id2). Split + trim +
+    // drop empties client-side (light); the server validates each is a UUID and caps
+    // the count. An all-empty list omits the key so a stray "--mailboxes ," is a no-op.
+    // `--mailboxes ""` sends [] (no allowlist: the whole pool rotates again).
+    if (options.mailboxes !== undefined)
+        settings.mailbox_ids = readCsvOption(options.mailboxes);
+    // Sender profiles (--sender-profiles id1,id2): the sequence sends from these
+    // unified identities. The server resolves them into senderAccountIds + mailbox_ids.
+    const senderProfileIds = readCsvOption(options.senderProfiles);
+    if (options.senderProfiles !== undefined)
+        settings.sender_profile_ids = senderProfileIds;
+    return Object.keys(settings).length > 0 ? settings : undefined;
+}
+export function registerSequencesFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("sequences")
+        .description("Multichannel outreach sequences: one enrollment per lead can span LinkedIn, email, WhatsApp, human call tasks, and connected-CRM tasks. LinkedIn steps dispatch natively within sender limits, with zero additional credits per action; connected-account monthly charges remain separate; email steps send natively or place/move/stop the lead in a bound Instantly campaign (BYOK); crm_task can exact-match/upsert/link CRM records and create a mapped external follow-up (HubSpot first), with replay-safe per-operation receipts. A reply always stops that lead, on every channel. To also pause the replier's colleagues, set `--company-reply-pause` on `create`/`update` (pick the reply categories); to pause or resume a company by hand or from a workflow (e.g. a meeting was booked), use `pause-company` / `resume-company` / `paused-companies`. A pause is resumable; a company do-not-contact entry (`suppressions`) is a permanent block.")
+        .addCommand(addContractFlags(new Command("list")
+        .description("List sequences with persisted launch status kept separate from current operational state. Fleet counts report marked-active versus operationally-live (active with nonterminal work), and rows explain flowing, paced, paused, blocked, degraded, drained, or empty work without SQL. An active sequence whose every lead has finished shows drained (completed); leads enrolled into it later are contacted on its next dispatch tick. --stats joins each row's LIFETIME funnel.")
+        .option("--status <status>", "Filter by status: draft, active, paused, or archived.")
+        .addOption(new Option("--operational-state <state>", "Filter by current work state; fleet counts remain unfiltered: empty, drained, never_started (enrolled leads, never launched), blocked, degraded, flowing, paced, or paused (work waiting on a paused sequence).").choices(["empty", "drained", "never_started", "blocked", "degraded", "flowing", "paced", "paused"]))
+        .addOption(new Option("--lifecycle <lifecycle>", "Filter by the lifecycle a person reads; fleet counts remain unfiltered: draft, active, completed (active, every lead finished), paused, or archived.").choices([...SEQUENCE_LIFECYCLES]))
+        .addOption(new Option("--channel <channel>", "Only sequences carrying this channel.").choices(["email", "linkedin", "whatsapp"]))
+        .option("--tag <tag>", "Only sequences carrying this workspace tag (see `oxygen tags list`).")
+        .option("--stats", "Attach lifetime stats per sequence (a stats pass per row — slower on large workspaces)."), SEQUENCE_LIST_PROJECTION_CONTRACT)
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleReadActionWithLens("sequences list", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            const operationalState = readOption(options.operationalState);
+            if (operationalState)
+                params.set("operational_state", operationalState);
+            const lifecycle = readOption(options.lifecycle);
+            if (lifecycle)
+                params.set("lifecycle", lifecycle);
+            const channel = readOption(options.channel);
+            if (channel)
+                params.set("channel", channel);
+            const tag = readOption(options.tag);
+            if (tag)
+                params.set("tag", tag);
+            if (options.stats)
+                params.set("include", "stats");
+            const projection = readContractFlags(options, SEQUENCE_LIST_PROJECTION_CONTRACT);
+            const omit = typeof projection.omit === "string" ? readOption(projection.omit) : undefined;
+            if (omit)
+                params.set("omit", omit);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/sequences${suffix ? `?${suffix}` : ""}`);
+        }, formatSequenceListHealth);
+    }))
+        .addCommand(new Command("send")
+        .description("Initiate one net-new LinkedIn message through a one-recipient, one-step hosted Sequence. First call without a sequence id: pass --recipient, --text/--text-file, and --sender to create the inert draft and preview (no message, no credits). After showing that preview, re-run with the returned sequence id plus --approved --max-credits N. Existing-thread replies stay in `oxygen inbox send`.")
+        .argument("[sequence]", "Sequence id returned by the preview call. Omit when creating the preview; required with --approved.")
+        .option("--recipient <url-or-id>", "LinkedIn personal-profile URL or provider member id. Preview call only.")
+        .option("--recipient-name <name>", "Optional display name stored on the enrollment. Preview call only.")
+        .option("--text <text>", "Message body. Preview call only; use either --text or --text-file.")
+        .option("--text-file <path>", "Read the message body from a file. Preview call only; use either --text-file or --text.")
+        .option("--sender <ref>", "Connected LinkedIn sender id, connection id, or Unipile account id. List choices with `oxygen senders list`.")
+        .option("--approved", "Approve the previewed Sequence for live dispatch. Requires the returned sequence id and --max-credits.")
+        .option("--max-credits <n>", "Positive credit ceiling for the live LinkedIn dispatch.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences send", options, () => {
+            const sequenceId = readOption(sequence);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (sequenceId) {
+                if (readOption(options.recipient) || readOption(options.recipientName) || readOption(options.text) || readOption(options.textFile) || readOption(options.sender)) {
+                    throw new OxygenError("conflicting_flags", "With a sequence id, pass only --approved and --max-credits; recipient, copy, and sender are fixed by the previewed draft.", { exitCode: 1 });
+                }
+                return requestOxygen("/api/cli/sequences/send", { method: "POST", body: { sequence: sequenceId, ...(options.approved ? { approved: true } : {}), ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}) } });
+            }
+            if (options.approved)
+                throw new OxygenError("sequence_preview_required", "Preview first without --approved; then pass the returned sequence id with --approved --max-credits N.", { exitCode: 1 });
+            const recipient = readOption(options.recipient);
+            const sender = readOption(options.sender);
+            const text = readPublishingPostText(options, true);
+            if (!recipient)
+                throw new OxygenError("invalid_request", "--recipient is required for the preview call.", { exitCode: 1 });
+            if (!sender)
+                throw new OxygenError("invalid_request", "--sender is required for the preview call; list choices with `oxygen senders list`.", { exitCode: 1 });
+            return requestOxygen("/api/cli/sequences/send", { method: "POST", body: { recipient, text, sender, ...(readOption(options.recipientName) ? { recipient_name: readOption(options.recipientName) } : {}) } });
+        });
+    }))
+        .addCommand(new Command("workflows")
+        .description("Compatibility-only maintenance for existing sequencer presets. Do not create new Teams notifications here: use `oxygen workflows` (web: Sequence → Launch → Connected workflows) with a sequence event trigger and Microsoft Teams Send Message.")
+        .addCommand(new Command("list")
+        .description("List the two legacy sequencer presets with armed state, editable config, and ordinary workflow deep-links.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences workflows list", options, () => requestOxygen("/api/cli/sequencer/reply-workflows"));
+    }))
+        .addCommand(new Command("configure")
+        .description("Preview or maintain an existing legacy preset. New Teams notifications must use an ordinary connected workflow; this command remains only for compatibility. Omit --live for a zero-write preview. Live arming requires --armed --approved and a positive per-delivery --max-credits cap.")
+        .argument("<template>", "crm-lead-stage-router or the legacy sequencer-positive-reply-teams preset (existing configurations only).")
+        .option("--config-file <path>", "JSON object containing the managed workflow configuration.")
+        .option("--armed", "Arm the workflow.")
+        .option("--disarmed", "Disarm the workflow.")
+        .option("--live", "Persist the configuration. Omit for a dry-run preview.")
+        .option("--approved", "Explicitly approve standing authority for this exact workflow revision.")
+        .option("--max-credits <n>", "Hard per-delivery credit ceiling (the legacy Teams preset requires at least 0.02).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (template, options) => {
+        await handleAsyncAction("sequences workflows configure", options, () => {
+            if (options.armed === options.disarmed) {
+                throw new Error("Pass exactly one of --armed or --disarmed.");
+            }
+            const configPath = readOption(options.configFile);
+            const config = configPath
+                ? readJsonFileValue(resolve(configPath), "--config-file")
+                : undefined;
+            if (config !== undefined && !isRecord(config)) {
+                throw new Error("--config-file must contain a JSON object.");
+            }
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            return requestOxygen("/api/cli/sequencer/reply-workflows", {
+                method: "POST",
+                body: {
+                    template_id: template,
+                    armed: options.armed === true,
+                    mode: options.live ? "live" : "dry_run",
+                    ...(config ? { config } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                },
+            });
+        });
+    })))
+        .addCommand(new Command("hubspot-sync")
+        .description("Project sequence activity, native email/LinkedIn timeline entries, and reply outcomes into the connected HubSpot portal. One workspace setting manages the event and classified-reply workflows across every sequence.")
+        .addCommand(new Command("show")
+        .description("Show the connected portal, live contact schema, activity/status configuration, component health, and enabled state.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences hubspot-sync show", options, () => requestOxygen("/api/cli/sequencer/hubspot-sync"));
+    }))
+        .addCommand(new Command("configure")
+        .description("Preview or save the workspace-wide HubSpot projection. Existing fields need no new grant; creating missing properties requires --approved and HubSpot property-creation access.")
+        .option("--config-file <path>", "Full or partial JSON configuration: mappings, timeline_events, LinkedIn identity property, lead-status property, sequence/reply status mappings, and opt-out status.")
+        .option("--mappings-file <path>", "JSON object mapping every sequencer event key to a HubSpot contact datetime-property internal name; use an empty string to disable an event.")
+        .option("--armed", "Enable future event delivery.")
+        .option("--disarmed", "Disable future event delivery.")
+        .option("--live", "Persist the configuration. Omit for a zero-write dry-run preview.")
+        .option("--approved", "Approve the exact live mapping and any recommended properties shown by the preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences hubspot-sync configure", options, () => {
+            if (options.armed === options.disarmed) {
+                throw new Error("Pass exactly one of --armed or --disarmed.");
+            }
+            const configPath = readOption(options.configFile);
+            const configValue = configPath
+                ? readJsonFileValue(resolve(configPath), "--config-file")
+                : undefined;
+            if (configValue !== undefined && !isRecord(configValue)) {
+                throw new Error("--config-file must contain a JSON object.");
+            }
+            const mappingsPath = readOption(options.mappingsFile);
+            const mappings = mappingsPath
+                ? readJsonFileValue(resolve(mappingsPath), "--mappings-file")
+                : undefined;
+            if (mappings !== undefined && !isRecord(mappings)) {
+                throw new Error("--mappings-file must contain a JSON object.");
+            }
+            const config = {
+                ...(configValue ?? {}),
+                ...(mappings
+                    ? {
+                        mappings: {
+                            ...(isRecord(configValue?.mappings)
+                                ? configValue.mappings
+                                : {}),
+                            ...mappings,
+                        },
+                    }
+                    : {}),
+            };
+            return requestOxygen("/api/cli/sequencer/hubspot-sync", {
+                method: "POST",
+                body: {
+                    armed: options.armed === true,
+                    mode: options.live ? "live" : "dry_run",
+                    ...(Object.keys(config).length > 0 ? { config } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    })))
+        .addCommand(new Command("hubspot-list-import")
+        .description("Discover saved HubSpot contact lists and configure one bounded DNC-first automatic import into an Oxygen Sequence. Draft and paused recipients stay pending until launch or resume.")
+        .addCommand(new Command("lists")
+        .description("List saved HubSpot contact/company segments and readable identity fields available for a Sequence import. These no-bill definition reads change no members, DNC entries, rows, workflows, or enrollments.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--query <text>", "Optional case-insensitive words to match in the HubSpot list name.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences hubspot-list-import lists", options, () => {
+            const params = new URLSearchParams({ sequence });
+            const query = readOption(options.query);
+            if (query)
+                params.set("query", query);
+            return requestOxygen(`/api/cli/sequencer/hubspot-list-import?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("configure")
+        .description("Preview or start a scheduled HubSpot-list import. Preview first; then pass its reviewed fingerprint with --live --approved. The complete DNC list is applied before leads are read or enrolled.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .requiredOption("--lead-list <id>", "Exact HubSpot ILS contact-list id whose current members should be imported.")
+        .requiredOption("--dnc-list <id>", "Different exact HubSpot ILS contact-list id synchronized additively into Oxygen DNC first.")
+        .option("--company-dnc-list <id>", "Optional HubSpot company-list id synchronized as all-channel company DNC.")
+        .option("--contact-linkedin-property <name>", "Optional contact LinkedIn profile property internal name.")
+        .option("--contact-company-domain-property <name>", "Optional explicit company-domain property on contacts, copied to lead rows.")
+        .option("--contact-company-linkedin-property <name>", "Optional explicit company LinkedIn URL property on contacts.")
+        .option("--contact-properties <list>", "Comma-separated extra HubSpot contact properties to hydrate (max 50).")
+        .option("--company-domain-property <name>", "Company-list domain property (default domain).", "domain")
+        .option("--company-linkedin-property <name>", "Optional company-list LinkedIn URL property.")
+        .option("--cron <expression>", "Standing cron cadence. Defaults to every 15 minutes.")
+        .option("--timezone <iana>", "IANA timezone. Defaults to UTC.")
+        .option("--max-records-per-list <n>", "Hard complete-snapshot cap per list (1-5000).", "5000")
+        .option("--max-credits <n>", "Hard credit ceiling per delivery.", "10")
+        .option("--include-contacted", "Allow leads already contacted by another active Sequence (default excludes them).")
+        .option("--reviewed-fingerprint <hash>", "Fingerprint returned by the exact dry-run preview; required for live activation.")
+        .option("--idempotency-key <key>", "Optional idempotency key for the immediate first durable run.")
+        .option("--live", "Create/bind the Table if needed, arm the Workflow, and enqueue the first cycle.")
+        .option("--approved", "Approve the reviewed recurring HubSpot reads, additive DNC writes, Table upserts, and Sequence enrollment.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences hubspot-list-import configure", options, () => {
+            const maxRecords = readPositiveInt(options.maxRecordsPerList);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (maxRecords === undefined || maxRecords > 5000) {
+                throw new Error("--max-records-per-list must be between 1 and 5000.");
+            }
+            if (maxCredits === undefined) {
+                throw new Error("--max-credits must be a positive number.");
+            }
+            const reviewedFingerprint = readOption(options.reviewedFingerprint);
+            if (options.live && !reviewedFingerprint) {
+                throw new Error("Live activation requires --reviewed-fingerprint from the exact dry-run preview.");
+            }
+            return requestOxygen("/api/cli/sequencer/hubspot-list-import", {
+                method: "POST",
+                body: {
+                    sequence,
+                    lead_list_id: options.leadList,
+                    dnc_list_id: options.dncList,
+                    ...(readOption(options.companyDncList) ? { company_dnc_list_id: readOption(options.companyDncList) } : {}),
+                    ...(readOption(options.contactLinkedinProperty) ? { contact_linkedin_property: readOption(options.contactLinkedinProperty) } : {}),
+                    ...(readOption(options.contactCompanyDomainProperty) ? { contact_company_domain_property: readOption(options.contactCompanyDomainProperty) } : {}),
+                    ...(readOption(options.contactCompanyLinkedinProperty) ? { contact_company_linkedin_property: readOption(options.contactCompanyLinkedinProperty) } : {}),
+                    ...(options.contactProperties !== undefined ? { contact_properties: readCsvOption(options.contactProperties) } : {}),
+                    ...(readOption(options.companyDomainProperty) ? { company_domain_property: readOption(options.companyDomainProperty) } : {}),
+                    ...(readOption(options.companyLinkedinProperty) ? { company_linkedin_property: readOption(options.companyLinkedinProperty) } : {}),
+                    mode: options.live ? "live" : "dry_run",
+                    max_records_per_list: maxRecords,
+                    max_credits: maxCredits,
+                    exclude_contacted: options.includeContacted !== true,
+                    ...(readOption(options.cron) ? { cron: readOption(options.cron) } : {}),
+                    ...(readOption(options.timezone) ? { timezone: readOption(options.timezone) } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(reviewedFingerprint ? { reviewed_fingerprint: reviewedFingerprint } : {}),
+                    ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
+                },
+            });
+        });
+    })))
+        .addCommand(addContractFlags(new Command("analytics")
+        .description("Show selected-window sequencer analytics with persisted status kept separate from operational state, fleet marked-active versus operationally-live counts, current open work, sent/terminal-failed/deferral totals, failure classes, and action-kind breakdowns. Also includes per-sequence funnels and native email attribution under analytics.emailAttribution: byMailbox, byDomain, and explicit unattributed facts. With --sequence, analytics.senderPerformance groups channel-conditional counts and rates by sending person; analytics.messagePerformance reports each copy-bearing deterministic step variant, target/actual distribution, contacted recipients, and type-specific accepted/reply/positive outcomes (absent for note-less connect-only campaigns). Message-level reply outcomes require preserved step/variant provenance, so older unattributed replies remain in campaign totals without being guessed into a message row. Provider-owned campaigns appear only after their telemetry is normalized into Oxygen's native Sequence ledgers. Also reports whether the reply → CRM automation is armed, with a link to the workflow. Omit --projection for all sections in one read; --projection value --path /analytics selects all analytics sections. value_json is escaped JSON text, paged losslessly with value_cursor.")
+        .option("--sender <id>", "Filter to one sender from `oxygen senders list` or `oxygen senders profiles list`, or a key from this output's senders list. Repeatable.", collectRepeatable, [])
+        .option("--json", "Print a JSON envelope."), SEQUENCE_ANALYTICS_READ_CONTRACT, {
+        range: { valueName: "<preset>", parse: readOption },
+        from: { valueName: "<date>", parse: readOption }, to: { valueName: "<date>", parse: readOption },
+        sequence: { valueName: "<sequence>", parse: readOption },
+        campaigns: { valueName: "<ids>", parse: readOption }, senders: { valueName: "<ids>", parse: readOption },
+    })
+        .action(async (options) => {
+        const fetchAnalytics = () => {
+            const query = readContractFlags(options, SEQUENCE_ANALYTICS_READ_CONTRACT, {
+                range: { parse: readOption }, from: { parse: readOption }, to: { parse: readOption },
+                sequence: { parse: readOption }, campaigns: { parse: readOption }, senders: { parse: readOption },
+            });
+            const senders = [...readCsvOption(typeof query.senders === "string" ? query.senders : undefined), ...(options.sender ?? []).flatMap(value => readCsvOption(value))];
+            if (senders.length > 0)
+                query.senders = senders.join(",");
+            else
+                delete query.senders;
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined && value !== null)
+                    params.set(key, String(value));
+            }
+            const qs = params.toString();
+            return requestOxygen(`/api/cli/sequences/analytics${qs ? `?${qs}` : ""}`);
+        };
+        const windowRequested = ["projection", "path", "valueCursor", "maxChars"].some(key => options[key] !== undefined);
+        if (windowRequested)
+            await handleAsyncAction("sequences analytics", options, fetchAnalytics);
+        else
+            await handleReadActionWithLens("sequences analytics", options, fetchAnalytics, formatSequenceAnalyticsHealth);
+    }))
+        .addCommand(new Command("create")
+        .description("Create a draft multichannel sequence from a steps JSON file. Supports LinkedIn, email, WhatsApp, human call_task, and connected-CRM crm_task journeys. Assign LinkedIn senders with --senders (optional at create — a draft can sit senderless, but enroll/start require at least one for LinkedIn journeys). Native email sends through connected Google/Microsoft mailboxes, including Microsoft SMTP transport; optional --email-* flags bind an Instantly campaign. Install/read the oxygen-sequencer skill for per-step senders (references/email.md, references/linkedin.md), the launch ladder and complete mapped CRM task examples (references/calls-and-crm-tasks.md).")
+        .addHelpText("after", "\nSenders: each new lead gets one of the --sender-profiles people, the one with the fewest of this sequence's leads (a lead already talking to one of your LinkedIn accounts keeps that account's person), and its LinkedIn and email steps come from that person (email from one of their inboxes). Per step, in the steps file: email_send.sender_profile_id sends that email from any inbox of one selected person (the normal inbox rotation spreads leads across that person's inboxes and each lead keeps its one; a lead already assigned to that person keeps its own inbox; with none usable the lead waits, never using a colleague's inbox), and email_send.sender_mailbox_id from one exact inbox (set one or neither); a LinkedIn step's sender_profile_id sends it from one selected person. Invite, message, inmail and withdraw_invite steps must share one sender_profile_id or none: that person then owns every lead's LinkedIn thread (LinkedIn allows one of your accounts per conversation). visit_profile, follow, like_post and comment_post may each name anyone selected. An email whose From changes, including the return to the lead's inbox, needs its own subject_template. To check who sends each step, run `sequences start <sequence>` without --approved; nothing changes.\n")
+        .requiredOption("--name <name>", "Human-readable sequence name.")
+        .requiredOption("--slug <slug>", "Unique slug for the sequence.")
+        .requiredOption("--steps-file <path>", "Path to a JSON file: { \"steps\": [...] }. LinkedIn steps (visit_profile | invite | wait_for_connection | message | inmail | follow | like_post | comment_post | withdraw_invite), email steps (email_send | email_enroll | email_move | email_stop), WhatsApp (whatsapp_message), human call tasks (call_task), connected-CRM tasks (crm_task; channel crm; exact identity record_mappings + explicit create/update policy + record_links + dynamic task property_mappings/associations), and control steps (wait | wait_for_signal | branch | stop), each with an `id`. Copy templates support {{column}} interpolation from the lead's row, {{column|fallback}} inline fallbacks, deterministic spintax — {{RANDOM|a|b|c}} or industry-standard bare {Hi|Hey|Hello}, nestable like {Would {Tuesday|Thursday} work|next week?} — and {% if column %}…{% endif %} conditionals; a bare {…} region is spintax only when it contains a top-level |, so literal braces (CSS/JSON) pass through. Every step's copy can also use {{sender_first_name}}, {{sender_last_name}} and {{sender_full_name}} (alias {{sender_name}}): the name of the person who sends that step (their sender profile, else the account or inbox display name), with no table column needed; email steps add {{sender_email}} (the from address). A row column of the same name WINS on collision, and a missing name renders empty. comment_post takes text_template and/or ai_prompt — a KG-grounded comment generated at send time (a paid AI call) that falls back to text_template if generation fails. A `branch` routes on signals (then/else) or the legacy connection_accepted/already_connected/open_profile sugar (then_id/else_id). A signal condition can also branch on the LEAD'S DATA: a data leaf { has_column: \"email\" } is true when that row_values column has a non-empty value (add present:false for \"missing\") — e.g. route leads that have an email down an email arm and the rest down a LinkedIn arm. MINIMAL EMAIL STEP SHAPE: { \"id\": \"s1\", \"channel\": \"email\", \"kind\": \"email_send\", \"subject_template\": \"...\", \"body_template\": \"...\" } — body_template is REQUIRED on email_send; subject_template is OPTIONAL and is the one control that decides threading: give a step its own subject and it goes out as a NEW email, omit it and the step continues the lead's previous email in the same thread, going out as \"Re: <the previous email's subject>\" (what the retired email_reply kind used to be — still accepted on input, rewritten into this shape, and reported under `warnings` in the response). The FIRST email step of a sequence must carry a subject, since it has no earlier thread to continue. MINIMAL WHATSAPP STEP SHAPE: { \"id\": \"s1\", \"channel\": \"whatsapp\", \"kind\": \"whatsapp_message\", \"template\": \"Hi {{first_name|there}} …\" } — template is REQUIRED, and a live WhatsApp start also needs the sequence's --whatsapp-cold-initiate opt-in. MINIMAL WAIT STEP SHAPE: { \"id\": \"w1\", \"kind\": \"wait\", \"days\": 3 } — days and/or hours, at least 1 hour in total. A/B tests use an explicit `variants` array of copy partials on the step (up to 25 alternates, a–z; spintax varies wording INSIDE one variant and is not A/B-tracked). For the complete replay-safe crm_task upsert mapping shape, read `oxygen skills get oxygen-sequencer --file references/calls-and-crm-tasks.md`.")
+        .option("--channels <list>", "Comma-separated channels: linkedin,email,whatsapp,call,crm. Defaults to the channels the journey touches. crm_task currently supports HubSpot.")
+        .option("--whatsapp-cold-initiate", "WhatsApp: allow cold-initiating new chats (no prior conversation). Required to start a WhatsApp sequence live — WhatsApp via Unipile is unofficial WhatsApp Web, so cold-initiating is an explicit ban-risk opt-in.")
+        .addOption(new Option("--whatsapp-duplicate-scope <scope>", "Prevent duplicate WhatsApp copy in this campaign (default) or all campaigns.").choices(["campaign", "workspace"]))
+        .option("--phone-column-key <key>", "WhatsApp: row_values key holding each lead's phone number (else falls back to phone/phone_number/mobile).")
+        .option("--senders <ids>", "Comma-separated LinkedIn or WhatsApp sender account ids (or connection / Unipile ids; `senders list` / `whatsapp accounts` list them). Optional at create; enroll and start require at least one when the journey has LinkedIn or WhatsApp steps (attach later with `sequences update --senders`).")
+        .option("--table <id>", "Source table id or slug whose rows supply {{column}} template values.")
+        .option("--from-table <id>", "Alias of --table: the source table id or slug this sequence draws its leads and {{column}} values from.")
+        .option("--enroll", "After creating the sequence, immediately enroll every row of the bound table (same as running `sequences enroll --from-table` next). Requires --table/--from-table. Enrolling spends no credits and sends nothing.")
+        .option("--url-column <key>", "Column key holding each lead's LinkedIn URL/provider id.")
+        .option("--email-provider <provider>", "Omit for native email through connected Google/Microsoft mailboxes, including Microsoft SMTP transport. Set 'instantly' to bind an Instantly campaign with --email-connection and --email-definition-file. To push rows into a campaign you already run in Smartlead, lemlist, HeyReach or Instantly, use `oxygen sequences push-external`.")
+        .option("--email-connection <id>", "Instantly connection id for the email track. Defaults to the org's active Instantly connection.")
+        .option("--email-definition-file <path>", "Path to a JSON file with the email content spec (subjects/bodies/delays/subsequences) compiled to an Instantly campaign on start.")
+        .option("--max-credits <n>", "Stored credit ceiling (0 or more); 0 is valid for a draft. Omit to leave the ceiling unset. Creating a draft sends nothing; live start has its own approval and recipient limits.")
+        .option("--max-live-sends <n>", "Total live-send and CRM-write ceiling across channels, including LinkedIn invites/messages (positive integer). Required for live email/WhatsApp/CRM-task tracks; optional for LinkedIn.")
+        .option("--max-emails-per-mailbox-per-day <n>", "Per-mailbox daily email cap (positive integer) applied across the sending pool; also sets each mailbox's send pace (send window ÷ cap, catching up when a slot is missed). Daily capacity = this cap × sendable mailboxes; `sequences stats` reports it under daily_budget.")
+        .option("--schedule-timezone <tz>", "One sending schedule for every channel, the same as Launch's Sending schedule: IANA zone, e.g. Europe/Berlin. Give it with --schedule-days, --schedule-hours-start and --schedule-hours-end; it sets the email window and the LinkedIn/WhatsApp window together. Without it, email sends weekdays 09:00-17:00 UTC. To give one channel different hours, or to send email in each recipient's own timezone, run `sequences update` after creating (--send-window-file, --linkedin-*).")
+        .option("--schedule-days <days>", "Sending schedule days: mon-fri, mon,wed,fri, or ISO numbers 1-7 (1 = Monday).")
+        .option("--schedule-hours-start <HH:MM>", "Sending schedule start, local to --schedule-timezone, e.g. 09:00.")
+        .option("--schedule-hours-end <HH:MM>", "Sending schedule end (exclusive), e.g. 17:00. An email step's own send_window (on the step in --steps-file) still overrides it for that step. LinkedIn sends also stay inside each LinkedIn account's working hours (default 07:00-22:00 in the account's timezone; set with `oxygen senders limits set`); WhatsApp accounts and email mailboxes have no hours of their own.")
+        .option("--max-emails-per-day <n>", "Sequence-wide daily live-send cap across all senders/mailboxes. Unset means no additional sequence-wide cap; mailbox caps still apply. Omit on update to keep the current setting.")
+        .option("--max-new-enrollments-per-day <n>", "Daily cap on NEW first-touch leads. Unset means no additional intake cap; sending limits still apply. Omit on update to keep the current setting.")
+        .option("--sequence-prioritization <mode>", "Under a tight daily budget, serve 'followups' or 'new_leads' first.")
+        .option("--esp-matching <mode>", "Native-email ESP matching: 'prefer' (DEFAULT) biases toward a mailbox on the recipient's own provider, falling back to any; 'off' rotates mailboxes freely; 'strict' requires a same-provider mailbox and defers the send when none exists.")
+        .option("--esp-routing-file <path>", "Path to a JSON file holding the WHOLE native-email routing policy: { mode?, routes? }. `routes` is keyed by the RECIPIENT's provider and its values are relative send shares per sending provider, so { \"google\": { \"microsoft\": 100 } } sends Google-hosted recipients from Microsoft inboxes. Replaces --esp-matching and the file is the complete policy, not a patch. To stop sending from a domain, leave its inboxes out with --mailboxes.")
+        .option("--sender-failover <mode>", "What happens when an enrollment's LinkedIn/WhatsApp sender goes unavailable: 'wait' (default) resumes when the sender recovers; 'rebind' moves UNTOUCHED enrollments (no thread, no pending invite, no lead binding) to the least-loaded healthy sender in the pool after ~5h of confirmed outage.")
+        .option("--email-min-gap-minutes <n>", "Minimum same-mailbox gap, default 12 minutes (integer 0-720; 0 disables the extra gap). Sends are spread across the window and may be farther apart. Daily caps and windows still apply.")
+        .option("--opportunity-value <usd>", "Estimated USD value of one positive-reply opportunity (>= 0). Analytics-only: sequence stats multiply it by the positive-reply count to report pipeline $ (stats.opportunities). Never gates a send or spends a credit.")
+        .option("--mailboxes <ids>", "Per-sequence sending-account allowlist for native email (Instantly's 'Accounts to use'): comma-separated mailbox ids. Native email sends rotate ONLY over these mailboxes instead of the whole pool. Omit for the whole pool. Note: a narrow allowlist plus --esp-matching strict can starve sends when no allowed same-provider mailbox exists (surfaced as blocked defer reasons in stats).")
+        .option("--sender-profiles <ids>", "Send from these sender profiles (unified LinkedIn/WhatsApp/inbox identities): comma-separated profile ids (`oxygen senders profiles list` lists them). The server resolves each into its senders + inboxes. Live start is blocked if a selected profile lacks an account for a channel the journey uses.")
+        .option("--no-stop-on-bounce", "Keep a lead's enrollment running after a hard bounce (default: stop it). The bounce is still recorded as an email_bounced signal either way.")
+        .option("--exclude-contacted", "Default every enroll into this sequence to cross-campaign exclusion — skip leads any OTHER active sequence is already contacting. A per-enroll `sequences enroll --exclude-contacted` / `--no-exclude-contacted` always overrides this default. Off by default.")
+        .option("--no-exclude-contacted", "Turn the sequence-level exclude-contacted default back OFF (enrollments then exclude cross-campaign only when a call opts in).")
+        .option("--company-reply-pause <off|default|statuses>", "Pause the replier's company in this campaign when a reply has one of these statuses. Oxygen detects the company from work-email domains or explicit company fields; with no company identity, only the replier stops. New sequences start with this setting off. 'default' = interested,neutral,not_now,not_interested; or comma-separated Inbox status keys (`inbox labels list`); 'off' disables it. Read the saved setting with `sequences get`.")
+        .option("--stop-on-reply-scope <scope>", "(deprecated: use --company-reply-pause) 'company_domain' = --company-reply-pause interested,neutral,not_now,not_interested,wrong_person; 'lead' = off.")
+        .option("--bounce-protection <json>", "Sequence bounce policy JSON (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 sequence, not the fleet. Rates are fractions; mailbox protection is separate.")
+        .option("--auto-optimize", "Enable the sequence-wide A/B auto-winner (default on).")
+        .option("--no-auto-optimize", "Disable the sequence-wide A/B auto-winner; manual variant decisions stay available.")
+        .option("--include-unsubscribe", "Add an unsubscribe option to emails, the same as Launch's switch: a visible recipient-bound link (plain text shows the URL, HTML a linked Unsubscribe label) plus one-click headers that mail apps show as an Unsubscribe button, both on first-touch cold emails; in-thread follow-ups carry neither. Zapbox sends (mailboxes imported from Zapmail, `transport: \"zapbox\"` in `mailboxes list --json`) carry the link only. Off by default. There is no separate opt-out text: write any reply-to-stop line into the email copy. `sequences update` can switch on the link or the headers alone.")
+        .option("--no-include-unsubscribe", "Turn off both the visible unsubscribe link and the one-click headers.")
+        .option("--tracking-opens", "Opt in to open tracking (default off). Requires a verified tracking domain and deployment tracking secret.")
+        .option("--no-tracking-opens", "Turn OFF the open pixel for this sequence's native email sends (a deliverability knob — a pixel is spam-filter surface).")
+        .option("--tracking-clicks", "Opt in to click tracking (default off). Requires a verified tracking domain and deployment tracking secret.")
+        .option("--no-tracking-clicks", "Turn OFF click-link rewriting for this sequence's native email sends (links go out untouched).")
+        .option("--tags <csv>", "Comma-separated workspace tags linking this sequence to tables, workflows, and knowledge.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences create", options, () => {
+            const stepsPath = readOption(options.stepsFile);
+            if (!stepsPath)
+                throw new Error("--steps-file is required.");
+            const definition = readJsonFileValue(resolve(stepsPath), "--steps-file");
+            const channels = readCsvOption(options.channels);
+            const senders = readCsvOption(options.senders);
+            const tags = readCsvOption(options.tags);
+            const email = readCampaignEmailBinding(options);
+            const maxCredits = readCreditCeilingOrZero(options.maxCredits);
+            const maxLiveSends = readPositiveInt(options.maxLiveSends);
+            const settings = readSequenceSettings(options);
+            // `--from-table` is the phrase customers already use for enroll,
+            // so it names the same thing here rather than being a second
+            // concept; `--table` stays for every existing script.
+            const sourceTable = readOption(options.fromTable) ?? readOption(options.table);
+            if (options.enroll && !sourceTable) {
+                throw new Error("--enroll needs a source table: pass --from-table <table> (or --table <table>).");
+            }
+            return requestOxygen("/api/cli/sequences", {
+                method: "POST",
+                body: {
+                    name: readOption(options.name),
+                    slug: readOption(options.slug),
+                    definition,
+                    ...(channels.length > 0 ? { channels } : {}),
+                    ...(senders.length > 0 ? { senders } : {}),
+                    ...(tags.length > 0 ? { tags } : {}),
+                    ...(sourceTable ? { source_table_id: sourceTable } : {}),
+                    ...(options.enroll ? { enroll_from_table: true } : {}),
+                    ...(readOption(options.urlColumn) ? { linkedin_url_column_key: readOption(options.urlColumn) } : {}),
+                    ...(email ? { email } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                    ...(maxLiveSends !== undefined ? { max_live_sends: maxLiveSends } : {}),
+                    ...(options.trackingOpens !== undefined ? { tracking_opens: options.trackingOpens } : {}),
+                    ...(options.trackingClicks !== undefined ? { tracking_clicks: options.trackingClicks } : {}),
+                    ...(settings ? { settings } : {}),
+                    ...readUnifiedSequenceBody(options),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("draft")
+        .description("Draft an email outreach sequence with AI, grounded in the workspace Knowledge Graph (voice, positioning, campaign learnings) — Instantly's AI sequence generator, with provenance. PAID (one AI call, typically ~15 credits [low tier]; an under-cap call errors BEFORE spending and prints the live estimate) — requires --max-credits. Prints the drafted steps + the KG pages that grounded them; nothing is saved until you re-run with --create (which needs --name and --slug). Even created, it lands as a DRAFT — enrolling leads and starting it stay approval-gated.")
+        .requiredOption("--goal <goal>", "Plain-language goal for the sequence (e.g. \"book demos with RevOps leaders at Series A SaaS\"). The trusted brief the copy is written to.")
+        .option("--audience <audience>", "Who the sequence targets (e.g. \"RevOps leaders at 20-100 person B2B SaaS\"). Sharpens the Knowledge Graph retrieval.")
+        .option("--table <id>", "Source table id whose column keys become the {{column|fallback}} personalization tokens the copy may use.")
+        .option("--steps <n>", "How many emails in the journey (1-7). Defaults to 4.")
+        .option("--variants <n>", "Copy variants per email for A/B testing (1-3). Defaults to 1.")
+        .requiredOption("--max-credits <n>", "Credit cap for the AI call (required — this is a paid action).")
+        .option("--create", "Save the draft as a DRAFT sequence (requires --name and --slug). Without this, the draft is only previewed.")
+        .option("--name <name>", "Human-readable sequence name (required with --create).")
+        .option("--slug <slug>", "Unique slug for the sequence (required with --create).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        try {
+            const data = await requestOxygen("/api/cli/sequences/draft", {
+                method: "POST",
+                body: buildSequenceDraftBody(options),
+            });
+            emitSuccess("sequences draft", data, options);
+            if (!options.json)
+                writeSequenceDraftPreview(data);
+            writeCreditsReceipt(data);
+        }
+        catch (error) {
+            emitCliFailure("sequences draft", error);
+        }
+    }))
+        .addCommand(new Command("update")
+        .description("Update a sequence. Journey structure/channels/email binding are draft-only so revised scope receives a fresh launch approval; a started sequence may only re-time waits it already has (clear a delay by zeroing it, never by deleting the step — enrollments track position by index); sender pools can change while draft or paused; launch caps change through `sequences start` after first start. Name, throttles, the sending schedule, tags, the unsubscribe option (off by default), and open/click tracking toggles remain editable as allowed by the server. Pass only the fields you want to change.")
+        .addHelpText("after", "\nSenders: email_send.sender_profile_id sends one email from any inbox of a selected person (a lead already assigned to that person keeps its own inbox), and email_send.sender_mailbox_id from one exact inbox of a selected sender; a LinkedIn step's sender_profile_id sends it from a selected person (invite, message, inmail and withdraw_invite share one or none). Omit both to use the lead's assigned person. An email whose From changes needs its own subject_template. `sequences start <sequence>` without --approved shows who sends each step; nothing changes.\n")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--name <name>", "New human-readable sequence name.")
+        .option("--steps-file <path>", "Path to a JSON file: { \"steps\": [...] } replacing the journey. Once started, only wait timing may change: same steps, same order (zero a delay, never delete its step). Copy supports {{column}} interpolation; every step also takes {{sender_first_name}} / {{sender_last_name}} / {{sender_full_name}} for the person who sends it, and email adds {{sender_email}} (a same-named row column wins). A `branch` can also route on the lead's data with a data leaf { has_column: \"email\" } (true when that row_values column is non-empty; present:false for \"missing\").")
+        .option("--channels <list>", "Draft only: comma-separated channels: linkedin,email,whatsapp,call,crm.")
+        .option("--whatsapp-cold-initiate", "WhatsApp: allow cold-initiating new chats (no prior conversation). Required to start a WhatsApp sequence live (draft-editable).")
+        .option("--no-whatsapp-cold-initiate", "WhatsApp: stop allowing cold chats; a live WhatsApp start then refuses.")
+        .addOption(new Option("--whatsapp-duplicate-scope <scope>", "Prevent duplicate WhatsApp copy in this campaign (default) or all campaigns.").choices(["campaign", "workspace"]))
+        .option("--phone-column-key <key>", "WhatsApp: row_values key holding each lead's phone number (else falls back to phone/phone_number/mobile). \"\" clears it back to auto-detect.")
+        .option("--email-column-key <key>", "Native email: row_values key holding each lead's email (else falls back to email/email_address/work_email). Maps a non-English header (e.g. E-Mail). \"\" clears it back to auto-detect.")
+        .option("--linkedin-url-column-key <key>", "LinkedIn: row_values key holding each lead's profile URL (else falls back to linkedin_url/linkedinUrl/linkedin/profile_url). \"\" clears it back to auto-detect.")
+        .option("--senders <ids>", "LinkedIn or WhatsApp accounts attached directly, besides the --sender-profiles people's own accounts: comma-separated sender account ids (or connection / Unipile ids; `senders list` / `whatsapp accounts` list them). Replaces the directly attached set; \"\" removes them all and keeps the selected senders. `sequences get` lists both under sender_pool. Draft/paused only.")
+        .option("--source-table <idOrSlug>", "Bind the table this sequence enrolls leads from (id or slug). Only lands while the sequence has no source table yet (first-writer-wins); its rows become enrollable leads. Draft/paused only.")
+        .option("--email-provider <provider>", "Optional linked-campaign provider: 'instantly'. Omit to preserve the existing binding; --clear-email removes it on a draft. Native email needs no provider binding and sends through connected Google/Microsoft mailboxes, including Microsoft SMTP transport.")
+        .option("--email-connection <id>", "Instantly connection id for the email track.")
+        .option("--email-definition-file <path>", "Path to a JSON file with the email content spec (subjects/bodies/delays/subsequences).")
+        .option("--clear-email", "Remove the email binding from the sequence (draft only).")
+        .option("--max-credits <n>", "Stored draft credit ceiling (0 or more); 0 is valid. Changing a started sequence's cap requires its normal live-start approval.")
+        .option("--max-live-sends <n>", "Draft-time total live-send and CRM-write ceiling across channels, including LinkedIn invites/messages (positive integer). After first start, change it through `sequences start`.")
+        .option("--max-emails-per-mailbox-per-day <n>", "Per-mailbox daily email cap (0 or more) applied across the sending pool; also sets each mailbox's send pace (send window ÷ cap, catching up when a slot is missed). Daily capacity = this cap × sendable mailboxes; `sequences stats` reports it under daily_budget.")
+        .option("--schedule-timezone <tz>", "One sending schedule for every channel, the same as Launch's Sending schedule: IANA zone, e.g. Europe/Berlin. Give it with --schedule-days, --schedule-hours-start and --schedule-hours-end; it sets the email window and the LinkedIn/WhatsApp window together. Use it instead of --send-window-file and the --linkedin-* flags. Email set to send in each recipient's own timezone keeps doing so, with this zone for leads that have none.")
+        .option("--schedule-days <days>", "Sending schedule days: mon-fri, mon,wed,fri, or ISO numbers 1-7 (1 = Monday).")
+        .option("--schedule-hours-start <HH:MM>", "Sending schedule start, local to --schedule-timezone, e.g. 09:00.")
+        .option("--schedule-hours-end <HH:MM>", "Sending schedule end (exclusive), e.g. 17:00. An email step's own send_window (on the step in --steps-file) still overrides it for that step. LinkedIn sends also stay inside each LinkedIn account's working hours (default 07:00-22:00 in the account's timezone; set with `oxygen senders limits set`); WhatsApp accounts and email mailboxes have no hours of their own.")
+        .option("--send-window-file <path>", "Email-only window JSON: { timezone, days?, start, end, timezone_mode?, recipient_timezone_column? }; days are ISO 1-7. New sequences default to weekdays 09:00-17:00 UTC. Use it to keep email on different hours from LinkedIn/WhatsApp, or to send in each recipient's own timezone (timezone_mode recipient, which --schedule-* then keeps); for one schedule across channels, use --schedule-* instead.")
+        .option("--linkedin-invite-schedule <json>", 'LinkedIn invites only: { "timezone": "Europe/Berlin", "days": [1,2,3,4,5,6,7], "start": "09:00", "end": "17:00" }. Replaces the general Sequence schedule for invites; account working hours still apply. null restores the general schedule.')
+        .option("--linkedin-message-schedule <json>", 'LinkedIn messages and InMail only: { "timezone": "Europe/Berlin", "days": [1,2,3,4,5], "start": "10:00", "end": "16:00" }. Replaces the general Sequence schedule for messages; account working hours still apply. null restores the general schedule.')
+        .option("--linkedin-timezone <tz>", "LinkedIn/WhatsApp-only sending schedule: IANA zone, e.g. Europe/Zurich. Set with --linkedin-days, --linkedin-hours-start and --linkedin-hours-end; for LinkedIn the window narrows each account's working hours, for WhatsApp it is the only hours limit. For one schedule across channels, use --schedule-* instead.")
+        .option("--linkedin-days <days>", "LinkedIn sending schedule days: mon-fri, mon,wed,fri, or ISO numbers 1-7 (1 = Monday).")
+        .option("--linkedin-hours-start <HH:MM>", "LinkedIn sending schedule start, local to --linkedin-timezone, e.g. 06:45.")
+        .option("--linkedin-hours-end <HH:MM>", "LinkedIn sending schedule end (exclusive), e.g. 18:30. Must be after the start. For LinkedIn the window only narrows each account's working hours (default 07:00-22:00, see senders limits get), never widens them.")
+        .option("--max-emails-per-day <n|none>", "Sequence-wide daily cap on live sends across every channel (email, LinkedIn, WhatsApp) and sender; 0 sends nothing. `none` removes the cap; mailbox and account caps still apply. Omit to keep the current setting.")
+        .option("--max-new-enrollments-per-day <n|none>", "Daily cap on NEW first-touch leads (0 or more). `none` removes it; sending limits still apply. Omit to keep the current setting.")
+        .option("--sequence-prioritization <mode>", "Under a tight daily budget, serve 'followups' or 'new_leads' first.")
+        .option("--esp-matching <mode>", "Native-email ESP matching: 'prefer' (DEFAULT) biases toward a mailbox on the recipient's own provider, falling back to any; 'off' rotates mailboxes freely; 'strict' requires a same-provider mailbox and defers the send when none exists. Changes only the mode: routes saved by --esp-routing-file or the web stay.")
+        .option("--esp-routing-file <path>", "Path to a JSON file holding the WHOLE native-email routing policy: { mode?, routes? }. `routes` is keyed by the RECIPIENT's provider and its values are relative send shares per sending provider, so { \"google\": { \"microsoft\": 100 } } sends Google-hosted recipients from Microsoft inboxes. Replaces --esp-matching and the file is the complete policy, not a patch. To stop sending from a domain, leave its inboxes out with --mailboxes.")
+        .option("--sender-failover <mode>", "What happens when an enrollment's LinkedIn/WhatsApp sender goes unavailable: 'wait' (default) resumes when the sender recovers; 'rebind' moves UNTOUCHED enrollments (no thread, no pending invite, no lead binding) to the least-loaded healthy sender in the pool after ~5h of confirmed outage.")
+        .option("--email-min-gap-minutes <n>", "Minimum same-mailbox gap, default 12 minutes (integer 0-720; 0 disables the extra gap). Sends are spread across the window and may be farther apart. Daily caps and windows still apply.")
+        .option("--opportunity-value <usd>", "Estimated USD value of one positive-reply opportunity (>= 0). Analytics-only: sequence stats multiply it by the positive-reply count to report pipeline $ (stats.opportunities). Never gates a send or spends a credit.")
+        .option("--mailboxes <ids>", "Per-sequence sending-account allowlist for native email (Instantly's 'Accounts to use'): comma-separated mailbox ids. Native email sends rotate ONLY over these mailboxes instead of the whole pool. Note: a narrow allowlist plus --esp-matching strict can starve sends when no allowed same-provider mailbox exists (surfaced as blocked defer reasons in stats). \"\" removes the allowlist.")
+        .option("--sender-profiles <ids>", "Send from these sender profiles (unified LinkedIn/WhatsApp/inbox identities): comma-separated profile ids (`oxygen senders profiles list` lists them). The server resolves each into its senders + inboxes. Live start is blocked if a selected profile lacks an account for a channel the journey uses.")
+        .option("--no-stop-on-bounce", "Keep a lead's enrollment running after a hard bounce (default: stop it). The bounce is still recorded as an email_bounced signal either way.")
+        .option("--exclude-contacted", "Default every enroll into this sequence to cross-campaign exclusion — skip leads any OTHER active sequence is already contacting. A per-enroll `sequences enroll --exclude-contacted` / `--no-exclude-contacted` always overrides this default. Off by default.")
+        .option("--no-exclude-contacted", "Turn the sequence-level exclude-contacted default back OFF (enrollments then exclude cross-campaign only when a call opts in).")
+        .option("--company-reply-pause <off|default|statuses>", "Pause the replier's company in this campaign when a reply has one of these statuses. Oxygen detects the company from work-email domains or explicit company fields; with no company identity, only the replier stops. New sequences start with this setting off. 'default' = interested,neutral,not_now,not_interested; or comma-separated Inbox status keys (`inbox labels list`); 'off' disables it. Read the saved setting with `sequences get`.")
+        .option("--stop-on-reply-scope <scope>", "(deprecated: use --company-reply-pause) 'company_domain' = --company-reply-pause interested,neutral,not_now,not_interested,wrong_person; 'lead' = off.")
+        .option("--bounce-protection <json>", "Sequence bounce policy JSON (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 sequence, not the fleet. Rates are fractions; mailbox protection is separate.")
+        .option("--auto-optimize", "Turn the A/B auto-winner on (the default): every step with variants is judged on replies, pausing losers once each variant has 100 sends and 5 replies, unless the step sets its own auto_optimize.")
+        .option("--no-auto-optimize", "Disable the sequence-wide A/B auto-winner; manual variant decisions stay available.")
+        .option("--include-unsubscribe", "Add an unsubscribe option to emails, the same as Launch's switch: a visible recipient-bound link (plain text shows the URL, HTML a linked Unsubscribe label) plus one-click headers that mail apps show as an Unsubscribe button, both on first-touch cold emails; in-thread follow-ups carry neither. Zapbox sends (mailboxes imported from Zapmail, `transport: \"zapbox\"` in `mailboxes list --json`) carry the link only. Off by default. There is no separate opt-out text: write any reply-to-stop line into the email copy.")
+        .option("--no-include-unsubscribe", "Turn off both the visible unsubscribe link and the one-click headers.")
+        .option("--include-unsubscribe-headers", "Only the one-click unsubscribe headers (default off); --include-unsubscribe turns on the headers and the visible link together.")
+        .option("--no-include-unsubscribe-headers", "Omit one-click headers.")
+        .option("--include-unsubscribe-link", "Only the visible recipient-bound unsubscribe footer on first-touch cold emails (default off; --include-unsubscribe adds the one-click headers too). Plain-text messages show the URL, while HTML messages show a linked Unsubscribe label.")
+        .option("--no-include-unsubscribe-link", "Turn the visible unsubscribe footer OFF. Future first-touch emails send the authored body unchanged; existing suppression records remain enforced.")
+        .option("--tracking-opens", "Opt in to open tracking (default off). Requires a verified tracking domain and deployment tracking secret.")
+        .option("--no-tracking-opens", "Turn OFF the open pixel for this sequence's native email sends (a deliverability knob — a pixel is spam-filter surface).")
+        .option("--tracking-clicks", "Opt in to click tracking (default off). Requires a verified tracking domain and deployment tracking secret.")
+        .option("--no-tracking-clicks", "Turn OFF click-link rewriting for this sequence's native email sends (links go out untouched).")
+        .option("--tags <csv>", "Replace the sequence's workspace tags (comma-separated; \"\" clears them). The ONE field an ARCHIVED sequence still accepts — tag finished campaigns to link their learnings across the workspace.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences update", options, () => {
+            const body = {};
+            const name = readOption(options.name);
+            if (name)
+                body.name = name;
+            // Whole-set replace; `--tags ""` clears. Distinct from the
+            // omitted flag (undefined), which leaves tags untouched.
+            if (options.tags !== undefined)
+                body.tags = readCsvOption(options.tags);
+            const stepsPath = readOption(options.stepsFile);
+            if (stepsPath) {
+                body.definition = readJsonFileValue(resolve(stepsPath), "--steps-file");
+            }
+            const channels = readCsvOption(options.channels);
+            if (channels.length > 0)
+                body.channels = channels;
+            // The directly attached accounts, replaced as a set; `--senders ""`
+            // sends [] to remove them (the selected senders keep theirs).
+            if (options.senders !== undefined)
+                body.senders = readCsvOption(options.senders);
+            const sourceTable = readOption(options.sourceTable);
+            if (sourceTable)
+                body.source_table_id = sourceTable;
+            // Explicit "" clears the LinkedIn mapping back to auto-detect, so
+            // send whenever the flag was passed (not only when truthy).
+            if (options.linkedinUrlColumnKey !== undefined) {
+                body.linkedin_url_column_key = readOption(options.linkedinUrlColumnKey) ?? "";
+            }
+            const maxCredits = readCreditCeilingOrZero(options.maxCredits);
+            if (maxCredits !== undefined)
+                body.max_credits = maxCredits;
+            const maxLiveSends = readPositiveInt(options.maxLiveSends);
+            if (maxLiveSends !== undefined)
+                body.max_live_sends = maxLiveSends;
+            const settings = readSequenceSettings(options);
+            if (settings)
+                body.settings = settings;
+            Object.assign(body, readUnifiedSequenceBody(options));
+            // Tri-state tracking toggles: only send the key when a flag was
+            // explicitly passed, so an unrelated update never flips tracking.
+            if (options.trackingOpens !== undefined)
+                body.tracking_opens = options.trackingOpens;
+            if (options.trackingClicks !== undefined)
+                body.tracking_clicks = options.trackingClicks;
+            if (options.clearEmail) {
+                body.email = null;
+            }
+            else {
+                const email = readCampaignEmailBinding(options);
+                if (email)
+                    body.email = email;
+            }
+            if (Object.keys(body).length === 0) {
+                throw new Error("Provide at least one field to update (--name, --steps-file, --source-table, --channels, --senders, --tags, --email-*, --clear-email, --max-credits, --max-live-sends, --max-emails-per-mailbox-per-day, --schedule-* sending schedule, --send-window-file, --linkedin-* schedule, --company-reply-pause, --[no-]include-unsubscribe, --[no-]include-unsubscribe-link, --no-stop-on-bounce, --[no-]exclude-contacted, or --[no-]tracking-opens / --[no-]tracking-clicks).");
+            }
+            return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}`, {
+                method: "PATCH",
+                body,
+            });
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Get a sequence's definition, senders, status, and credit usage. --readiness adds the launch check — whether it CAN go live, why not, and the mailbox pool it would send from — without touching it; `sequences preview <sequence>` (a read; 0 credits) shows who sends each step (sender_journey).")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--readiness", "Add launch_readiness: blockers (e.g. a missing send cap), warnings, and the resolved sending mailboxes. Read-only — sends nothing, changes nothing, spends nothing. Skips the LinkedIn rendered-copy scan, which stays in `sequences start` without --approved.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences get", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}${options.readiness ? "?include=readiness" : ""}`));
+    }))
+        .addCommand(new Command("enroll")
+        .description("Enroll leads into a sequence. Enrolling spends no credits. An active sequence contacts the new leads on its next dispatch tick; a draft or paused one holds them until `sequences start`. --from-table enrolls every not-yet-enrolled row of the sequence's bound source table (up to 500 per run; the response's from_table.has_more says whether to run again) — for a LinkedIn sequence the profile is read from the bound table's URL column, where a full /in/ URL and a bare public handle carrying a hyphen or digit (ada-lovelace) both work, so no pre-resolved provider ids are needed; each handle Oxygen canonicalized is echoed in linkedin_handles_canonicalized (value + url) to check before start, and every row that still cannot be resolved is named in unresolved_linkedin_lead_details (row, value, reason) rather than only counted in unresolved_linkedin_leads. In a LinkedIn + email sequence a row with no usable profile but a recipient email is still enrolled for the email steps (its LinkedIn steps are skipped as no_linkedin_profile, a connection wait passes at once and a connection branch takes its not-connected path) and is listed in linkedin_unavailable_lead_details instead; unresolved_linkedin_leads names only rows that were not enrolled. --leads-file enrolls an explicit JSON list { leads: [...] }: for an email/WhatsApp sequence a lead identified only by an email (row_values.email) or phone (row_values.phone) is auto-filed as a row in the sequence's leads table (auto-creating and binding one if there is none), deduped by email/phone, so no table has to exist first (the table is returned as leads_table with a web_url); a LinkedIn + email sequence auto-files an email-only lead the same way; a LinkedIn lead needs a lead_provider_id, a lead_profile_url (a /in/ URL or a bare public handle with a hyphen or digit), or a table_row_id whose row carries one of those. A CRM-only lead needs a stable table_row_id or lead_provider_id in addition to mapped row_values; a HubSpot contact id used in crm_task associations identifies the destination record, not the Oxygen enrollment. When the sequence is bound to a source table, a lead's table_row_id auto-snapshots that row's columns (incl. AI/tool outputs) into row_values for {{column}} copy — explicit row_values win. Idempotent per table row (and per email/phone for auto-filed leads). WhatsApp-only campaigns also enroll each normalized number once across all source rows and enrollment statuses; mixed campaigns keep other channels and skip duplicate WhatsApp actions. Duplicate protection defaults to this campaign; --whatsapp-duplicate-scope on create/update can additionally block identical copy across all campaigns. The org do-not-contact list is always enforced; --exclude-contacted and --suppress-list add further opt-in skips (reported under skipped_by_reason). Leads already owned by a sender account (from an earlier real send) are routed back to that same account; a lead owned by a sender NOT on this sequence is skipped (bound_to_other_sender) unless --ignore-sender-bindings. This enrolls into an OXYGEN Sequence; to put the same rows into a campaign you already run in Smartlead, Instantly, lemlist or HeyReach, use `sequences push-external`. esp.pool_scope identifies the active workspace inventory used for routing and strict_deferred_leads estimates; these estimates omit sequence sender restrictions, readiness and daily limits. A zero estimate does not guarantee readiness. Review sequences preview before launch.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--leads-file <path>", "Path to a JSON file: { \"leads\": [{ row_values: { email }, lead_name }] } for cold email; { lead_provider_id, lead_name, table_row_id, row_values } for LinkedIn/existing rows; CRM-only leads require table_row_id or a stable lead_provider_id alongside mapped row_values. A CRM association object id is not the enrollment identity. Exactly one of --leads-file or --from-table.")
+        .option("--from-table", "Enroll every not-yet-enrolled row of the sequence's bound source table (up to 500 per run; re-run to continue). Exactly one of --leads-file or --from-table.")
+        .option("--exclude-contacted", "Also skip leads any OTHER active sequence is already contacting (cross-campaign exclusion), for THIS enroll. Off by default; forces exclusion on even if the sequence's exclude_contacted default is off.")
+        .option("--no-exclude-contacted", "Force-INCLUDE cross-campaign leads for this enroll even when the sequence's exclude_contacted default is on (per-call override).")
+        .option("--suppress-list <ids>", "Per-call do-not-enroll lead provider ids dropped for this enroll only: a comma-separated list, or @<path> to a file of ids (comma/whitespace separated).")
+        .option("--ignore-sender-bindings", "Enroll leads even when they are already owned by a sender account outside this sequence's pool (overrides the one-person-one-sender guarantee). Off by default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences enroll", options, () => {
+            const leadsPath = readOption(options.leadsFile);
+            if (options.fromTable && leadsPath) {
+                throw new Error("Provide exactly one of --leads-file or --from-table.");
+            }
+            if (!options.fromTable && !leadsPath) {
+                throw new Error("Provide exactly one of --leads-file or --from-table.");
+            }
+            const suppressList = parseSuppressListOption(options.suppressList);
+            const sharedFlags = {
+                // Tri-state: --exclude-contacted (true) / --no-exclude-contacted (false)
+                // / absent (undefined → the route falls back to the sequence's default).
+                ...(options.excludeContacted === undefined ? {} : { exclude_contacted: options.excludeContacted }),
+                ...(suppressList.length > 0 ? { suppress_list: suppressList } : {}),
+                ...(options.ignoreSenderBindings ? { ignore_sender_bindings: true } : {}),
+            };
+            if (options.fromTable) {
+                return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/enroll`, {
+                    method: "POST",
+                    body: { from_table: true, ...sharedFlags },
+                });
+            }
+            const parsed = readJsonFileValue(resolve(leadsPath), "--leads-file");
+            return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/enroll`, {
+                method: "POST",
+                body: {
+                    leads: parsed.leads ?? [],
+                    ...sharedFlags,
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("push-external")
+        .description("Inspect a possible push from an Oxygen table into an existing Smartlead, Instantly, lemlist, or HeyReach campaign. The preview shows field mapping, sample leads, row counts, and whether the live push is available. An own-key campaign lookup carries Oxygen's quoted per-call platform fee after repricing, so an unapproved preview does not call the provider. When live_executable is false, use the provider's own importer or `oxygen sequences create --from-table`.")
+        .requiredOption("--provider <provider>", "External sequencer: smartlead, instantly, lemlist, or heyreach.")
+        .requiredOption("--campaign <name-or-id>", "The campaign that already exists in that tool. A name is resolved against your connected account (exact id, then exact name, then a unique partial match).")
+        .requiredOption("--from-table <table>", "Table id or slug whose rows are pushed.")
+        .option("--rows <row_ids>", "Comma-separated row ids to push. Defaults to the whole table.")
+        .option("--excluded-rows <row_ids>", "Comma-separated row ids omitted from the whole-table/filter selection; cannot combine with --rows.")
+        .option("--filter-json <json>", "Filter object or array selecting the rows, e.g. '{\"column\":\"email\",\"op\":\"is_not_null\"}'.")
+        .option("--mode <mode>", "dry_run (default) or live.")
+        .option("--approved", "Required for --mode live: confirms the external write after inspecting the dry run.")
+        .option("--field-mapping-json <json>", "Override the detected column mapping, e.g. '{\"email\":\"work_email\",\"first_name\":\"fname\"}'. Keys: email, first_name, last_name, company, website, linkedin_url, phone, job_title.")
+        .option("--sender-account <id>", "HeyReach only: the LinkedIn sender account id the leads are added against (list them with `oxygen tools run heyreach.linkedin_accounts_get_all --input-json '{}' --credential-mode user_api_key`).")
+        .option("--connection-id <id>", "Specific integration connection id. Defaults to the workspace's active connection for that provider.")
+        .option("--force", "Push rows again even when they already carry a successful push to this campaign.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleSequenceWriteAction("sequences push-external", options, () => {
+            const rows = readCsvOption(options.rows);
+            const filterJson = readOption(options.filterJson);
+            if (rows.length > 0 && filterJson) {
+                throw new Error("Pass either --rows or --filter-json, not both.");
+            }
+            const excludedRowIds = splitCommaList(options.excludedRows);
+            if (rows.length > 0 && excludedRowIds.length > 0)
+                throw new OxygenError("invalid_selection", "--excluded-rows cannot combine with --rows.", { exitCode: 2 });
+            const selection = rows.length > 0
+                ? { mode: "row_ids", row_ids: rows }
+                : filterJson || excludedRowIds.length > 0
+                    ? { mode: "all_matching", filters: filterJson ? JSON.parse(filterJson) : [], ...(excludedRowIds.length > 0 ? { excluded_row_ids: excludedRowIds } : {}) }
+                    : null;
+            const fieldMappingJson = readOption(options.fieldMappingJson);
+            return requestOxygen("/api/cli/sequences/push-external", {
+                method: "POST",
+                body: {
+                    provider: readOption(options.provider),
+                    campaign: readOption(options.campaign),
+                    table: readOption(options.fromTable),
+                    mode: readOption(options.mode) ?? "dry_run",
+                    ...(selection ? { selection } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(options.force ? { force: true } : {}),
+                    ...(readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {}),
+                    ...(readOption(options.senderAccount) ? { sender_account_id: readOption(options.senderAccount) } : {}),
+                    ...(fieldMappingJson ? { field_mapping: parseJsonObject(fieldMappingJson) } : {}),
+                },
+            });
+        }, formatSequencePushExternal);
+    }))
+        .addCommand(new Command("start")
+        .description("Preview or start a sequence. Without --approved this is the launch check and changes nothing: it returns launch_readiness (blockers and warnings), sender_journey (each step's From, candidate inboxes and assignment; no leads needed), rendered pending-lead LinkedIn/WhatsApp copy, character counts/limits, copy blockers, per-kind scope, sender/mailbox capacity, CRM readiness and safety caps. Email copy is not rendered; inspect its saved templates and unsubscribe settings with sequences get. Live start requires --approved; --max-credits is optional. Email/WhatsApp/CRM-task journeys additionally require --max-live-sends because their external actions cost 0 Oxygen credits. --dry-run starts the sequence in simulated mode (it leaves draft), with no send, provider campaign, CRM task or credits. Live start enables the standing reply → CRM automation only if it has never been configured. Planned counts include only leads each step's channel can reach; skipped_actions_by_reason and channel_coverage show the rest.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--approved", "Approve and activate live. Without this flag, returns a preview only, including copy_preview rendered samples and blockers.")
+        .option("--max-credits <n>", "Optional positive credit ceiling. Omit for the free launch preview. Live start uses the saved ceiling when omitted; an unset ceiling means unbounded credits, not recipient approval.")
+        .option("--max-live-sends <n>", "Total live-send and CRM-write ceiling across channels, including LinkedIn invites/messages (positive integer). Required for email, WhatsApp, or crm_task steps; optional for LinkedIn.")
+        .option("--dry-run", "Activate the sequence (status draft → active, startedAt set) in dry-run mode: every step advances with simulated actions — no sends, CRM writes, provider calls, or credits. This is NOT the preview: `sequences start` with no flags is the side-effect-free launch preview. A later live start (--approved) restarts those leads from the first step so they are contacted for real, except deleted source rows, a person another live campaign contacts under exclude_contacted, and older duplicates of a person.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences start", options, () => {
+            const maxCredits = readPositiveNumber(options.maxCredits, "Omit --max-credits for the free launch preview. To set a live credit ceiling, pass a positive value after reviewing the preview; recipient approval remains separate.");
+            const maxLiveSends = readPositiveInt(options.maxLiveSends);
+            return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/start`, {
+                method: "POST",
+                body: {
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                    ...(maxLiveSends !== undefined ? { max_live_sends: maxLiveSends } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("preview")
+        .description("The free launch check, as a read: the same preview sequences start returns without --approved. It returns launch_readiness (blockers and warnings), sender_journey (who sends each step and how an inbox is picked), copy_preview (rendered pending-lead LinkedIn/WhatsApp copy, character counts and scan), caps and estimated credits. Email copy is not rendered here: `sequences render` shows it, and every A/B variant, for leads of the bound table. Changes nothing and costs 0 credits; it never starts, resumes or dry-runs the sequence. Start with sequences start <sequence> --approved after review. Planned counts include only leads each step's channel can reach; skipped_actions_by_reason, channel_coverage and copy_preview.skipped_leads show the rest.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences preview", options, () => 
+        // The start route's preview branch: no approved, no dry_run, no ceilings.
+        requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/start`, { method: "POST", body: {} }));
+    }))
+        .addCommand(new Command("render")
+        .description("Render a sequence's copy as the web step editor's Preview does: every A/B variant of each step (email subject/body, LinkedIn note/message/InMail, WhatsApp, comments) for leads of the bound table, or sample values when it has none, signed by one eligible sender. Works on a draft with nobody enrolled. Read-only, 0 credits. Each lead gets one variant at send; this shows all of them side by side, and spintax shows one pick per lead.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--step <stepId>", "Render only this step.")
+        .option("--variant <id>", "Render only this variant (a is the base step, then b, c, ...).")
+        .option("--row <ids>", "Comma-separated table_row_ids of the bound table to render for (at most 10). Default: its first rows.")
+        .option("--sender <profileId>", "Sign as this sender profile (one the step may send from; the response lists eligible_senders). Default: the first eligible.")
+        .option("--limit <n>", "How many leads to render when --row is not given (1-10, default 3).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleSequenceRenderAction(sequence, options);
+    }))
+        .addCommand(new Command("signal")
+        .description("Record an external GTM signal (e.g. linkedin_connected, email_replied, company_raised_funds, job_change, web_visit, intent) onto a running sequence's enrollment(s) to drive signal-triggered branch/wait control. Target an enrollment by --enrollment or --lead (at least one is required); the server validates the signal name.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .requiredOption("--signal <name>", "Signal to record: linkedin_connected, linkedin_replied, whatsapp_replied, email_sent, email_opened, email_clicked, email_replied, email_bounced, company_hiring, company_raised_funds, job_change, new_hire, web_visit, intent.")
+        .option("--enrollment <id>", "Target enrollment id.")
+        .option("--lead <provider_id>", "Target enrollment by its lead provider id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleSequenceSignalAction(sequence, options);
+    }))
+        .addCommand(new Command("duplicate")
+        .description("Duplicate a sequence as a new DRAFT: copies the steps, settings, channels, source table, caps, tags and sender pool. Never copies enrollments, stats, A/B decisions or an Instantly email binding (re-bind with `sequences update` if the source used one; native email steps need no binding). The copy is inert until you `sequences start` it; this is how a started journey gets new steps.")
+        .argument("<sequence>", "Source sequence id or slug.")
+        .option("--name <name>", "Name for the copy. Defaults to '<source name> (copy)'.")
+        .option("--slug <slug>", "Slug for the copy. Defaults to the source slug + '-copy' (then -copy-2, ...).")
+        .option("--no-senders", "Do not copy the source's sender pool onto the copy.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleSequenceDuplicateAction(sequence, options);
+    }))
+        .addCommand(new Command("pause")
+        .description("Pause an active sequence (stops new dispatches; enrollments resume on un-pause).")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences pause", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/status`, {
+            method: "POST", body: { status: "paused" },
+        }));
+    }))
+        .addCommand(new Command("resume")
+        .description("Resume a paused sequence. A campaign paused at its live send cap pauses again at once: raise the cap and resume in one step with `sequences start <sequence> --max-live-sends <n>` (preview, then --approved).")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences resume", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/status`, {
+            method: "POST", body: { status: "active" },
+        }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Permanently delete a sequence and everything it owns (enrollments, actions, sender links, schedules). To stop dispatch without deleting, use `sequences pause`; active sequences must be paused first. Runs without --approved to preview the blast radius; pass --approved to purge. The current CLI does not create new archived sequences; legacy archived sequences remain readable and taggable.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--approved", "Confirm the previewed permanent deletion.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences delete", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}${options.approved ? "?approved=true" : ""}`, { method: "DELETE" }));
+    }))
+        .addCommand(new Command("enrollments")
+        .description("List per-lead enrollment state plus the latest action status, error, attempts, and retry time. --view compact answers 'when is each lead's next message due' per lead: lead, status, invite (accepted, pending, not_invited), accepted_at, current_step and next_due. next_due.summary says it in words, at_local/gives_up_at_local give the time in the campaign's timezone (its schedule's, else UTC) and at/gives_up_at in UTC. Reasons: step_scheduled (planned send time; held_by names what holds it, e.g. send_cap_reached), planner_due (when the planner next looks at the lead), not_started (begins when the campaign is started or resumed), nothing_scheduled (enrolled, no step will run), waiting_for_connection / waiting_for_signal (no send time; acceptance makes the next step due at once; gives_up_at is when the wait ends, and on_timeout says whether the lead then leaves or moves on), finished. A failed lead carries failure: the cause in words (cause_recorded false when OXYGEN never recorded one) and provider_contact (made; none = the step never started; nothing_sent; unknown). missing_source_row is true for a lead whose source-table row was deleted: still enrolled and contacted (remove with `contacts-remove --missing-source-rows`); null when the campaign has no live source table to check against, or the check failed. channels says which of the sequence's channels reach each lead: usable, and unavailable with a reason (no_linkedin_profile = enrolled for email only, its LinkedIn steps are skipped; no_recipient_email; no_phone_number).")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--status <status>", "Filter by enrollment status (pending, active, waiting_connection, waiting_signal, replied, completed, stopped, failed, excluded). pending = enrolled, not started (next_due not_started); waiting_connection = invite sent, not accepted yet. Status is the lead's progress, not its invite: use --invite accepted for the leads that accepted.")
+        .option("--step <n>", "Only leads currently on this step (0-based index, as in the sequence's steps).")
+        .option("--invite <state>", "Only leads in this LinkedIn invite state: accepted (invited and connected), pending (invited, not accepted yet) or not_invited (no invite: already connected before, suppressed or email-only).")
+        .option("--view <view>", "compact (default) or full (every enrollment field) (one short row per lead with next_due in words and local time).")
+        .option("--order <order>", "created (default) or due: soonest next_due first, then waiting leads by gives_up_at, then leads with nothing due.")
+        .option("--limit <n>", "Maximum enrollments to return (1-500).")
+        .option("--offset <n>", "Skip this many enrollments; pass next_offset from the previous page to continue.")
+        .option("--full", "Read every enrollment field (same as --view full).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences enrollments", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            const step = readOption(options.step);
+            if (step)
+                params.set("step", step);
+            const invite = readOption(options.invite);
+            if (invite)
+                params.set("invite", invite);
+            const view = options.full ? "full" : readOption(options.view) ?? "compact";
+            if (view)
+                params.set("view", view);
+            const order = readOption(options.order);
+            if (order)
+                params.set("order", order);
+            const limit = readOption(options.limit);
+            if (limit)
+                params.set("limit", limit);
+            const offset = readOption(options.offset);
+            if (offset)
+                params.set("offset", offset);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/enrollments${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("contacts")
+        .description("List a launched campaign's table-backed contacts with full source variables, contact tags, and factual or assigned sender. A contact carries every tag it reached: contacted means an invite, message or email was sent (a profile visit is not), and a positive reply is also replied and contacted. Contacts removed from this campaign are hidden; source rows remain intact. missing_source_row_count (first page only) counts enrolled leads whose source-table row was deleted: still contacted, never listed (remove them with `contacts-remove --missing-source-rows`).")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--contact-state <tags>", "Only contacts with any of these tags, comma-separated: not_contacted, contacted, connected, replied, positive_reply; or all.", "all")
+        .option("--exclude-contact-state <tags>", "Hide contacts with any of these tags, comma-separated.")
+        .option("--limit <n>", "Maximum contacts per page (1-500). Page with --cursor (next_cursor from the previous page) or --offset.", "100")
+        .option("--cursor <c>", "Pagination cursor from the previous page's next_cursor.")
+        .option("--offset <n>", "Skip this many contacts before the page (0-based); an absolute alternative to --cursor.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences contacts", options, () => {
+            const contactTags = ["not_contacted", "contacted", "connected", "replied", "positive_reply"];
+            const readTags = (flag, raw) => {
+                const tags = raw.split(",").map((tag) => tag.trim()).filter(Boolean);
+                if (tags.length === 0 || tags.some((tag) => !contactTags.includes(tag))) {
+                    throw new Error(`${flag} takes comma-separated tags: ${contactTags.join(", ")}.`);
+                }
+                return tags.join(",");
+            };
+            const contactStateRaw = readOption(options.contactState) ?? "all";
+            const contactState = contactStateRaw === "all" ? "all" : readTags("--contact-state", contactStateRaw);
+            const excludeRaw = readOption(options.excludeContactState);
+            const excludeContactState = excludeRaw ? readTags("--exclude-contact-state", excludeRaw) : null;
+            const limit = readPositiveInt(options.limit);
+            if (limit === undefined || limit > 500) {
+                throw new Error("--limit must be between 1 and 500.");
+            }
+            const params = new URLSearchParams({
+                contact_state: contactState,
+                limit: String(limit),
+            });
+            if (excludeContactState)
+                params.set("exclude_contact_state", excludeContactState);
+            const cursor = readOption(options.cursor);
+            if (cursor)
+                params.set("cursor", cursor);
+            const offsetRaw = readOption(options.offset);
+            if (offsetRaw !== null) {
+                const offset = Number(offsetRaw);
+                if (!Number.isInteger(offset) || offset < 0) {
+                    throw new OxygenError("invalid_offset", "--offset must be a non-negative integer.", {
+                        details: { offset: offsetRaw },
+                        exitCode: 2,
+                    });
+                }
+                params.set("offset", String(offset));
+            }
+            return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/contacts?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("contacts-remove")
+        .description("Remove leads from this campaign only: selected source-table rows (--table-row-ids), or every enrolled lead whose source-table row was deleted (--missing-source-rows; deleting a row never removes its lead). Preview by default and names those leads; --approved stops pending enrollment work and queues delegated-provider cleanup while preserving source rows and historical analytics. Permanent: a removed lead cannot be re-enrolled in this campaign. Finished leads stay as they are, except one a dry run finished while the sequence is still in dry run, which a live start would otherwise restart.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--table-row-ids <ids>", "Comma-separated source table row UUIDs (maximum 500).")
+        .option("--missing-source-rows", "Select enrolled leads whose source-table row was deleted (up to 500 per call, oldest first).")
+        .option("--approved", "Apply the previewed campaign-only removal.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences contacts-remove", options, async () => {
+            const rowIdsOption = readOption(options.tableRowIds);
+            if (Boolean(rowIdsOption) === (options.missingSourceRows === true)) {
+                throw new OxygenError("invalid_request", "Pass exactly one of --table-row-ids <ids> or --missing-source-rows.", { exitCode: 2 });
+            }
+            let selector = { missing_source_rows: true };
+            if (rowIdsOption) {
+                const tableRowIds = rowIdsOption
+                    .split(",")
+                    .map((value) => value.trim())
+                    .filter(Boolean);
+                if (tableRowIds.length === 0 || tableRowIds.length > 500) {
+                    throw new Error("--table-row-ids must contain between 1 and 500 row UUIDs.");
+                }
+                selector = { table_row_ids: tableRowIds };
+            }
+            const data = await requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/contacts`, {
+                method: "POST",
+                body: {
+                    ...selector,
+                    approved: options.approved === true,
+                },
+            });
+            if (!options.json)
+                writeContactsRemoveSummary(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("pause-company")
+        .description("Pause messaging to a company in your campaigns — e.g. after a meeting is booked — and resume it later. Holds every lead of that company (work-email domain, company domain, or LinkedIn company page) in every campaign, or only the --sequence ones; nothing is sent to them until `sequences resume-company`. --dry-run previews the leads it would hold.")
+        .option("--domain <domain>", "The company's domain, e.g. acme.com.")
+        .option("--email <email>", "Any work email at the company; its domain names the company (personal mail hosts such as gmail.com are refused).")
+        .option("--linkedin-company <url>", "The company's LinkedIn page, e.g. https://www.linkedin.com/company/acme.")
+        .option("--record <id>", "A CRM record id: a company; a person (their work-email domain and every linked company); or any record linked to companies, such as a deal.")
+        .option("--sequence <id>", "Pause only in this campaign (id or slug). Repeat for several; omit to pause in every campaign.", collectRepeatable, [])
+        .option("--note <text>", "Why it is paused, shown with the pause (max 500 characters).")
+        .option("--dry-run", "Preview the campaigns and leads that would be held; change nothing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences pause-company", options, async () => {
+            const sequenceIds = readRepeatableIds(options.sequence);
+            const note = readOption(options.note);
+            const data = await requestOxygen("/api/cli/sequences/company-pauses", {
+                method: "POST",
+                body: {
+                    ...readCompanyIdentityOptions(options, "pause"),
+                    ...(sequenceIds.length > 0 ? { sequence_ids: sequenceIds } : {}),
+                    ...(note ? { note } : {}),
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                },
+            });
+            if (!options.json)
+                writeCompanyPauseSummary(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("resume-company")
+        .description("Resume messaging to a paused company: its held leads continue where they stopped (due steps are spread over the next hour, waits keep their remaining time). Name one pause with --hold, or the company with one identity flag; --sequence narrows the resume to those campaigns.")
+        .option("--hold <id>", "The pause to resume (`id` from `sequences paused-companies`).")
+        .option("--domain <domain>", "The company's domain, e.g. acme.com.")
+        .option("--email <email>", "Any work email at the company.")
+        .option("--linkedin-company <url>", "The company's LinkedIn page URL.")
+        .option("--record <id>", "A CRM company, person or deal record id.")
+        .option("--sequence <id>", "Resume only in this campaign (id or slug). Repeatable.", collectRepeatable, [])
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences resume-company", options, async () => {
+            const hold = readOption(options.hold);
+            if (hold && countCompanyIdentityOptions(options) > 0) {
+                throw new OxygenError("company_identity_ambiguous", "Name the pause with --hold, or the company with one of --domain, --email, --linkedin-company, or --record — not both.", { exitCode: 2 });
+            }
+            const sequenceIds = readRepeatableIds(options.sequence);
+            const data = await requestOxygen("/api/cli/sequences/company-pauses/resume", {
+                method: "POST",
+                body: {
+                    ...(hold ? { hold_id: hold } : readCompanyIdentityOptions(options, "resume")),
+                    ...(sequenceIds.length > 0 ? { sequence_ids: sequenceIds } : {}),
+                },
+            });
+            if (!options.json)
+                writeCompanyPauseSummary(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("paused-companies")
+        .description("List the companies paused in your campaigns — by a reply (waiting for its classification, or classified into a paused status) or by hand/automation — with the leads each one holds.")
+        .option("--sequence <id>", "Only pauses in this campaign (id or slug).")
+        .option("--all", "Include resumed/released pauses (history).")
+        .option("--limit <n>", "Maximum pauses to return (1-500, default 100).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences paused-companies", options, async () => {
+            const params = new URLSearchParams();
+            const sequence = readOption(options.sequence);
+            if (sequence)
+                params.set("sequence_id", sequence);
+            if (options.all)
+                params.set("include_released", "true");
+            const limitRaw = readOption(options.limit);
+            if (limitRaw !== null) {
+                const limit = readPositiveInt(limitRaw);
+                if (limit === undefined || limit > 500)
+                    throw new Error("--limit must be between 1 and 500.");
+                params.set("limit", String(limit));
+            }
+            const suffix = params.toString();
+            const data = await requestOxygen(`/api/cli/sequences/company-pauses${suffix ? `?${suffix}` : ""}`);
+            if (!options.json)
+                writeCompanyPauseSummary(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("reconcile")
+        .description("Safely reconcile one ambiguous LinkedIn invite/message from provider reads. Zero credits. Preview-only unless --approved; never resends.")
+        .argument("<sequence>", "Sequence id or slug. The sequence must be paused.")
+        .requiredOption("--action <id>", "Failed/canceled live action UUID to reconcile.")
+        .option("--approved", "Apply an exact provider match to local state. No provider write or resend occurs.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences reconcile", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/reconcile`, {
+            method: "POST",
+            body: {
+                action_id: readOption(options.action),
+                approved: options.approved === true,
+            },
+        }));
+    }))
+        .addCommand(new Command("retry-deferred")
+        .description("Preview or re-ready pending actions deferred by LinkedIn working hours or an email send window on a PAUSED sequence. Email actions refresh their snapshotted window from the current campaign settings. Applying never sends, spends credits, resumes the sequence, or bypasses window/spacing/quota/cap checks.")
+        .argument("<sequence>", "Paused sequence id or slug.")
+        .option("--limit <n>", "Maximum actions to preview/retry (1-500, default 100).")
+        .option("--approved", "Apply the bounded local retry. The sequence remains paused.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences retry-deferred", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/retry-deferred`, {
+            method: "POST",
+            body: {
+                approved: options.approved === true,
+                ...(readOption(options.limit)
+                    ? { limit: readPositiveInt(options.limit) }
+                    : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("recover-capacity")
+        .description("Preview definitive no-effect terminal failures that Oxygen can replay safely: provider-capacity denials and exact allowlisted request-format defects. Recover the signed scope only on a PAUSED Sequence. Recovery restores local action/enrollment state; it never sends, calls a provider, spends credits, or resumes dispatch.")
+        .argument("<sequence>", "Sequence id or slug. Preview may run while active; apply requires paused.")
+        .option("--limit <n>", "Maximum candidate failure rows to inspect (1-5000, default 500). A truncated preview cannot be approved.")
+        .option("--approval-token <token>", "Exact unexpired token returned by the preview.")
+        .option("--approved", "Apply the exact signed scope. Requires --approval-token; the Sequence remains paused.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences recover-capacity", options, () => {
+            const approvalToken = readOption(options.approvalToken);
+            if (options.approved === true && !approvalToken) {
+                throw new Error("--approval-token is required with --approved.");
+            }
+            if (options.approved !== true && approvalToken) {
+                throw new Error("--approval-token may only be used with --approved.");
+            }
+            const limit = readOption(options.limit)
+                ? readPositiveInt(options.limit)
+                : undefined;
+            if (limit !== undefined && limit > 5_000) {
+                throw new Error("--limit must be between 1 and 5000.");
+            }
+            return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/recover-capacity`, {
+                method: "POST",
+                body: {
+                    approved: options.approved === true,
+                    ...(approvalToken ? { approval_token: approvalToken } : {}),
+                    ...(limit === undefined ? {} : { limit }),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("stats")
+        .description("Show one sequence's persisted launch status and current operational state separately, including reasons, open work, lifetime sent/terminal-failed/deferral counts, and the funnel. Today's completed sends, reservations and remaining capacity appear in the default output and daily_budget. operational.reasons carries why work is waiting (outside_send_window, mailbox_spacing, daily_send_cap_reached, ...). For a per-day send series use `sequences analytics --sequence <id> --range <window>`.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleReadActionWithLens("sequences stats", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/stats`), formatSequenceStatsHealth);
+    }))
+        .addCommand(new Command("esp")
+        .description("ESP breakdown of this sequence's email sending scope: which provider each enrolled lead's mail routes through (google/microsoft, plus named gateways like Proofpoint/Mimecast and non-matchable hosts), folded against your sending mailbox pool. Shows how many leads the CURRENT --esp-matching mode would defer before you turn it on. Resolves domains from MX + SPF (0 credits, DNS only) and caches the result, warming the send path. Preview before flipping strict/prefer.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--max-lookups <n>", "Cap uncached domains resolved over DNS this call (0-2000). The remainder is reported as domains_unresolved and resolves on the next call.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences esp", options, () => {
+            const query = options.maxLookups ? `?max_lookups=${encodeURIComponent(options.maxLookups)}` : "";
+            return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/esp${query}`);
+        });
+    }))
+        .addCommand(new Command("events")
+        .description("Chronological activity feed for a sequence (like Instantly's Sending Activities): sends, failures, deferrals, opens, clicks, replies, bounces, unsubscribes, and positive reply-status transitions, newest first. Email events include mailboxEmail and sendingDomain when durable evidence preserved them; missing identity remains null instead of being guessed. Keyset-paginated via --before.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--enrollment <id>", "Scope the feed to one enrollment id.")
+        .option("--kind <list>", "Comma-separated event kinds to include (sent,failed,skipped,open,click,replied,bounced,unsubscribed,positive).")
+        .option("--include-bots", "Include bot-attributed opens/clicks (excluded by default).")
+        .option("--limit <n>", "Maximum events to return (1-200, default 50).")
+        .option("--before <iso>", "Keyset cursor: only events strictly before this ISO timestamp (pass the previous page's next_before).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleSequenceEventsAction(sequence, options);
+    }))
+        .addCommand(new Command("variants")
+        .description("Generic per-step action/base-variant scoreboard for one sequence, plus native email by_mailbox, by_domain, reply types, rates, and explicit unattributed facts. This rollup is not the copy-only analytics.messagePerformance view; base rows can represent non-message actions, and campaign replies may lack step/variant provenance. Provider-owned campaigns appear only after normalization into Oxygen's native Sequence ledgers. Also returns reversible auto-winner state (paused variants + evidence); flags run or override/reset that state.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--auto-optimize", "Run the auto-winner now on every step with variants (the whole sequence): once each active variant clears its thresholds (default 100 sends and 5 replies), pause the variants converting below the leader, on the step's metric — reply by default, or the click/open its own auto_optimize names (click/open need native open/click tracking; opens are soft signals under Apple Mail Privacy Protection). Nothing is evaluated while the sequence's auto-winner is off. Reversible.")
+        .option("--pause <variant>", "Manually pause one variant (requires --step). Overrides the auto-winner.")
+        .option("--activate <variant>", "Manually reactivate one paused variant (requires --step).")
+        .option("--reset [variant]", "Clear an auto/manual decision: one variant (with --step), a whole step (--step only), or the entire sequence (no value). Reactivates the affected variants.")
+        .option("--step <stepId>", "Step id to scope --pause/--activate/--reset to.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleSequenceVariantsAction(sequence, options);
+    })));
+}