@oxygen-agent/cli 1.1010.650 → 1.1010.905

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.1010.650
+Version: 1.1010.905

package/dist/auto-update.d.ts

@@ -0,0 +1,129 @@
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { type CliEndpoint } from "./runtime.js";
+import { type UpdateOptions } from "./update.js";
+export declare const AUTO_UPDATE_DISABLE_ENV = "OXYGEN_NO_AUTO_UPDATE";
+/** Set on the re-run after a floor-driven update; stops a second attempt. */
+export declare const AUTO_UPDATED_FROM_ENV = "OXYGEN_CLI_AUTO_UPDATED";
+export declare const BACKGROUND_CHECK_INTERVAL_MS: number;
+export type AutoUpdateResult = {
+    at: string;
+    from: string;
+    to: string | null;
+    ok: boolean;
+    trigger: "background" | "floor";
+    error?: string;
+};
+export type AutoUpdateState = {
+    auto_update?: "on" | "off";
+    last_check_at?: string;
+    latest_seen?: string;
+    last_check_error?: string;
+    last_result?: AutoUpdateResult;
+    notice_pending?: boolean;
+};
+export type AutoUpdateIneligibleReason = "ci" | "disabled_by_env" | "disabled_by_setting" | "dev_binary" | "not_global_npm_install" | "non_production_endpoint";
+export type AutoUpdateEligibility = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: AutoUpdateIneligibleReason;
+};
+type SpawnSyncFn = (command: string, args: string[], options: {
+    stdio: "inherit" | "ignore";
+    env: NodeJS.ProcessEnv;
+    windowsHide: boolean;
+    timeout?: number;
+}) => {
+    status: number | null;
+    error?: Error;
+};
+type SpawnDetachedFn = (command: string, args: string[], env: NodeJS.ProcessEnv) => void;
+export type AutoUpdateRuntime = {
+    env?: NodeJS.ProcessEnv;
+    argv?: readonly string[];
+    execPath?: string;
+    modulePath?: string;
+    now?: () => Date;
+    fetch?: typeof fetch;
+    update?: (options: UpdateOptions) => Promise<{
+        updated: boolean;
+    }>;
+    spawnSync?: SpawnSyncFn;
+    spawnDetached?: SpawnDetachedFn;
+    /** Reads the version npm left on disk; defaults to the running package's package.json. */
+    readInstalledVersion?: () => string | null;
+    stderr?: (text: string) => void;
+    exit?: (code: number) => never;
+};
+export declare function recordMutatingRequestAnswered(): void;
+/** Call before reading piped stdin: a re-run could not read it a second time. */
+export declare function markStdinConsumed(): void;
+/** Test-only: reset the per-process guards. */
+export declare function resetAutoUpdateProcessGuards(): void;
+export declare function autoUpdateStatePath(env?: NodeJS.ProcessEnv): string;
+export declare function readAutoUpdateState(env?: NodeJS.ProcessEnv): AutoUpdateState;
+/** Best-effort: an unwritable config directory must never fail a command. */
+export declare function writeAutoUpdateState(state: AutoUpdateState, env?: NodeJS.ProcessEnv): boolean;
+export declare function autoUpdateEligibility(runtime?: AutoUpdateRuntime & {
+    endpoint?: CliEndpoint;
+    state?: AutoUpdateState;
+}): AutoUpdateEligibility;
+/**
+ * The reactive path. Returns the error to throw (annotated with why no update
+ * happened), or — after a successful update — re-runs the command in the new
+ * binary and exits with its status.
+ */
+export declare function recoverFromCliFloorRejection(error: OxygenError, endpoint: CliEndpoint, runtime?: AutoUpdateRuntime): Promise<OxygenError>;
+/**
+ * The proactive path, called once at CLI start. Never blocks: it reads a small
+ * state file, prints any pending notice to stderr, and — at most once a day —
+ * spawns a detached `update --background` worker.
+ */
+export declare function maybeScheduleBackgroundUpdate(runtime?: AutoUpdateRuntime): void;
+export declare function fetchLatestCliVersion(fetchImpl?: typeof fetch): Promise<string>;
+export type BackgroundUpdateOutcome = {
+    action: "skipped";
+    reason: AutoUpdateIneligibleReason;
+} | {
+    action: "check_failed";
+    error: string;
+} | {
+    action: "up_to_date";
+    latest: string;
+} | {
+    action: "updated";
+    latest: string;
+} | {
+    action: "update_failed";
+    latest: string;
+    error: string;
+};
+/** The detached worker behind `oxygen update --background`. Prints nothing. */
+export declare function runBackgroundUpdate(runtime?: AutoUpdateRuntime): Promise<BackgroundUpdateOutcome>;
+export type AutoUpdateStatus = {
+    current_version: string;
+    latest_version: string | null;
+    latest_error?: string;
+    update_available: boolean | null;
+    /** Present for --enable-auto/--disable-auto: a dry run reports what would change and writes nothing. */
+    dry_run?: boolean;
+    setting_changed?: boolean;
+    auto_update: {
+        setting: "on" | "off";
+        active: boolean;
+        reason: AutoUpdateIneligibleReason | null;
+        reason_text: string | null;
+        /** The step that works here: how to turn updates on, or how to update by hand. Null while active. */
+        next_step: string | null;
+        disable: string;
+        last_check_at: string | null;
+        last_result: AutoUpdateResult | null;
+    };
+    state_path: string;
+};
+/** `oxygen update --status`, `--enable-auto`, `--disable-auto`. Checks npm live. */
+export declare function readAutoUpdateStatus(runtime?: AutoUpdateRuntime & {
+    setting?: "on" | "off";
+    dryRun?: boolean;
+}): Promise<AutoUpdateStatus>;
+export {};

