@oxygen-agent/cli 1.1010.650 → 1.1010.721

package/node_modules/@oxygen/shared/dist/linkedin-sequences.d.ts

@@ -247,4 +247,118 @@ export declare function truncateLinkedInInviteNote(note: string, limit: number):
     truncated: boolean;
     originalLength: number;
 };
+export type LinkedInSenderLimits = {
+    invites_per_day: number;
+    invites_per_week: number;
+    messages_per_day: number;
+    inmails_per_day: number;
+    /**
+     * InMails in a rolling 30 days (today and the 29 before it, in the account's
+     * day). Checked under the same sender row lock as the weekly invite cap, so
+     * concurrent claims cannot both pass a stale sum.
+     */
+    inmails_per_month: number;
+    profile_views_per_day: number;
+    /**
+     * Invisible profile and company lookups (`users_get` with notify:false,
+     * `company_get`). The member is never notified, so these are reads, but
+     * Unipile relays LinkedIn's ~100 profile retrievals a day for them.
+     */
+    profile_lookups_per_day: number;
+    /** Skill endorsements. Used to share the follow cap. */
+    endorsements_per_day: number;
+    /**
+     * Sent-invitation withdrawals (the withdraw action itself, not the reads of
+     * the sent-invite list). LinkedIn blocks re-inviting a withdrawn member for
+     * three weeks; see the re-invite guard.
+     */
+    withdrawals_per_day: number;
+    /** Posts to the member's own feed, from every caller. Timing-exempt, never uncapped. */
+    posts_per_day: number;
+    follows_per_day: number;
+    likes_per_day: number;
+    comments_per_day: number;
+    total_actions_per_day: number;
+    min_action_spacing_seconds: number;
+    action_spacing_jitter_seconds: number;
+    interactive_min_spacing_seconds: number;
+    interactive_spacing_jitter_seconds: number;
+    /**
+     * Backstop on the interactive lane: how many human-paced sends an account may
+     * make in a rolling hour.
+     *
+     * Mostly redundant with messages_per_day (whose maximum is 40), and that is
+     * deliberate — it bounds BURST SHAPE rather than volume. Volume is already
+     * capped; this stops the whole daily allowance being spent in four minutes if
+     * the interactive classification is ever wrong, which is the one failure mode
+     * the daily cap cannot see.
+     */
+    interactive_sends_per_hour: number;
+    relations_reads_per_day: number;
+    messages_reads_per_day: number;
+    searches_per_day: number;
+    sales_nav_search_results_per_day: number;
+    api_reads_per_day: number;
+    total_reads_per_day: number;
+    relations_ingest_reads_per_day: number;
+    api_ingest_reads_per_day: number;
+    messages_ingest_reads_per_day: number;
+    /**
+     * Network-capture read budgets: the two-phase allowance for enumerating an
+     * account's OWN 1st-degree connections and followers into a workspace table.
+     *
+     * Two keys, not one, because Unipile's own guidance for the relations list is
+     * explicitly two-phase: a heavier initial sync, then "retrieving the first page
+     * only a few times a day with randomly spaced intervals". One flat number would
+     * either make the first walk take weeks or leave a steady-state drip reading far
+     * more than it needs forever. Both still meter as `relations_ingest_read` against
+     * one shared daily counter, so an account cannot spend both budgets at once.
+     */
+    network_backfill_reads_per_day: number;
+    network_delta_reads_per_day: number;
+};
+/**
+ * Safe defaults for LinkedIn action limits.
+ *
+ * PROVENANCE, because these numbers get copied and should not be laundered into
+ * authority they do not have:
+ *
+ * - The 20-25/day connection-request range and the 40/day message posture come
+ *   from third-party operator playbooks describing HeyReach-style outreach, NOT
+ *   from HeyReach. HeyReach's own sending-limits article publishes no numbers at
+ *   all — it only says you configure per-action daily limits and that it "will
+ *   always try to reach those limits". An earlier version of this comment cited
+ *   HeyReach directly; that attribution was wrong.
+ * - The READ budgets (relations/api/messages, ingest and network capture) are
+ *   anchored on Unipile's documented per-route recommendations, which relay
+ *   LinkedIn's own limits: ~80-100 invitations/day, ~100 profile retrievals/day,
+ *   and 100/day per account for "all other routes" — the bucket users_relations
+ *   and users_followers fall into. Unipile enforces none of it; cadence is ours
+ *   to choose, and exceeding returns 429/500 and can disconnect the account.
+ *   See developer.unipile.com/docs/provider-limits-and-restrictions.
+ *
+ * The weekly invite and 200-total-action guards stay enforced independently.
+ * Users can lower limits per account, but never raise them above
+ * LINKEDIN_SENDER_LIMIT_MAXIMUMS.
+ */
+export declare const LINKEDIN_SENDER_LIMIT_DEFAULTS: LinkedInSenderLimits;
+export declare const LINKEDIN_SENDER_LIMIT_MAXIMUMS: LinkedInSenderLimits;
+/**
+ * LinkedIn refuses a new invitation to a member whose earlier invitation from
+ * the same account was withdrawn, for about three weeks. OXYGEN records every
+ * withdrawal it makes and refuses the re-invite itself for this long, so the
+ * refusal is ours (with a reset time) instead of a provider 422.
+ */
+export declare const LINKEDIN_REINVITE_COOLDOWN_DAYS = 21;
+/**
+ * Whether a refused invitation is LinkedIn's re-invite cooldown: Unipile answers
+ * HTTP 422 with the `cannot_resend_yet` error type. Anchored on the type, with
+ * the message as a fallback for the provider shapes that carry the type only in
+ * the sentence. Pure and total.
+ */
+export declare function isLinkedInReinviteCooldownRefusal(input: {
+    status: number | null;
+    providerType: string | null;
+    providerMessage: string | null;
+}): boolean;
 export {};

