@oxygen-agent/cli 1.1011.98 → 1.1011.322

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.1011.98
+Version: 1.1011.322

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

@@ -165,6 +165,10 @@ export function renderPrimaryProviderBoard(payload, options = {}) {
         ((num(summary.fallback_providers) ?? 0) > 0
             ? ` · ${count(summary.fallback_providers)} default-chain fallback${(num(summary.fallback_providers) ?? 0) === 1 ? "" : "s"}` +
                 ((num(summary.fallback_critical) ?? 0) > 0 ? ` (${count(summary.fallback_critical)} critical)` : "")
+            : "") +
+        ((num(summary.outside_chain_providers) ?? 0) > 0
+            ? ` · ${count(summary.outside_chain_providers)} managed outside every chain` +
+                ((num(summary.outside_chain_critical) ?? 0) > 0 ? ` (${count(summary.outside_chain_critical)} critical)` : "")
             : ""));
     out(`COGS (managed primaries): 30d ${usd(summary.cost_30d_usd)} · 7d ${usd(summary.cost_7d_usd)}`);
     out(renderGuards(obj(board.guards)));
@@ -189,17 +193,23 @@ export function renderPrimaryProviderBoard(payload, options = {}) {
     }
     // A dry fallback account is invisible until a primary fails, which is
     // exactly when nobody has time to notice it — so it renders here too.
-    const fallbacks = arr(board.default_chain_fallbacks)
-        .map((row) => obj(row))
-        .filter((row) => row !== null)
-        .sort((a, b) => postureRank(str(obj(a.posture)?.level)) - postureRank(str(obj(b.posture)?.level)) ||
-        (str(a.provider) ?? "").localeCompare(str(b.provider) ?? ""));
+    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):");
         for (const row of fallbacks)
             out(renderProvider(row, now, binary));
     }
+    // Managed data providers no routed chain reaches. Direct tool calls and product
+    // features still spend OXYGEN's key there, and until this group existed a dead
+    // key or a dry wallet on one of them showed on no surface at all.
+    const outsideChains = rowsWorstFirst(board.managed_outside_chains);
+    if (outsideChains.length > 0) {
+        out("");
+        out("Managed outside every chain (OXYGEN holds the key; direct tool calls and product features reach them, no routed chain does):");
+        for (const row of outsideChains)
+            out(renderProvider(row, now, binary));
+    }
     const intents = arr(board.intents_without_primary)
         .map((row) => obj(row))
         .filter((row) => row !== null);
@@ -234,6 +244,14 @@ export function renderPrimaryProviderBoard(payload, options = {}) {
     }
     return lines.join("\n");
 }
