@oxygen-agent/cli 1.1014.1600 → 1.1014.1763

package/node_modules/@oxygen/shared/dist/plan-capabilities.d.ts

@@ -49,7 +49,7 @@
 import type { PlanTier, PricingPlanDefinition } from "./billing.js";
 import { CREDIT_GATE_RETIRED_CAPABILITIES, isCapabilityRetiredByCreditGate } from "./credit-gate.js";
 import { type RepricingOptions } from "./repricing.js";
-export declare const PLAN_GATED_CAPABILITIES: readonly ["sender_connect", "linkedin_connect", "sequence_dispatch", "publishing_connect", "publishing_deliver", "managed_email_infrastructure", "byok_provider_keys"];
+export declare const PLAN_GATED_CAPABILITIES: readonly ["sender_connect", "linkedin_connect", "sequence_dispatch", "publishing_connect", "publishing_deliver", "managed_email_infrastructure", "byok_provider_keys", "bulk_email"];
 export type PlanGatedCapability = (typeof PLAN_GATED_CAPABILITIES)[number];
 /**
  * Every tier except `free` unblocks every gated capability.
@@ -83,7 +83,7 @@ export declare function isPlanGatedCapability(value: unknown): value is PlanGate
  * (`assertCreditGateArmed`). Until then every one of them stays walled exactly
  * as before.
  *
- * Four capabilities stay walled under the gate:
+ * Five capabilities stay walled under the gate:
  * - `linkedin_connect` and `sender_connect`: every sending account connects
  *   only on a plan (founder, current chat, 2026-10-12), whatever the balance.
  *   That covers a LinkedIn account, a mailbox (imported or bought), a WhatsApp
@@ -94,6 +94,8 @@ export declare function isPlanGatedCapability(value: unknown): value is PlanGate
  *   Instagram, TikTok, YouTube and Facebook, which have no reservation price yet
  *   (P-18). Connecting them without one would make them free and unmetered, so
  *   they stay on the plan until that price is ratified.
+ * - `bulk_email`: newsletters share one sending reputation across customers, so
+ *   they stay on a plan whatever the balance (user, current chat, 2026-10-21).
  */
 export { CREDIT_GATE_RETIRED_CAPABILITIES, isCapabilityRetiredByCreditGate };
 /**

package/node_modules/@oxygen/shared/dist/plan-capabilities.js

@@ -56,6 +56,7 @@ export const PLAN_GATED_CAPABILITIES = [
     "publishing_deliver",
     "managed_email_infrastructure",
     "byok_provider_keys",
+    "bulk_email",
 ];
 /**
  * Every tier except `free` unblocks every gated capability.
@@ -110,6 +111,14 @@ export const PLAN_GATED_CAPABILITY_COPY = {
         freeAlternative: "Every provider in the catalog already works on Free using OXYGEN's managed keys and your credits — including enrichment, AI columns, and phone lookups. Bringing your own key is what needs a plan.",
         deepLinkPath: "/settings/integrations",
     },
+    // Newsletters through OXYGEN's shared sending infrastructure are paid-only
+    // (user, current chat, 2026-10-21), whatever the balance: a free workspace's
+    // list must never reach the reputation every customer shares.
+    bulk_email: {
+        label: "Sending newsletters",
+        freeAlternative: "Subscription lists and newsletter Sequences can be set up on Free. Adding a sending domain and sending to subscribers is what needs a plan.",
+        deepLinkPath: "/sequencer/accounts?tab=newsletter",
+    },
 };
 export function isPlanGatedCapability(value) {
     return (typeof value === "string"
@@ -127,7 +136,7 @@ export function isPlanGatedCapability(value) {
  * (`assertCreditGateArmed`). Until then every one of them stays walled exactly
  * as before.
  *
- * Four capabilities stay walled under the gate:
+ * Five capabilities stay walled under the gate:
  * - `linkedin_connect` and `sender_connect`: every sending account connects
  *   only on a plan (founder, current chat, 2026-10-12), whatever the balance.
  *   That covers a LinkedIn account, a mailbox (imported or bought), a WhatsApp
@@ -138,6 +147,8 @@ export function isPlanGatedCapability(value) {
  *   Instagram, TikTok, YouTube and Facebook, which have no reservation price yet
  *   (P-18). Connecting them without one would make them free and unmetered, so
  *   they stay on the plan until that price is ratified.
+ * - `bulk_email`: newsletters share one sending reputation across customers, so
+ *   they stay on a plan whatever the balance (user, current chat, 2026-10-21).
  */
 export { CREDIT_GATE_RETIRED_CAPABILITIES, isCapabilityRetiredByCreditGate };
 /**

package/node_modules/@oxygen/shared/dist/plan-limits-view.d.ts

@@ -126,6 +126,8 @@ export type PlanLimitsSpendDefaults = {
     /** The most a run approved above the default may spend (decision F.4). */
     agent_run_approved_max_credits?: number;
     copilot_approval_free_per_call_credits?: number;
