@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.1014.136
+Version: 1.1014.619

package/dist/admin-primary-providers-render.js

@@ -1,17 +1,4 @@
-// Human rendering for `oxygen admin primary-providers`.
-//
-// The board answers three operator questions — does each primary provider work,
-// what does it cost us, and what stops a runaway — and until this file existed
-// the CLI answered them with ~1,500 lines of raw JSON while the MCP tool printed
-// a worst-first summary. Same route, same payload, two completely different
-// things to read. This renders the same facts the MCP text summary and the web
-// board render, so the three surfaces agree in front of a human, not only in
-// JSON.
-//
-// Every field is read defensively: the CLI receives untyped JSON from a server
-// that may be older or newer than the binary, and a board that silently drops a
-// column an operator is looking for is the exact failure this file exists to
-// stop. Unknown/absent reads as "—", never as zero.
+import { formatProviderEnvRequirements } from "@oxygen/shared/provider-selection";
 function obj(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -196,7 +183,7 @@ export function renderPrimaryProviderBoard(payload, options = {}) {
     const fallbacks = rowsWorstFirst(board.default_chain_fallbacks);
     if (fallbacks.length > 0) {
         out("");
-        out("Default-chain fallbacks (not primary anywhere — a routed chain reaches them when its primary fails):");
+        out("Default-chain fallbacks and conditional companions (fallback, preflight and optional verification roles; not primary anywhere):");
         for (const row of fallbacks)
             out(renderProvider(row, now, binary));
     }
@@ -210,6 +197,19 @@ export function renderPrimaryProviderBoard(payload, options = {}) {
         for (const row of outsideChains)
             out(renderProvider(row, now, binary));
     }
+    const productRails = rowsWorstFirst(board.product_rails);
+    if (productRails.length) {
+        out("");
+        out("Product services (default, conditional and legacy rails):");
+        for (const row of productRails) {
+            const selection = obj(row.selection);
+            if (selection)
+                out(`  ${str(selection.supplier)} · ${arr(selection.uses).join(", ")} · ${str(selection.selection)} · ${str(selection.condition)}`);
+            // Product services have their own operational controls; a data-provider
+            // spend breaker is not proof that their direct calls will stop.
+            out(renderProvider(row, now, binary, false));
+        }
+    }
     const intents = arr(board.intents_without_primary)
         .map((row) => obj(row))
         .filter((row) => row !== null);
@@ -280,7 +280,7 @@ function renderGuards(guards) {
     }
     return `Guards: ${parts.join(" · ")}`;
 }
-function renderProvider(row, now, binary) {
+function renderProvider(row, now, binary, allowSpendHalt = true) {
     const lines = [];
     const posture = obj(row.posture) ?? {};
     const health = obj(row.health) ?? {};
@@ -290,6 +290,14 @@ function renderProvider(row, now, binary) {
     const limits = obj(row.limits) ?? {};
     const links = obj(row.links) ?? {};
     const provider = str(row.provider) ?? "?";
+    const requiredEnv = arr(row.required_env).map(str).filter((name) => name !== null);
+    if (!requiredEnv.length && str(row.managed_key_env_var))
+        requiredEnv.push(str(row.managed_key_env_var));
+    const alternatives = arr(row.required_env_any).map(str).filter((name) => name !== null);
+    const requirements = formatProviderEnvRequirements(requiredEnv, alternatives);
+    const configuration = row.key_configured === false
+        ? requiredEnv.length > 1 || alternatives.length ? `INCOMPLETE (requires ${requirements})` : `NOT SET (${requirements || "—"})`
+        : requirements || "customer-supplied";
     const level = str(posture.level) ?? "unknown";
     const functions = arr(row.functions).map((fn) => String(fn));
     // A catch-all escalation lane is the only route to its provider and is
@@ -313,7 +321,7 @@ function renderProvider(row, now, binary) {
     ].filter((part) => part !== null);
     lines.push(`  - ${provider} [${level}]${functions.length > 0 ? ` ${functions.join("+")}` : ""}` +
         `${escalations.length > 0 ? ` (catch-all escalation: ${escalations.join(", ")})` : ""} · ` +
-        `key ${row.key_configured === false ? `NOT SET (${str(row.managed_key_env_var) ?? "—"})` : str(row.managed_key_env_var) ?? "customer-supplied"} · ` +
+        `key ${configuration} · ` +
         `health ${healthStatus} (${healthDetail.join(", ")})`);
     const scope = str(traffic.scope) ?? "workspace_attributed";
     const trafficLine = row.traffic_7d === undefined
@@ -332,7 +340,7 @@ function renderProvider(row, now, binary) {
     const ceilings = arr(limits.ceilings).map((ceiling) => obj(ceiling)).filter((c) => c !== null);
     const worstCeiling = [...ceilings].sort((a, b) => (num(b.utilization) ?? -1) - (num(a.utilization) ?? -1))[0];
     const breaker = obj(limits.breaker);
-    lines.push(`      rate ${firstPolicy
+    lines.push(!allowSpendHalt ? "      Service controls: inspect the owning product rail." : `      rate ${firstPolicy
         ? `${count(firstPolicy.limit)}${windowLabel(firstPolicy.window_seconds)}` +
             `${num(firstPolicy.max_in_flight) === null ? "" : ` · ${count(firstPolicy.max_in_flight)} in flight`}` +
             ` · ${firstPolicy.window_expired === true ? "idle" : `${count(firstPolicy.current)} this window`}` +
@@ -352,7 +360,7 @@ function renderProvider(row, now, binary) {
     ].filter((part) => part !== null);
     if (linkParts.length > 0)
         lines.push(`      ${linkParts.join(" · ")}`);
-    if (level === "critical" || level === "attention") {
+    if (allowSpendHalt && (level === "critical" || level === "attention")) {
         lines.push(`      halt: ${binary} admin spend halt --scope provider --key ${provider}`);
     }
     return lines.join("\n");

package/dist/cli-output.d.ts

@@ -0,0 +1,12 @@
+export type JsonOptions = {
+    json?: boolean;
+    full?: boolean;
+};
+export declare function writeJson(value: unknown): void;
+export declare function emitSuccess<T>(command: string, data: T, options: JsonOptions): void;
+export declare function handleAsyncAction(command: string, options: JsonOptions, action: () => Promise<unknown>): Promise<void>;
+export declare function emitCliFailure(command: string, error: unknown): void;
+export declare function writeBillingNotices(command: string, data: unknown): void;
+export declare function asPayloadRecord(value: unknown): Record<string, unknown> | null;
+export declare function writeCreditsReceipt(data: unknown): void;
+export declare function readDetailsNumber(details: unknown, key: string): number | null;

package/dist/cli-output.js

@@ -0,0 +1,395 @@
+import { formatProviderLaneNotices } from "./column-run-notices.js";
+import { recordCliDiagnosticFailure } from "./diagnostics.js";
+import { formatInboxNeedsReplyNotice } from "./inbox-needs-reply-notice.js";
+import { serializeCliJson } from "./json-output.js";
+import { formatMailboxRampNotice } from "./mailbox-ramp-notice.js";
+import { formatSearchAiFilterTotalsNotice } from "./search-ai-filter-notice.js";
+import { isRecord } from "./util.js";
+import { exitCodeForOxygenError, OxygenError, success, toFailure } from "@oxygen/shared/cli-result";
+export function writeJson(value) {
+    process.stdout.write(serializeCliJson(value, process.argv.includes("--pretty")));
+}
+export function emitSuccess(command, data, options) {
+    if (options.json) {
+        writeJson(success(command, data));
+        return;
+    }
+    writeJson(data);
+}
+export async function handleAsyncAction(command, options, action) {
+    try {
+        const data = await action();
+        // BEFORE the envelope, deliberately: an unpaid renewal or a recurring shortfall is the
+        // reason the customer ran the command, and a warning printed after 150 lines of JSON
+        // has already scrolled away. stdout stays the clean machine-readable envelope — the
+        // same stdout/stderr split writeDryRunNotice and writeCreditsReceipt use.
+        writeBillingNotices(command, data);
+        emitSuccess(command, data, options);
+        writeDryRunNotice(data);
+        writeManagedProviderAvailabilityNotice(data);
+        writeAvatarWarning(data);
+        writeCreditsReceipt(data);
+        writeSearchAiFilterTotalsNotice(data);
+        writeInboxNeedsReplyNotice(data);
+        writeMailboxRampNotice(data);
+    }
+    catch (error) {
+        emitCliFailure(command, error);
+    }
+}
+// The preview-time face of the managed-provider credit bench (OXP-1.14.11).
+// `companies search plan` / `companies search run --mode dry_run` carry
+// `provider_availability` and `verify email` (dry_run) carries
+// `catch_all_escalation_available`; both are in the envelope for --json readers,
+// but a benched provider buried in a 150-line plan is exactly how a customer
+// sizes and approves a run that Oxygen already knows will be refused. One line
+// per benched provider on stderr, same stdout/stderr split as the dry-run notice.
+function writeManagedProviderAvailabilityNotice(data) {
+    const payload = asPayloadRecord(data);
+    if (!payload)
+        return;
+    const availability = asPayloadRecord(payload.provider_availability);
+    // `columns run --dry-run` and `enrich-column preview` name their lanes: one
+    // line per lane that cannot run, led by the verdict (OXP-1.14.12).
+    if (availability && Array.isArray(availability.lanes)) {
+        for (const line of formatProviderLaneNotices(availability))
+            process.stderr.write(`${line}\n`);
+        return;
+    }
+    if (availability) {
+        const providers = asPayloadRecord(availability.providers) ?? {};
+        for (const [provider, entry] of Object.entries(providers)) {
+            const record = asPayloadRecord(entry);
+            if (record?.status !== "benched" && record?.status !== "unknown")
+                continue;
+            const message = typeof record.message === "string" ? record.message
+                : record.status === "unknown" ? `Oxygen could not check its managed ${provider} account availability.`
+                    : `Oxygen's managed ${provider} account is benched.`;
+            const nextAction = typeof record.next_action === "string" ? ` ${record.next_action}` : "";
+            process.stderr.write(`! ${message}${nextAction}\n`);
+        }
+        return;
+    }
+    if ((payload.catch_all_escalation_available === false || payload.catch_all_escalation_availability === "unknown")
+        && typeof payload.next_action === "string") {
+        process.stderr.write(`! ${payload.next_action}\n`);
+    }
+}
+// Single-source the CLI failure-emit contract: write the machine-readable
+// failure envelope to stdout, surface any spend-gate hint on stderr, and set the
+// process exit code from the error. Command handlers that don't route through
+// handleAsyncAction catch straight into this so the shape can't drift.
+export function emitCliFailure(command, error) {
+    recordCliDiagnosticFailure(error);
+    writeJson(toFailure(command, error));
+    writeMaxCreditsHint(error);
+    process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
+}
+function writeDryRunNotice(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const preview = data.preview;
+    if (!preview || typeof preview !== "object" || Array.isArray(preview))
+        return;
+    const block = preview;
+    if (typeof block.message === "string")
+        process.stderr.write(`${block.message}\n`);
+    if (typeof block.next_step === "string")
+        process.stderr.write(`${block.next_step}\n`);
+    const byok = readByokCredentialMode(data);
+    if (byok) {
+        const fee = asPayloadRecord(asPayloadRecord(data)?.credits)?.estimated_credits;
+        process.stderr.write(typeof fee === "number"
+            ? `Your own-key run (${byok}) is estimated at ${fee} Oxygen credits; your provider bills its call separately.\n`
+            : `Your own-key run (${byok}) may incur an Oxygen platform fee; check the current credit quote before running it live. Your provider bills its call separately.\n`);
+    }
+}
+/**
+ * The tool run's credential mode when the call is NOT on Oxygen's managed key
+ * — the one fact that decides whether a quoted credit estimate means anything.
+ * Null for managed runs and for payloads with no billing block at all.
+ */
+function readByokCredentialMode(data) {
+    const result = asPayloadRecord(asPayloadRecord(data)?.result);
+    const billing = asPayloadRecord(asPayloadRecord(result?.meta)?.billing);
+    const mode = billing?.credential_mode;
+    if (mode !== "byok" && mode !== "user_api_key")
+        return null;
+    return mode;
+}
+// A sender-profile write that could not durably host the photo still succeeds —
+// the profile is saved, just with a picture no inbox vendor will ever be able to
+// fetch. That is the one failure mode nobody notices until the mailboxes ship
+// faceless and the vendor refuses to change them, so the server's
+// `avatar_warning` gets its own stderr line instead of living only inside the
+// stdout envelope a human never reads.
+function writeAvatarWarning(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const warning = data.avatar_warning;
+    if (typeof warning === "string" && warning.trim())
+        process.stderr.write(`${warning}\n`);
+}
+// The human half of the unpaid-renewal surfaces: `billing balance` warnings, the
+// `billing allowance` past_due segment, and the billing state of each managed domain in
+// `domains list`. All three are already in the JSON envelope (and stay there for --json);
+// these lines exist because none of them is legible at a glance in a payload, and the one
+// customer this shipped for could read every number in the product and still not learn
+// that 139,000 credits of renewals had failed.
+export function writeBillingNotices(command, data) {
+    const payload = asPayloadRecord(data);
+    if (!payload)
+        return;
+    // Any list that carries connected accounts (senders, WhatsApp numbers, mailboxes,
+    // billing commitments) says so when some stopped sending because their monthly
+    // credit reservation could not be renewed (decision 2.8). Before the envelope, for
+    // the same reason as the renewal notices below.
+    const paused = asPayloadRecord(payload.reservations_paused);
+    if (paused && typeof paused.message === "string" && paused.message.trim()) {
+        process.stderr.write(`! ${paused.message}\n`);
+    }
+    if (command === "billing balance") {
+        for (const warning of readWarningMessages(payload))
+            process.stderr.write(`! ${warning}\n`);
+        return;
+    }
+    if (command === "billing allowance") {
+        const unpaid = asPayloadRecord(payload.renewals_past_due);
+        if (!unpaid)
+            return;
+        const count = typeof unpaid.count === "number" ? unpaid.count : 0;
+        const credits = typeof unpaid.credits_required === "number" ? unpaid.credits_required : 0;
+        // Said explicitly because it is the one number in this command that is NOT part of the
+        // pool: it is money the biller could not take, so it is not in total_credits.
+        process.stderr.write(`! renewals unpaid: ${count} item${count === 1 ? "" : "s"}, ${credits.toLocaleString("en-US")} credits — not included in total_credits. Run \`oxygen billing balance\` for the top-up amount.\n`);
+        return;
+    }
+    if (command === "domains list") {
+        const managed = Array.isArray(payload.managed_domains) ? payload.managed_domains : [];
+        const unpaid = managed
+            .map((row) => asPayloadRecord(row))
+            .filter((row) => row?.internal_billing_status === "past_due")
+            .map((row) => (typeof row.domain === "string" ? row.domain : "unknown"));
+        if (unpaid.length === 0)
+            return;
+        // The vendor keeps these live, so their `status` still reads `active` — which is
+        // exactly why naming them is worth a line.
+        process.stderr.write(`! renewal unpaid on ${unpaid.length} managed domain${unpaid.length === 1 ? "" : "s"}: ${unpaid.join(", ")} (see internal_billing_status)\n`);
+    }
+}
+function readWarningMessages(payload) {
+    if (!Array.isArray(payload.warnings))
+        return [];
+    return payload.warnings
+        .map((warning) => asPayloadRecord(warning)?.message)
+        .filter((message) => typeof message === "string" && message.trim().length > 0);
+}
+export function asPayloadRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+// Paid envelopes (push 3 legibility) carry a `credits` block: quote on
+// dry_run, receipt on live, remaining balance on both. Mirror it as one
+// stderr line so spend stays visible in a terminal without polluting the
+// machine-read stdout envelope.
+export function writeCreditsReceipt(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const credits = data.credits;
+    if (!credits || typeof credits !== "object" || Array.isArray(credits))
+        return;
+    const block = credits;
+    const remaining = typeof block.credits_remaining === "number"
+        ? block.credits_remaining.toLocaleString("en-US")
+        : null;
+    if (typeof block.credits_used === "number") {
+        process.stderr.write(`spent ${block.credits_used.toLocaleString("en-US")} credits${remaining !== null ? `, ${remaining} remaining` : ""}\n`);
+        return;
+    }
+    if (typeof block.estimated_credits === "number") {
+        const byok = readByokCredentialMode(data);
+        process.stderr.write(byok
+            ? `estimated ${block.estimated_credits.toLocaleString("en-US")} Oxygen credits for a live run on your own key (${byok})${remaining !== null ? `, ${remaining} available` : ""}\n`
+            : `estimated ${block.estimated_credits.toLocaleString("en-US")} credits for a live run${remaining !== null ? `, ${remaining} available` : ""}\n`);
+        // Last, where an agent reading the tail of the output sees it: the
+        // estimate above is a ceiling, and only kept posts are charged
+        // (blind acceptance, 2026-09-25: agents read `| tail` and missed it).
+        // The same for what an existing table's saved auto-run adds to this run.
+        for (const key of ["ai_filter_reasons", "standing_auto_run"]) {
+            const summary = asPayloadRecord(data[key])?.summary;
+            if (typeof summary === "string")
+                process.stderr.write(`${summary}\n`);
+        }
+    }
+}
+function writeSearchAiFilterTotalsNotice(data) {
+    const notice = formatSearchAiFilterTotalsNotice(data);
+    if (notice)
+        process.stderr.write(`${notice}\n`);
+}
+function writeInboxNeedsReplyNotice(data) {
+    const notice = formatInboxNeedsReplyNotice(data);
+    if (notice)
+        process.stderr.write(`${notice}\n`);
+}
+function writeMailboxRampNotice(data) {
+    const notice = formatMailboxRampNotice(data);
+    if (notice)
+        process.stderr.write(`${notice}\n`);
+}
+// Paid live runs and ambiguous external-effect retries are refused server-side with typed safety-gate errors
+// (max_credits_required, approval_required, spend_cap_required,
+// spend_cap_too_low). Surface each as a one-line stderr hint with the concrete
+// re-run flags so users don't have to dig values out of the JSON envelope
+// (stderr keeps --json stdout machine-clean).
+function writeMaxCreditsHint(error) {
+    if (!(error instanceof OxygenError))
+        return;
+    switch (error.code) {
+        // The plan wall. Unlike every other case in this switch, no flag on the
+        // command can unblock it — so the hint names the capability in the
+        // customer's own words, says what still works without upgrading, and gives
+        // the URL. A raw `upgrade_required` code with a JSON blob is the worst
+        // possible version of the single most important refusal in the product.
+        // The BYOK run gate keeps its own code but carries the same upgrade fields,
+        // including once a free workspace's seven-day key grace has ended. Without
+        // an upgrade_url (an older server) it has no hint, as before.
+        case "byok_requires_paid_plan":
+        case "upgrade_required": {
+            if (error.code === "byok_requires_paid_plan" && !readDetailsString(error.details, "upgrade_url"))
+                return;
+            const label = readDetailsString(error.details, "capability_label")
+                ?? "This capability";
+            const upgradeUrl = readDetailsString(error.details, "upgrade_url");
+            const nextStep = readDetailsString(error.details, "next_step");
+            // BYOK names the smallest plan that includes it ("the $99 plan or above").
+            const requirement = readDetailsString(error.details, "minimum_plan_label") ?? "a paid plan";
+            process.stderr.write(`hint: ${label} needs ${requirement}.\n`);
+            if (nextStep)
+                process.stderr.write(`hint: ${nextStep}\n`);
+            if (upgradeUrl)
+                process.stderr.write(`hint: upgrade at ${upgradeUrl}\n`);
+            return;
+        }
+        case "effect_unknown_approval_required": {
+            process.stderr.write("hint: verify every affected external destination in error.details, then re-run with --approved-effect-unknown only if another execution is safe\n");
+            return;
+        }
+        // A connect refused because the balance cannot carry the account's first
+        // monthly credit reservation. Only that shape carries reservation_credits;
+        // every other insufficient_credits keeps its own message.
+        case "insufficient_credits": {
+            const reservation = readDetailsNumber(error.details, "reservation_credits");
+            if (reservation === null)
+                return;
+            const nextStep = readDetailsString(error.details, "next_step");
+            const topupUrl = readDetailsString(error.details, "topup_url");
+            process.stderr.write(`hint: this connect reserves ${reservation} credits a month; add credits, then connect again\n`);
+            if (nextStep)
+                process.stderr.write(`hint: ${nextStep}\n`);
+            if (topupUrl)
+                process.stderr.write(`hint: top up at ${topupUrl}\n`);
+            return;
+        }
+        case "seats_retired": {
+            const nextStep = readDetailsString(error.details, "next_step");
+            process.stderr.write(`hint: sending seats are retired; connected accounts reserve credits instead${nextStep ? ` — see \`${nextStep}\`` : ""}\n`);
+            return;
+        }
+        case "max_credits_required": {
+            const recommended = readDetailsNumber(error.details, "recommended_max_credits");
+            if (recommended === null)
+                return;
+            process.stderr.write(`hint: re-run with --max-credits ${recommended} to approve the spend cap\n`);
+            return;
+        }
+        case "approval_required": {
+            // A COLLABORATION gate reuses this code but is not a spend gate: no flag
+            // on this command can unblock it, because the whole point is that a
+            // second party decides. Printing the "--approved --max-credits" hint here
+            // would send the operator hunting for a flag that does not exist, so the
+            // gate branch runs first and prints the command the OTHER person runs.
+            const gateKind = readDetailsString(error.details, "gate_kind");
+            if (gateKind) {
+                const nextStep = readDetailsString(error.details, "next_step");
+                process.stderr.write(`hint: blocked by the ${gateKind} approval gate — ${nextStep ?? "ask an assignee to decide it"}\n`);
+                const lastDecision = isRecord(error.details) && isRecord(error.details.last_decision)
+                    ? error.details.last_decision
+                    : null;
+                if (lastDecision) {
+                    const note = readDetailsString(lastDecision, "note");
+                    process.stderr.write(`hint: the last answer was ${readDetailsString(lastDecision, "status") ?? "recorded"}${note ? ` — "${note}"` : ""}; revise, then ask again\n`);
+                }
+                const requestUrl = readDetailsString(error.details, "pending_request_web_url")
+                    ?? readDetailsString(error.details, "subject_web_url");
+                if (requestUrl)
+                    process.stderr.write(`hint: ${requestUrl}\n`);
+                return;
+            }
+            // An Agent run or trigger asked for more than the default Agent run
+            // ceiling: the one extra flag is the approval, so name it with the numbers.
+            if (readDetailsString(error.details, "approval_kind") === "agent_ceiling_above_default") {
+                const requested = readDetailsNumber(error.details, "requested_max_credits");
+                const defaultMax = readDetailsNumber(error.details, "default_max_credits");
+                process.stderr.write(`hint: ${requested ?? "this"} credits is above your default Agent run ceiling of ${defaultMax ?? "your plan"}; re-run with --approve-above-default to approve it, or lower --max-credits\n`);
+                return;
+            }
+            if (error.message.startsWith("Public replies require --approved")) {
+                process.stderr.write("hint: inspect the exact preview, then re-run with its --content-hash <sha256> and --approved\n");
+                return;
+            }
+            // Free-but-irreversible gates (tables/columns delete --now) approve with
+            // --yes and spend nothing — the spend-flag hint would name flags the
+            // command does not take. The server message is the signal: it spells out
+            // "(CLI: --yes)" on those gates.
+            // Amplification grants name their own three flags and have no dry run.
+            if (error.message.includes("--acknowledge-risk")) {
+                process.stderr.write("hint: re-run with --approved --max-credits <n> --acknowledge-risk\n");
+                return;
+            }
+            if (error.message.includes("--yes")) {
+                process.stderr.write("hint: inspect the preview, then re-run with --yes to approve the permanent deletion\n");
+                return;
+            }
+            const estimated = readDetailsNumber(error.details, "estimated_credits");
+            process.stderr.write(`hint: inspect the dry run, then re-run with --approved --max-credits <n>${estimated !== null ? ` (estimated ~${estimated} credits)` : ""}\n`);
+            return;
+        }
+        case "spend_cap_required": {
+            const estimated = readDetailsNumber(error.details, "estimated_credits");
+            process.stderr.write(`hint: re-run with --max-credits ${estimated !== null ? estimated : "<n>"} to cap the spend\n`);
+            return;
+        }
+        case "spend_cap_too_low": {
+            const estimated = readDetailsNumber(error.details, "estimated_credits")
+                ?? readDetailsNumber(error.details, "estimated_max_credits");
+            if (estimated === null)
+                return;
+            process.stderr.write(`hint: the estimate is ${estimated} credits; re-run with --max-credits ${estimated} or higher\n`);
+            return;
+        }
+        case "copilot_send_timeout": {
+            const nextStep = readDetailsString(error.details, "next_step");
+            const interrupt = readDetailsString(error.details, "interrupt_command");
+            if (nextStep)
+                process.stderr.write(`hint: the turn is still running; read it with \`${nextStep}\`\n`);
+            if (interrupt)
+                process.stderr.write(`hint: stop it (and its spend) with \`${interrupt}\`\n`);
+            return;
+        }
+        default:
+    }
+}
+export function readDetailsNumber(details, key) {
+    if (!details || typeof details !== "object" || Array.isArray(details))
+        return null;
+    const value = details[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function readDetailsString(details, key) {
+    if (!isRecord(details))
+        return null;
+    const value = details[key];
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/dist/cli-paths.d.ts

@@ -0,0 +1 @@
+export declare const CLI_MODULE_DIR: string;

package/dist/cli-paths.js

@@ -0,0 +1,3 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+export const CLI_MODULE_DIR = dirname(fileURLToPath(import.meta.url));

package/dist/cli-profile-context.d.ts

@@ -0,0 +1,3 @@
+export type CliProfileSource = "flag" | "env" | "file" | "default";
+export declare function recordCliProfileFlag(profile: string): void;
+export declare function cliProfileSource(fallback: Exclude<CliProfileSource, "flag">): CliProfileSource;

package/dist/cli-profile-context.js

@@ -0,0 +1,13 @@
+// Capture the launch environment before Commander's preAction hook applies flags.
+const initialProfileEnv = process.env.OXYGEN_PROFILE?.trim() || null;
+let profileFlag = null;
+export function recordCliProfileFlag(profile) {
+    profileFlag = profile;
+}
+export function cliProfileSource(fallback) {
+    if (profileFlag)
+        return "flag";
+    if (initialProfileEnv)
+        return "env";
+    return fallback;
+}

package/dist/command-manifest.d.ts

@@ -21,6 +21,21 @@ export type CommandManifestEntry = {
     preview_by_default: boolean;
     json_supported: boolean;
     hidden: boolean;
+    execution_modes?: {
+        default: "live";
+        dry_run: {
+            credits: 0;
+            generates: false;
+            approval_required: false;
+        };
+        live: {
+            credits: number;
+            generates: true;
+            approval_required: true;
+            approval_scope: "exact_input_and_preview_cost";
+            minimum_max_credits: number;
+        };
+    };
 };
 export type CommandManifest = {
     binary: string;

package/dist/command-manifest.js

@@ -1,4 +1,5 @@
 import { OPERATION_SPECS } from "@oxygen/shared/contracts/operations";
+import { SPINTAX_GENERATION_CREDITS } from "@oxygen/shared/contracts/spintax";
 import { CLI_EXIT_CODE_TABLE, OXYGEN_VERSION, inferUserCapabilityRoute, serializeCapabilityRoute, } from "@oxygen/shared";
 const DEFAULT_COMMAND_SEARCH_LIMIT = 10;
 const MAX_COMMAND_SEARCH_LIMIT = 25;
@@ -108,8 +109,12 @@ const MUTATING_COMMANDS = new Set([
     // credits. The exact exceptions disclose writes without inventing spend.
     "billing balance",
     "billing seats",
-    // The ledger audit reads that same balance first, with the same conditional writes.
+    // A sponsorship quote reads that same reconciling balance. It creates no
+    // reservation, but a due grant or sponsored-credit expiry can still write.
+    "ugc sponsorship preview",
+    // The ledger audit and usage read that same balance first, with conditional writes.
     "billing audit",
+    "billing usage",
     // Creates an approval or Checkout link; a first plan's Checkout can start the
     // first-month offer window. The plan changes only after confirmation.
     "billing change",
@@ -136,6 +141,9 @@ const MUTATING_COMMANDS = new Set([
     "viewers enrichment",
     // A noun leaf that switches a bought domain's yearly paid renewal on or off.
     "domains renewal",
+    // Runs the isolated renderer and writes its pages back as workspace files. It
+    // is free since 2026-10-14, so no --approved/--max-credits flag reports it.
+    "visuals render-start",
     // The plain standup view in an interactive terminal moves the user's Home
     // "last seen" marker, as a web Home visit does; `--json`, or output that is not
     // a terminal (an agent's shell, a pipe), is a pure read that leaves it alone
@@ -151,6 +159,7 @@ const MUTATING_COMMANDS = new Set([
 // mode, but a small number of approved operations are explicitly
 // zero-credit. Keep those exceptions exact so discovery never invents spend.
 const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
+    "domains dns apply",
     // The compatibility --approved flag never bypasses canonical proposal review.
     // Wiki revisions and canonical pin changes are free (Knowledge audit, 2026-10-06).
     "knowledge page upsert",
@@ -226,6 +235,7 @@ const READ_ONLY_COMMANDS = new Set([
 // invocation still previews, so machine-readable discovery must not imply that
 // calling the command without its confirmation flag writes anything.
 const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
+    "domains dns apply",
     "mailboxes warmup enable",
     "mailboxes warmup google",
     "deliverability placement-test run",
@@ -445,6 +455,18 @@ function toManifestEntry(command, path) {
             PREVIEW_BY_DEFAULT_COMMANDS.has(commandName),
         json_supported: flagStrings.some((flags) => flags.includes("--json")),
         hidden: isHiddenCommand(command),
+        ...(commandName === "spintax generate" ? {
+            execution_modes: {
+                default: "live",
+                dry_run: { credits: 0, generates: false, approval_required: false },
+                live: {
+                    credits: SPINTAX_GENERATION_CREDITS,
+                    generates: true, approval_required: true,
+                    approval_scope: "exact_input_and_preview_cost",
+                    minimum_max_credits: SPINTAX_GENERATION_CREDITS,
+                },
+            },
+        } : {}),
     };
 }
 function isHiddenCommand(command) {