+/** Provider rows from one board group, worst posture first, then by name. */
+function rowsWorstFirst(value) {
+    return arr(value)
+        .map((row) => obj(row))
+        .filter((row) => row !== null)
+        .sort((a, b) => postureRank(str(obj(a.posture)?.level)) - postureRank(str(obj(b.posture)?.level)) ||
+        (str(a.provider) ?? "").localeCompare(str(b.provider) ?? ""));
+}
 const INTENT_KIND_COPY = {
     fallback_only: "fallback only — paid routed steps exist but none is seeded primary (the real gap):",
     preflight_only: "preflight only — every step is a free sizing/count probe (by design):",
@@ -285,6 +303,8 @@ function renderProvider(row, now, binary) {
     const healthStatus = str(health.latest_status) ?? (probe === "none" ? "unmonitored" : "no data");
     const healthDetail = [
         `${probe} probe`,
+        // No zero-credit read exists for this vendor; the reasons below say why.
+        str(health.unwatchable) ? "structurally unwatchable" : null,
         ago(health.last_checked_at, now),
         num(health.uptime_pct_96h) === null ? null : `${pct(health.uptime_pct_96h)} up 96h`,
         (num(health.degraded_pct_96h) ?? 0) > 0 ? `${pct(health.degraded_pct_96h)} degraded` : null,

package/dist/column-run-notices.d.ts

@@ -9,6 +9,16 @@
  * live run, or a preview the server could not produce).
  */
 export declare function formatAiPromptPreviewNotice(data: unknown): string | null;
+/**
+ * `columns run --dry-run` and `enrich-column preview` carry
+ * `provider_availability.lanes`: whether Oxygen's managed account behind each
+ * lane can take a call right now (OXP-1.14.12). On 2026-09-27 a BounceBan
+ * column's dry run printed nothing while that account was benched and the
+ * approved run then deferred forever. One line for the verdict (with the fix
+ * when no lane can run), then one line per lane that cannot run. `--json`
+ * readers get the fields; nothing is printed while every lane can run.
+ */
+export declare function formatProviderLaneNotices(availability: unknown): string[];
 /**
  * Advisory reference findings from `columns add` / `update` / `rename`.
  *
@@ -19,3 +29,9 @@ export declare function formatAiPromptPreviewNotice(data: unknown): string | nul
  * sibling's reference. Printed to stderr so `--json` piping stays clean.
  */
 export declare function formatColumnReferenceNotices(data: unknown): string[];
+/**
+ * The inputs `columns add --capability` mapped, in `--input` syntax, or the
+ * warning and command for one it could not find. The envelope carries both for
+ * `--json` readers; this is the line a human sees on stderr.
+ */
+export declare function formatEnrichmentInputMappingNotice(data: unknown): string[];

package/dist/column-run-notices.js

@@ -30,11 +30,41 @@ export function formatAiPromptPreviewNotice(data) {
     const truncation = preview.truncated === true
         ? ` — truncated to ${shown.length} of ${chars} chars`
         : "";
+    const state = isRecord(preview.state) && isRecord(preview.state.row)
+        ? JSON.stringify(preview.state.row, null, 2)
+        : null;
     return [
         `prompt preview — row ${rowId} (${source}), before grounding${truncation}:`,
         shown,
+        ...(state ? [`row values sent separately in classification state:\n${state.slice(0, 4000)}${state.length > 4000 ? "… (truncated)" : ""}`] : []),
     ].join("\n");
 }
+/**
+ * `columns run --dry-run` and `enrich-column preview` carry
+ * `provider_availability.lanes`: whether Oxygen's managed account behind each
+ * lane can take a call right now (OXP-1.14.12). On 2026-09-27 a BounceBan
+ * column's dry run printed nothing while that account was benched and the
+ * approved run then deferred forever. One line for the verdict (with the fix
+ * when no lane can run), then one line per lane that cannot run. `--json`
+ * readers get the fields; nothing is printed while every lane can run.
+ */
+export function formatProviderLaneNotices(availability) {
+    if (!isRecord(availability) || !Array.isArray(availability.lanes))
+        return [];
+    const lines = [];
+    for (const lane of availability.lanes) {
+        if (!isRecord(lane) || (lane.availability !== "degraded" && lane.availability !== "unknown"))
+            continue;
+        const state = lane.availability === "unknown" ? "availability unknown" : "unavailable";
+        const detail = readRecordString(lane, "message") ?? readRecordString(lane, "next_action");
+        lines.push(`! ${readRecordString(lane, "tool_id") ?? "a lane"} ${state}${detail ? `: ${detail}` : ""}`);
+    }
+    const message = readRecordString(availability, "message");
+    if (lines.length === 0 || !message)
+        return lines;
+    const fix = availability.will_produce_results === false ? readRecordString(availability, "next_action") : null;
+    return [`! ${message}${fix ? ` ${fix}` : ""}`, ...lines];
+}
 /**
  * Advisory reference findings from `columns add` / `update` / `rename`.
  *
@@ -57,3 +87,30 @@ export function formatColumnReferenceNotices(data) {
     }
     return notices;
 }
+/**
+ * The inputs `columns add --capability` mapped, in `--input` syntax, or the
+ * warning and command for one it could not find. The envelope carries both for
+ * `--json` readers; this is the line a human sees on stderr.
+ */
+export function formatEnrichmentInputMappingNotice(data) {
+    if (!isRecord(data) || !isRecord(data.input_mapping))
+        return [];
+    const notices = [];
+    const mapped = isRecord(data.input_mapping.mapped) ? Object.entries(data.input_mapping.mapped) : [];
+    if (mapped.length > 0) {
+        const origin = data.input_mapping.source === "auto_detected" ? "Inputs mapped from this table" : "Inputs";
+        notices.push(`${origin}: ${mapped.map(([input, reads]) => `${input}=${String(reads)}`).join(", ")}.`);
+    }
+    const gap = Array.isArray(data.warnings)
+        ? data.warnings.find((entry) => isRecord(entry) && entry.code === "enrichment_inputs_unmapped")
+        : undefined;
+    if (isRecord(gap)) {
+        const message = readRecordString(gap, "message");
+        if (message)
+            notices.push(`warning: ${message}`);
+        const nextAction = readRecordString(data, "next_action");
+        if (nextAction)
+            notices.push(nextAction);
+    }
+    return notices;
+}

package/dist/command-manifest.js

@@ -25,8 +25,9 @@ const COMMAND_SEARCH_STOP_WORDS = new Set([
 // leaf in the tree using that verb, so the default (mutates:false) would have
 // advertised the most consequential collaboration write as a read.
 const MUTATING_VERBS = new Set([
+    "forget-whatsapp-chat",
     "start-whatsapp",
-    "brand-approve", "revoke-invite", "confirm",
+    "revoke-invite", "confirm",
     // Exact leaf: `ugc creators set-target` writes one creator's posting deal.
     "set-target",
     "infrastructure-exit",
@@ -116,6 +117,7 @@ const MUTATING_COMMANDS = new Set([
 // zero-credit. Keep those exceptions exact so discovery never invents spend.
 const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
     "inbox delete-message",
+    "inbox forget-whatsapp-chat",
     "tables watcher preview",
     "knowledge repositories connect",
     "knowledge repositories resolve",
@@ -129,6 +131,12 @@ const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
     "ugc sponsorship cancel",
     // A Function binding stores a cap for future runs; creating it executes nothing.
     "functions bind",
+    // Same shape: a draft Sequence stores its LinkedIn --max-credits ceiling for a
+    // later approved `sequences start`, which carries its own cap. Creating or
+    // editing one spends nothing; the manifest said otherwise while MCP called
+    // the same tools free (blind user eval, 2026-09-29).
+    "sequences create",
+    "sequences update",
     // Starting an attended session itself is free. This legacy compatibility
     // flag neither authorizes nor caps later inference; only `copilot send` can
     // trigger the billed model loop.
@@ -166,6 +174,7 @@ const READ_ONLY_COMMANDS = new Set([
 // calling the command without its confirmation flag writes anything.
 const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     "inbox delete-message",
+    "inbox forget-whatsapp-chat",
     "tables watcher preview",
     "ugc creators invite",
     "ugc creators send-invite",

package/dist/connectors-commands.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+import { type ContractFlagOverlay } from "./contract-flags.js";
+type JsonOptions = {
+    json?: boolean;
+};
+type Handle = (command: string, options: JsonOptions, action: () => Promise<unknown>) => Promise<void>;
+export declare const CONNECTORS_FLAG_OVERLAY: ContractFlagOverlay;
+/** The PATCH body for the flags given; one of the two workspace flags is required. */
+export declare function buildConnectorUpdateBody(options: Record<string, unknown>): Record<string, unknown>;
+export declare function registerConnectorsCommands(program: Command, handle: Handle): void;
+export {};

package/dist/connectors-commands.js

@@ -0,0 +1,63 @@
+// `oxygen connectors`: the apps a person connected to OXYGEN with OAuth
+// (ChatGPT, Claude, Codex…) and the workspace each one works in without asking.
+// The set command's flags come from the shared contract that also generates
+// `oxygen_connector_update` and validates the route, so the CLI and MCP cannot
+// disagree about what can be set.
+import { Command } from "commander";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { CONNECTOR_UPDATE_OPERATION } from "@oxygen/shared/contracts/connectors";
+import { operationPath } from "@oxygen/shared/contracts/operations";
+import { addContractFlags, readContractFlags } from "./contract-flags.js";
+import { requestOxygen } from "./http-client.js";
+const update = CONNECTOR_UPDATE_OPERATION;
+export const CONNECTORS_FLAG_OVERLAY = {
+    default_workspace: {
+        help: "The workspace this app should work in without asking: its id, slug or exact name from `orgs list`. You must be a member.",
+        valueName: "<workspace>",
+    },
+};
+/** The PATCH body for the flags given; one of the two workspace flags is required. */
+export function buildConnectorUpdateBody(options) {
+    const body = readContractFlags(options, update.contract, CONNECTORS_FLAG_OVERLAY);
+    if (!("default_workspace" in body)) {
+        throw new OxygenError("invalid_request", "Pass --default-workspace <workspace> to set where the app works, or --clear-default-workspace to have it ask each time.", { exitCode: 1 });
+    }
+    return body;
+}
+export function registerConnectorsCommands(program, handle) {
+    const connectors = program
+        .command("connectors")
+        .description("Connected apps: ChatGPT, Claude, Codex and any other app you connected to OXYGEN with OAuth, and the default workspace each one works in without asking. "
+        + "`connectors list` shows them; `connectors set <app> --default-workspace <workspace>` changes that app only. "
+        + "Picking a workspace inside an app changes the same setting, and the latest choice wins. This CLI keeps its own workspace (`orgs use`). "
+        + "Web: https://oxygen-agent.com/settings/connected-apps.");
+    connectors.addCommand(new Command("list")
+        .description("List your connected apps with each one's default workspace, when it was last used, and the workspaces you can choose from. Read-only, 0 credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handle("connectors list", options, () => requestOxygen("/api/cli/connectors"));
+    }));
+    connectors.addCommand(new Command("get")
+        .description("Show one connected app and its default workspace. Read-only, 0 credits.")
+        .argument("<connection>", update.cli.argument?.description ?? "The app's id or name.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (connection, options) => {
+        await handle("connectors get", options, () => requestOxygen(`/api/cli/connectors/${encodeURIComponent(connection)}`));
+    }));
+    connectors.addCommand(addContractFlags(new Command(update.cli.path.at(-1) ?? "set")
+        .description(update.cli.summary)
+        .argument(`<${update.cli.argument?.name ?? "connection"}>`, update.cli.argument?.description), update.contract, CONNECTORS_FLAG_OVERLAY)
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", `
+Examples:
+  oxygen connectors list
+  oxygen connectors set ChatGPT --default-workspace "Acme GTM"
+  oxygen connectors set <id> --clear-default-workspace
+`)
+        .action(async (connection, options) => {
+        await handle("connectors set", options, () => requestOxygen(operationPath(update, { connection }), {
+            method: update.method,
+            body: buildConnectorUpdateBody(options),
+        }));
+    }));
+}

package/dist/help.d.ts

@@ -1,4 +1,5 @@
-import type { Command } from "commander";
+import type { Command, CommanderError } from "commander";
+import { type CliFailure } from "@oxygen/shared/cli-result";
 export declare function applyOxygenHelp(program: Command, binaryName: string): void;
 /**
  * Turn commander's own edit-distance suggester on for EVERY command.
@@ -28,4 +29,29 @@ export declare function enableCommandSuggestions(command: Command): void;
  * all, or when the flag is not a long option.
  */
 export declare function unknownOptionHint(program: Command, argv: readonly string[], message: string): string | null;
+/**
+ * Drop the help flag when it follows an operand that names no subcommand.
+ *
+ * Commander answers `--help` before it checks the operand, so `oxygen sequence
+ * --help` printed the ROOT help and exited 0: a typo'd command read as success,
+ * and the agent took the root help for the group it meant (blind user eval,
+ * 2026-09-29). Without the flag the same argv fails as the unknown command it
+ * is, with commander's suggestion, our hint and exit 2. Only a group that takes
+ * no positional argument qualifies, so `sequences get <id> --help` still helps.
+ */
+export declare function withoutHelpForUnknownCommand(program: Command, argv: readonly string[]): string[];
 export declare function unknownCommandHint(program: Command, argv: readonly string[]): string | null;
+/**
+ * The failure envelope and exit code for a commander usage error, or null when
+ * the error is not one (`--help` and `--version` exit 0). Commander refuses
+ * before any action runs, so the envelope every handler prints never covered
+ * these: `ugc creators accept` without `--linkedin-url` gave `--json` callers an
+ * empty stdout and exit 1 (UGC E2E pass, 2026-09-29). `hint` is the first hint
+ * already written to stderr; it becomes `details.next_step`.
+ */
+export declare function commanderUsageFailure(program: Command, argv: readonly string[], error: CommanderError, hint: string | null): {
+    envelope: CliFailure;
+    exitCode: number;
+} | null;
+/** `--json` anywhere before a `--` terminator, where commander still reads options. */
+export declare function argvRequestsJson(argv: readonly string[]): boolean;

package/dist/help.js

@@ -1,4 +1,5 @@
 import { CLI_EXIT_CODE_TABLE } from "@oxygen/shared";
+import { exitCodeForErrorCode, failure } from "@oxygen/shared/cli-result";
 // Grouped `--help` for the ~70 top-level command groups: commander's default
 // registration-order wall (login, auth, profiles, ... before any GTM noun) is
 // the first thing every fresh agent reads, so order it by the OXYGEN OS layer
@@ -225,7 +226,7 @@ export function unknownOptionHint(program, argv, message) {
     const flag = /unknown option '(--[^']+)'/.exec(message)?.[1];
     if (!flag)
         return null;
-    const [command, path] = resolveCommandPath(program, argv);
+    const { command, path } = resolveCommandPath(program, argv);
     const longs = new Set();
     for (let current = command; current; current = current.parent) {
         for (const option of current.options)
@@ -245,45 +246,127 @@ export function unknownOptionHint(program, argv, message) {
     }
     return `Hint: \`${path}\` has no \`${bare}\`. ${helpLine}`;
 }
-/** Walk the command path in argv (stopping at the first option) and return the deepest command with its printable path. */
+/**
+ * Walk the command path in argv and return the deepest command, its printable
+ * path, and the first token that is no subcommand of it (`next`). Root options
+ * and their values (`--org <id>`, `--profile <name>`) are stepped over, since
+ * agents routinely pass them first; any other option ends the walk, because
+ * options below the root are commander's business.
+ */
 function resolveCommandPath(program, argv) {
-    let current = program;
+    let command = program;
     let path = program.name();
-    for (const token of argv) {
-        if (token.startsWith("-"))
-            break;
-        const child = current.commands.find((candidate) => candidate.name() === token || candidate.aliases().includes(token));
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token.startsWith("-")) {
+            const flag = token.split("=")[0];
+            const option = program.options.find((candidate) => candidate.long === flag || candidate.short === flag);
+            if (!option)
+                break;
+            const value = argv[index + 1];
+            if (!token.includes("=") && (option.required || (option.optional && value !== undefined && !value.startsWith("-"))))
+                index += 1;
+            continue;
+        }
+        const child = command.commands.find((candidate) => candidate.name() === token || candidate.aliases().includes(token));
         if (!child)
-            break;
-        current = child;
+            return { command, path, next: token };
+        command = child;
         path = `${path} ${token}`;
     }
-    return [current, path];
+    return { command, path };
+}
+/**
+ * Drop the help flag when it follows an operand that names no subcommand.
+ *
+ * Commander answers `--help` before it checks the operand, so `oxygen sequence
+ * --help` printed the ROOT help and exited 0: a typo'd command read as success,
+ * and the agent took the root help for the group it meant (blind user eval,
+ * 2026-09-29). Without the flag the same argv fails as the unknown command it
+ * is, with commander's suggestion, our hint and exit 2. Only a group that takes
+ * no positional argument qualifies, so `sequences get <id> --help` still helps.
+ */
+export function withoutHelpForUnknownCommand(program, argv) {
+    const args = argv.slice(2);
+    const end = args.indexOf("--");
+    const scanned = end < 0 ? args : args.slice(0, end);
+    const isHelp = (token) => token === "--help" || token === "-h";
+    if (!scanned.some(isHelp))
+        return [...argv];
+    const { command, next } = resolveCommandPath(program, args);
+    if (next === undefined || command.commands.length === 0 || command.registeredArguments.length > 0)
+        return [...argv];
+    return [...argv.slice(0, 2), ...args.filter((token, index) => !(index < scanned.length && isHelp(token)))];
 }
 export function unknownCommandHint(program, argv) {
-    let current = program;
-    let path = program.name();
-    for (const token of argv) {
-        // Options and their values are commander's business; only the command path
-        // is walked here.
-        if (token.startsWith("-"))
-            break;
-        const child = current.commands.find((candidate) => candidate.name() === token || candidate.aliases().includes(token));
-        if (child) {
-            current = child;
-            path = `${path} ${token}`;
-            continue;
-        }
-        if (current.commands.length === 0)
-            return null;
-        return buildUnknownCommandHint(current, path, token);
-    }
-    return null;
+    const { command, path, next } = resolveCommandPath(program, argv);
+    if (next === undefined || command.commands.length === 0)
+        return null;
+    return buildUnknownCommandHint(command, path, next);
+}
+/**
+ * Commander's refusals, each as the `missing_*` / `invalid_*` code the exit
+ * table classes as 2 (usage). `commander.help` is a command group run without
+ * a subcommand (help on stderr); `commander.error` is a command's own
+ * `command.error(...)`.
+ */
+const COMMANDER_USAGE_CODES = {
+    "commander.missingMandatoryOptionValue": "missing_required_option",
+    "commander.optionMissingArgument": "missing_option_value",
+    "commander.missingArgument": "missing_argument",
+    "commander.help": "missing_subcommand",
+    "commander.unknownOption": "invalid_option",
+    "commander.unknownCommand": "invalid_command",
+    "commander.excessArguments": "invalid_arguments",
+    "commander.invalidArgument": "invalid_argument",
+    "commander.conflictingOption": "invalid_option_combination",
+    "commander.error": "invalid_request",
+};
+/**
+ * The failure envelope and exit code for a commander usage error, or null when
+ * the error is not one (`--help` and `--version` exit 0). Commander refuses
+ * before any action runs, so the envelope every handler prints never covered
+ * these: `ugc creators accept` without `--linkedin-url` gave `--json` callers an
+ * empty stdout and exit 1 (UGC E2E pass, 2026-09-29). `hint` is the first hint
+ * already written to stderr; it becomes `details.next_step`.
+ */
+export function commanderUsageFailure(program, argv, error, hint) {
+    if (error.exitCode === 0)
+        return null;
+    const code = COMMANDER_USAGE_CODES[error.code];
+    if (!code)
+        return null;
+    const { path } = resolveCommandPath(program, argv);
+    const message = error.code === "commander.help"
+        ? `\`${path}\` needs a subcommand.`
+        : error.message.replace(/^error:\s*/, "");
+    const option = /option '(-[^' ]+)/.exec(message)?.[1];
+    const helpFor = error.code === "commander.help" ? "subcommands" : "options";
+    return {
+        envelope: failure(path.split(" ").slice(1).join(" ") || program.name(), {
+            code,
+            message,
+            details: {
+                commander_code: error.code,
+                ...(option ? { option } : {}),
+                next_step: hint?.replace(/^Hint:\s*/, "") ?? `Run \`${path} --help\` for its ${helpFor}.`,
+            },
+        }),
+        exitCode: exitCodeForErrorCode(code),
+    };
+}
+/** `--json` anywhere before a `--` terminator, where commander still reads options. */
+export function argvRequestsJson(argv) {
+    const end = argv.indexOf("--");
+    return (end < 0 ? argv : argv.slice(0, end)).includes("--json");
 }
 function buildUnknownCommandHint(parent, path, token) {
     const names = parent.commands.map((command) => command.name()).filter((name) => name !== "help");
     const lower = token.toLowerCase();
-    const synonym = (COMMAND_SYNONYMS[lower] ?? []).find((candidate) => names.includes(candidate));
+    // A read intent on a budget must never point at the mutating `set` command.
+    const synonym = path.endsWith(" budget") && lower === "get" && names.includes("list")
+        ? "list"
+        : (COMMAND_SYNONYMS[lower] ?? []).find((candidate) => names.includes(candidate));
     // A unique prefix is the other guess commander cannot make: `tables desc`
     // scores too far from `describe` on edit distance, but it names exactly one
     // command.

package/dist/http-client.js

@@ -5,6 +5,11 @@ import { defaultApiUrl, loadCredentialsWithEndpoint } from "./credentials.js";
 import { assertResolvedApiUrl, cliEndpointDetails, describeCliEndpoint, isProdApiUrl, resolveCliUpdateGuidance, } from "./runtime.js";
 const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 const CLI_COMPATIBILITY_CHECK_TIMEOUT_MS = 5_000;
+// A write that fails in transit may already have been applied before the
+// connection dropped or the client gave up, so a blind retry can repeat it.
+// Replay on the Idempotency-Key is per route (most routes ignore the header),
+// so this must not promise that a same-key retry is safe.
+const UNCONFIRMED_WRITE_NEXT_STEP = "This change may already have been applied. Check the current state (for example with the matching list or get command) before you retry.";
 const cliCompatibilityCheckKeys = new Set();
 export async function requestOxygen(// skipcq: JS-R1005
 path, options = {}) {
@@ -99,6 +104,7 @@ path, options = {}) {
     catch (error) {
         if (error instanceof OxygenError)
             throw error;
+        const unconfirmedWrite = method === "GET" ? {} : { next_step: UNCONFIRMED_WRITE_NEXT_STEP };
         if (timeout.timedOut() || (timeoutMs !== undefined && isAbortError(error))) {
             throw new OxygenError("network_timeout", "Oxygen API request timed out.", {
                 details: {
@@ -107,6 +113,7 @@ path, options = {}) {
                     timeout_ms: timeoutMs,
                     trace_id: traceId,
                     ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
+                    ...unconfirmedWrite,
                 },
                 exitCode: 1,
             });
@@ -116,6 +123,7 @@ path, options = {}) {
                 api_url: apiUrl,
                 reason: error instanceof Error ? error.message : "unknown",
                 ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
+                ...unconfirmedWrite,
             },
             exitCode: 1,
         });