package/node_modules/@oxygen/shared/dist/linkedin-sequences.js

@@ -196,3 +196,153 @@ export function truncateLinkedInInviteNote(note, limit) {
     const kept = cut === 0 ? head : head.slice(0, cut);
     return { note: kept.join("").trimEnd(), truncated: true, originalLength };
 }
+/**
+ * Safe defaults for LinkedIn action limits.
+ *
+ * PROVENANCE, because these numbers get copied and should not be laundered into
+ * authority they do not have:
+ *
+ * - The 20-25/day connection-request range and the 40/day message posture come
+ *   from third-party operator playbooks describing HeyReach-style outreach, NOT
+ *   from HeyReach. HeyReach's own sending-limits article publishes no numbers at
+ *   all — it only says you configure per-action daily limits and that it "will
+ *   always try to reach those limits". An earlier version of this comment cited
+ *   HeyReach directly; that attribution was wrong.
+ * - The READ budgets (relations/api/messages, ingest and network capture) are
+ *   anchored on Unipile's documented per-route recommendations, which relay
+ *   LinkedIn's own limits: ~80-100 invitations/day, ~100 profile retrievals/day,
+ *   and 100/day per account for "all other routes" — the bucket users_relations
+ *   and users_followers fall into. Unipile enforces none of it; cadence is ours
+ *   to choose, and exceeding returns 429/500 and can disconnect the account.
+ *   See developer.unipile.com/docs/provider-limits-and-restrictions.
+ *
+ * The weekly invite and 200-total-action guards stay enforced independently.
+ * Users can lower limits per account, but never raise them above
+ * LINKEDIN_SENDER_LIMIT_MAXIMUMS.
+ */
+export const LINKEDIN_SENDER_LIMIT_DEFAULTS = {
+    invites_per_day: 20,
+    invites_per_week: 100,
+    messages_per_day: 40,
+    inmails_per_day: 10,
+    // Competitors cap open-profile InMail near 800/month; 400 leaves headroom.
+    inmails_per_month: 400,
+    profile_views_per_day: 50,
+    profile_lookups_per_day: 80,
+    endorsements_per_day: 5,
+    withdrawals_per_day: 10,
+    // Matches the order of magnitude of a busy human poster; the publishing
+    // scheduler's own 25-per-24h ceiling stays a second guard.
+    posts_per_day: 10,
+    follows_per_day: 20,
+    likes_per_day: 20,
+    comments_per_day: 5,
+    total_actions_per_day: 150,
+    min_action_spacing_seconds: 300,
+    action_spacing_jitter_seconds: 300,
+    // 1s, no jitter: a person working their own inbox should never meet this gate.
+    // It exists only to stop a genuine burst — a stuck key, a runaway client — from
+    // firing an account's whole hour in a second, and to keep the per-account row
+    // lock (and with it the hourly counter) in play. Jitter is 0 deliberately: the
+    // variance in human sending is the human, and adding 0-5s on top only makes the
+    // product feel slow. Non-zero spacing is still required — see the fast-path note
+    // in reserveLinkedInSenderActionSlot.
+    interactive_min_spacing_seconds: 1,
+    interactive_spacing_jitter_seconds: 0,
+    // The primary bound on human sending now that it no longer claims the daily
+    // message cap. 200/hour is ~3/minute sustained: never felt by someone answering
+    // their inbox, and still a hard ceiling if the interactive classification is
+    // ever wrong.
+    interactive_sends_per_hour: 200,
+    // Conservative read budgets: roughly human-speed usage. Bulk scraping
+    // (full contact-list exports, whole-inbox pulls, search harvesting) is
+    // impossible by default — the pattern that gets accounts banned.
+    relations_reads_per_day: 20,
+    messages_reads_per_day: 200,
+    searches_per_day: 20,
+    sales_nav_search_results_per_day: 1000,
+    api_reads_per_day: 200,
+    total_reads_per_day: 1000,
+    // Conservative ingestion drips: a large network/history import spreads over
+    // many days rather than bursting, and stays well within total_reads_per_day.
+    // History backfill is the slowest drip (full thread walks are the most
+    // ban-sensitive bulk read), so its default is the tightest of the three.
+    relations_ingest_reads_per_day: 15,
+    api_ingest_reads_per_day: 20,
+    messages_ingest_reads_per_day: 10,
+    // Network capture, phase 1: 40% of Unipile's documented ~100/day recommendation
+    // for these routes. At 50 members a page that is ~2,000 people/day, so a typical
+    // network lands in days rather than weeks while leaving most of the account's
+    // daily read headroom unused.
+    network_backfill_reads_per_day: 40,
+    // Phase 2, once the walk is exhausted: Unipile's "first page a few times a day".
+    // New connections and followers arrive at the TOP of both listings, so a handful
+    // of first-page reads catches them all; the drip re-walks deeper only if it finds
+    // a full page of new people.
+    network_delta_reads_per_day: 4,
+};
+export const LINKEDIN_SENDER_LIMIT_MAXIMUMS = {
+    invites_per_day: 30,
+    invites_per_week: 150,
+    messages_per_day: 40,
+    // Lowered 40 → 25 and 150 → 100 (2026-09-26, founder decision "add missing
+    // caps + tighten"): operator playbooks put InMail at ≤25/day and profile views
+    // at 50-100. Stored overrides above these clamp at read time.
+    inmails_per_day: 25,
+    inmails_per_month: 800,
+    profile_views_per_day: 100,
+    // Unipile relays ~100 profile retrievals a day as LinkedIn's own ceiling.
+    profile_lookups_per_day: 100,
+    endorsements_per_day: 10,
+    withdrawals_per_day: 20,
+    posts_per_day: 25,
+    follows_per_day: 50,
+    likes_per_day: 50,
+    // Lowered 50 → 20 (2026-09-25): public comments are the most visible automated
+    // signal an account emits, and the one LinkedIn's inauthentic-engagement
+    // enforcement keys on. Stored overrides above this clamp at read time.
+    comments_per_day: 20,
+    total_actions_per_day: 200,
+    min_action_spacing_seconds: 3600,
+    action_spacing_jitter_seconds: 1800,
+    interactive_min_spacing_seconds: 3600,
+    interactive_spacing_jitter_seconds: 1800,
+    // Lowered 1000 → 300 (2026-09-25): 5/minute sustained is still far above
+    // anyone answering their own inbox, and bounds a misclassified bulk send.
+    interactive_sends_per_hour: 300,
+    relations_reads_per_day: 100,
+    messages_reads_per_day: 600,
+    searches_per_day: 100,
+    sales_nav_search_results_per_day: 1000,
+    api_reads_per_day: 1000,
+    total_reads_per_day: 2000,
+    relations_ingest_reads_per_day: 100,
+    api_ingest_reads_per_day: 200,
+    messages_ingest_reads_per_day: 200,
+    // 100/day is Unipile's own documented recommendation for "all other routes",
+    // which is the bucket users_relations and users_followers fall into. Our hard
+    // maximum is exactly the vendor's number and must not be raised above it.
+    network_backfill_reads_per_day: 100,
+    network_delta_reads_per_day: 20,
+};
+// ===== Re-invite cooldown =====
+/**
+ * LinkedIn refuses a new invitation to a member whose earlier invitation from
+ * the same account was withdrawn, for about three weeks. OXYGEN records every
+ * withdrawal it makes and refuses the re-invite itself for this long, so the
+ * refusal is ours (with a reset time) instead of a provider 422.
+ */
+export const LINKEDIN_REINVITE_COOLDOWN_DAYS = 21;
+/**
+ * Whether a refused invitation is LinkedIn's re-invite cooldown: Unipile answers
+ * HTTP 422 with the `cannot_resend_yet` error type. Anchored on the type, with
+ * the message as a fallback for the provider shapes that carry the type only in
+ * the sentence. Pure and total.
+ */
+export function isLinkedInReinviteCooldownRefusal(input) {
+    if (input.status !== 422)
+        return false;
+    if (typeof input.providerType === "string" && /(?:^|\/)cannot_resend_yet$/u.test(input.providerType.trim()))
+        return true;
+    return typeof input.providerMessage === "string" && /\bcannot_resend_yet\b/u.test(input.providerMessage);
+}