package/dist/auto-update.js

@@ -0,0 +1,392 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { isVersionGreater, parseSemver } from "@oxygen/shared/semver";
+import { OXYGEN_VERSION } from "@oxygen/shared/version";
+import { resolveConfigDir } from "./credentials.js";
+import { resolveCliBinaryName, resolveCliUpdateGuidance } from "./runtime.js";
+import { detectCliInstall, readInstalledCliVersion, updateCli } from "./update.js";
+// The npm `oxygen` CLI keeps itself current in two ways:
+//
+// 1. Floor rejection (reactive). When the API refuses this CLI with
+//    `cli_update_required`, the CLI installs the newest release and re-runs the
+//    exact command once. The API refuses before doing any work, so the re-run
+//    cannot repeat a side effect — and the client refuses to re-run once any
+//    mutating request of its own has been answered in this process.
+// 2. Background (proactive). At most once a day a detached child checks npm and
+//    installs a newer release; the command that spawned it never waits, and the
+//    next run prints one stderr line saying what happened.
+//
+// Neither ever runs for `oxygen-dev`, under CI, for a CLI that is not a global
+// npm install (npx, a source checkout), or once turned off with
+// `oxygen update --disable-auto` / OXYGEN_NO_AUTO_UPDATE=1.
+export const AUTO_UPDATE_DISABLE_ENV = "OXYGEN_NO_AUTO_UPDATE";
+/** Set on the re-run after a floor-driven update; stops a second attempt. */
+export const AUTO_UPDATED_FROM_ENV = "OXYGEN_CLI_AUTO_UPDATED";
+export const BACKGROUND_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const CLI_PACKAGE_NAME = "@oxygen-agent/cli";
+const NPM_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/@oxygen-agent%2Fcli/dist-tags";
+const NPM_CHECK_TIMEOUT_MS = 10_000;
+const SKILLS_REFRESH_TIMEOUT_MS = 120_000;
+// Why automatic updates cannot run, and the one step that works instead. Both
+// ship in the `--status` envelope: an agent reads JSON, so a remedy printed only
+// in the terminal text never reaches it.
+const AUTO_UPDATE_REASON_TEXT = {
+    ci: "off because CI is set",
+    disabled_by_env: "off because OXYGEN_NO_AUTO_UPDATE is set",
+    disabled_by_setting: "off (turned off with --disable-auto)",
+    dev_binary: "not available for oxygen-dev; rebuild it from the dev branch",
+    not_global_npm_install: "not available: this CLI is not a global npm install (npx or a project's node_modules)",
+    non_production_endpoint: "not available against a non-production API",
+};
+const AUTO_UPDATE_NEXT_STEP = {
+    ci: "Update deliberately in CI: oxygen update --package @oxygen-agent/cli@<version>",
+    disabled_by_env: "Unset OXYGEN_NO_AUTO_UPDATE to turn automatic updates back on",
+    disabled_by_setting: "oxygen update --enable-auto",
+    dev_binary: "npm run install-dev-cli (from the latest dev checkout)",
+    not_global_npm_install: "Install globally to get automatic updates: npm install -g @oxygen-agent/cli (or update in place: npm install @oxygen-agent/cli@latest)",
+    non_production_endpoint: "oxygen update",
+};
+// A command that already sent a mutating request must never be re-run whole:
+// the per-route floors can refuse a LATER request after an earlier one wrote.
+let mutatingRequestAnswered = false;
+let stdinConsumed = false;
+export function recordMutatingRequestAnswered() {
+    mutatingRequestAnswered = true;
+}
+/** Call before reading piped stdin: a re-run could not read it a second time. */
+export function markStdinConsumed() {
+    stdinConsumed = true;
+}
+/** Test-only: reset the per-process guards. */
+export function resetAutoUpdateProcessGuards() {
+    mutatingRequestAnswered = false;
+    stdinConsumed = false;
+}
+export function autoUpdateStatePath(env = process.env) {
+    return join(resolveConfigDir(env), "update-state.json");
+}
+export function readAutoUpdateState(env = process.env) {
+    try {
+        const parsed = JSON.parse(readFileSync(autoUpdateStatePath(env), "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Best-effort: an unwritable config directory must never fail a command. */
+export function writeAutoUpdateState(state, env = process.env) {
+    try {
+        const path = autoUpdateStatePath(env);
+        mkdirSync(resolveConfigDir(env), { recursive: true });
+        const temp = `${path}.${process.pid}.tmp`;
+        writeFileSync(temp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temp, path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isTruthyEnv(value) {
+    const normalized = value?.trim().toLowerCase();
+    return Boolean(normalized && normalized !== "0" && normalized !== "false");
+}
+export function autoUpdateEligibility(runtime = {}) {
+    const env = runtime.env ?? process.env;
+    const argv = runtime.argv ?? process.argv;
+    if (isTruthyEnv(env[AUTO_UPDATE_DISABLE_ENV]))
+        return { eligible: false, reason: "disabled_by_env" };
+    if (isTruthyEnv(env.CI))
+        return { eligible: false, reason: "ci" };
+    const state = runtime.state ?? readAutoUpdateState(env);
+    if (state.auto_update === "off")
+        return { eligible: false, reason: "disabled_by_setting" };
+    if (resolveCliBinaryName(env, argv) === "oxygen-dev")
+        return { eligible: false, reason: "dev_binary" };
+    const modulePath = runtime.modulePath ?? fileURLToPath(import.meta.url);
+    if (detectCliInstall(modulePath).kind !== "global")
+        return { eligible: false, reason: "not_global_npm_install" };
+    // Pointed at a non-production API, npm can only reinstall the version that
+    // API's floor is refusing; the endpoint is the fault, not the binary.
+    if (runtime.endpoint && resolveCliUpdateGuidance(runtime.endpoint, env, argv).channel !== "npm") {
+        return { eligible: false, reason: "non_production_endpoint" };
+    }
+    return { eligible: true };
+}
+function withAutoUpdateDetails(error, autoUpdate) {
+    const details = error.details && typeof error.details === "object" && !Array.isArray(error.details)
+        ? { ...error.details, auto_update: autoUpdate }
+        : { auto_update: autoUpdate };
+    return new OxygenError(error.code, error.message, { details, exitCode: error.exitCode });
+}
+// npm can exit 0 having written somewhere the running binary never loads, so an
+// automatic update trusts only the version it can read back from its own package.
+function readInstalledVersion(runtime) {
+    if (runtime.readInstalledVersion)
+        return runtime.readInstalledVersion();
+    const install = detectCliInstall(runtime.modulePath ?? fileURLToPath(import.meta.url));
+    return install.kind === "global" ? readInstalledCliVersion(install.packageDir) : null;
+}
+function readMinimumCliVersion(error) {
+    const details = error.details;
+    if (!details || typeof details !== "object")
+        return null;
+    const value = details.minimum_cli_version;
+    return typeof value === "string" ? value : null;
+}
+/**
+ * The reactive path. Returns the error to throw (annotated with why no update
+ * happened), or — after a successful update — re-runs the command in the new
+ * binary and exits with its status.
+ */
+export async function recoverFromCliFloorRejection(error, endpoint, runtime = {}) {
+    if (error.code !== "cli_update_required")
+        return error;
+    const env = runtime.env ?? process.env;
+    const argv = runtime.argv ?? process.argv;
+    const stderr = runtime.stderr ?? ((text) => { process.stderr.write(text); });
+    if (env[AUTO_UPDATED_FROM_ENV]) {
+        return withAutoUpdateDetails(error, { attempted: false, reason: "already_updated_once", updated_from: env[AUTO_UPDATED_FROM_ENV] });
+    }
+    const eligibility = autoUpdateEligibility({ ...runtime, endpoint });
+    if (!eligibility.eligible)
+        return withAutoUpdateDetails(error, { attempted: false, reason: eligibility.reason });
+    if (mutatingRequestAnswered)
+        return withAutoUpdateDetails(error, { attempted: false, reason: "command_already_wrote" });
+    if (stdinConsumed)
+        return withAutoUpdateDetails(error, { attempted: false, reason: "stdin_consumed" });
+    const minimum = readMinimumCliVersion(error);
+    stderr(`[oxygen] CLI ${OXYGEN_VERSION} is older than this API accepts${minimum ? ` (minimum ${minimum})` : ""}; updating automatically...\n`);
+    const now = runtime.now ?? (() => new Date());
+    const update = runtime.update ?? ((options) => updateCli(options, { env }));
+    const state = readAutoUpdateState(env);
+    const fail = (reason, extra = {}) => {
+        writeAutoUpdateState({
+            ...state,
+            last_result: { at: now().toISOString(), from: OXYGEN_VERSION, to: null, ok: false, trigger: "floor", error: reason },
+        }, env);
+        stderr("[oxygen] Automatic update failed. Run `oxygen update` to update manually.\n");
+        return withAutoUpdateDetails(error, { attempted: true, ok: false, reason, ...extra });
+    };
+    try {
+        await update({ json: true, skipSkillsInstall: true });
+    }
+    catch (updateError) {
+        const stderrText = updateError instanceof OxygenError && updateError.details && typeof updateError.details === "object"
+            ? updateError.details.stderr
+            : undefined;
+        return fail(updateError instanceof Error ? updateError.message : String(updateError), typeof stderrText === "string" ? { npm_stderr: stderrText.slice(0, 2000) } : {});
+    }
+    const installed = readInstalledVersion(runtime);
+    if (!installed || !isVersionGreater(installed, OXYGEN_VERSION)) {
+        return fail(`npm finished but this CLI's own install still reports ${installed ?? "no version"}`);
+    }
+    writeAutoUpdateState({
+        ...state,
+        last_result: { at: now().toISOString(), from: OXYGEN_VERSION, to: installed, ok: true, trigger: "floor" },
+    }, env);
+    const execPath = runtime.execPath ?? process.execPath;
+    const entry = argv[1];
+    if (!entry)
+        return withAutoUpdateDetails(error, { attempted: true, ok: true, reason: "rerun_unavailable" });
+    refreshSkillsInBackground({ ...runtime, env, argv, execPath });
+    stderr("[oxygen] Updated. Re-running your command with the new version...\n");
+    const run = runtime.spawnSync ?? defaultSpawnSync;
+    const child = run(execPath, [entry, ...argv.slice(2)], {
+        stdio: "inherit",
+        env: { ...env, [AUTO_UPDATED_FROM_ENV]: OXYGEN_VERSION },
+        windowsHide: true,
+    });
+    if (child.error) {
+        return withAutoUpdateDetails(error, { attempted: true, ok: true, reason: "rerun_failed", rerun_error: child.error.message });
+    }
+    const exit = runtime.exit ?? ((code) => process.exit(code));
+    return exit(child.status ?? 1);
+}
+/** Refresh the product skills from the NEW binary, detached and best-effort. */
+function refreshSkillsInBackground(runtime) {
+    const entry = runtime.argv[1];
+    if (!entry)
+        return;
+    try {
+        (runtime.spawnDetached ?? defaultSpawnDetached)(runtime.execPath, [entry, "update", "--refresh-skills"], runtime.env);
+    }
+    catch {
+        // Skills refresh is a convenience; `oxygen skills install` remains the manual path.
+    }
+}
+function defaultSpawnSync(...args) {
+    const [command, commandArgs, options] = args;
+    const result = spawnSync(command, commandArgs, options);
+    return { status: result.status, ...(result.error ? { error: result.error } : {}) };
+}
+function defaultSpawnDetached(command, args, env) {
+    const child = spawn(command, args, { detached: true, stdio: "ignore", env, windowsHide: true });
+    child.on("error", () => undefined);
+    child.unref();
+}
+function formatNotice(result) {
+    if (result.ok) {
+        return `[oxygen] Updated automatically from ${result.from}${result.to ? ` to ${result.to}` : ""}. `
+            + "Turn this off with `oxygen update --disable-auto`.\n";
+    }
+    return `[oxygen] Automatic update${result.to ? ` to ${result.to}` : ""} failed (${result.error ?? "unknown error"}). `
+        + "Run `oxygen update` to update manually.\n";
+}
+function isUpdateCommand(args) {
+    const first = args.find((arg) => !arg.startsWith("-"));
+    return first === "update";
+}
+/**
+ * The proactive path, called once at CLI start. Never blocks: it reads a small
+ * state file, prints any pending notice to stderr, and — at most once a day —
+ * spawns a detached `update --background` worker.
+ */
+export function maybeScheduleBackgroundUpdate(runtime = {}) {
+    try {
+        const env = runtime.env ?? process.env;
+        const argv = runtime.argv ?? process.argv;
+        const args = argv.slice(2);
+        if (isUpdateCommand(args) || env[AUTO_UPDATED_FROM_ENV])
+            return;
+        const now = runtime.now ?? (() => new Date());
+        let state = readAutoUpdateState(env);
+        if (state.notice_pending && state.last_result) {
+            (runtime.stderr ?? ((text) => { process.stderr.write(text); }))(formatNotice(state.last_result));
+            state = { ...state, notice_pending: false };
+            writeAutoUpdateState(state, env);
+        }
+        if (!autoUpdateEligibility({ ...runtime, env, argv, state }).eligible)
+            return;
+        const lastCheck = state.last_check_at ? Date.parse(state.last_check_at) : Number.NaN;
+        if (Number.isFinite(lastCheck) && now().getTime() - lastCheck < BACKGROUND_CHECK_INTERVAL_MS)
+            return;
+        // Claim the slot before spawning so concurrent commands don't stampede npm.
+        if (!writeAutoUpdateState({ ...state, last_check_at: now().toISOString() }, env))
+            return;
+        const entry = argv[1];
+        if (!entry)
+            return;
+        (runtime.spawnDetached ?? defaultSpawnDetached)(runtime.execPath ?? process.execPath, [entry, "update", "--background"], env);
+    }
+    catch {
+        // Keeping the CLI current must never break the command the user ran.
+    }
+}
+export async function fetchLatestCliVersion(fetchImpl = fetch) {
+    const response = await fetchImpl(NPM_DIST_TAGS_URL, {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(NPM_CHECK_TIMEOUT_MS),
+    });
+    if (!response.ok)
+        throw new Error(`npm registry answered HTTP ${response.status}`);
+    const body = await response.json();
+    const latest = typeof body.latest === "string" ? body.latest.trim() : "";
+    if (!parseSemver(latest))
+        throw new Error("npm registry returned no usable latest version");
+    return latest;
+}
+/** The detached worker behind `oxygen update --background`. Prints nothing. */
+export async function runBackgroundUpdate(runtime = {}) {
+    const env = runtime.env ?? process.env;
+    const argv = runtime.argv ?? process.argv;
+    const now = runtime.now ?? (() => new Date());
+    const state = readAutoUpdateState(env);
+    const eligibility = autoUpdateEligibility({ ...runtime, env, argv, state });
+    if (!eligibility.eligible)
+        return { action: "skipped", reason: eligibility.reason };
+    let latest;
+    try {
+        latest = await fetchLatestCliVersion(runtime.fetch ?? fetch);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeAutoUpdateState({ ...readAutoUpdateState(env), last_check_error: message }, env);
+        return { action: "check_failed", error: message };
+    }
+    const checked = { ...readAutoUpdateState(env), latest_seen: latest };
+    delete checked.last_check_error;
+    if (!isVersionGreater(latest, OXYGEN_VERSION)) {
+        writeAutoUpdateState(checked, env);
+        return { action: "up_to_date", latest };
+    }
+    const update = runtime.update ?? ((options) => updateCli(options, { env }));
+    try {
+        await update({ json: true, skipSkillsInstall: true, package: `${CLI_PACKAGE_NAME}@${latest}` });
+        const installed = readInstalledVersion(runtime);
+        if (installed !== latest) {
+            throw new Error(`npm finished but this CLI's own install reports ${installed ?? "no version"}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeAutoUpdateState({
+            ...checked,
+            notice_pending: true,
+            last_result: { at: now().toISOString(), from: OXYGEN_VERSION, to: latest, ok: false, trigger: "background", error: message },
+        }, env);
+        return { action: "update_failed", latest, error: message };
+    }
+    writeAutoUpdateState({
+        ...checked,
+        notice_pending: true,
+        last_result: { at: now().toISOString(), from: OXYGEN_VERSION, to: latest, ok: true, trigger: "background" },
+    }, env);
+    const entry = argv[1];
+    if (entry) {
+        (runtime.spawnSync ?? defaultSpawnSync)(runtime.execPath ?? process.execPath, [entry, "update", "--refresh-skills"], {
+            stdio: "ignore",
+            env,
+            windowsHide: true,
+            timeout: SKILLS_REFRESH_TIMEOUT_MS,
+        });
+    }
+    return { action: "updated", latest };
+}
+/** `oxygen update --status`, `--enable-auto`, `--disable-auto`. Checks npm live. */
+export async function readAutoUpdateStatus(runtime = {}) {
+    const env = runtime.env ?? process.env;
+    let state = readAutoUpdateState(env);
+    let settingChanged;
+    if (runtime.setting) {
+        settingChanged = (state.auto_update === "off" ? "off" : "on") !== runtime.setting;
+        state = { ...state, auto_update: runtime.setting };
+        if (!runtime.dryRun && !writeAutoUpdateState(state, env)) {
+            throw new OxygenError("config_write_failed", `Could not save the auto-update setting to ${autoUpdateStatePath(env)}.`, {
+                details: { state_path: autoUpdateStatePath(env) },
+                exitCode: 1,
+            });
+        }
+    }
+    const eligibility = autoUpdateEligibility({ ...runtime, env, state });
+    let latest = null;
+    let latestError;
+    try {
+        latest = await fetchLatestCliVersion(runtime.fetch ?? fetch);
+    }
+    catch (error) {
+        latestError = error instanceof Error ? error.message : String(error);
+    }
+    return {
+        current_version: OXYGEN_VERSION,
+        latest_version: latest,
+        ...(latestError ? { latest_error: latestError } : {}),
+        update_available: latest ? isVersionGreater(latest, OXYGEN_VERSION) : null,
+        ...(runtime.setting ? { dry_run: runtime.dryRun === true, setting_changed: settingChanged === true } : {}),
+        auto_update: {
+            setting: state.auto_update === "off" ? "off" : "on",
+            active: eligibility.eligible,
+            reason: eligibility.eligible ? null : eligibility.reason,
+            reason_text: eligibility.eligible ? null : AUTO_UPDATE_REASON_TEXT[eligibility.reason],
+            next_step: eligibility.eligible ? null : AUTO_UPDATE_NEXT_STEP[eligibility.reason],
+            disable: "oxygen update --disable-auto (or set OXYGEN_NO_AUTO_UPDATE=1)",
+            last_check_at: state.last_check_at ?? null,
+            last_result: state.last_result ?? null,
+        },
+        state_path: autoUpdateStatePath(env),
+    };
+}

package/dist/command-manifest.js

@@ -68,7 +68,7 @@ const MUTATING_VERBS = new Set([
     // `support chat` starts or continues a customer-authored Plain Thread. The
     // conversational noun is still a real external write.
     "buy", "call", "cancel", "chat", "chat-action", "claim", "clear",
-    "comment", "configure", "connect", "create", "decide", "delete", "delete-message", "delist", "disable",
+    "comment", "configure", "connect", "convert", "create", "decide", "delete", "delete-message", "delist", "disable",
     "disconnect", "dispatch", "done", "draft", "duplicate", "edit", "emit", "enable", "enroll",
     // Exact leaf, not a `field` prefix: `support admin field-set` writes a Plain
     // Thread field, while a future `field-get` would be a read.
@@ -89,6 +89,9 @@ const MUTATING_VERBS = new Set([
     "unarchive", "unpublish", "unshare",
     "unbind", "unsubscribe", "update", "upload", "upsert", "use", "warm-send", "warmup",
     "withdraw", "write",
+    // `voice numbers release` returns a number to the carrier: irreversible,
+    // someone else can take it within minutes. It is the only `release` leaf.
+    "release",
 ]);
 // Exact commands that must not inherit a read-only discovery label. Warmup
 // status persists state and can pause the provider; reconnect replaces its
@@ -103,6 +106,8 @@ const MUTATING_COMMANDS = new Set([
     // whose own subcommands (list/set/enable/disable/backfill, catalog/entries)
     // already carry their own correctly-classified verbs.
     "viewers enrichment",
+    // A noun leaf that switches a bought domain's yearly paid renewal on or off.
+    "domains renewal",
 ]);
 // `--approved` usually identifies a paid or externally mutating execution
 // mode, but a small number of approved operations are explicitly
@@ -126,6 +131,10 @@ const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
     // flag neither authorizes nor caps later inference; only `copilot send` can
     // trigger the billed model loop.
     "copilot start",
+    // Releasing a phone number STOPS its monthly charge; it never buys anything.
+    "voice numbers release",
+    // Both previews without --approved; approval cancels or archives, never charges.
+    "domains delete",
     "mailboxes delete",
     // Previews without --approved; with it, removes a program no creator ever
     // joined. No provider call, no credits.
@@ -171,6 +180,7 @@ const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     // an agent that previewing the play arms it, and the preview would go unrun.
     "linkedin intent autoenroll",
     "mailboxes emailguard auto-enroll",
+    "domains delete",
     "mailboxes delete",
     "sequences recover-capacity",
     "support admin done",
@@ -178,6 +188,10 @@ const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     // A bare call reads the Plain workspace and prints the plan; --apply writes.
     "support admin setup",
     "verify email",
+    // Both fenced by --approved: a bare call prices (buy) or describes (release)
+    // what would change and writes nothing.
+    "voice numbers buy",
+    "voice numbers release",
     "workflows webhooks rotate",
 ]);
 export function buildCommandManifest(program, binaryName) {

package/dist/credentials.d.ts

@@ -77,4 +77,6 @@ export declare function pickProfileNameForUserSession(userId: string, candidateS
 export declare function switchCredentialProfile(profile: string, env?: NodeJS.ProcessEnv): Promise<CredentialProfile>;
 export declare function updateActiveOrganizationForProfile(profile: string, organization: StoredOrganization, env?: NodeJS.ProcessEnv): Promise<CredentialProfile>;
 export declare function normalizeApiUrl(value: string): string;
+/** The CLI's per-user config directory; `OXYGEN_CONFIG_DIR` overrides it. */
+export declare function resolveConfigDir(env?: NodeJS.ProcessEnv): string;
 export {};

package/dist/credentials.js

@@ -411,12 +411,15 @@ function credentialStore(env) {
         return "credential-manager";
     return "file";
 }
-function credentialsPath(env) {
-    const configDir = env.OXYGEN_CONFIG_DIR?.trim()
+/** The CLI's per-user config directory; `OXYGEN_CONFIG_DIR` overrides it. */
+export function resolveConfigDir(env = process.env) {
+    return env.OXYGEN_CONFIG_DIR?.trim()
         || (process.platform === "win32"
             ? join(env.APPDATA || join(homedir(), "AppData", "Roaming"), "oxygen")
             : join(homedir(), ".config", "oxygen"));
-    return join(configDir, "credentials.json");
+}
+function credentialsPath(env) {
+    return join(resolveConfigDir(env), "credentials.json");
 }
 function readFileCredentialPayload(env) {
     const path = credentialsPath(env);

package/dist/functions-commands.js

@@ -47,7 +47,7 @@ export function registerFunctionsCommands(program, handle) {
     functions.command("rename <function> <name>").description("Rename a Function while preserving its identity, callers and published execution.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, name, options) => handle("functions rename", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "rename", function: ref, display_name: name } })));
-    functions.command("delete <function>").description("Preview removal from the Function library, then remove it with --yes; preserves backing tables, rows and run history. Connected callers or active runs block deletion.")
+    functions.command("delete <function>").description("Preview removal from the Function library, then remove it with --yes; preserves backing tables, rows and run history. The preview names every column that calls it: those stop running, keeping the values they already wrote. Only the Function's own active runs block deletion.")
         .addHelpText("after", "\nDeleting your own Function is final: there is no restore, unlike `tables delete`. To reuse the logic, `tables duplicate` the backing Table and draft a new Function from the copy.\n")
         .option("--yes", "Confirm removal of this Function after reviewing its callers.")
         .option("--json", "Print a JSON envelope.")