+    /** Every plan: a step quoted strictly under this needs no approval (Philipp, 2026-10-21). */
+    copilot_approval_free_below_credits?: number;
     copilot_approval_free_per_session_credits?: number;
     copilot_attended_turn_backstop_credits?: number;
     org_daily_spend_guard?: {

package/node_modules/@oxygen/shared/dist/plan-limits-view.js

@@ -298,6 +298,9 @@ export function planLimitsSpendDefaults(payload) {
         row("Agent run default cap", spend.agent_run_max_total_credits, "agent_run_max_total_credits", agentKey("max_total_credits")),
         row("Agent model calls", spend.agent_run_max_inference_credits, "agent_run_max_inference_credits", agentKey("max_inference_credits")),
         row("Copilot without approval, per step", spend.copilot_approval_free_per_call_credits, "copilot_approval_free_per_call_credits"),
+        ...(typeof spend.copilot_approval_free_below_credits === "number"
+            ? [row("Any step quoted under", spend.copilot_approval_free_below_credits, "copilot_approval_free_below_credits")]
+            : []),
         row("Copilot without approval, per chat", spend.copilot_approval_free_per_session_credits, "copilot_approval_free_per_session_credits"),
         row("Copilot turn limit", spend.copilot_attended_turn_backstop_credits, "copilot_attended_turn_backstop_credits"),
     ];

package/node_modules/@oxygen/shared/dist/pricing-snapshot.generated.d.ts

@@ -64,6 +64,11 @@ export declare const BYOK_PLATFORM_FEE_CREDITS = 0.05;
 export declare const LINKEDIN_URL_FOUND_CREDITS = 5;
 /** Email, LinkedIn and WhatsApp sends are free; the pool pays for seats and inboxes. */
 export declare const SEND_CREDITS = 0;
+/**
+ * One newsletter email sent through a sending domain, 5x the AWS price (user,
+ * 2026-10-21). Read through bulkEmailCredits() in email-delivery.ts.
+ */
+export declare const BULK_EMAIL_CREDITS_PER_EMAIL = 0.05;
 /** Every LinkedIn action is 0 under the pure seat model. */
 export declare const LINKEDIN_ACTION_CREDITS: {
     readonly visit_profile: 0;

package/node_modules/@oxygen/shared/dist/pricing-snapshot.generated.js

@@ -102,6 +102,11 @@ export const BYOK_PLATFORM_FEE_CREDITS = 0.05;
 export const LINKEDIN_URL_FOUND_CREDITS = 5;
 /** Email, LinkedIn and WhatsApp sends are free; the pool pays for seats and inboxes. */
 export const SEND_CREDITS = 0;
+/**
+ * One newsletter email sent through a sending domain, 5x the AWS price (user,
+ * 2026-10-21). Read through bulkEmailCredits() in email-delivery.ts.
+ */
+export const BULK_EMAIL_CREDITS_PER_EMAIL = 0.05;
 /** Every LinkedIn action is 0 under the pure seat model. */
 export const LINKEDIN_ACTION_CREDITS = {
     visit_profile: 0,

package/node_modules/@oxygen/shared/dist/product-analytics-events.d.ts

@@ -40,6 +40,14 @@ export declare const PRODUCT_EVENTS: {
      * Once per (workspace, person), gated by `organizations.metadata.onboarding_play_sent`.
      */
     readonly ONBOARDING_PLAY_SENT: "onboarding_play_sent";
+    /**
+     * Agent-led onboarding's Start, opened from /setup/brain while the page renders:
+     * no command or browser event sees it, so a failure here was invisible in PostHog.
+     * `outcome` is opened, pending (the workspace database is still provisioning) or
+     * failed; `error_code` is the machine code of a failure; `trace_id` finds the
+     * server trace in SigNoz. Once per page visit, a handful per signup.
+     */
+    readonly AGENT_ONBOARDING_ATTEMPTED: "agent_onboarding_attempted";
     /**
      * The prescribed first play (inbound-led outbound), walked on ANY surface.
      *
@@ -97,6 +105,8 @@ export declare const PRODUCT_EVENTS: {
      * Copilot is a Control surface, not a primitive, but its turns are durable
      * worker runs like the others and it had no outcome event at all. Counts,
      * credits and ids only — never the user message or the assistant text.
+     * `onboarding_role` is start, research or research_report on the guided
+     * onboarding turns OXYGEN funds, null otherwise.
      */
     readonly COPILOT_TURN_SETTLED: "copilot_turn_settled";
     /** Revenue lifecycle. */
@@ -158,6 +168,25 @@ export declare const PRODUCT_EVENTS: {
     readonly WEB_NAVIGATION_MEANINGFUL: "web_navigation_meaningful";
     readonly WEB_NAVIGATION_USABLE: "web_navigation_usable";
     readonly WEB_NAVIGATION_USABLE_TIMEOUT: "web_navigation_usable_timeout";
+    /**
+     * Browser-side web-analytics signals, captured by posthog-js only for a
+     * consenting visitor, so each one carries the visit's `$session_id`.
+     *
+     * `session_engaged`: once per session, after a page has been visible for
+     * 10 s. PostHog counts a one-page session under 10 s as a bounce and measures
+     * duration between the session's events; mobile and in-app browsers often
+     * send no `$pageleave`, so a reader who stayed on one page looked like a
+     * 0-second bounce. No properties.
+     *
+     * `signup_completed`: the browser twin of `user_signed_up` (sent by the Clerk
+     * webhook, which has no session), where the ad networks' signup conversions
+     * fire: the first setup page after the onboarding survey, which carries
+     * `signup=complete`. It is the web-analytics conversion goal: channel,
+     * landing page and bounce join to it through the session. Once per account
+     * per browser; deliberately absent from KPI_TYPE_TO_EVENT.
+     */
+    readonly SESSION_ENGAGED: "session_engaged";
+    readonly SIGNUP_COMPLETED: "signup_completed";
     /** Pipeline heartbeat: proves ingestion is alive when the product is quiet. */
     readonly POSTHOG_CANARY: "posthog_canary";
 };

package/node_modules/@oxygen/shared/dist/product-analytics-events.js

@@ -40,6 +40,14 @@ export const PRODUCT_EVENTS = {
      * Once per (workspace, person), gated by `organizations.metadata.onboarding_play_sent`.
      */
     ONBOARDING_PLAY_SENT: "onboarding_play_sent",
+    /**
+     * Agent-led onboarding's Start, opened from /setup/brain while the page renders:
+     * no command or browser event sees it, so a failure here was invisible in PostHog.
+     * `outcome` is opened, pending (the workspace database is still provisioning) or
+     * failed; `error_code` is the machine code of a failure; `trace_id` finds the
+     * server trace in SigNoz. Once per page visit, a handful per signup.
+     */
+    AGENT_ONBOARDING_ATTEMPTED: "agent_onboarding_attempted",
     /**
      * The prescribed first play (inbound-led outbound), walked on ANY surface.
      *
@@ -97,6 +105,8 @@ export const PRODUCT_EVENTS = {
      * Copilot is a Control surface, not a primitive, but its turns are durable
      * worker runs like the others and it had no outcome event at all. Counts,
      * credits and ids only — never the user message or the assistant text.
+     * `onboarding_role` is start, research or research_report on the guided
+     * onboarding turns OXYGEN funds, null otherwise.
      */
     COPILOT_TURN_SETTLED: "copilot_turn_settled",
     /** Revenue lifecycle. */
@@ -158,6 +168,25 @@ export const PRODUCT_EVENTS = {
     WEB_NAVIGATION_MEANINGFUL: "web_navigation_meaningful",
     WEB_NAVIGATION_USABLE: "web_navigation_usable",
     WEB_NAVIGATION_USABLE_TIMEOUT: "web_navigation_usable_timeout",
+    /**
+     * Browser-side web-analytics signals, captured by posthog-js only for a
+     * consenting visitor, so each one carries the visit's `$session_id`.
+     *
+     * `session_engaged`: once per session, after a page has been visible for
+     * 10 s. PostHog counts a one-page session under 10 s as a bounce and measures
+     * duration between the session's events; mobile and in-app browsers often
+     * send no `$pageleave`, so a reader who stayed on one page looked like a
+     * 0-second bounce. No properties.
+     *
+     * `signup_completed`: the browser twin of `user_signed_up` (sent by the Clerk
+     * webhook, which has no session), where the ad networks' signup conversions
+     * fire: the first setup page after the onboarding survey, which carries
+     * `signup=complete`. It is the web-analytics conversion goal: channel,
+     * landing page and bounce join to it through the session. Once per account
+     * per browser; deliberately absent from KPI_TYPE_TO_EVENT.
+     */
+    SESSION_ENGAGED: "session_engaged",
+    SIGNUP_COMPLETED: "signup_completed",
     /** Pipeline heartbeat: proves ingestion is alive when the product is quiet. */
     POSTHOG_CANARY: "posthog_canary",
 };

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

@@ -14,6 +14,8 @@ export type RecipePrimitive = typeof RECIPE_PRIMITIVES[number];
 export declare const RECIPE_PREREQUISITE_KINDS: readonly ["sender", "mailbox", "domain", "integration", "knowledge", "asset", "plan", "data"];
 export type RecipePrerequisiteKind = typeof RECIPE_PREREQUISITE_KINDS[number];
 export declare const RECIPE_BODY_SECTIONS: readonly ["The Play", "Before You Start", "Steps", "If It Goes Wrong"];
+export declare const RECIPE_SKILL_PLAY_BODY_SECTIONS: readonly ["When", "Numbers", "Steps", "Kill and scale"];
+export declare const RECIPE_BODY_SHAPES: readonly (readonly string[])[];
 export declare const RECIPE_SLUG_PATTERN: RegExp;
 export declare function recipeWikiSlug(recipeSlug: string): string;
 export declare const RECIPE_KIT_MAX_STAGES = 6;

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

@@ -77,6 +77,19 @@ export const RECIPE_BODY_SECTIONS = [
     "Steps",
     "If It Goes Wrong",
 ];
+// The four sections of a play written inside its feature skill (the 2026-10-21
+// sourcing, sequencer and signals plays). The lint takes the shape a body's
+// first heading names and holds the body to exactly that shape.
+export const RECIPE_SKILL_PLAY_BODY_SECTIONS = [
+    "When",
+    "Numbers",
+    "Steps",
+    "Kill and scale",
+];
+export const RECIPE_BODY_SHAPES = [
+    RECIPE_BODY_SECTIONS,
+    RECIPE_SKILL_PLAY_BODY_SECTIONS,
+];
 export const RECIPE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,119}$/;
 // Wiki slug an install writes: slots into the starter wiki's seeded
 // [[playbooks]] hub convention ([[playbook-outbound]] etc.).

package/node_modules/@oxygen/shared/dist/sending-domain-faults.d.ts

@@ -0,0 +1,21 @@
+import { CliHttpError } from "./cli-http-error.js";
+export declare const SENDING_DOMAIN_FAULT_CODES: {
+    readonly ownedElsewhere: "sending_domain_owned_elsewhere";
+    readonly reserved: "sending_domain_reserved";
+    readonly requiresDomain: "sending_domain_requires_domain";
+    readonly inUse: "sending_domain_in_use";
+    readonly workspacePaused: "bulk_email_workspace_paused";
+    readonly postalAddressRequired: "newsletter_postal_address_required";
+};
+/** Reasons a bulk job waits instead of sending; recorded on the job, never shown as an error. */
+export declare const BULK_EMAIL_DEFER_REASONS: readonly ["bulk_email_daily_allowance", "send_rate", "tenant_paused"];
+export type BulkEmailDeferReason = (typeof BULK_EMAIL_DEFER_REASONS)[number];
+export declare function sendingDomainOwnedElsewhereError(): CliHttpError;
+export declare function sendingDomainReservedError(): CliHttpError;
+export declare function sendingDomainRequiresDomainError(): CliHttpError;
+export declare function sendingDomainInUseError(): CliHttpError;
+export declare function bulkEmailWorkspacePausedError(): CliHttpError;
+/** Every bulk email carries the sender's postal address; a newsletter goes live only once the brand kit holds one. */
+export declare const NEWSLETTER_POSTAL_ADDRESS_REQUIRED_MESSAGE = "Add your postal address to the brand kit before sending a newsletter.";
+export declare const NEWSLETTER_POSTAL_ADDRESS_NEXT_STEP = "Add a postal address in Sequencer \u2192 Accounts \u2192 Newsletter \u2192 Brand kit (CLI: `oxygen sequences brand-kit set --postal-address`; MCP: oxygen_domains_sending action=brand_kit_set), then start again.";
+export declare function newsletterPostalAddressRequiredError(details?: Record<string, unknown>): CliHttpError;

package/node_modules/@oxygen/shared/dist/sending-domain-faults.js

@@ -0,0 +1,53 @@
+import { CliHttpError } from "./cli-http-error.js";
+// Customer-facing refusals for workspace sending domains (ADR 0023): fixed copy,
+// a machine code and a next step. None names SES, AWS or another workspace, and
+// an ownership refusal never says which domain it collided with.
+export const SENDING_DOMAIN_FAULT_CODES = {
+    ownedElsewhere: "sending_domain_owned_elsewhere",
+    reserved: "sending_domain_reserved",
+    requiresDomain: "sending_domain_requires_domain",
+    inUse: "sending_domain_in_use",
+    workspacePaused: "bulk_email_workspace_paused",
+    postalAddressRequired: "newsletter_postal_address_required",
+};
+/** Reasons a bulk job waits instead of sending; recorded on the job, never shown as an error. */
+export const BULK_EMAIL_DEFER_REASONS = ["bulk_email_daily_allowance", "send_rate", "tenant_paused"];
+export function sendingDomainOwnedElsewhereError() {
+    return new CliHttpError(409, SENDING_DOMAIN_FAULT_CODES.ownedElsewhere, "This domain is already used for sending by another workspace.", {
+        details: { retryable: false, next_step: "Use a different subdomain, such as news.<your domain>, or contact support if this is your domain." },
+        exitCode: 1,
+    });
+}
+export function sendingDomainReservedError() {
+    return new CliHttpError(403, SENDING_DOMAIN_FAULT_CODES.reserved, "This domain can't be used as a sending domain.", {
+        details: { retryable: false, next_step: "Use a subdomain of a domain your workspace owns." },
+        exitCode: 1,
+    });
+}
+export function sendingDomainRequiresDomainError() {
+    return new CliHttpError(400, SENDING_DOMAIN_FAULT_CODES.requiresDomain, "Add the domain to your workspace before sending from it.", {
+        details: { retryable: false, next_step: "Add the domain in Sequencer → Domains, then add the sending domain again." },
+        exitCode: 1,
+    });
+}
+export function sendingDomainInUseError() {
+    return new CliHttpError(409, SENDING_DOMAIN_FAULT_CODES.inUse, "This sending domain still has emails waiting to send.", {
+        details: { retryable: true, next_step: "Pause or finish the Sequences that use it, then remove it again." },
+        exitCode: 1,
+    });
+}
+export function bulkEmailWorkspacePausedError() {
+    return new CliHttpError(503, SENDING_DOMAIN_FAULT_CODES.workspacePaused, "Newsletter sending is paused for this workspace.", {
+        details: { retryable: false, next_step: "Contact support to review recent bounces and complaints." },
+        exitCode: 1,
+    });
+}
+/** Every bulk email carries the sender's postal address; a newsletter goes live only once the brand kit holds one. */
+export const NEWSLETTER_POSTAL_ADDRESS_REQUIRED_MESSAGE = "Add your postal address to the brand kit before sending a newsletter.";
+export const NEWSLETTER_POSTAL_ADDRESS_NEXT_STEP = "Add a postal address in Sequencer → Accounts → Newsletter → Brand kit (CLI: `oxygen sequences brand-kit set --postal-address`; MCP: oxygen_domains_sending action=brand_kit_set), then start again.";
+export function newsletterPostalAddressRequiredError(details = {}) {
+    return new CliHttpError(409, SENDING_DOMAIN_FAULT_CODES.postalAddressRequired, NEWSLETTER_POSTAL_ADDRESS_REQUIRED_MESSAGE, {
+        details: { ...details, retryable: false, next_step: NEWSLETTER_POSTAL_ADDRESS_NEXT_STEP },
+        exitCode: 1,
+    });
+}

package/node_modules/@oxygen/shared/dist/sending-domain-rollout.d.ts

@@ -0,0 +1,30 @@
+export declare const SENDING_DOMAIN_ROLLOUT_CODE = "sending_domain_rollout_unavailable";
+export declare const SENDING_DOMAIN_ROLLOUT_MESSAGE = "Sending-domain setup and delivery are not available yet.";
+/** The operator switch that admits the sending-domain lane in one environment. */
+export declare const SENDING_DOMAIN_DELIVERY_READY_ENV = "OXYGEN_SENDING_DOMAIN_DELIVERY_READY";
+export declare function sendingDomainDeliveryAvailable(env?: Readonly<Record<string, string | undefined>>): boolean;
+export declare function assertSendingDomainDeliveryAvailable(): void;
+/** Inspect raw intent: invalid/partial settings must never fall back to a mailbox. */
+export declare function hasSendingDomainDeliveryIntent(settings: unknown): boolean;
+export declare function assertSendingDomainSequenceReady(settings: unknown): void;
+/**
+ * Rollback fence: the only `settings.mailbox_ids` entry of a sending-domain
+ * Sequence. Older web and worker images ignore `email_delivery` (before #8332)
+ * or fell back to inboxes on partial settings (until #8449); reading this
+ * allowlist they find no mailbox and wait instead of mailing a newsletter from
+ * personal inboxes. The nil UUID passes every mailbox-id validator old and new
+ * and no mailbox row is ever created with it.
+ */
+export declare const SENDING_DOMAIN_MAILBOX_FENCE = "00000000-0000-0000-0000-000000000000";
+/**
+ * Settings as stored: with sending-domain intent the mailbox allowlist is
+ * exactly the fence; without it any fence entry is removed (a Sequence that
+ * switched back to inboxes uses the whole pool unless it names inboxes again).
+ */
+export declare function withSendingDomainMailboxFence<T extends Record<string, unknown>>(settings: T): T;
+/** Settings as web, CLI and MCP show them: the fence is storage, never an inbox. */
+export declare function withoutSendingDomainMailboxFence<T extends Record<string, unknown>>(settings: T): T;
+/** A Sequence as a read returns it, with the fence hidden from its settings. */
+export declare function withoutSequenceMailboxFence<S extends {
+    settings?: object | null;
+}>(sequence: S): S;

package/node_modules/@oxygen/shared/dist/sending-domain-rollout.js

@@ -0,0 +1,75 @@
+import { CliHttpError } from "./cli-http-error.js";
+export const SENDING_DOMAIN_ROLLOUT_CODE = "sending_domain_rollout_unavailable";
+export const SENDING_DOMAIN_ROLLOUT_MESSAGE = "Sending-domain setup and delivery are not available yet.";
+/** The operator switch that admits the sending-domain lane in one environment. */
+export const SENDING_DOMAIN_DELIVERY_READY_ENV = "OXYGEN_SENDING_DOMAIN_DELIVERY_READY";
+// Operator-admitted lane. An operator sets OXYGEN_SENDING_DOMAIN_DELIVERY_READY=1
+// in one environment only after every web and worker role there runs source
+// containing the SES ownership registry, per-workspace tenants and health,
+// proven-volume pacing, newsletter billing and the bulk_email plan gate (this
+// commit and later). Unlike write-rollout.ts it never defaults on outside
+// production: unset, "true", "yes" or anything but "1" keeps it closed. Every
+// caller reads the process environment; none passes its own env, so no request,
+// account role or queue-family selector can qualify itself
+// (sending-domain-rollout.test.ts scans the callers).
+export function sendingDomainDeliveryAvailable(env = typeof process === "undefined" ? {} : process.env) {
+    return env[SENDING_DOMAIN_DELIVERY_READY_ENV] === "1";
+}
+export function assertSendingDomainDeliveryAvailable() {
+    if (!sendingDomainDeliveryAvailable())
+        throw new CliHttpError(503, SENDING_DOMAIN_ROLLOUT_CODE, SENDING_DOMAIN_ROLLOUT_MESSAGE, {
+            details: { retryable: false, next_step: "Keep sending-domain campaigns stopped until sending-domain delivery is available." }, exitCode: 1,
+        });
+}
+/** Inspect raw intent: invalid/partial settings must never fall back to a mailbox. */
+export function hasSendingDomainDeliveryIntent(settings) {
+    if (!settings || typeof settings !== "object")
+        return false;
+    const value = settings.email_delivery;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const delivery = value;
+    return delivery.mode === "sending_domain" || ["sending_domain_id", "from_address", "from_name", "reply_to_mailbox_id", "subscription_list_id"]
+        .some(key => delivery[key] !== undefined);
+}
+export function assertSendingDomainSequenceReady(settings) {
+    if (hasSendingDomainDeliveryIntent(settings))
+        assertSendingDomainDeliveryAvailable();
+}
+/**
+ * Rollback fence: the only `settings.mailbox_ids` entry of a sending-domain
+ * Sequence. Older web and worker images ignore `email_delivery` (before #8332)
+ * or fell back to inboxes on partial settings (until #8449); reading this
+ * allowlist they find no mailbox and wait instead of mailing a newsletter from
+ * personal inboxes. The nil UUID passes every mailbox-id validator old and new
+ * and no mailbox row is ever created with it.
+ */
+export const SENDING_DOMAIN_MAILBOX_FENCE = "00000000-0000-0000-0000-000000000000";
+/**
+ * Settings as stored: with sending-domain intent the mailbox allowlist is
+ * exactly the fence; without it any fence entry is removed (a Sequence that
+ * switched back to inboxes uses the whole pool unless it names inboxes again).
+ */
+export function withSendingDomainMailboxFence(settings) {
+    return hasSendingDomainDeliveryIntent(settings)
+        ? { ...settings, mailbox_ids: [SENDING_DOMAIN_MAILBOX_FENCE] }
+        : withoutSendingDomainMailboxFence(settings);
+}
+/** Settings as web, CLI and MCP show them: the fence is storage, never an inbox. */
+export function withoutSendingDomainMailboxFence(settings) {
+    const ids = settings.mailbox_ids;
+    if (!Array.isArray(ids))
+        return settings;
+    const kept = ids.filter((entry) => !(typeof entry === "string" && entry.trim() === SENDING_DOMAIN_MAILBOX_FENCE));
+    if (kept.length === ids.length)
+        return settings;
+    const { mailbox_ids: _fenced, ...rest } = settings;
+    return (kept.length > 0 ? { ...rest, mailbox_ids: kept } : rest);
+}
+/** A Sequence as a read returns it, with the fence hidden from its settings. */
+export function withoutSequenceMailboxFence(sequence) {
+    if (!sequence.settings)
+        return sequence;
+    const view = withoutSendingDomainMailboxFence(sequence.settings);
+    return view === sequence.settings ? sequence : { ...sequence, settings: view };
+}

package/node_modules/@oxygen/shared/dist/sequence-failures.d.ts

@@ -1,7 +1,7 @@
 export declare const SEQUENCE_FAILURE_SCHEMA_VERSION = 1;
 export declare const SEQUENCE_FAILURE_RETRY_AFTER_MAX_MS: number;
 export declare const WHATSAPP_UNCERTAIN_DELIVERY_MESSAGE = "WhatsApp delivery is uncertain. Automatic resending is blocked.";
-export declare const SEQUENCE_FAILURE_CLASSES: readonly ["capacity", "recipient", "authorization_scope", "funding", "validation", "provider", "internal", "effect_unknown", "unknown"];
+export declare const SEQUENCE_FAILURE_CLASSES: readonly ["capacity", "recipient", "authorization_scope", "integration", "funding", "validation", "provider", "internal", "effect_unknown", "unknown"];
 export type SequenceFailureClass = (typeof SEQUENCE_FAILURE_CLASSES)[number];
 export type SequenceFailureEffectOutcome = "not_applied" | "applied" | "unknown";
 export type SequenceFailureEnvelope = {
@@ -58,3 +58,12 @@ export declare function hasSequenceFailureSignal(error: unknown): boolean;
  * `not_applied` outcome from retryability, status, or error text.
  */
 export declare function readSequenceFailure(error: unknown, overrides?: SequenceFailureOverrides): SequenceFailureEnvelope;
+/**
+ * The class a reader shows for a stored Sequence error that already names one
+ * (the events feed, a failed lead's cause). A v1 envelope reads through
+ * {@link readSequenceFailure}, so it agrees with the Sequence summary's
+ * `failure:<class>` for the same row, including a class refined since it was
+ * written. An unversioned stored class is shown as written; no stored class is
+ * null, never a guess.
+ */
+export declare function storedSequenceFailureClass(error: unknown): string | null;

package/node_modules/@oxygen/shared/dist/sequence-failures.js

@@ -8,6 +8,10 @@ export const SEQUENCE_FAILURE_CLASSES = [
     "capacity",
     "recipient",
     "authorization_scope",
+    // The connected integration does not offer an operation the step needs (an
+    // action its gateway does not expose, a tool OXYGEN has no route for).
+    // Reconnecting cannot fix it; OXYGEN has to change the integration route.
+    "integration",
     "funding",
     "validation",
     "provider",
@@ -158,13 +162,21 @@ export function readSequenceFailure(error, overrides = {}) {
     // do not: their stray `failure_class` fields are mapped from the underlying
     // facts. Effect-unknown remains the fail-safe exception even for a malformed
     // v1 envelope, because it must never be made replay-safe by a stale class.
+    // A stored class the classifier has since refined (see
+    // REFINABLE_STORED_CLASSES) reads as the refinement, so rows written before
+    // the classifier knew their code stop reading `failure:unknown` forever.
+    const storedClass = existingVersion === SEQUENCE_FAILURE_SCHEMA_VERSION &&
+        existingClass &&
+        FAILURE_CLASS_SET.has(existingClass)
+        ? existingClass
+        : null;
     const failureClass = effectOutcome === "unknown"
         ? "effect_unknown"
-        : existingVersion === SEQUENCE_FAILURE_SCHEMA_VERSION &&
-            existingClass &&
-            FAILURE_CLASS_SET.has(existingClass)
-            ? existingClass
-            : classified;
+        : storedClass === null
+            ? classified
+            : refinesStoredClass(storedClass, classified)
+                ? classified
+                : storedClass;
     return {
         failure_schema_version: SEQUENCE_FAILURE_SCHEMA_VERSION,
         failure_class: failureClass,
@@ -180,6 +192,48 @@ export function readSequenceFailure(error, overrides = {}) {
         ...(hardBounce !== null ? { hard_bounce: hardBounce } : {}),
     };
 }
+/**
+ * The class a reader shows for a stored Sequence error that already names one
+ * (the events feed, a failed lead's cause). A v1 envelope reads through
+ * {@link readSequenceFailure}, so it agrees with the Sequence summary's
+ * `failure:<class>` for the same row, including a class refined since it was
+ * written. An unversioned stored class is shown as written; no stored class is
+ * null, never a guess.
+ */
+export function storedSequenceFailureClass(error) {
+    const record = asRecord(error);
+    const stored = typeof record?.failure_class === "string" ? record.failure_class.trim() : "";
+    if (!record || !stored)
+        return null;
+    return record.failure_schema_version === SEQUENCE_FAILURE_SCHEMA_VERSION
+        ? readSequenceFailure(record).failure_class
+        : stored;
+}
+const INTEGRATION_ACTION_MISSING_CODE = /(?:composio|provider|integration)[_-]?action[_-]?(?:missing|not[_-]?(?:found|exposed|supported))|tool[_-]?not[_-]?(?:found|executable)|composio[_-]?integration[_-]?unknown/i;
+/**
+ * Stored v1 classes the classifier may refine at read time. `unknown` records
+ * only that the writer lacked evidence, so a diagnostic class the current
+ * classifier derives from the same stored facts replaces it. `integration` was
+ * split out of `internal`, so an `internal` row whose code names a missing
+ * integration action reads as `integration`. Classes that gate a decision
+ * (capacity recovery re-readies `capacity`, `recipient` is excluded from
+ * unresolved work and recovery, `effect_unknown` blocks replay) are never
+ * reached by refinement: those rows keep reading exactly what was written.
+ */
+const REFINABLE_STORED_CLASSES = {
+    unknown: new Set([
+        "integration",
+        "authorization_scope",
+        "funding",
+        "validation",
+        "provider",
+        "internal",
+    ]),
+    internal: new Set(["integration"]),
+};
+function refinesStoredClass(stored, classified) {
+    return REFINABLE_STORED_CLASSES[stored]?.has(classified) === true;
+}
 function classifySequenceFailure(input) {
     const codes = [input.code, input.providerSubtype]
         .filter(Boolean)
@@ -205,6 +259,13 @@ function classifySequenceFailure(input) {
         /auth|permission|scope|credential|forbidden|unauthori[sz]ed|not[_-]?connected|connection[_-]?(?:invalid|expired)/i.test(codes)) {
         return "authorization_scope";
     }
+    // An action or tool OXYGEN called that the connected integration does not
+    // expose (`composio_action_not_found`, SignalFisher 2026-10-22: crm_task's
+    // HUBSPOT_CRM_OBJECTS_GET lookup). Not the lead's fault and not the
+    // connection's permissions: checked before the recipient and 4xx bands,
+    // which a gateway's "tool not found" status would otherwise land in.
+    if (INTEGRATION_ACTION_MISSING_CODE.test(codes))
+        return "integration";
     if (input.hardBounce === true ||
         /crm_record_(?:not_found|missing)|recipient|hard[_-]?bounce|invalid[_-]?(?:profile|recipient|member)|lead[_-]?not[_-]?found|already[_-]?(?:connected|invited)|not[_-]?eligible|cannot[_-]?(?:message|invite)/i.test(codes)) {
         return "recipient";
@@ -214,12 +275,13 @@ function classifySequenceFailure(input) {
         /crm_(?:record_|task_)(?:mapping|association|identity|property)|validation|invalid[_-]?request|bad[_-]?request|malformed|required[_-]?field|unsupported[_-]?(?:input|value)/i.test(codes)) {
         return "validation";
     }
+    // A Sequence action row that disappeared is OXYGEN's own bookkeeping.
     if (/action[_-]?not[_-]?found/i.test(codes))
         return "internal";
     if ((input.httpStatus !== null && input.httpStatus >= 500) ||
         (input.httpStatus === 404 && input.retryable === true) ||
         input.provider !== null ||
-        /provider|upstream|tool[_-]?unavailable|network|timeout|temporar(?:y|ily)[_-]?unavailable/i.test(codes)) {
+        /provider|upstream|tool[_-]?unavailable|network|timeout|temporar(?:y|ily)[_-]?unavailable|composio[_-]?(?:action|file[_-]?upload)[_-]?failed/i.test(codes)) {
         return "provider";
     }
     if (/^(?:TypeError|ReferenceError|RangeError|SyntaxError)$/i.test(input.errorName ?? "") ||

package/node_modules/@oxygen/shared/dist/sequence-lifecycle.d.ts

@@ -1,6 +1,32 @@
-/** Every lifecycle a person reads: the stored statuses plus the derived `completed`. */
-export declare const SEQUENCE_LIFECYCLES: readonly ["draft", "active", "completed", "paused", "archived"];
+/**
+ * Every lifecycle a person reads: the stored statuses plus the derived
+ * `scheduled` and `completed`.
+ */
+export declare const SEQUENCE_LIFECYCLES: readonly ["draft", "scheduled", "active", "completed", "paused", "archived"];
 export type SequenceLifecycle = (typeof SEQUENCE_LIFECYCLES)[number];
+/** How far ahead a scheduled start may be set. */
+export declare const SEQUENCE_START_AT_MAX_DAYS = 30;
+/**
+ * The stored scheduled start (`settings.start_at`) when it is still ahead of
+ * `now`, else null. A past, absent or unreadable value means the Sequence runs
+ * as soon as it is active.
+ */
+export declare function sequenceScheduledStartAt(settings: {
+    start_at?: unknown;
+} | null | undefined, now?: Date): Date | null;
+/**
+ * Read a requested scheduled start: an ISO 8601 timestamp with a timezone
+ * (`Z` or `±hh:mm`), in the future and at most {@link SEQUENCE_START_AT_MAX_DAYS}
+ * days ahead. Returns the canonical UTC form (`toISOString`) that is stored, so
+ * every stored value is one Postgres can cast.
+ */
+export declare function parseSequenceStartAt(value: unknown, now?: Date): {
+    ok: true;
+    startAt: string;
+} | {
+    ok: false;
+    message: string;
+};
 /**
  * The lifecycle word a person reads for a Sequence.
  *
@@ -10,10 +36,15 @@ export type SequenceLifecycle = (typeof SEQUENCE_LIFECYCLES)[number];
  * is the derived operational state; `drained` means every enrolled lead has
  * reached an end. An active Sequence in that state reads as completed.
  *
+ * An active Sequence whose `settings.start_at` is still ahead reads as
+ * scheduled: it was started, but the planner contacts nobody before then.
+ *
  * Derived on read and never stored: operational health is one derived
  * contract, not another lifecycle (docs/primitives/sequences.md, 2026-08-26).
  * Enrolling new leads makes the same Sequence read as active again with no
  * transition to undo. A paused Sequence stays paused, because someone decided
  * that and the decision still holds.
  */
-export declare function sequenceDisplayStatus<Status extends string>(status: Status, operationalState: string | null | undefined): Status | "completed";
+export declare function sequenceDisplayStatus<Status extends string>(status: Status, operationalState: string | null | undefined, settings?: {
+    start_at?: unknown;
+} | null, now?: Date): Status | "completed" | "scheduled";