@corvio/admin-cli 0.1.0-beta.4 → 0.1.0-beta.6

package/README.md

@@ -10,3 +10,5 @@ corvio-admin catalog --json
 ```
 
 For Agents and CI, inject `CORVIO_ADMIN_API_KEY='cva_...'`; it takes precedence over the stored device-link credential. Every data query requires a purpose and returns an auditable receipt. This package contains no ordinary Workspace commands. See [the administrator CLI guide](https://corvio.ai/developers/admin-cli).
+
+Unknown/duplicate options, malformed bounds, and invalid JSON fail locally. API calls use the same bounded transport/runtime safety policy as the Workspace CLI. `corvio-admin skill download` reads the protected manifest first and verifies the archive SHA-256 before writing the zip.

package/dist/cli.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 
+import { createHash } from "node:crypto";
+
 import {
   ApiClient,
   CliError,
   EXIT,
+  assertKnownOptions,
+  assertPositionalCount,
   clearAdminCredential,
   listOption,
   normalizeApiBase,
@@ -20,9 +24,29 @@ import {
   writeResult,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.4";
+const VERSION = "0.1.0-beta.6";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const USER_AGENT = `corvio-admin-cli/${VERSION}`;
+const GLOBAL_OPTIONS = Object.freeze(["api-base", "json", "no-input", "help", "version"]);
+const COMMAND_OPTIONS = Object.freeze({
+  "auth:login": ["force", "scopes"],
+  "auth:status": [],
+  "auth:logout": [],
+  "capabilities:": [],
+  "update:check": [],
+  "skill:download": ["output"],
+  "catalog:": [],
+  "query:": ["file", "purpose", "dataset", "fields", "group-by", "metrics", "filters", "order-by", "limit", "cursor"],
+  "data:query": ["file", "purpose", "dataset", "fields", "group-by", "metrics", "filters", "order-by", "limit", "cursor"],
+  "workspaces:list": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "users:list": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "worker-jobs:list": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "runs:list": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "runs:content": ["id", "purpose"],
+  "usage:events": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "usage:summary": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "receipts:get": ["id"],
+});
 
 const HELP = `Corvio Platform Administrator CLI ${VERSION}
 
