@oxygen-agent/cli 1.1010.650 → 1.1010.905

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

@@ -1,5 +1,7 @@
-import { AUTOMATION_ACTION_CREDITS as SNAPSHOT_AUTOMATION_ACTION_CREDITS, CREDITS_PER_USD as SNAPSHOT_CREDITS_PER_USD, PRICING_PLAN_SNAPSHOT, TOPUP_USD_CENTS_PER_100_CREDITS as SNAPSHOT_TOPUP_USD_CENTS_PER_100_CREDITS, } from "./pricing-snapshot.generated.js";
+import { CREDITS_PER_USD as SNAPSHOT_CREDITS_PER_USD, PRICING_PLAN_SNAPSHOT, MANAGED_INBOX_CREDITS_PER_MONTH as SNAPSHOT_MANAGED_MAILBOX_CREDITS_PER_MONTH, SENDING_MAILBOX_CREDITS_PER_MONTH as SNAPSHOT_SENDING_MAILBOX_CREDITS_PER_MONTH, } from "./pricing-snapshot.generated.js";
+import { currentSubscriptionGrantSlice, dueSubscriptionGrantSlices, } from "./billing-anchors.js";
 import { freeTierEntitlementEnabled } from "./plan-capabilities.js";
+import { AUTOMATION_STEP_CREDITS_REPRICING, AUTOMATION_STEPS_COUNT_TOWARD_RUN_CAP_REPRICING, isRepricingInForce, BYOK_PLATFORM_FEE_REPRICING, OXYGEN_49_BYOK_REPRICING, repricedValue, TOPUP_RATE_REPRICING, } from "./repricing.js";
 import { asRecordOrNull } from "./type-guards.js";
 export const WEEKLY_USAGE_WINDOW_DAYS = 7;
 export const BILLING_CURRENCIES = ["usd"];