package/node_modules/@oxygen/shared/dist/otlp-log-sink.js

@@ -1,5 +1,7 @@
 import { log } from "./log.js";
 import { resolveDeployEnv } from "./deploy-env.js";
+import { processResourceIdentity } from "./process-resource.js";
+import { OXYGEN_VERSION } from "./version.js";
 import { sanitizeLogFields } from "./redaction.js";
 import { trace } from "@opentelemetry/api";
 import { operationalLogSnapshot } from "./operational-telemetry.js";
@@ -44,6 +46,7 @@ async function rejectedRecords(response, batchLength) {
         reader.releaseLock();
     }
 }
+const OTEL_TRACE_ID = /^[a-f\d]{32}$/i;
 // OTLP severity numbers (logs data model): the base of each 4-value band.
 const SEVERITY_NUMBERS = { debug: 5, info: 9, warn: 13, error: 17 };
 // Set by log() on every record; they become the OTLP record's own fields rather
@@ -197,6 +200,10 @@ export function createOtlpLogSink(options) {
             ?? process.env.NODE_ENV
             ?? null,
         "deployment.sha": process.env.OXYGEN_GIT_SHA ?? process.env.VERCEL_GIT_COMMIT_SHA,
+        "service.version": OXYGEN_VERSION,
+        // host.name + service.instance.id: which box and which process emitted a
+        // line, the same identity the trace/metric resources now carry.
+        ...processResourceIdentity(),
         ...resourceOverrides,
     });
     const queue = [];
