@oxygen-agent/cli 1.1011.855 → 1.1011.1091

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.855
+Version: 1.1011.1091

package/dist/admin-lead-magnet-commands.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+type Handle = (command: string, options: {
+    json?: boolean;
+}, action: () => Promise<unknown>) => Promise<void>;
+/** `oxygen admin lead-magnets`: the staff CMS for the public /resources catalog, the same rows /admin/lead-magnets edits. */
+export declare function registerAdminLeadMagnetCommands(program: Command, handle: Handle): void;
+export {};

package/dist/admin-lead-magnet-commands.js

@@ -0,0 +1,128 @@
+import { readFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { Option } from "commander";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { resolveLiveDryRunMode } from "./cli-values.js";
+import { requestOxygen } from "./http-client.js";
+// The resource JSON documented in docs/marketing-resources.md, mapped to the API body.
+const FILE_FIELDS = {
+    slug: "slug", title: "title", description: "description", imageUrl: "image_url", imageAlt: "image_alt",
+    redirectUrl: "redirect_url", status: "status", sortOrder: "sort_order",
+};
+const COVER_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp" };
+// The server's own ceiling (LEAD_MAGNET_MAX_IMAGE_BYTES), checked first so an oversized file is never sent.
+const MAX_COVER_BYTES = 4 * 1024 * 1024;
+const usageError = (message) => new OxygenError("invalid_request", message, { exitCode: 2 });
+/** `oxygen admin lead-magnets`: the staff CMS for the public /resources catalog, the same rows /admin/lead-magnets edits. */
+export function registerAdminLeadMagnetCommands(program, handle) {
+    const admin = program.commands.find((command) => command.name() === "admin");
+    if (!admin)
+        throw new Error("Admin commands must be registered first.");
+    const leadMagnets = admin
+        .command("lead-magnets")
+        .description("Publish, update and unpublish the email-gated lead magnets (resources) on the public /resources catalog. Staff only.");
+    leadMagnets
+        .command("list")
+        .description("List every lead magnet (resource) on /resources, drafts included, with status and public URL. Staff only, read-only.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("admin lead-magnets list", options, () => requestOxygen("/api/cli/admin/lead-magnets")));
+    leadMagnets
+        .command("get")
+        .description("Show one lead magnet (resource) by slug: every field, draft or published, and its public /resources URL. Staff only, read-only.")
+        .argument("<slug>", "The resource's slug (its /resources/<slug> path) or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action((slug, options) => handle("admin lead-magnets get", options, () => requestOxygen(`/api/cli/admin/lead-magnets/${encodeURIComponent(slug)}`)));
+    leadMagnets
+        .command("upsert")
+        .description("Publish or update the lead magnet (resource) at a slug on /resources from a resource JSON file and/or flags; --cover uploads a local image. Dry run by default: prints the exact row and changed fields, uploads and writes nothing. --live applies it, and a published resource is public at once. Staff only.")
+        .option("--file <path>", "Resource JSON with slug, title, description, imageUrl, imageAlt, redirectUrl, status, sortOrder. Flags override its values.")
+        .option("--slug <slug>", "Permanent public slug (/resources/<slug>): lowercase letters, digits and hyphens. A new slug creates another resource.")
+        .option("--title <text>", "Title, up to 160 characters.")
+        .option("--description <text>", "Brief description, up to 600 characters.")
+        .option("--redirect-url <url>", "HTTPS link the visitor opens after entering an email.")
+        .option("--cover <path>", "Local PNG, JPEG or WebP cover image, up to 4 MB, uploaded to public storage on --live.")
+        .option("--image-url <url>", "HTTPS URL of an already hosted cover image, instead of --cover.")
+        .option("--image-alt <text>", "Cover alt text. Defaults to the title.")
+        .addOption(new Option("--status <status>", "published lists it on /resources; draft hides it. A new resource defaults to draft.").choices(["published", "draft"]))
+        .option("--sort-order <n>", "Catalog position, lowest first. Defaults to 0.")
+        .option("--dry-run", "Preview without uploading or writing (the default).")
+        .option("--live", "Upload the cover and write the resource.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("admin lead-magnets upsert", options, () => upsertLeadMagnet(options)));
+    leadMagnets
+        .command("unpublish")
+        .description("Unpublish a lead magnet (resource): set it to draft, which removes it and its page from /resources and keeps its email records. Dry run by default; --live applies it. Staff only.")
+        .argument("<slug>", "The resource's slug.")
+        .option("--dry-run", "Preview without writing (the default).")
+        .option("--live", "Unpublish it.")
+        .option("--json", "Print a JSON envelope.")
+        .action((slug, options) => handle("admin lead-magnets unpublish", options, () => requestOxygen(`/api/cli/admin/lead-magnets/${encodeURIComponent(slug)}`, {
+        method: "POST",
+        body: { status: "draft", mode: resolveLiveDryRunMode(options) },
+    })));
+}
+async function upsertLeadMagnet(options) {
+    const mode = resolveLiveDryRunMode(options);
+    if (options.cover !== undefined && options.imageUrl !== undefined) {
+        throw new OxygenError("conflicting_flags", "Pass either --cover or --image-url, not both.", { exitCode: 1 });
+    }
+    const fromFile = options.file === undefined ? {} : await readResourceFile(options.file);
+    if (options.slug !== undefined && fromFile.slug !== undefined && fromFile.slug !== options.slug) {
+        throw usageError(`--slug ${options.slug} does not match the file's slug ${String(fromFile.slug)}. The slug is the resource's identity: drop --slug or fix the file.`);
+    }
+    const flags = {
+        slug: options.slug, title: options.title, description: options.description, redirect_url: options.redirectUrl,
+        image_url: options.imageUrl, image_alt: options.imageAlt, status: options.status,
+        sort_order: options.sortOrder === undefined ? undefined : readSortOrder(options.sortOrder),
+    };
+    const { slug, ...fields } = { ...fromFile, ...Object.fromEntries(Object.entries(flags).filter(([, value]) => value !== undefined)) };
+    if (typeof slug !== "string" || !slug)
+        throw usageError("Name the resource with --slug, or a slug in --file.");
+    // A local cover replaces any imageUrl the file carries.
+    if (options.cover !== undefined)
+        delete fields.image_url;
+    const body = { ...fields, mode };
+    if (options.cover === undefined) {
+        return requestOxygen(`/api/cli/admin/lead-magnets/${encodeURIComponent(slug)}`, { method: "POST", body });
+    }
+    const form = new FormData();
+    form.append("payload", JSON.stringify(body));
+    form.append("image", await readCover(options.cover));
+    return requestOxygen(`/api/cli/admin/lead-magnets/${encodeURIComponent(slug)}`, { method: "POST", formData: form });
+}
+async function readResourceFile(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(resolve(path), "utf8"));
+    }
+    catch (error) {
+        throw usageError(`--file must be a readable JSON file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw usageError("--file must hold one JSON object.");
+    const unknown = Object.keys(parsed).filter((key) => !Object.hasOwn(FILE_FIELDS, key));
+    if (unknown.length > 0) {
+        throw usageError(`--file has unknown fields: ${unknown.join(", ")}. A resource file has ${Object.keys(FILE_FIELDS).join(", ")}.`);
+    }
+    return Object.fromEntries(Object.entries(parsed).map(([key, value]) => [FILE_FIELDS[key], value]));
+}
+async function readCover(path) {
+    const type = COVER_TYPES[extname(path).toLowerCase()];
+    if (!type)
+        throw usageError("--cover must be a .png, .jpg, .jpeg or .webp image.");
+    let bytes;
+    try {
+        bytes = await readFile(resolve(path));
+    }
+    catch (error) {
+        throw usageError(`--cover could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (bytes.byteLength > MAX_COVER_BYTES)
+        throw usageError("--cover must be 4 MB or smaller.");
+    return new File([bytes], basename(path), { type });
+}
+function readSortOrder(value) {
+    if (!/^-?\d+$/.test(value.trim()))
+        throw usageError("--sort-order must be a whole number.");
+    return Number(value);
+}

package/dist/command-manifest.js

@@ -78,6 +78,9 @@ const MUTATING_VERBS = new Set([
     // Thread field, while a future `field-get` would be a read.
     "field-set",
     "file", "forward", "grant", "harvest", "history", "import", "insert", "interrupt", "invite",
+    // `crm keep` clears a seeded sample record's marker for good: from then on the
+    // record counts in pipeline totals. A verb that reads like "leave as is".
+    "keep",
     "label-add", "label-remove", "launch", "log", "login", "logout", "mark-all-read", "mark-read", "materialize", "merge",
     "migrate",
     "move", "note", "off", "onboard", "order", "pause", "pin", "priority", "provision",
@@ -101,10 +104,18 @@ const MUTATING_VERBS = new Set([
 // status persists state and can pause the provider; reconnect replaces its
 // connection and can restart provider history. Other status commands are reads.
 const MUTATING_COMMANDS = new Set([
+    // These balance reads can post an eligible due grant or expire due sponsored
+    // credits. The exact exceptions disclose writes without inventing spend.
+    "billing balance",
+    "billing seats",
     // A default preview is free; approval restores provider seats and billing.
     "managed-inboxes recover",
     "mailboxes warmup status",
     "mailboxes warmup reconnect",
+    // Approval creates a provider consent link; status can attach its receipt.
+    "mailboxes warmup google",
+    // Immediately moves a provider proxy and may pause or resume the sender.
+    "senders proxy-country",
     // A noun leaf with its own action (not a group), so the default would
     // advertise a STANDING per-viewer paid-enrichment toggle as a read. `enrichment`
     // itself is not a MUTATING_VERBS entry because the other two `enrichment`
@@ -129,6 +140,10 @@ 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([
+    // 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",
+    "knowledge page pin",
     "inbox delete-message",
     "inbox forget-whatsapp-chat",
     "tables watcher preview",
@@ -163,12 +178,18 @@ const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
     // progress are covered by the existing monthly mailbox commitment.
     "mailboxes connect-oauth",
     "mailboxes sync",
+    // Separate Google consent always has a zero-credit ceiling; enrollment bills
+    // through its own warmup enable command.
+    "mailboxes warmup google",
     // Previews without --approved; with it, removes a program no creator ever
     // joined. No provider call, no credits.
     "ugc programs delete",
     // This approval only reopens exact fingerprint-bound tenant rows. It never
     // calls the provider, dispatches an action, or touches the credit ledger.
     "sequences recover-capacity",
+    // Provider reads are free; approval only records an exact match locally.
+    // Neither branch resends or writes to the provider.
+    "sequences reconcile",
     // Credential replacement is destructive but does not execute the graph,
     // call a provider, or spend Oxygen credits.
     "workflows webhooks rotate",
@@ -182,6 +203,10 @@ const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
 // one. Keep the exception exact so genuine `run` actions remain mutations.
 const READ_ONLY_COMMANDS = new Set([
     "workflows run",
+    // `history` is a mutating verb for `whatsapp history` (it backfills a chat);
+    // these two only read a row's and a cell's recorded changes.
+    "rows history",
+    "cells history",
     // Inspect existing creator receipts; never generate or import again.
     "ugc posts draft-status",
     "ugc posts history",
@@ -190,6 +215,9 @@ 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([
+    "mailboxes warmup google",
+    "deliverability placement-test run",
+    "deliverability placement-test send",
     "managed-inboxes recover",
     // /api/cli/find/run treats an omitted mode as dry_run for every Find capability.
     "find email",
@@ -222,6 +250,7 @@ const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     // No action reads progress; an action previews until --approved.
     "mailboxes sync",
     "sequences recover-capacity",
+    "sequences reconcile",
     "support admin done",
     "support admin reply",
     // A bare call reads the Plain workspace and prints the plan; --apply writes.

package/dist/crm-support-flags.d.ts

@@ -8,4 +8,5 @@ export declare function readCrmPhotoFields(options: {
 }): Record<string, unknown>;
 export declare function readCrmFileLabel(options: object): Record<string, unknown>;
 export declare function buildCrmObjectsPath(options: object): string;
+export declare function buildCrmRecordPath(object: string, rowId: string, options: object): string;
 export declare function buildCrmConnectionsPath(object: string, rowId: string, options: object): string;

package/dist/crm-support-flags.js

@@ -1,5 +1,5 @@
 import { OxygenError } from "@oxygen/shared/cli-result";
-import { CRM_CONNECTIONS_QUERY_CONTRACT, CRM_NOTE_EDIT_CONTRACT, CRM_OBJECTS_QUERY_CONTRACT, CRM_PHOTOS_CONTRACT, CRM_FILE_COMPLETE_CONTRACT } from "@oxygen/shared/contracts/crm-support";
+import { CRM_CONNECTIONS_QUERY_CONTRACT, CRM_NOTE_EDIT_CONTRACT, CRM_OBJECTS_QUERY_CONTRACT, CRM_PHOTOS_CONTRACT, CRM_FILE_COMPLETE_CONTRACT, CRM_RECORD_QUERY_CONTRACT } from "@oxygen/shared/contracts/crm-support";
 import { validateContract } from "@oxygen/shared/contracts/schema";
 import { addContractFlags, readContractFlags } from "./contract-flags.js";
 import { assertModeFlagsExclusive } from "./cli-values.js";
@@ -19,6 +19,7 @@ function replaceFlags(command, attributes, contract, overlay) {
 export function registerCrmSupportFlags(program) {
     const crm = child(program, "crm");
     replaceFlags(child(crm, "objects"), [], CRM_OBJECTS_QUERY_CONTRACT);
+    replaceFlags(child(crm, "get"), [], CRM_RECORD_QUERY_CONTRACT);
     replaceFlags(child(crm, "connections"), ["conversationLimit", "sequenceLimit"], CRM_CONNECTIONS_QUERY_CONTRACT);
     replaceFlags(child(child(crm, "notes"), "update"), ["body", "title", "pin", "unpin"], CRM_NOTE_EDIT_CONTRACT, NOTE_OVERLAY);
     replaceFlags(child(crm, "photos"), ["limit", "live"], CRM_PHOTOS_CONTRACT);
@@ -55,6 +56,9 @@ function queryPath(path, query) {
     return params.size ? `${path}?${params}` : path;
 }
 export function buildCrmObjectsPath(options) { return queryPath("/api/cli/crm/objects", checkedFlags(options, CRM_OBJECTS_QUERY_CONTRACT)); }
+export function buildCrmRecordPath(object, rowId, options) {
+    return queryPath(`/api/cli/crm/objects/${encodeURIComponent(object)}/records/${encodeURIComponent(rowId)}`, checkedFlags(options, CRM_RECORD_QUERY_CONTRACT));
+}
 export function buildCrmConnectionsPath(object, rowId, options) {
     return queryPath(`/api/cli/crm/objects/${encodeURIComponent(object)}/records/${encodeURIComponent(rowId)}/connections`, checkedFlags(options, CRM_CONNECTIONS_QUERY_CONTRACT));
 }

package/dist/customer-operation-commands.js

@@ -32,6 +32,10 @@ const GROUP_PURPOSES = {
     onboarding: "Save workspace discovery choices and continue onboarding.",
 };
 const OPERATION_FLAGS = {
+    "tables rows remove-selection": {
+        table: { help: "Table id or slug." },
+        row_ids: { help: "Comma-separated exact row IDs. Choose this or --selection-json." },
+    },
     "tables favorite": { favorite: { negateHelp: "Unstar the selected Table or folder (favorite: false)." } },
     "tables favorites": { details: { negateHelp: "Return stored star keys without names or links (details: false)." } },
 };
@@ -92,7 +96,7 @@ export function registerCustomerOperationCommands(program, handle) {
         command.action((options, selected) => handle(spec.cli.path.join(" "), { ...options, json: selected.optsWithGlobals().json === true }, async () => {
             let input;
             try {
-                input = readContractFlags(options, contract, overlay);
+                input = readContractFlags(ancestorConsumedOptions(command, selected, options), contract, overlay);
                 if (spec.multipart && options.file !== undefined) {
                     if (input[spec.multipart.contentField] !== undefined)
                         throw new OxygenError("invalid_request", "Choose --file or the base64 content flag, not both.", { exitCode: 2 });
@@ -139,6 +143,31 @@ export function registerCustomerOperationCommands(program, handle) {
         }));
     }
 }
+/**
+ * Commander lets an ancestor that declares the same flag consume it, so a value
+ * the user typed for this leaf lands on the parent and the leaf reads nothing:
+ * `sequences contacts rows --limit 1` sent no limit at all, because the native
+ * `sequences contacts` list owns `--limit` too, and the server returned its
+ * default page (OXP-1.11.67). Take such a value back only when the user typed it
+ * (value source `cli`); an ancestor's own default never becomes this leaf's input.
+ */
+function ancestorConsumedOptions(leaf, selected, options) {
+    const merged = { ...options };
+    for (const option of leaf.options) {
+        const key = option.attributeName();
+        if (merged[key] !== undefined)
+            continue;
+        for (let ancestor = selected.parent; ancestor; ancestor = ancestor.parent) {
+            const owned = ancestor.options.find((candidate) => candidate.long === option.long);
+            if (!owned)
+                continue;
+            if (ancestor.getOptionValueSource(owned.attributeName()) === "cli")
+                merged[key] = ancestor.opts()[owned.attributeName()];
+            break;
+        }
+    }
+    return merged;
+}
 function uploadContentType(filePath) {
     const types = {
         ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".svg": "image/svg+xml",

package/dist/functions-commands.js

@@ -42,7 +42,7 @@ export function registerFunctionsCommands(program, handle) {
         .requiredOption("--expected-draft-hash <hash>", "function.draft.contentHash returned by draft or describe; rejects concurrent edits.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions publish", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "publish", function: ref, expected_draft_hash: options.expectedDraftHash } })));
-    functions.command("runs <function>").description("Inspect a Function's latest 100 invocations, the table that called each one, and their captured versions. For a call that did not complete, creditsUsed can show the estimate; `table-runs provider-summary <run_id>` reports the credits actually captured.")
+    functions.command("runs <function>").description("Inspect a Function's latest 100 invocations, the table that called each one, and their captured versions and bindings: each run's overwrite policy, output mapping and run condition as they were when it ran. Per row, the calling table's Function cell records overwrite_policy, written_columns, overwritten_columns (filled cells it replaced) and kept_columns (filled cells empty_only left). For a call that did not complete, creditsUsed can show the estimate; `table-runs provider-summary <run_id>` reports the credits actually captured.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions runs", options, () => requestOxygen(`/api/cli/functions/runs?${new URLSearchParams({ function: ref })}`)));
     functions.command("rename <function> <name>").description("Rename a Function while preserving its identity, callers and published execution.")

package/dist/help.js

@@ -141,6 +141,7 @@ export function applyOxygenHelp(program, binaryName) {
         "",
         "Agent quickstart:",
         `  1. ${binaryName} login                      connect this terminal (or set OXYGEN_API_KEY)`,
+        `     ${binaryName} whoami --summary-json     confirm the active workspace and identity (0 credits)`,
         // `login` auto-installs the skills, but an agent authenticating with
         // OXYGEN_API_KEY never runs it — without this step nothing on any
         // first-touch surface names the skill that teaches the GTM loops.
@@ -163,8 +164,9 @@ export function applyOxygenHelp(program, binaryName) {
         "Conventions:",
         "  --json prints a stable envelope {ok, data|error, meta}; errors always print it.",
         "  Free Sequence launch previews omit --approved and --max-credits.",
-        "  Credit-spending commands require --approved --max-credits <n>; zero-credit",
-        "  external writes require --approved plus the command's preview-bound plan token.",
+        "  Credit-spending commands require --approved --max-credits <n>.",
+        "  Zero-credit external writes require --approved; supply a preview-bound plan",
+        "  token when the command requires one (see its preview and --help).",
         "  State-changing responses include a web_url deep-link to inspect the result.",
     ].join("\n"));
     program.addHelpText("afterAll", `\nExit codes: ${exitCodeLine}`);
@@ -360,6 +362,12 @@ export function unknownCommandHint(program, argv) {
     const { command, path, next } = resolveCommandPath(program, argv);
     if (next === undefined || command.commands.length === 0)
         return null;
+    const identityExists = program.commands.some((candidate) => candidate.name() === "whoami");
+    const currentWorkspace = (command.parent === program && command.name() === "workspace" && next === "current")
+        || (command === program && next === "workspaces" && argv.some((token, index) => token === "workspaces" && argv[index + 1] === "current"));
+    if (identityExists && currentWorkspace) {
+        return `Hint: Active workspace and identity: \`${program.name()} whoami --summary-json\` (read-only, 0 credits).`;
+    }
     return buildUnknownCommandHint(command, path, next);
 }
 /**

package/dist/http-client.d.ts

@@ -6,6 +6,10 @@ type RequestOptions = {
     /** Stream a native authenticated download to an exclusively created file. */
     binaryOutputPath?: string;
     method?: "GET" | "POST" | "PATCH" | "DELETE";
+    /** A native read that uses POST for its selection payload. Never set on a write. */
+    readOnly?: boolean;
+    /** Only for audited preview routes that request no product mutation. */
+    previewOnly?: boolean;
     body?: Record<string, unknown>;
     formData?: FormData;
     credentials?: StoredCredentials;

package/dist/http-client.js

@@ -11,6 +11,7 @@ const CLI_COMPATIBILITY_CHECK_TIMEOUT_MS = 5_000;
 // 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 FAILED_READ_NEXT_STEP = "This read failed. Check your connection; it is safe to retry the same read.";
 const cliCompatibilityCheckKeys = new Set();
 export async function requestOxygen(// skipcq: JS-R1005
 path, options = {}) {
@@ -75,7 +76,13 @@ path, options = {}) {
     // echoed in error details so a re-run (OXYGEN_IDEMPOTENCY_KEY=<key>) can
     // retry without duplicating the write once the route supports replay.
     const method = options.method ?? "GET";
-    const idempotencyKey = method === "GET"
+    const readOnly = method === "GET" || options.readOnly === true;
+    const recovery = {
+        next_step: options.previewOnly
+            ? "This was a preview; no changes were requested. Retry the preview when Oxygen is reachable."
+            : readOnly ? FAILED_READ_NEXT_STEP : UNCONFIRMED_WRITE_NEXT_STEP,
+    };
+    const idempotencyKey = readOnly
         ? undefined
         : options.idempotencyKey ?? process.env.OXYGEN_IDEMPOTENCY_KEY ?? randomUUID();
     if (idempotencyKey) {
@@ -108,7 +115,6 @@ 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: {
@@ -117,9 +123,9 @@ path, options = {}) {
                     timeout_ms: timeoutMs,
                     trace_id: traceId,
                     ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
-                    ...unconfirmedWrite,
+                    ...recovery,
                 },
-                exitCode: 1,
+                exitCode: 8,
             });
         }
         throw new OxygenError("network_error", "Unable to reach Oxygen API.", {
@@ -127,9 +133,9 @@ path, options = {}) {
                 api_url: apiUrl,
                 reason: error instanceof Error ? error.message : "unknown",
                 ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
-                ...unconfirmedWrite,
+                ...recovery,
             },
-            exitCode: 1,
+            exitCode: 5,
         });
     }
     finally {
@@ -141,12 +147,17 @@ path, options = {}) {
         // calling the gateway's page an invalid envelope.
         if (!(error instanceof OxygenError) || ![502, 503, 504].includes(response.status))
             throw error;
-        throw new OxygenError("invalid_response", `Oxygen API did not answer in time (HTTP ${response.status}); the outcome is unknown.`, {
+        const message = options.previewOnly
+            ? `Oxygen API did not answer in time (HTTP ${response.status}); the preview was not returned.`
+            : readOnly
+                ? `Oxygen API did not answer in time (HTTP ${response.status}); the read was not returned.`
+                : `Oxygen API did not answer in time (HTTP ${response.status}); the outcome is unknown.`;
+        throw new OxygenError("invalid_response", message, {
             details: {
                 status: response.status,
                 trace_id: response.headers.get("x-oxygen-trace-id") ?? traceId,
                 ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
-                ...(method === "GET" ? {} : { next_step: UNCONFIRMED_WRITE_NEXT_STEP }),
+                ...recovery,
             },
             exitCode: 1,
         });
@@ -173,11 +184,11 @@ path, options = {}) {
         if (error.code === "cli_update_required")
             throw await recoverFromCliFloorRejection(error, endpoint);
         // Any other answer to a write may have written something; never re-run the command after it.
-        if (method !== "GET")
+        if (!readOnly)
             recordMutatingRequestAnswered();
         throw error;
     }
-    if (method !== "GET")
+    if (!readOnly)
         recordMutatingRequestAnswered();
     return envelope.data;
 }