@@ -34,10 +36,10 @@ export const OXYGEN_PLAN_KEYS = [
 // person's booking page into every public pricing card.
 export const CONTACT_SALES_URL = "mailto:priority@oxygen-agent.com";
 // One Oxygen credit is worth $0.01 of managed work: $1 = 100 credits.
-// Subscription plans convert at face value — every subscription dollar grants
-// exactly 100 credits — while on-demand top-up packs price the same credit
-// at $1.25 per 100, making subscription credits exactly 20% cheaper than
-// credits bought on demand.
+// Subscription plans convert at least at face value — every subscription dollar
+// grants 100 credits, and the $499, $999 and $1,999 plans add a volume bonus on
+// top (see planVolumeBonusCredits) — while on-demand top-ups price the same
+// credit higher, so subscription credits are always the cheaper way to buy.
 //
 // Re-denominated from $1 = 1,000 credits on 2026-09-19. That was a PURE unit
 // change: every credit-denominated price divided by 10 in the same release, so
@@ -48,11 +50,23 @@ export const CONTACT_SALES_URL = "mailto:priority@oxygen-agent.com";
 // disagreed every markup-derived price would be silently wrong by the ratio.
 // Change them in packages/control-db/src/pricing/seed.ts.
 export const CREDITS_PER_USD = SNAPSHOT_CREDITS_PER_USD;
-export const TOPUP_USD_CENTS_PER_100_CREDITS = SNAPSHOT_TOPUP_USD_CENTS_PER_100_CREDITS;
-// On-demand purchases start at the original fixed packs' $10 floor and run up
-// to a $1,250 ceiling, in any 100-credit increment. The ceiling is a
-// single-checkout guard rail, not a spend cap: a workspace that needs more
-// tops up again (purchased credits never expire).
+/**
+ * US cents per 100 on-demand top-up credits right now. The rate rises from 125
+ * ($1.25) to the seed's 130 ($1.30) at the 2026-09 repricing's effective instant
+ * (decision 1.5, slice S10), so it is read per call through the switch and never
+ * from the snapshot: plan credits are then at least 23% cheaper (1 - 1.00/1.30),
+ * where they were 20% cheaper at $1.25. A page that shows it resolves it on the
+ * server and passes the number down, because a client bundle cannot read the
+ * switch.
+ */
+export function creditTopupUsdCentsPer100(options = {}) {
+    return repricedValue(TOPUP_RATE_REPRICING, options);
+}
+// On-demand purchases run from 800 to 100,000 credits in any 100-credit
+// increment ($10.00 to $1,250 at $1.25 per 100; $10.40 to $1,300 at $1.30). The
+// ceiling is a single-checkout guard rail, not a spend cap: a workspace that
+// needs more tops up again (purchased credits never expire). The range and step
+// are unchanged by the 2026-09 repricing (proposal P-7).
 export const CREDIT_TOPUP_MIN_CREDITS = 800;
 export const CREDIT_TOPUP_MAX_CREDITS = 100_000;
 export const CREDIT_TOPUP_STEP_CREDITS = 100;
@@ -65,8 +79,8 @@ export function isValidCreditTopupCredits(credits) {
 }
 /**
  * A shortfall expressed as an amount `oxygen billing topup` will actually SELL:
- * rounded up onto the 1,000-credit step and clamped into the purchasable
- * [8,000 .. 1,000,000] band. A next_action (or an alert email) naming a number the
+ * rounded up onto CREDIT_TOPUP_STEP_CREDITS (100) and clamped into the purchasable
+ * [CREDIT_TOPUP_MIN_CREDITS .. CREDIT_TOPUP_MAX_CREDITS] band (800 .. 100,000). A next_action (or an alert email) naming a number the
  * top-up route refuses with `invalid_topup_amount` is not a next action, it is a
  * second dead end during the incident it exists to end.
  *
@@ -83,16 +97,87 @@ export function creditTopupAmountForShortfall(credits) {
     const stepped = Math.ceil(credits / CREDIT_TOPUP_STEP_CREDITS) * CREDIT_TOPUP_STEP_CREDITS;
     return Math.min(CREDIT_TOPUP_MAX_CREDITS, Math.max(CREDIT_TOPUP_MIN_CREDITS, stepped));
 }
-export function creditTopupUsdCents(credits) {
+/** Price of a custom top-up at the rate in force now (`creditTopupUsdCentsPer100`). */
+export function creditTopupUsdCents(credits, options = {}) {
+    return creditTopupUsdCentsAtRate(credits, creditTopupUsdCentsPer100(options));
+}
+/**
+ * Price of a custom top-up at an explicit rate. A checkout session records the
+ * rate it was quoted at (`CREDIT_TOPUP_RATE_METADATA_KEY`), and fulfillment
+ * re-prices it at THAT rate, never the rate in force when Stripe confirms the
+ * payment: a session opened before a rate change and paid after it must still
+ * be credited.
+ */
+export function creditTopupUsdCentsAtRate(credits, usdCentsPer100) {
     if (!isValidCreditTopupCredits(credits))
         return null;
-    return (credits / 100) * TOPUP_USD_CENTS_PER_100_CREDITS;
+    if (!Number.isInteger(usdCentsPer100) || usdCentsPer100 <= 0)
+        return null;
+    return (credits / 100) * usdCentsPer100;
+}
+/** Checkout-session metadata key carrying the rate a top-up was quoted at. */
+export const CREDIT_TOPUP_RATE_METADATA_KEY = "usd_cents_per_100";
+/**
+ * Every top-up rate (US cents per 100 credits) a checkout has been or can be
+ * minted at. Append when the rate changes; never remove one, because an unpaid
+ * session quoted at it can still be paid. The first entry is also the rate of
+ * sessions created before the rate was written into their metadata.
+ *
+ * 130 is the 2026-09 rate (decision 1.5). It is listed before the switch's
+ * instant as well, so a session minted after the instant is still credited if
+ * an operator rolls the switch back before the customer pays. Accepting a rate
+ * higher than the one in force can never credit a purchase cheaply.
+ */
+export const CREDIT_TOPUP_SOLD_USD_CENTS_PER_100 = [125, 130];
+export const CREDIT_TOPUP_LEGACY_USD_CENTS_PER_100 = CREDIT_TOPUP_SOLD_USD_CENTS_PER_100[0];
+/**
+ * Whether fulfillment may price a session at `usdCentsPer100`: a rate OXYGEN has
+ * sold at, or the rate in force now. Anything else is metadata no OXYGEN server
+ * wrote, and it is refused rather than credited at a cheaper rate.
+ */
+export function isAcceptedCreditTopupRate(usdCentsPer100, currentUsdCentsPer100 = creditTopupUsdCentsPer100()) {
+    if (!Number.isInteger(usdCentsPer100) || usdCentsPer100 <= 0)
+        return false;
+    return usdCentsPer100 === currentUsdCentsPer100
+        || CREDIT_TOPUP_SOLD_USD_CENTS_PER_100.includes(usdCentsPer100);
+}
+/**
+ * Credits one workflow step costs right now. Every step a live run executes
+ * (a manifest step, a billable graph node, a recipe checkpoint, the durable
+ * recipe runtime) draws this from the one credit pool; rows written inside a run
+ * are free (repricing 2026-09, decisions 6.1 and 6.2). Seed key:
+ * charge.automation.action.
+ *
+ * The step price rises 0.001 → 0.05 at the repricing's effective instant (S07),
+ * so it is read per call through the switch and never from the snapshot. A page
+ * that shows it resolves it on the server and passes the number down.
+ */
+export function automationStepCredits(options = {}) {
+    return repricedValue(AUTOMATION_STEP_CREDITS_REPRICING, options);
+}
+/**
+ * Credits one provider call made with the customer's own API key (BYOK) costs
+ * right now: the platform fee of decision 6.3. The vendor bills the call to the
+ * customer's own account; this is OXYGEN's fee for running it. Seed key:
+ * charge.byok.platform_fee.
+ *
+ * 0 until the repricing's effective instant (S07), then 0.05, so it is read per
+ * call through the switch and never from the snapshot. Every BYOK provider call
+ * is admitted and captured at this price by `chargeByokCall`
+ * (`@oxygen/integrations`).
+ */
+export function byokPlatformFeeCredits(options = {}) {
+    return repricedValue(BYOK_PLATFORM_FEE_REPRICING, options);
+}
+/**
+ * Whether the step credits a live run executes count toward its approved
+ * `max_credits` and a trigger's per-delivery ceiling (proposal P-45). Dark until
+ * the step price rises with it: counting 0.001 steps would only tighten ceilings
+ * customers already approved.
+ */
+export function automationStepsCountTowardRunCap(options = {}) {
+    return repricedValue(AUTOMATION_STEPS_COUNT_TOWARD_RUN_CAP_REPRICING, options);
 }
-// Workflow/automation actions (steps, tool calls, row writes, retries) draw
-// from the same credit pool at a flat capacity-guard rate — the old separate
-// monthly action allowance + USD overage meter economy is retired (2026-07-14).
-// Seed key: charge.automation.action.
-export const AUTOMATION_ACTION_CREDITS = SNAPSHOT_AUTOMATION_ACTION_CREDITS;
 // ---------------------------------------------------------------------------
 // FIXED (committed) credit commitments — recurring per-resource monthly charges
 // ---------------------------------------------------------------------------
@@ -122,26 +207,47 @@ export const CREDIT_COMMITMENT_KINDS = [
     "deliverability_unit",
     "linkedin_account",
     "whatsapp_account",
+    // Repricing 2026-09 (S20, decisions 2.2 and 2.4). Priced in the pricing seed
+    // (seat.x_account, seat.phone_number) and reserve nothing until the
+    // repricing's effective-date switch.
+    "x_account",
+    "phone_number",
 ];
 /**
  * Sequencer platform fee per CONNECTED SENDING MAILBOX per month, in credits
  * ($1.00). Charged on EVERY mailbox wired to the sequencer — BYOK/self-connected
  * Gmail and Microsoft inboxes included — and it STACKS on Oxygen-sold mailboxes,
- * which additionally pay their own mailbox/warmup/placement lines.
+ * which additionally pay their own mailbox/warmup/placement lines. Read from the
+ * pricing seed (`commitment.sending_mailbox`) through the generated snapshot, so
+ * there is one definition of the price.
  */
-export const SENDING_MAILBOX_MONTHLY_CREDITS = 100;
+export const SENDING_MAILBOX_MONTHLY_CREDITS = SNAPSHOT_SENDING_MAILBOX_CREDITS_PER_MONTH;
 /**
- * Oxygen-sold managed mailbox per month, in credits ($3.00). Flat, superseding
- * the dynamic vendor-COGS x 1.25 quote for the recurring mailbox line.
+ * Grace window after a commitment goes past_due before the account disconnects.
+ * Repricing 2026-09 decision 2.8: sending from the account pauses at once, and
+ * after 7 days without funds the account disconnects (replacing the earlier 14
+ * days with no auto-cancel). The pause and the disconnect sweep are slice S23.
  */
-export const MANAGED_MAILBOX_MONTHLY_CREDITS = 300;
+export const COMMITMENT_PAST_DUE_GRACE_DAYS = 7;
 /**
- * Grace window after a commitment goes past_due before the owning subsystem may
- * suspend the resource. Notify -> pause -> lapse; never auto-cancel. Aligned with
- * the subscription entitlement grace so a customer never hits two different
- * clocks for the same missed payment.
+ * P-15 (PROPOSED default, awaiting ratification): what "disconnect" means for a
+ * rented phone number. Releasing a number at the carrier is irreversible, so it is
+ * suspended at COMMITMENT_PAST_DUE_GRACE_DAYS (it already cannot dial while past
+ * due) and released only after this many days without funds.
  */
-export const COMMITMENT_PAST_DUE_GRACE_DAYS = 14;
+export const PHONE_NUMBER_PAST_DUE_RELEASE_DAYS = 30;
+const GRACE_DAY_MS = 24 * 60 * 60 * 1000;
+export function commitmentGraceSchedule(kind, pastDueSince) {
+    const graceEnds = new Date(pastDueSince.getTime() + COMMITMENT_PAST_DUE_GRACE_DAYS * GRACE_DAY_MS);
+    if (kind === "phone_number") {
+        return {
+            teardown: "release",
+            teardownAt: new Date(pastDueSince.getTime() + PHONE_NUMBER_PAST_DUE_RELEASE_DAYS * GRACE_DAY_MS),
+            suspendedAt: graceEnds,
+        };
+    }
+    return { teardown: "disconnect", teardownAt: graceEnds, suspendedAt: null };
+}
 /**
  * Reconnect window in which an ENDED commitment resumes instead of starting a new
  * one. The single most important anti-double-charge rule: a Unipile re-auth, a
@@ -178,7 +284,10 @@ export function ratifiedCommitmentCredits(kind) {
         case "sending_mailbox":
             return SENDING_MAILBOX_MONTHLY_CREDITS;
         case "managed_mailbox":
-            return MANAGED_MAILBOX_MONTHLY_CREDITS;
+            // The pricing seed's `commitment.managed_mailbox`, the one definition (S32).
+            // Before the 2026-09 switch the price in force is lower: resolve it with
+            // repricedChargeCredits from ./repricing.js.
+            return SNAPSHOT_MANAGED_MAILBOX_CREDITS_PER_MONTH;
         // Ratified in @oxygen/control-db (MAILBOX_WARMUP_MONTHLY_CREDITS /
         // DELIVERABILITY_UNIT_MONTHLY_CREDITS) since 2026-07-29, alongside the seat
         // prices below. @oxygen/shared cannot import control-db, so these still
@@ -187,24 +296,75 @@ export function ratifiedCommitmentCredits(kind) {
         case "mailbox_warmup":
         case "deliverability_unit":
             return null;
-        // Signed in control-db (LINKEDIN_ACCOUNT_MONTHLY_CREDITS /
-        // WHATSAPP_ACCOUNT_MONTHLY_CREDITS) — control-db cannot import @oxygen/shared,
-        // so the constants live there and the caller passes them.
+        // Connected-account reservations are priced in the pricing seed
+        // (seat.*_account, seat.phone_number) and resolved, through the 2026-09
+        // repricing switch, by commitmentPrice in @oxygen/integrations.
         case "linkedin_account":
         case "whatsapp_account":
+        case "x_account":
+        case "phone_number":
             return null;
     }
 }
-export const CREDIT_TOPUP_PACKS = [
+/**
+ * The dollar packs sold at $1.25 per 100 credits, on offer until the 2026-09
+ * repricing's effective instant. The id is the pack's price in dollars.
+ */
+export const CREDIT_TOPUP_LEGACY_PACKS = [
     { id: "10", usdCents: 1_000, credits: 800 },
     { id: "25", usdCents: 2_500, credits: 2_000 },
     { id: "100", usdCents: 10_000, credits: 8_000 },
     { id: "250", usdCents: 25_000, credits: 20_000 },
 ];
+/**
+ * The credit-first packs on offer from the 2026-09 repricing's instant, at $1.30
+ * per 100 credits (decision 1.5; the pack set is PROPOSED P-7). Dollar packs at
+ * $1.30 would buy fractional credits ($10 → 769.2), so these fix the credits and
+ * the id names them. The ids are new on purpose: fulfillment credits a pack
+ * session `pack.credits` without re-checking its amount, so reusing '10' or '25'
+ * with a new price would credit an old unpaid session from the new table.
+ */
+export const CREDIT_TOPUP_PACKS_2026_09 = [
+    { id: "1000", usdCents: 1_300, credits: 1_000 },
+    { id: "2000", usdCents: 2_600, credits: 2_000 },
+    { id: "8000", usdCents: 10_400, credits: 8_000 },
+    { id: "20000", usdCents: 26_000, credits: 20_000 },
+];
+/** Every pack id a checkout session may carry, whichever table sold it. */
+export const CREDIT_TOPUP_KNOWN_PACKS = [
+    ...CREDIT_TOPUP_LEGACY_PACKS,
+    ...CREDIT_TOPUP_PACKS_2026_09,
+];
+/** The packs on offer now: the dollar packs until the switch, the credit-first packs from it. */
+export function creditTopupPacks(options = {}) {
+    return isRepricingInForce(options) ? CREDIT_TOPUP_PACKS_2026_09 : CREDIT_TOPUP_LEGACY_PACKS;
+}
+/**
+ * Any pack a session may name, with the credits and price it was SOLD at. Used by
+ * fulfillment, which must credit an old session its original credits whichever
+ * packs are on offer when Stripe confirms the payment.
+ */
 export function resolveCreditTopupPack(id) {
     if (!id)
         return null;
-    return CREDIT_TOPUP_PACKS.find((pack) => pack.id === id) ?? null;
+    return CREDIT_TOPUP_KNOWN_PACKS.find((pack) => pack.id === id) ?? null;
+}
+/**
+ * How the top-up route sells a pack id right now. A pack on offer sells at its
+ * own price. Any other known id (a dollar pack after the switch from an older
+ * CLI, or a credit-first pack before it) still works and buys the pack's credits
+ * as a custom amount at the rate in force, so an old client sees the current
+ * quote and never an old price. Null for an unknown id.
+ */
+export function quoteCreditTopupPack(id, options = {}) {
+    const pack = resolveCreditTopupPack(id);
+    if (!pack)
+        return null;
+    const offered = creditTopupPacks(options).some((candidate) => candidate.id === pack.id);
+    if (offered)
+        return { pack, offered, credits: pack.credits, usdCents: pack.usdCents };
+    const usdCents = creditTopupUsdCents(pack.credits, options);
+    return usdCents == null ? null : { pack, offered, credits: pack.credits, usdCents };
 }
 // Card-required free trial: every new signup chooses a self-serve Stripe plan,
 // gets TRIAL_CREDIT_GRANT credits (a value-demonstration budget sized to the
@@ -290,6 +450,86 @@ function planPricing(planKey) {
         byokEnabled: row.byokEnabled,
     };
 }