@@ -277,9 +284,19 @@ export function createOtlpLogSink(options) {
             droppedOverflow += 1;
         }
         const activeSpan = trace.getActiveSpan()?.spanContext();
+        // A request correlation id that is not an OTel trace id (the CLI's UUID
+        // `x-oxygen-trace-id`) cannot be the record's traceId, but it is the one key
+        // a customer can quote; keep it as an attribute instead of discarding it,
+        // and let the active span supply the real trace/span ids.
+        const requestTraceId = typeof record.trace_id === "string" && record.trace_id !== ""
+            && !OTEL_TRACE_ID.test(record.trace_id) ? record.trace_id : null;
+        const { trace_id: _requestTraceId, ...withoutRequestTraceId } = record;
+        const base = requestTraceId
+            ? { ...withoutRequestTraceId, "oxygen.request_trace_id": requestTraceId }
+            : record;
         queue.push(operationalLogSnapshot(sanitizeLogFields({
-            ...record,
-            ...(activeSpan && (!record.trace_id || record.trace_id === activeSpan.traceId)
+            ...base,
+            ...(activeSpan && (requestTraceId || !record.trace_id || record.trace_id === activeSpan.traceId)
                 ? { trace_id: activeSpan.traceId, span_id: activeSpan.spanId }
                 : {}),
         })));

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

@@ -0,0 +1,118 @@
+import { type LimitsTier } from "./plan-limits.js";
+import type { RepricingOptions } from "./repricing.js";
+/**
+ * The seven plan bands of the 2026-09 repricing (spec § 4, slice S06): free
+ * plus one band per Oxygen plan size. They sit BESIDE the five-rung
+ * `LimitsTier`, which cannot tell $49 from $99 or $199 from $499, so any limit
+ * that differs between those sizes (storage, the per-delivery spend default)
+ * is resolved from the band instead of the rung.
+ *
+ * A band never changes a limit by itself. Until a limit is re-keyed onto the
+ * band, it keeps reading its rung, and `PLAN_BAND_LIMITS_TIER` says which rung
+ * that is.
+ */
+export type PlanBand = "free" | "49" | "99" | "199" | "499" | "999" | "1999";
+export declare const PLAN_BAND_ORDER: readonly PlanBand[];
+/** The limits rung each band enforces at today. */
+export declare const PLAN_BAND_LIMITS_TIER: Readonly<Record<PlanBand, LimitsTier>>;
+/**
+ * PROPOSED (P-57, repricing spec § 4): a grandfathered or legacy plan takes the
+ * band of the limits rung it enforces at today, so no grandfathered customer
+ * loses a storage or rate limit. The pro rung spans $199–$499, whose columns
+ * differ only in the per-delivery spend default, which grandfathered plans
+ * resolve from their own monthly credits instead (P-62); it maps to the lower
+ * band. Enterprise enforces at the scale rung and therefore takes the top band.
+ */
+export declare const LEGACY_PLAN_BAND_BY_LIMITS_TIER: Readonly<Record<LimitsTier, PlanBand>>;
+/**
+ * Map a raw plan-tier string (subscription `tier`, metadata tier, legacy plan
+ * key, or an Oxygen plan key like `oxygen_499`) onto its band. Unknown or absent
+ * tiers land on the unentitled "free" band, the same fail-closed rule as
+ * `limitsTierForPlanTier`.
+ */
+export declare function planBandForPlanTier(tier: string | null | undefined): PlanBand;
+/**
+ * The band of an org whose limits rung is already resolved (no second lookup).
+ * An unentitled org keeps no plan tier, so it takes the free band.
+ */
+export declare function planBandForLimitsResolution(resolution: {
+    planTier: string | null;
+    entitled: boolean;
+}): PlanBand;
+/** The band's monthly price, read from the Oxygen plan it names; null for free. */
+export declare function planBandMonthlyPriceCents(band: PlanBand): number | null;
+export declare function planBandLabel(band: PlanBand): string;
+/**
+ * Request rates, per minute unless named otherwise. The totals bound every
+ * `/api/cli/*` call; the operation buckets bind first for the calls a script
+ * makes most (row reads and writes, live tool and AI calls, dry runs, bulk
+ * imports). A 429 names the bucket it hit in `error.details.bucket`: the
+ * totals are `cli.requests`, the others `tenant_read.requests`,
+ * `tenant_write.requests`, `tool_live.requests` / `ai_live.requests`,
+ * `tool_dry_run.requests` and `bulk_import.requests`.
+ */
+export type ApiRateLimitsReport = {
+    org_requests_per_minute: number;
+    key_requests_per_minute: number;
+    tenant_read_requests_per_key_per_minute: number;
+    tenant_write_requests_per_key_per_minute: number;
+    live_action_requests_per_key_per_minute: number;
+    live_action_requests_per_org_per_hour: number;
+    tool_dry_run_requests_per_key_per_minute: number;
+    bulk_import_tables_per_org_per_hour: number;
+    /**
+     * Row budgets shared by every key in the workspace: each row a request reads
+     * or writes is one unit (`tenant_read.units`, `tenant_write.units`). The
+     * window is an hour on free and a day on paid plans.
+     */
+    rows_read_per_org: {
+        rows: number;
+        window_seconds: number;
+    };
+    rows_written_per_org: {
+        rows: number;
+        window_seconds: number;
+    };
+};
+/** The API rates a limits rung enforces, read from `PLAN_LIMITS`. */
+export declare function describeApiRateLimits(tier: LimitsTier): ApiRateLimitsReport;
+/**
+ * The limits in force today for one band, as the `/api/cli/limits` contract
+ * reports them. Every value is read from the constant that enforces it; nothing
+ * here is a second copy. Monthly credits are the Oxygen plan's grant (free has
+ * none, so its org-daily guard does not apply).
+ */
+export type PlanBandLimitsReport = {
+    band: PlanBand;
+    label: string;
+    monthly_price_usd: number | null;
+    monthly_credits: number | null;
+    limits_tier: LimitsTier;
+    api: ApiRateLimitsReport;
+    storage: {
+        table_row_limit: number;
+        workspace_row_limit: number;
+        workspace_database_warning_bytes: number;
+        workspace_database_limit_bytes: number;
+        /** Equal to rows per Table (PROPOSED P-60): one file can fill an empty Table. */
+        import_max_rows_per_file: number;
+        import_max_file_bytes: number;
+    };
+    spend: {
+        trigger_run_credit_ceiling: number | null;
+        auto_run_batch_credit_ceiling: number | null;
+        agent_run_max_total_credits: number;
+        agent_run_max_inference_credits: number;
+        org_daily_guard_warn_credits: number | null;
+        org_daily_guard_block_credits: number | null;
+        byok_column_run_max_rows: number | null;
+        byok_provider_daily_calls: number | null;
+    };
+    signals: {
+        max_events: number;
+        max_window_days: number;
+    };
+};
+export declare function describePlanBandLimits(band: PlanBand, options?: RepricingOptions): PlanBandLimitsReport;
+/** Every band's limits in force today, smallest first. */
+export declare function describePlanBandLadder(options?: RepricingOptions): PlanBandLimitsReport[];

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

@@ -0,0 +1,147 @@
+import { resolveBasePricingPlan } from "./billing.js";
+import { planLimitsForTier, limitsTierForPlanTier } from "./plan-limits.js";
+import { DEFAULT_AUTO_RUN_BATCH_CREDIT_CEILING, DEFAULT_BYOK_COLUMN_RUN_MAX_ROWS, DEFAULT_BYOK_PROVIDER_DAILY_CALL_CAP, DEFAULT_TRIGGER_RUN_CREDIT_CEILING, resolveOrgDailySpendGuard, } from "./spend-safety.js";
+import { resolveWorkspaceTableCapacity } from "./table-capacity.js";
+export const PLAN_BAND_ORDER = [
+    "free",
+    "49",
+    "99",
+    "199",
+    "499",
+    "999",
+    "1999",
+];
+/** The limits rung each band enforces at today. */
+export const PLAN_BAND_LIMITS_TIER = Object.freeze({
+    free: "free",
+    "49": "starter",
+    "99": "starter",
+    "199": "pro",
+    "499": "pro",
+    "999": "team",
+    "1999": "scale",
+});
+/**
+ * PROPOSED (P-57, repricing spec § 4): a grandfathered or legacy plan takes the
+ * band of the limits rung it enforces at today, so no grandfathered customer
+ * loses a storage or rate limit. The pro rung spans $199–$499, whose columns
+ * differ only in the per-delivery spend default, which grandfathered plans
+ * resolve from their own monthly credits instead (P-62); it maps to the lower
+ * band. Enterprise enforces at the scale rung and therefore takes the top band.
+ */
+export const LEGACY_PLAN_BAND_BY_LIMITS_TIER = Object.freeze({
+    free: "free",
+    starter: "99",
+    pro: "199",
+    team: "999",
+    scale: "1999",
+});
+/**
+ * Map a raw plan-tier string (subscription `tier`, metadata tier, legacy plan
+ * key, or an Oxygen plan key like `oxygen_499`) onto its band. Unknown or absent
+ * tiers land on the unentitled "free" band, the same fail-closed rule as
+ * `limitsTierForPlanTier`.
+ */
+export function planBandForPlanTier(tier) {
+    const plan = resolveBasePricingPlan(tier);
+    if (!plan || plan.tier === "free")
+        return "free";
+    if (plan.tier === "oxygen")
+        return oxygenPlanBand(plan.monthlyPriceCents);
+    return LEGACY_PLAN_BAND_BY_LIMITS_TIER[limitsTierForPlanTier(tier)];
+}
+/**
+ * The band of an org whose limits rung is already resolved (no second lookup).
+ * An unentitled org keeps no plan tier, so it takes the free band.
+ */
+export function planBandForLimitsResolution(resolution) {
+    return resolution.entitled ? planBandForPlanTier(resolution.planTier) : "free";
+}
+/**
+ * An Oxygen plan sits on the largest size at or below its price. A plan with no
+ * resolvable price takes the entry size, the same rung `limitsTierForPlanTier`
+ * gives it.
+ */
+function oxygenPlanBand(monthlyPriceCents) {
+    if (monthlyPriceCents === null)
+        return "49";
+    let band = "49";
+    for (const candidate of PLAN_BAND_ORDER) {
+        const price = planBandMonthlyPriceCents(candidate);
+        if (price !== null && price <= monthlyPriceCents)
+            band = candidate;
+    }
+    return band;
+}
+/** The band's monthly price, read from the Oxygen plan it names; null for free. */
+export function planBandMonthlyPriceCents(band) {
+    if (band === "free")
+        return null;
+    return resolveBasePricingPlan(`oxygen_${band}`)?.monthlyPriceCents ?? null;
+}
+export function planBandLabel(band) {
+    return band === "free" ? "Free" : `Oxygen $${Number(band).toLocaleString("en-US")}`;
+}
+/** The API rates a limits rung enforces, read from `PLAN_LIMITS`. */
+export function describeApiRateLimits(tier) {
+    const cli = planLimitsForTier(tier).cli;
+    return {
+        org_requests_per_minute: cli.global.orgRequestsPerMinute,
+        key_requests_per_minute: cli.global.keyRequestsPerMinute,
+        tenant_read_requests_per_key_per_minute: cli.tenantRead.requestsPerMinute,
+        tenant_write_requests_per_key_per_minute: cli.tenantWrite.requestsPerMinute,
+        // ai_live and tool_live are separate buckets with equal limits at every rung.
+        live_action_requests_per_key_per_minute: cli.toolLive.requestsPerMinute,
+        // Both org windows are hourly on every rung (pinned by plan-band.test.ts).
+        live_action_requests_per_org_per_hour: cli.toolLive.orgRequests.limit,
+        tool_dry_run_requests_per_key_per_minute: cli.toolDryRun.requestsPerMinute,
+        bulk_import_tables_per_org_per_hour: cli.bulkImport.orgRequests.limit,
+        rows_read_per_org: { rows: cli.tenantRead.orgUnits.limit, window_seconds: cli.tenantRead.orgUnits.windowSeconds },
+        rows_written_per_org: { rows: cli.tenantWrite.orgUnits.limit, window_seconds: cli.tenantWrite.orgUnits.windowSeconds },
+    };
+}
+export function describePlanBandLimits(band, options = {}) {
+    const limitsTier = PLAN_BAND_LIMITS_TIER[band];
+    const storage = resolveWorkspaceTableCapacity(band, options);
+    const limits = planLimitsForTier(limitsTier);
+    const monthlyPriceCents = planBandMonthlyPriceCents(band);
+    const monthlyCredits = band === "free"
+        ? null
+        : resolveBasePricingPlan(`oxygen_${band}`)?.monthlyCredits ?? null;
+    const dailyGuard = resolveOrgDailySpendGuard(monthlyCredits);
+    return {
+        band,
+        label: planBandLabel(band),
+        monthly_price_usd: monthlyPriceCents === null ? null : monthlyPriceCents / 100,
+        monthly_credits: monthlyCredits,
+        limits_tier: limitsTier,
+        api: describeApiRateLimits(limitsTier),
+        storage: {
+            table_row_limit: storage.tableRowLimit,
+            workspace_row_limit: storage.workspaceRowLimit,
+            workspace_database_warning_bytes: storage.workspaceDatabaseWarningBytes,
+            workspace_database_limit_bytes: storage.workspaceDatabaseLimitBytes,
+            import_max_rows_per_file: storage.tableRowLimit,
+            import_max_file_bytes: limits.import.maxFileBytes,
+        },
+        spend: {
+            // Bands are Oxygen plan sizes, so their spend tier is their limits rung.
+            trigger_run_credit_ceiling: DEFAULT_TRIGGER_RUN_CREDIT_CEILING[limitsTier],
+            auto_run_batch_credit_ceiling: DEFAULT_AUTO_RUN_BATCH_CREDIT_CEILING[limitsTier],
+            agent_run_max_total_credits: limits.agents.maxTotalCredits,
+            agent_run_max_inference_credits: limits.agents.maxInferenceCredits,
+            org_daily_guard_warn_credits: dailyGuard?.warnCredits ?? null,
+            org_daily_guard_block_credits: dailyGuard?.blockCredits ?? null,
+            byok_column_run_max_rows: DEFAULT_BYOK_COLUMN_RUN_MAX_ROWS[limitsTier],
+            byok_provider_daily_calls: DEFAULT_BYOK_PROVIDER_DAILY_CALL_CAP[limitsTier],
+        },
+        signals: {
+            max_events: limits.signals.maxEvents,
+            max_window_days: limits.signals.maxWindowDays,
+        },
+    };
+}
+/** Every band's limits in force today, smallest first. */
+export function describePlanBandLadder(options = {}) {
+    return PLAN_BAND_ORDER.map((band) => describePlanBandLimits(band, options));
+}