@@ -47,6 +71,47 @@ Authentication:
 This package contains no Workspace ask, search, docs, files, sync, or share commands.
 `;
 
+function resourcePath(value) {
+  return encodeURIComponent(String(value));
+}
+
+function validateInvocation(options, positionals) {
+  const [command, rawAction] = positionals;
+  if (!command || command === "help" || command === "version" || options.help || options.version) return;
+  const defaultActions = {
+    update: "check",
+    workspaces: "list",
+    users: "list",
+    "worker-jobs": "list",
+  };
+  const action = ["capabilities", "catalog", "query"].includes(command)
+    ? ""
+    : rawAction || defaultActions[command] || "";
+  const schema = COMMAND_OPTIONS[`${command}:${action}`];
+  if (!schema) {
+    throw new CliError(`Unknown administrator command: ${positionals.join(" ")}`, {
+      code: "unknown_command",
+    });
+  }
+  assertKnownOptions(options, [...GLOBAL_OPTIONS, ...schema]);
+  const maximum = new Set(["runs:content", "receipts:get"]).has(`${command}:${action}`)
+    ? 3
+    : action
+      ? 2
+      : 1;
+  assertPositionalCount(positionals, maximum);
+}
+
+function parseJsonValue(value, optionName) {
+  try {
+    return JSON.parse(String(value));
+  } catch {
+    throw new CliError(`Option --${optionName} must contain valid JSON.`, {
+      code: "invalid_json_option",
+    });
+  }
+}
+
 function baseUrl(options, credential = null) {
   return normalizeApiBase(
     options["api-base"]
@@ -76,7 +141,7 @@ function listQuery(options) {
     purpose: option(options, "purpose", { required: true }),
     workspace_id: options["workspace-id"],
     status: options.status,
-    limit: numberOption(options, "limit", 100),
+    limit: numberOption(options, "limit", 100, { maximum: 200 }),
     cursor: options.cursor,
   };
 }
@@ -216,7 +281,15 @@ async function catalog(options) {
 async function query(options) {
   let body;
   if (options.file) {
-    body = JSON.parse(await readTextFile(options.file));
+    try {
+      body = JSON.parse(await readTextFile(options.file));
+    } catch (error) {
+      if (error?.code === "ENOENT") throw error;
+      throw new CliError("--file must contain a valid JSON request object.", { code: "invalid_json_file" });
+    }
+    if (!body || Array.isArray(body) || typeof body !== "object") {
+      throw new CliError("--file must contain a JSON object.", { code: "invalid_json_file" });
+    }
     if (options.purpose) body.purpose = options.purpose;
   } else {
     body = {
@@ -224,10 +297,10 @@ async function query(options) {
       purpose: option(options, "purpose", { required: true }),
       fields: listOption(options, "fields"),
       group_by: listOption(options, "group-by"),
-      metrics: options.metrics ? JSON.parse(options.metrics) : [],
-      filters: options.filters ? JSON.parse(options.filters) : [],
-      order_by: options["order-by"] ? JSON.parse(options["order-by"]) : [],
-      limit: numberOption(options, "limit", 100),
+      metrics: options.metrics ? parseJsonValue(options.metrics, "metrics") : [],
+      filters: options.filters ? parseJsonValue(options.filters, "filters") : [],
+      order_by: options["order-by"] ? parseJsonValue(options["order-by"], "order-by") : [],
+      limit: numberOption(options, "limit", 100, { maximum: 200 }),
       cursor: options.cursor || null,
     };
   }
@@ -243,7 +316,15 @@ async function listResource(options, resource) {
 async function downloadSkill(options) {
   const { api } = await client(options);
   const output = String(options.output || "corvio-admin-data.zip");
+  const manifest = await api.request("/admin/skill/manifest.json");
   const bytes = await api.requestBytes("/admin/skill/corvio-admin-data.zip");
+  const actualHash = createHash("sha256").update(bytes).digest("hex");
+  if (!manifest.archive_sha256 || actualHash !== manifest.archive_sha256) {
+    throw new CliError("Administrator Skill archive did not match its manifest SHA-256.", {
+      code: "admin_skill_integrity_mismatch",
+      exitCode: EXIT.REMOTE,
+    });
+  }
   const path = await writeBinaryFile(output, bytes);
   writeResult({
     downloaded: true,
@@ -256,6 +337,7 @@ async function main({ options, positionals }) {
   const [command, action, id] = positionals;
   if (options.version || command === "version") return writeResult(VERSION, { json: options.json });
   if (options.help || !command || command === "help") return writeResult(HELP.trimEnd(), { json: false });
+  validateInvocation(options, positionals);
   if (command === "auth") {
     if (action === "login") return authLogin(options);
     if (action === "status") return authStatus(options);
@@ -276,7 +358,7 @@ async function main({ options, positionals }) {
     const runId = id || option(options, "id", { required: true });
     const purpose = option(options, "purpose", { required: true });
     const { api } = await client(options);
-    return writeResult(await api.request(`/admin/runs/${runId}/content`, { query: { purpose } }), { json: options.json });
+    return writeResult(await api.request(`/admin/runs/${resourcePath(runId)}/content`, { query: { purpose } }), { json: options.json });
   }
   if (command === "usage" && action === "events") return listResource(options, "usage/events");
   if (command === "usage" && action === "summary") {
@@ -286,7 +368,7 @@ async function main({ options, positionals }) {
   if (command === "receipts" && action === "get") {
     const receiptId = id || option(options, "id", { required: true });
     const { api } = await client(options);
-    return writeResult(await api.request(`/admin/data/query-receipts/${receiptId}`), { json: options.json });
+    return writeResult(await api.request(`/admin/data/query-receipts/${resourcePath(receiptId)}`), { json: options.json });
   }
   throw new CliError(`Unknown administrator command: ${positionals.join(" ")}`);
 }

package/dist/core.js

@@ -32,6 +32,59 @@ function exitCodeForStatus(status) {
   return EXIT.REMOTE;
 }
 
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const MAX_REQUEST_TIMEOUT_MS = 10 * 60_000;
+const RETRYABLE_HTTP_STATUSES = new Set([408, 429, 502, 503, 504]);
+
+function normalizeRequestTimeout(value, fallback = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const raw = value === undefined || value === null || value === "" ? fallback : Number(value);
+  if (!Number.isSafeInteger(raw) || raw < 1 || raw > MAX_REQUEST_TIMEOUT_MS) {
+    throw new CliError(
+      `Request timeout must be an integer between 1 and ${MAX_REQUEST_TIMEOUT_MS} milliseconds.`,
+      { code: "invalid_request_timeout" },
+    );
+  }
+  return raw;
+}
+
+function networkFailureDetails({
+  cause,
+  url,
+  method,
+  requestHeaders = {},
+  body = undefined,
+  retrySafe = false,
+}) {
+  const nested = cause && typeof cause === "object" ? cause.cause : null;
+  const causeCode = String(nested?.code || cause?.code || "").trim() || null;
+  const syscall = String(nested?.syscall || cause?.syscall || "").trim() || null;
+  const normalizedMethod = String(method || "GET").toUpperCase();
+  const operationKey = String(requestHeaders["idempotency-key"] || requestHeaders["Idempotency-Key"] || "").trim();
+  const revision = body?.expected_content_revision;
+  const revisionGuarded = normalizedMethod === "PUT" && Number.isSafeInteger(revision) && revision >= 0;
+  const safeToRetry = retrySafe || ["GET", "HEAD"].includes(normalizedMethod) || Boolean(operationKey) || revisionGuarded;
+  const timedOut = cause?.name === "TimeoutError" || cause?.name === "AbortError";
+  return {
+    method: normalizedMethod,
+    origin: new URL(String(url)).origin,
+    response_received: false,
+    timed_out: timedOut,
+    safe_to_retry: safeToRetry,
+    retry_safety: operationKey
+      ? "idempotency_key"
+      : revisionGuarded
+        ? "revision_guard"
+        : retrySafe
+          ? "operation_contract"
+          : safeToRetry
+            ? "read_only"
+            : "unknown_commit_state",
+    ...(operationKey ? { idempotency_key: operationKey } : {}),
+    ...(causeCode ? { cause_code: causeCode } : {}),
+    ...(syscall ? { syscall } : {}),
+  };
+}
+
 export function parseArgv(argv) {
   const options = Object.create(null);
   const positionals = [];
@@ -42,19 +95,34 @@ export function parseArgv(argv) {
     "allow-actions",
     "private-link",
     "force",
+    "once",
+    "include-revoked",
+    "start-new-chain",
     "help",
     "version",
   ]);
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
+    if (value === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
     if (!value.startsWith("--")) {
       positionals.push(value);
       continue;
     }
     const separator = value.indexOf("=");
     const name = value.slice(2, separator === -1 ? undefined : separator);
+    if (!name) throw new CliError("Option name must not be empty.", { code: "invalid_option" });
+    if (Object.hasOwn(options, name)) {
+      throw new CliError(`Option --${name} was provided more than once.`, { code: "duplicate_option" });
+    }
     if (booleanOptions.has(name)) {
-      options[name] = separator === -1 ? true : value.slice(separator + 1) !== "false";
+      const booleanValue = separator === -1 ? "true" : value.slice(separator + 1);
+      if (booleanValue !== "true" && booleanValue !== "false") {
+        throw new CliError(`Option --${name} must be true or false.`, { code: "invalid_boolean_option" });
+      }
+      options[name] = booleanValue === "true";
       continue;
     }
     if (separator !== -1) {
@@ -71,6 +139,21 @@ export function parseArgv(argv) {
   return { options, positionals };
 }
 
+export function assertKnownOptions(options, allowed) {
+  const allowedSet = new Set(allowed);
+  for (const name of Object.keys(options)) {
+    if (!allowedSet.has(name)) {
+      throw new CliError(`Unknown option --${name}.`, { code: "unknown_option" });
+    }
+  }
+}
+
+export function assertPositionalCount(positionals, maximum) {
+  if (positionals.length > maximum) {
+    throw new CliError(`Unexpected argument: ${positionals[maximum]}`, { code: "unexpected_argument" });
+  }
+}
+
 export function option(options, name, { required = false, fallback = undefined } = {}) {
   const value = options[name] ?? fallback;
   if (required && (value === undefined || String(value).trim() === "")) {
@@ -85,28 +168,43 @@ export function listOption(options, name, fallback = []) {
   return String(value).split(",").map((item) => item.trim()).filter(Boolean);
 }
 
-export function numberOption(options, name, fallback) {
+export function numberOption(options, name, fallback, { minimum = 1, maximum = Number.MAX_SAFE_INTEGER } = {}) {
   const value = options[name];
   if (value === undefined) return fallback;
-  const parsed = Number.parseInt(String(value), 10);
-  if (!Number.isFinite(parsed) || parsed < 1) {
-    throw new CliError(`Option --${name} must be a positive integer.`, { code: "invalid_number_option" });
+  const normalized = String(value).trim();
+  const parsed = /^\d+$/.test(normalized) ? Number(normalized) : Number.NaN;
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+    throw new CliError(
+      `Option --${name} must be an integer between ${minimum} and ${maximum}.`,
+      { code: "invalid_number_option" },
+    );
   }
   return parsed;
 }
 
 export function normalizeApiBase(value, fallback) {
   const raw = String(value || fallback).trim().replace(/\/+$/, "");
-  if (!/^https:\/\//i.test(raw) && !/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?/i.test(raw)) {
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new CliError("Corvio API base must be a valid URL.", { code: "invalid_api_base" });
+  }
+  const localhost = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
+  if (parsed.username || parsed.password || (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && localhost))) {
     throw new CliError("Corvio API base must use HTTPS (localhost is allowed for development).", {
       code: "insecure_api_base",
     });
   }
-  return raw.endsWith("/v1") ? raw : `${raw}/v1`;
+  if (parsed.search || parsed.hash) {
+    throw new CliError("Corvio API base must not include a query string or fragment.", { code: "invalid_api_base" });
+  }
+  const normalized = parsed.toString().replace(/\/+$/, "");
+  return normalized.endsWith("/v1") ? normalized : `${normalized}/v1`;
 }
 
 function parseSemver(value) {
-  const match = String(value || "").trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+  const match = String(value || "").trim().match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/);
   if (!match) return null;
   return {
     core: match.slice(1, 4).map((item) => Number.parseInt(item, 10)),
@@ -187,15 +285,31 @@ export async function resolveNpmUpdateStatus({
 }
 
 export class ApiClient {
-  constructor({ baseUrl, credential = null, workspaceId = null, userAgent, fetchImpl = globalThis.fetch }) {
+  constructor({
+    baseUrl,
+    credential = null,
+    workspaceId = null,
+    userAgent,
+    fetchImpl = globalThis.fetch,
+    timeoutMs = process.env.CORVIO_REQUEST_TIMEOUT_MS,
+  }) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     this.credential = credential;
     this.workspaceId = String(workspaceId || "").trim() || null;
     this.userAgent = userAgent;
     this.fetchImpl = fetchImpl;
+    this.timeoutMs = normalizeRequestTimeout(timeoutMs);
   }
 
-  async request(path, { method = "GET", body, query, headers = {}, auth = true } = {}) {
+  async request(path, {
+    method = "GET",
+    body,
+    query,
+    headers = {},
+    auth = true,
+    retrySafe = false,
+    timeoutMs = this.timeoutMs,
+  } = {}) {
     const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
     for (const [key, value] of Object.entries(query || {})) {
       if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
@@ -216,18 +330,56 @@ export class ApiClient {
         requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
       }
     }
+    const normalizedTimeout = normalizeRequestTimeout(timeoutMs, this.timeoutMs);
     let response;
-    try {
-      response = await this.fetchImpl(url, {
-        method,
-        headers: requestHeaders,
-        body: body === undefined ? undefined : JSON.stringify(body),
-      });
-    } catch (cause) {
-      throw new CliError(`Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`, {
-        code: "network_error",
-        exitCode: EXIT.REMOTE,
-      });
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        response = await this.fetchImpl(url, {
+          method,
+          headers: requestHeaders,
+          body: body === undefined ? undefined : JSON.stringify(body),
+          signal: AbortSignal.timeout(normalizedTimeout),
+        });
+        const safety = networkFailureDetails({
+          cause: null,
+          url,
+          method,
+          requestHeaders,
+          body,
+          retrySafe,
+        });
+        if (attempt === 1 && safety.safe_to_retry && RETRYABLE_HTTP_STATUSES.has(response.status)) {
+          await response.body?.cancel().catch(() => {});
+          const retryAfterValue = response.headers.get("retry-after");
+          const retryAfterSeconds = retryAfterValue === null ? Number.NaN : Number(retryAfterValue);
+          const delayMs = Number.isFinite(retryAfterSeconds)
+            ? Math.min(2_000, Math.max(0, retryAfterSeconds * 1000))
+            : 150;
+          await sleep(delayMs);
+          continue;
+        }
+        break;
+      } catch (cause) {
+        const details = networkFailureDetails({ cause, url, method, requestHeaders, body, retrySafe });
+        if (attempt === 1 && details.safe_to_retry) {
+          await sleep(150);
+          continue;
+        }
+        throw new CliError(
+          details.timed_out
+            ? `Corvio did not respond within ${normalizedTimeout} ms.`
+            : `Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`,
+          {
+          code: details.timed_out ? "request_timeout" : "network_error",
+          exitCode: EXIT.REMOTE,
+          details: {
+            ...details,
+            attempts: attempt,
+            automatic_retry_attempted: attempt > 1,
+          },
+          },
+        );
+      }
     }
     const text = await response.text();
     let payload = null;
@@ -244,13 +396,18 @@ export class ApiClient {
         code: String(envelope.code || `http_${response.status}`),
         status: response.status,
         exitCode: exitCodeForStatus(response.status),
-        details: envelope.details || null,
+        details: {
+          ...(envelope.details || {}),
+          ...(envelope.request_id || response.headers.get("x-request-id")
+            ? { request_id: envelope.request_id || response.headers.get("x-request-id") }
+            : {}),
+        },
       });
     }
     return payload;
   }
 
-  async requestBytes(path, { query, headers = {}, auth = true } = {}) {
+  async requestBytes(path, { query, headers = {}, auth = true, timeoutMs = this.timeoutMs } = {}) {
     const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
     for (const [key, value] of Object.entries(query || {})) {
       if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
@@ -270,14 +427,38 @@ export class ApiClient {
         requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
       }
     }
+    const normalizedTimeout = normalizeRequestTimeout(timeoutMs, this.timeoutMs);
     let response;
-    try {
-      response = await this.fetchImpl(url, { method: "GET", headers: requestHeaders });
-    } catch (cause) {
-      throw new CliError(`Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`, {
-        code: "network_error",
-        exitCode: EXIT.REMOTE,
-      });
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        response = await this.fetchImpl(url, {
+          method: "GET",
+          headers: requestHeaders,
+          signal: AbortSignal.timeout(normalizedTimeout),
+        });
+        if (attempt === 1 && RETRYABLE_HTTP_STATUSES.has(response.status)) {
+          await response.body?.cancel().catch(() => {});
+          await sleep(150);
+          continue;
+        }
+        break;
+      } catch (cause) {
+        const details = networkFailureDetails({ cause, url, method: "GET", requestHeaders });
+        if (attempt === 1) {
+          await sleep(150);
+          continue;
+        }
+        throw new CliError(
+          details.timed_out
+            ? `Corvio did not respond within ${normalizedTimeout} ms.`
+            : `Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`,
+          {
+            code: details.timed_out ? "request_timeout" : "network_error",
+            exitCode: EXIT.REMOTE,
+            details: { ...details, attempts: attempt, automatic_retry_attempted: true },
+          },
+        );
+      }
     }
     const bytes = new Uint8Array(await response.arrayBuffer());
     if (!response.ok) {
@@ -293,25 +474,57 @@ export class ApiClient {
         code: String(envelope.code || `http_${response.status}`),
         status: response.status,
         exitCode: exitCodeForStatus(response.status),
-        details: envelope.details || null,
+        details: {
+          ...(envelope.details || {}),
+          ...(envelope.request_id || response.headers.get("x-request-id")
+            ? { request_id: envelope.request_id || response.headers.get("x-request-id") }
+            : {}),
+        },
       });
     }
     return bytes;
   }
 
-  async putUrl(url, content, { headers = {} } = {}) {
+  async putUrl(url, content, { headers = {}, timeoutMs = this.timeoutMs } = {}) {
+    const normalizedTimeout = normalizeRequestTimeout(timeoutMs, this.timeoutMs);
     let response;
-    try {
-      response = await this.fetchImpl(String(url), {
-        method: "PUT",
-        headers,
-        body: content,
-      });
-    } catch (cause) {
-      throw new CliError(`Unable to upload the file: ${cause instanceof Error ? cause.message : String(cause)}`, {
-        code: "upload_network_error",
-        exitCode: EXIT.REMOTE,
-      });
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        response = await this.fetchImpl(String(url), {
+          method: "PUT",
+          headers,
+          body: content,
+          signal: AbortSignal.timeout(normalizedTimeout),
+        });
+        if (attempt === 1 && RETRYABLE_HTTP_STATUSES.has(response.status)) {
+          await response.body?.cancel().catch(() => {});
+          await sleep(150);
+          continue;
+        }
+        break;
+      } catch (cause) {
+        const details = networkFailureDetails({
+          cause,
+          url,
+          method: "PUT",
+          requestHeaders: headers,
+          retrySafe: true,
+        });
+        if (attempt === 1) {
+          await sleep(150);
+          continue;
+        }
+        throw new CliError(
+          details.timed_out
+            ? `The file upload did not respond within ${normalizedTimeout} ms.`
+            : `Unable to upload the file: ${cause instanceof Error ? cause.message : String(cause)}`,
+          {
+            code: details.timed_out ? "upload_timeout" : "upload_network_error",
+            exitCode: EXIT.REMOTE,
+            details: { ...details, attempts: attempt, automatic_retry_attempted: true },
+          },
+        );
+      }
     }
     if (!response.ok) {
       const message = (await response.text()).slice(0, 500);
@@ -375,6 +588,23 @@ export async function readWorkspaceCredential(env = process.env) {
   return { key, source: "device_link", profile: profileName, metadata };
 }
 
+export function readAgentCredential(env = process.env) {
+  const key = String(env.CORVIO_AGENT_API_KEY || "").trim();
+  if (!key) {
+    throw new CliError(
+      "No Agent credential found. Set CORVIO_AGENT_API_KEY to the cvg_ secret returned when the Agent was created.",
+      { code: "agent_auth_required", exitCode: EXIT.AUTH },
+    );
+  }
+  if (!key.startsWith("cvg_")) {
+    throw new CliError("CORVIO_AGENT_API_KEY must be an Agent cvg_ key.", {
+      code: "invalid_agent_key",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  return { key, source: "environment", profile: null, metadata: null };
+}
+
 export async function storeWorkspaceCredential(payload, env = process.env) {
   const path = workspaceCredentialPath(env);
   const root = dirname(path);
@@ -534,7 +764,21 @@ export function writeError(error, { json = false, stderr = process.stderr } = {}
       ...(error instanceof CliError && error.details ? { details: error.details } : {}),
     },
   };
-  stderr.write(json ? `${JSON.stringify(safe)}\n` : `Error: ${safe.error.message}\n`);
+  if (json) {
+    stderr.write(`${JSON.stringify(safe)}\n`);
+    return;
+  }
+  stderr.write(`Error: ${safe.error.message}\n`);
+  if (safe.error.details?.request_id) stderr.write(`Request ID: ${safe.error.details.request_id}\n`);
+  if (safe.error.details?.safe_to_retry && safe.error.details?.idempotency_key) {
+    stderr.write(
+      `Safe retry: rerun the command with --idempotency-key ${safe.error.details.idempotency_key}\n`,
+    );
+  } else if (safe.error.details?.retry_safety === "revision_guard") {
+    stderr.write("Safe retry: rerun with the same --expected-revision; Corvio will reject an already-committed replacement.\n");
+  } else if (safe.error.details?.retry_safety === "unknown_commit_state") {
+    stderr.write("Retry state is unknown; read the remote object before repeating this mutation.\n");
+  }
 }
 
 export async function runMain(main, argv = process.argv.slice(2)) {
@@ -551,8 +795,8 @@ export async function runMain(main, argv = process.argv.slice(2)) {
 
 export async function openBrowser(url) {
   const target = String(url);
-  const command = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
-  const args = platform() === "win32" ? ["/c", "start", "", target] : [target];
+  const command = platform() === "darwin" ? "open" : platform() === "win32" ? "rundll32.exe" : "xdg-open";
+  const args = platform() === "win32" ? ["url.dll,FileProtocolHandler", target] : [target];
   return new Promise((resolvePromise) => {
     let settled = false;
     const finish = (opened) => {
@@ -584,14 +828,28 @@ export async function readTextFile(path) {
 export async function writeTextFile(path, content) {
   const target = resolve(String(path));
   await mkdir(dirname(target), { recursive: true });
-  await writeFile(target, content, "utf8");
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { encoding: "utf8", flag: "wx" });
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
   return target;
 }
 
 export async function writeBinaryFile(path, content) {
   const target = resolve(String(path));
   await mkdir(dirname(target), { recursive: true });
-  await writeFile(target, content);
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { flag: "wx" });
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
   return target;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corvio/admin-cli",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "description": "Official read-only Corvio platform administrator CLI.",
   "type": "module",
   "bin": {