+/**
+ * The volume bonus of a plan (repricing 2026-09, decision 1.3): the monthly
+ * credits it grants above face value ($1 = 100 credits). +5% on $499 (52,395),
+ * +10% on $999 (109,890), +15% on $1,999 (229,885); $49-$199 stay flat.
+ *
+ * DERIVED from the seeded monthlyCredits rather than declared, so the schedule
+ * lives in one place (packages/control-db/src/pricing/seed.ts). Only the
+ * purchasable Oxygen rungs carry a bonus: a legacy plan whose credits exceed its
+ * price (launch_50 bought 20,000 credits for $50 under the old unit) is not a
+ * volume bonus, and a contact-sales plan has no face value.
+ */
+export function planVolumeBonusCredits(planKey) {
+    if (!planKey || !OXYGEN_PLAN_KEYS.includes(planKey))
+        return 0;
+    const { monthlyPriceCents, monthlyCredits } = planPricing(planKey);
+    if (monthlyPriceCents === null || monthlyCredits === null)
+        return 0;
+    const faceValueCredits = Math.round((monthlyPriceCents / 100) * CREDITS_PER_USD);
+    return Math.max(0, monthlyCredits - faceValueCredits);
+}
+/**
+ * The volume bonus inside one subscription grant of `monthlyCredits` on
+ * `planKey`: the plan's bonus when the grant is the plan's seeded allowance, and
+ * 0 when a metadata override replaced it (a custom allowance carries no
+ * schedule to defer). Grant writers pass this to grantSubscriptionCredits.
+ */
+export function subscriptionGrantVolumeBonusCredits(planKey, monthlyCredits) {
+    if (!planKey || typeof monthlyCredits !== "number")
+        return 0;
+    const bonus = planVolumeBonusCredits(planKey);
+    return bonus > 0 && planPricing(planKey).monthlyCredits === monthlyCredits ? bonus : 0;
+}
+/** The volume bonus as a whole percentage of face value: 5, 10, 15, or 0. */
+export function planVolumeBonusPercent(planKey) {
+    const bonus = planVolumeBonusCredits(planKey);
+    if (bonus === 0 || !planKey)
+        return 0;
+    const faceValueCredits = Math.round(((planPricing(planKey).monthlyPriceCents ?? 0) / 100) * CREDITS_PER_USD);
+    return faceValueCredits > 0 ? Math.round((bonus / faceValueCredits) * 100) : 0;
+}
+/**
+ * Agency partner bonus (repricing 2026-09, decision 9.1): a partner earns
+ * +15% of its plan's face value in bonus credits every month, on every Oxygen
+ * size from $99, on top of the volume bonus. The two percentages ADD (spec
+ * PROPOSED default P-1, option A of the agency-partner benchmark): the $1,999
+ * plan grants 229,885 + 29,985 = 259,870, never 229,885 x 1.15.
+ *
+ * The bonus is its own ledger line (category `partner_bonus`), never part of
+ * the plan's monthlyCredits, so it stays out of every limit or guard derived
+ * from the plan allowance (P-3, P-54, P-61).
+ */
+export const PARTNER_BONUS_PERCENT = 15;
+/** The smallest plan that earns the partner bonus: $99 a month. */
+export const PARTNER_BONUS_MINIMUM_MONTHLY_PRICE_CENTS = 9_900;
+/**
+ * The monthly partner bonus of a plan: 15% of face value ($1 = 100 credits),
+ * rounded half up to a whole credit (section 2's rounding rule). 0 for Free,
+ * $49, the grandfathered Starter/Pro/Team and older legacy plans, and the
+ * contact-sales plans (P-3: Oxygen sizes only).
+ */
+export function planPartnerBonusCredits(planKey) {
+    if (!planKey || !OXYGEN_PLAN_KEYS.includes(planKey))
+        return 0;
+    const { monthlyPriceCents } = planPricing(planKey);
+    if (monthlyPriceCents === null || monthlyPriceCents < PARTNER_BONUS_MINIMUM_MONTHLY_PRICE_CENTS)
+        return 0;
+    const faceValueCredits = Math.round((monthlyPriceCents / 100) * CREDITS_PER_USD);
+    return Math.round((faceValueCredits * PARTNER_BONUS_PERCENT) / 100);
+}
+/**
+ * The partner bonus that rides with one subscription grant of `monthlyCredits`
+ * on `planKey`: the plan's bonus when the grant is the plan's seeded allowance,
+ * 0 when a metadata override replaced it (a custom contract is priced by hand).
+ */
+export function subscriptionGrantPartnerBonusCredits(planKey, monthlyCredits) {
+    if (!planKey || typeof monthlyCredits !== "number")
+        return 0;
+    const bonus = planPartnerBonusCredits(planKey);
+    return bonus > 0 && planPricing(planKey).monthlyCredits === monthlyCredits ? bonus : 0;
+}
 /**
  * The monthly-credit feature bullet, DERIVED rather than written down.
  *
@@ -302,8 +542,12 @@ function monthlyCreditsFeature(planKey) {
     const credits = planPricing(planKey).monthlyCredits;
     if (credits === null)
         return "Custom monthly credits";
-    return `${credits.toLocaleString("en-US")} credits every month`;
+    const bonusPercent = planVolumeBonusPercent(planKey);
+    return bonusPercent > 0
+        ? `${credits.toLocaleString("en-US")} credits every month (${bonusPercent}% volume bonus)`
+        : `${credits.toLocaleString("en-US")} credits every month`;
 }
+const BRING_YOUR_OWN_KEYS_FEATURE = "Bring your own keys";
 export const BASE_PRICING_PLANS = {
     // The ENTRY tier since 2026-08-16, superseding the 2026-07-22 retirement that
     // left this as the unentitled fallback for churned / never-subscribed orgs.
@@ -327,10 +571,14 @@ export const BASE_PRICING_PLANS = {
         monthlyAutomationActions: null,
         automationOverageCentsPerMillion: null,
         automationOverageEnabledDefault: false,
-        description: "Your CRM, tables, and workflows — free forever. Credits pay for enrichment and AI; connecting a sender, publishing, managed email infrastructure, and your own provider keys need a plan.",
+        // Static text cannot read the credit gate, and once it is in force a free
+        // workspace may connect senders, publish and buy managed email on credits
+        // (repricing 2026-09, S22). So it names only what needs a plan either way;
+        // the gate-aware walls speak for the rest.
+        description: "Your CRM and tables — free forever. Credits pay for enrichment, AI and workflow steps; your own provider keys need a paid plan.",
         ctaLabel: "Upgrade",
         features: [
-            "CRM, Tables, Workflows, and Knowledge — unmetered",
+            "CRM, Tables, and Knowledge — unmetered; workflows pay per step",
             "Sequences: author, preview, and enroll",
             "Agents and Workspace Copilot",
             "Credits for enrichment and AI, topped up any time",
@@ -355,7 +603,7 @@ export const BASE_PRICING_PLANS = {
             monthlyCreditsFeature("oxygen_49"),
             "All integrations",
             "Workflows",
-            "Bring your own keys",
+            BRING_YOUR_OWN_KEYS_FEATURE,
             "Standard support",
         ],
     },
@@ -518,14 +766,15 @@ export function resolveSubscriptionEntitlement(input) {
             : { entitled: true, reason: "trialing", graceEndsAt: null };
     }
     if (input.status === "past_due") {
-        if (!input.currentPeriodStart) {
+        const graceStartsAt = pastDueGraceStart(input, now);
+        if (!graceStartsAt) {
             return {
                 entitled: false,
                 reason: "missing_past_due_period_start",
                 graceEndsAt: null,
             };
         }
-        const graceEndsAt = new Date(input.currentPeriodStart.getTime() + PAST_DUE_GRACE_DAYS * 24 * 60 * 60 * 1000);
+        const graceEndsAt = new Date(graceStartsAt.getTime() + PAST_DUE_GRACE_DAYS * 24 * 60 * 60 * 1000);
         return graceEndsAt.getTime() > now.getTime()
             ? { entitled: true, reason: "past_due_grace", graceEndsAt }
             : { entitled: false, reason: "past_due_grace_expired", graceEndsAt };
@@ -539,6 +788,35 @@ export function resolveSubscriptionEntitlement(input) {
     }
     return { entitled: false, reason: "missing_subscription", graceEndsAt: null };
 }
+/**
+ * Where a past-due subscription's grace starts (OXP-43.4).
+ *
+ * The grace used to count from `currentPeriodStart`. For a monthly plan that is
+ * the renewal whose payment failed, but a yearly plan's period start can be
+ * months back, so a yearly subscriber who went past due mid-year lost access at
+ * once. The grace now counts from `pastDueSince`, the instant the unpaid streak
+ * was first seen. A stamp older than the current period start is left over from
+ * an earlier streak, so the period start wins over it, which keeps a monthly
+ * plan's grace at least as long as it always was. A row without a stamp
+ * (written before the column existed) counts from the monthly credit slice
+ * `now` falls in: its period start for a monthly plan, exactly as before.
+ */
+function pastDueGraceStart(input, now) {
+    const periodStart = validDateOrNull(input.currentPeriodStart);
+    const pastDueSince = validDateOrNull(input.pastDueSince);
+    if (pastDueSince) {
+        return periodStart && periodStart.getTime() > pastDueSince.getTime()
+            ? periodStart
+            : pastDueSince;
+    }
+    const periodEnd = validDateOrNull(input.currentPeriodEnd);
+    return periodStart && periodEnd
+        ? dueSubscriptionGrantSlices(periodStart, periodEnd, now).at(-1)?.start ?? periodStart
+        : periodStart;
+}
+function validDateOrNull(value) {
+    return value instanceof Date && !Number.isNaN(value.getTime()) ? value : null;
+}
 /**
  * The six purchasable rungs, keyed by plan key.
  *
@@ -566,10 +844,31 @@ function oxygenRung(planKey) {
         ctaLabel: dollars === null ? "Get started" : `Choose $${dollars.toLocaleString("en-US")}`,
         features: [
             monthlyCreditsFeature(planKey),
-            ...BASE_PRICING_PLANS.oxygen.features.slice(1),
+            // A rung without BYOK in the seed ($49 since the 2026-09 repricing) must not
+            // promise it. The card follows the seed, not the S07 hold below: it
+            // under-promises to a $49 customer for the notice period rather than
+            // advertising an entitlement that ends at the effective date.
+            ...BASE_PRICING_PLANS.oxygen.features
+                .slice(1)
+                .filter((feature) => pricing.byokEnabled || feature !== BRING_YOUR_OWN_KEYS_FEATURE),
         ],
     };
 }
+/**
+ * The plan in force for `planKey` right now: the catalog row with every value the
+ * 2026-09 repricing holds back until its effective date put back.
+ *
+ * Only the $49 plan's BYOK entitlement is held here (S22, decision 2.7): the seed
+ * and snapshot already say `false`, and until the switch's instant the plan keeps
+ * the `true` it was sold with. The representative `oxygen` row carries the $49
+ * numbers, so it is held the same way.
+ */
+function withRepricingHolds(planKey, plan, options = {}) {
+    if (planKey !== "oxygen_49" && planKey !== "oxygen")
+        return plan;
+    const byokEnabled = repricedValue(OXYGEN_49_BYOK_REPRICING, options);
+    return byokEnabled === plan.byokEnabled ? plan : { ...plan, byokEnabled };
+}
 const LEGACY_PRICING_PLAN_OVERRIDES = {
     launch_50: {
         ...BASE_PRICING_PLANS.starter,
@@ -617,7 +916,7 @@ const LEGACY_PRICING_PLAN_OVERRIDES = {
         description: "Legacy Scale plan.",
     },
 };
-export function resolveBasePricingPlan(tier) {
+export function resolveBasePricingPlan(tier, options = {}) {
     if (!tier)
         return null;
     // Plan KEYS before tiers: `subscriptions.tier` stores "oxygen_499", and the
@@ -625,9 +924,9 @@ export function resolveBasePricingPlan(tier) {
     // customer paid for.
     const oxygen = OXYGEN_PLAN_OVERRIDES[tier];
     if (oxygen)
-        return oxygen;
+        return withRepricingHolds(tier, oxygen, options);
     if (tier in BASE_PRICING_PLANS) {
-        return BASE_PRICING_PLANS[tier];
+        return withRepricingHolds(tier, BASE_PRICING_PLANS[tier], options);
     }
     const legacy = LEGACY_PRICING_PLAN_OVERRIDES[tier];
     return legacy ?? null;
@@ -751,6 +1050,50 @@ export function getCurrentBillingCycleKey(date = new Date()) {
  * billing-anchor shift without admitting a quarterly or annual period.
  */
 export const CREDIT_CYCLE_MAX_PERIOD_DAYS = 35;
+/**
+ * Annual billing (Repricing 2026-09, decision 1.2): a year costs ten months of
+ * the monthly price, and the credits are still granted monthly.
+ */
+export const ANNUAL_BILLING_MONTHS_CHARGED = 10;
+/** The yearly price of a rung, in cents: ten times its monthly price. */
+export function annualPlanPriceCents(monthlyPriceCents) {
+    return monthlyPriceCents * ANNUAL_BILLING_MONTHS_CHARGED;
+}
+export const PLAN_BILLING_INTERVALS = ["month", "year"];
+/**
+ * A billing interval as a customer or an agent types it. `month`/`monthly` and
+ * `year`/`yearly`/`annual`/`annually` are accepted; anything else is null so the
+ * caller can refuse it by name instead of silently billing monthly.
+ */
+export function parsePlanBillingInterval(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "month" || normalized === "monthly")
+        return "month";
+    if (normalized === "year"
+        || normalized === "yearly"
+        || normalized === "annual"
+        || normalized === "annually") {
+        return "year";
+    }
+    return null;
+}
+/**
+ * What one charge of a rung costs on an interval, in cents: the monthly price,
+ * or ten months' price for a year.
+ */
+export function planChargeCents(monthlyPriceCents, interval) {
+    return interval === "year" ? annualPlanPriceCents(monthlyPriceCents) : monthlyPriceCents;
+}
+/**
+ * The per-month equivalent of one charge, in cents, rounded to the cent: $990 a
+ * year is $82.50 a month. This is what `recurring_monthly` reports, so a yearly
+ * plan is never compared as if it cost $990 a month.
+ */
+export function planMonthlyEquivalentCents(chargeCents, interval) {
+    return interval === "year" ? Math.round(chargeCents / 12) : chargeCents;
+}
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 function startOfUtcMonth(date) {
     return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1));
@@ -800,6 +1143,22 @@ export function isStripeManagedSubscription(subscription) {
         && metadata.off_stripe !== "true"
         && metadata.synthetic !== true);
 }
+/**
+ * Whether a Stripe subscription is scheduled to end. A classic-billing-mode
+ * period-end cancel sets `cancel_at_period_end`; a Billing Portal cancel on a
+ * flexible-billing-mode subscription sets only `cancel_at` (to the period end)
+ * and leaves `cancel_at_period_end` false (Stripe billing-mode comparison docs;
+ * reproduced in test mode 2026-09-26). Reading the boolean alone showed a
+ * Portal-cancelled plan as renewing. `cancel_at` on a subscription that has
+ * already ended records when it ended, not a pending cancellation, so it only
+ * counts while the subscription is still live.
+ */
+export function stripeSubscriptionCancellationScheduled(subscription) {
+    if (subscription.cancel_at_period_end === true)
+        return true;
+    const ended = subscription.status === "canceled" || subscription.status === "incomplete_expired";
+    return !ended && subscription.cancel_at != null;
+}
 /**
  * The window the credit-allowance bar measures: "this month's credits", resolved
  * to the boundary at which the plan's grant actually renews.
@@ -822,6 +1181,20 @@ export function resolveCreditCycleWindow(input) {
     const subscription = input.subscription;
     const start = subscription?.currentPeriodStart ?? null;
     const end = subscription?.currentPeriodEnd ?? null;
+    if (subscription?.billingInterval === "year"
+        && !subscription.offStripe
+        && start != null
+        && end != null) {
+        const slice = currentSubscriptionGrantSlice(start, end, now);
+        if (slice) {
+            return {
+                start: slice.start,
+                end: slice.end,
+                source: "subscription_period",
+                label: `${formatUtcDay(slice.start)} – ${formatUtcDay(slice.end)}`,
+            };
+        }
+    }
     const usesPeriod = subscription != null
         && !subscription.offStripe
         && start != null