@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/remote-workspace.ts

@@ -22,7 +22,8 @@ import {
 export const REMOTE_WORKSPACE_USAGE = `Usage:
   ocx remote-workspace pair <hub-url> --pairing-code-stdin --root <absolute-path> [--root <absolute-path> ...] [--toolchain-root <absolute-directory> ...] [--executor-helper <absolute-file>] [--name <device-name>] [--json]
   ocx remote-workspace agent
-  ocx remote-workspace status [--json]`;
+  ocx remote-workspace status [--json]
+  ocx remote-workspace hub [status|runtimes|sessions] [--json]`;
 
 export interface RemoteWorkspaceCliDeps extends RuntimeApiDeps {
   store?: RemoteWorkspaceDeviceStateStore;
@@ -76,6 +77,10 @@ function publicStatus(state: RemoteWorkspaceDeviceState | null): Record<string,
 export async function runRemoteWorkspaceCommand(rawArgs: string[], deps: RemoteWorkspaceCliDeps = {}): Promise<number> {
   const args = [...rawArgs];
   const command = args.shift();
+  if (command === "hub") {
+    const { handleRemoteWorkspaceHubCommand } = await import("./remote-workspace-hub");
+    return handleRemoteWorkspaceHubCommand(args, deps);
+  }
   const store = deps.store ?? new RemoteWorkspaceDeviceFileStore();
   if (command === "status") {
     const wantsJson = takeJsonFlag(args);

package/src/cli/restart-failure.ts

@@ -0,0 +1,27 @@
+import type { ProxyRestartResult } from "./tray-proxy";
+
+export const INCOMPLETE_INSTALL_RECOVERY = "If the installer already exited or failed, run `ocx status`, stop any running proxy through its owner (`ocx stop`, or its service or desktop app), then reinstall with the same package manager and start it again (see https://opencodex.me/troubleshooting/update-failed/).";
+
+export function reportRestartFailure(result: Extract<ProxyRestartResult, { ok: false }>): void {
+  if (result.phase === "identity") {
+    console.error("Refusing to restart because the running proxy identity could not be attested. Run `ocx status` to inspect the intended proxy.");
+  } else if (result.phase === "request") {
+    const code = result.error instanceof Error ? result.error.message : "";
+    if (code === "restart_capability_unsupported") {
+      console.error("The running proxy predates process-bound restart support; no unsafe fallback was attempted.");
+      console.error("   After confirming this home owns the proxy, run `ocx stop` and then `ocx start` once.");
+    } else if (code === "restart_version_skew") {
+      console.error("This CLI is older than the running proxy (or versions cannot be compared). Use the newer installation's ocx to restart; check `which -a ocx` and run `ocx status`. No changes were made.");
+    } else if (code === "update_restart_home_unverified") {
+      console.error("The proxy home or lifecycle ownership could not be verified. Run `ocx status`; if a service owns the proxy, use its installation's `ocx service restart`, otherwise use the owning app or supervisor. No changes were made.");
+    } else if (code === "restart_package_tree_unsettled") {
+      console.error(`The proxy's package files are unsettled. Wait for the install to finish, then run \`ocx restart\`. ${INCOMPLETE_INSTALL_RECOVERY}`);
+    } else {
+      console.error("Proxy restart request could not be confirmed; no fallback stop/start was attempted. Run `ocx status` to inspect ownership and runtime state.");
+    }
+  } else if (result.phase === "replacement") {
+    console.error("Proxy restart was accepted, but no identity-verified replacement became healthy in time. Run `ocx status` to inspect the replacement.");
+  } else {
+    console.error("Proxy was not running and the fallback start did not become healthy. Run `ocx status` to inspect startup state.");
+  }
+}

package/src/cli/root.ts

@@ -8,11 +8,14 @@
  * the exit paths and the shim preflight, then returns the dispatchable head
  * for the command switch in src/cli/index.ts.
  */
-import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./help";
+import { printFullUsage, printSubcommandUsage, printUsage, printVersion } from "./help";
 import { parseReadyArgs, type ReadyArgs } from "./ready";
 import { parseResolveArgs, type ResolveArgs } from "./resolve";
 import { parseStopApproval } from "./stop-approval";
 import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
+import { findCommand } from "./registry";
+import { printUnknownCommand } from "./help-recovery";
+import { noteCredentialArgv, redactSecretArgs } from "./secret-args";
 
 export interface CliHead {
   kind: "version" | "help" | "ready" | "resolve" | "command";
@@ -20,6 +23,10 @@ export interface CliHead {
   args: string[];
   /** For kind "help": the subcommand whose usage should print, if any. */
   helpTarget?: string;
+  /** Explicit multi-token help topic; never passed to command execution. */
+  helpPath?: string[];
+  /** Complete static reference requested from root help. */
+  helpAll?: boolean;
   /** Present only for `ready`; undefined when the ready args failed to parse. */
   readyArgs?: ReadyArgs;
   /** Present only for `resolve`; undefined when the resolve args failed to parse. */
@@ -32,19 +39,26 @@ export function parseCliHead(argv: string[]): CliHead {
   if (command === "--version" || command === "-v" || command === "version") {
     return { kind: "version", command, args };
   }
-  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-    // `ocx help <sub>` carries the subcommand; bare/flag help prints the full usage.
+  const boundary = argv.indexOf("--");
+  const prefix = boundary < 0 ? argv : argv.slice(0, boundary);
+  const rootHelp = command === undefined || command === "help" || command === "--help" || command === "-h";
+  const commandHelp = prefix[1] === "help";
+  if (rootHelp || commandHelp || prefix.slice(1).some(value => value === "--help" || value === "-h")) {
+    const topic = rootHelp ? prefix.slice(1)
+      : commandHelp ? [command!, ...prefix.slice(2)] : prefix;
+    // Options and their operands are not part of a help topic. Keep argv intact.
+    const option = topic.findIndex((value, index) => value.startsWith("-")
+      && (index > 0 || (rootHelp && ["--all", "--help", "-h"].includes(value))));
+    const path = option < 0 ? topic : topic.slice(0, option);
     return {
       kind: "help",
       command,
       args,
-      ...(command === "help" && args[1] ? { helpTarget: args[1] } : {}),
+      ...(path.length ? { helpTarget: path[0] } : {}),
+      ...(path.length > 1 ? { helpPath: path } : {}),
+      ...(rootHelp && path.length === 0 && prefix.includes("--all") ? { helpAll: true } : {}),
     };
   }
-  if (command !== "help" && hasHelpFlag(args.slice(1))) {
-    // `ocx <cmd> --help|-h|help` prints that command's usage, not the full list.
-    return { kind: "help", command, args, helpTarget: command };
-  }
   // P1: pre-parse `ocx ready` and reject invalid arguments with exit 64 BEFORE
   // maybeAutoRestoreCodexShim (or any discovery/probe/filesystem-capable global
   // preflight) runs. `ready --help` / `help ready` already exited above, so this
@@ -65,14 +79,24 @@ export function parseCliHead(argv: string[]): CliHead {
   return { kind: "command", command, args };
 }
 
+export function uninstallArgsError(command: string | undefined, args: string[]): string | undefined {
+  if ((command !== "uninstall" && command !== "remove") || args.length <= 1) return undefined;
+  return `ocx ${command} does not accept arguments (got: ${redactSecretArgs(args.slice(1)).join(" ")}). No changes were made. See: ocx help ${command}`;
+}
+
 export async function runCli(argv: string[]): Promise<CliHead> {
+  noteCredentialArgv(argv);
   const head = parseCliHead(argv);
   switch (head.kind) {
     case "version":
       printVersion();
       process.exit(0);
     case "help": {
-      if (head.helpTarget) printSubcommandUsage(head.helpTarget);
+      if (head.helpAll) printFullUsage();
+      else if (head.helpTarget) printSubcommandUsage(head.helpTarget, head.helpPath, {
+        fallbackToParent: head.command !== "help" && head.command !== "--help"
+          && head.command !== "-h" && head.args[1] !== "help",
+      });
       else printUsage();
       process.exit(0);
     }
@@ -104,10 +128,19 @@ export async function runCli(argv: string[]): Promise<CliHead> {
       return head;
     }
     case "command":
+      if (head.command !== "internal" && !findCommand(head.command ?? "")) {
+        printUnknownCommand(head.command);
+        process.exit(1);
+      }
       if (head.command === "stop" && !parseStopApproval(head.args.slice(1)).ok) {
         console.error("Usage: ocx stop [--json [--expect-pid <pid> --expect-port <port> --expect-hostname <host> --expect-config-home <home> --expect-cli-version <version> --expect-compatibility-token <hex>]]");
         process.exit(64);
       }
+      const uninstallError = uninstallArgsError(head.command, head.args);
+      if (uninstallError) {
+        console.error(uninstallError);
+        process.exit(2);
+      }
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;
   }

package/src/cli/route-policy-write.ts

@@ -0,0 +1,137 @@
+/** Explicit create/replace/delete for routing profiles; contextual validation stays server-owned. */
+import { isValidPolicyId } from "../routing/profile";
+import { printCatalogResult, runCatalogAction } from "./catalog-command-result";
+import { readJsonInput, serializeManagementJson } from "./json-input";
+import { CliUsageError, runtimeBaseUrl, runtimeRequest, takeFlag, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx route policy create <id> --file <profile.json|-> [--json]
+  ocx route policy update <id> --file <profile.json|-> --expected-revision <revision> [--json]
+  ocx route policy remove <id> --yes [--json]`;
+const ERRORS: Readonly<Record<string, string>> = {
+  profile_exists: "Routing profile already exists. Use show and review an explicit update.",
+  profile_revision_conflict: "Routing profile changed. Read show again and review the changes before updating with its revision.",
+  unknown_profile: "Routing profile was not found on the selected target.",
+  invalid_profile: "The target refused the profile. Check its candidates, alias and policy settings against the target configuration.",
+  missing_profile_id: "A routing profile id is required.",
+  invalid_profile_mode: "The target refused the routing profile operation.",
+  alias_reference_conflict: "The alias change conflicts with existing model references. Resolve the conflicting mappings first.",
+  invalid_shadow_call_target: "The alias change would create an invalid shadow-call target. Inspect its routing references first.",
+};
+const PROFILE_KEYS = ["alias", "candidates", "require", "optimize", "limits", "unknownEvidence", "compatibility"];
+const REQUIRE_KEYS = ["minContextWindow", "minQuotaHeadroom", "tools", "imageInput", "structuredOutput", "reasoningEffort", "serviceTier", "localOnly", "remoteAllowed", "encryptedCodexTasks"];
+const WEIGHT_KEYS = ["latency", "health", "cost", "quota"];
+const UNKNOWN_KEYS = ["capability", "health", "quota", "cost"];
+const COMPATIBILITY_KEYS = ["requiredSuites", "minStatus", "maxEvidenceAgeMs", "unknownEvidence", "degradedEvidence"];
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+function only(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  return record(value) && Object.keys(value).every(key => keys.includes(key));
+}
+function text(value: unknown): value is string { return typeof value === "string" && value.trim().length > 0; }
+function nonnegative(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+function evidence(value: unknown): boolean { return value === "allow" || value === "penalize" || value === "exclude"; }
+function optionalFields(value: Record<string, unknown>, validators: Record<string, (value: unknown) => boolean>): boolean {
+  return Object.entries(validators).every(([key, accepts]) => !Object.hasOwn(value, key) || accepts(value[key]));
+}
+
+/** Shape/ownership only: do not invent a provider configuration to run contextual validators. */
+function editableProfile(value: unknown): value is Record<string, unknown> {
+  if (!only(value, PROFILE_KEYS) || !Array.isArray(value.candidates) || !value.candidates.length
+    || !value.candidates.every(candidate => only(candidate, ["provider", "model"]) && text(candidate.provider) && text(candidate.model))) return false;
+  if (Object.hasOwn(value, "alias") && typeof value.alias !== "string") return false;
+  if (Object.hasOwn(value, "require")) {
+    const required = value.require;
+    if (!only(required, REQUIRE_KEYS) || !optionalFields(required, {
+      minContextWindow: n => Number.isSafeInteger(n) && (n as number) > 0,
+      minQuotaHeadroom: n => nonnegative(n) && n <= 1,
+      reasoningEffort: n => typeof n === "string", serviceTier: n => typeof n === "string",
+    })) return false;
+    for (const key of ["tools", "imageInput", "structuredOutput", "localOnly", "remoteAllowed", "encryptedCodexTasks"]) {
+      if (Object.hasOwn(required, key) && typeof required[key] !== "boolean") return false;
+    }
+  }
+  if (Object.hasOwn(value, "optimize") && (!only(value.optimize, WEIGHT_KEYS) || !Object.values(value.optimize).every(nonnegative))) return false;
+  if (Object.hasOwn(value, "limits") && (!only(value.limits, ["maxEstimatedCostUsd", "onUnknownCost"])
+    || !optionalFields(value.limits, { maxEstimatedCostUsd: nonnegative, onUnknownCost: n => n === "allow" || n === "exclude" }))) return false;
+  if (Object.hasOwn(value, "unknownEvidence") && (!only(value.unknownEvidence, UNKNOWN_KEYS) || !Object.values(value.unknownEvidence).every(evidence))) return false;
+  if (Object.hasOwn(value, "compatibility")) {
+    const compatibility = value.compatibility;
+    if (!only(compatibility, COMPATIBILITY_KEYS) || !optionalFields(compatibility, {
+      requiredSuites: n => Array.isArray(n) && n.every(suite => only(suite, ["suiteId", "evidenceLayer"])
+        && text(suite.suiteId) && ["protocol_conformance", "live_route_compatibility"].includes(suite.evidenceLayer as string)),
+      minStatus: n => n === "PROBED" || n === "VERIFIED",
+      maxEvidenceAgeMs: n => Number.isSafeInteger(n) && (n as number) >= 0,
+      unknownEvidence: evidence, degradedEvidence: evidence,
+    })) return false;
+  }
+  return true;
+}
+
+function invalidResult(): never { throw new Error("Invalid routing profile result"); }
+
+function projectProfile(value: unknown, id: string, model: unknown): Record<string, unknown> {
+  if (!only(value, [...PROFILE_KEYS, "id", "model", "revision"]) || value.id !== id
+    || !text(value.revision) || !text(model) || value.model !== model
+    || (value.alias !== null && !text(value.alias))) invalidResult();
+  const { id: _id, model: _model, revision: _revision, alias, ...editable } = value;
+  const input = { ...editable, ...(alias === null ? {} : { alias }) };
+  if (!editableProfile(input) || model !== (alias ?? `policy/${id}`)
+    || !record(value.require) || !record(value.limits)
+    || !record(value.optimize) || !WEIGHT_KEYS.every(key => Object.hasOwn(value.optimize as object, key))
+    || !record(value.unknownEvidence) || !UNKNOWN_KEYS.every(key => Object.hasOwn(value.unknownEvidence as object, key))) invalidResult();
+  if (value.compatibility !== undefined && (!record(value.compatibility)
+    || !Array.isArray(value.compatibility.requiredSuites) || !evidence(value.compatibility.unknownEvidence)
+    || !evidence(value.compatibility.degradedEvidence))) invalidResult();
+  // Every nested field was admitted above; rebuild the envelope rather than echoing server metadata.
+  return { id, model, revision: value.revision, alias, ...editable };
+}
+
+function printResult(value: unknown, id: string, remove: boolean, wantsJson: boolean): number {
+  if (!only(value, remove ? ["success", "id", "catalogRefresh"] : ["success", "id", "model", "profile", "catalogRefresh"])
+    || value.success !== true || value.id !== id) invalidResult();
+  const data: Record<string, unknown> = { success: true, id };
+  const lines = [remove ? `Removed routing profile: ${id}` : `Saved routing profile: ${id}`];
+  if (!remove) {
+    data.profile = projectProfile(value.profile, id, value.model);
+    data.model = value.model;
+    lines.push(`Model: ${value.model}`, `Revision: ${(data.profile as Record<string, unknown>).revision}`);
+  }
+  return printCatalogResult(data, value.catalogRefresh, wantsJson, lines);
+}
+
+export async function handleRoutePolicyWriteCommand(
+  sub: "create" | "update" | "remove", argv: string[], deps: RuntimeApiDeps = {},
+): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const id = args.shift();
+    if (!id || !isValidPolicyId(id)) throw new CliUsageError("A valid exact routing profile id is required (letters, numbers, dot, underscore or hyphen; max 64).", USAGE);
+    const wantsJson = takeFlag(args, "--json");
+    const yes = takeFlag(args, "--yes");
+    const file = takeOptionWithSyntax(args, "--file")?.value;
+    const revision = takeOptionWithSyntax(args, "--expected-revision")?.value;
+    if (args.length) throw new CliUsageError("Unknown, repeated or unexpected routing profile arguments.", USAGE);
+    if (sub === "remove") {
+      if (!yes || file !== undefined || revision !== undefined) throw new CliUsageError("Removal requires --yes and does not accept a file or revision.", USAGE);
+    } else {
+      if (yes || !file?.trim()) throw new CliUsageError("Creation and update require --file and do not accept --yes.", USAGE);
+      if (sub === "update" ? !revision?.trim() : revision !== undefined) throw new CliUsageError("Update requires an explicit nonblank --expected-revision; create does not accept it.", USAGE);
+    }
+    let body: string | undefined;
+    if (sub !== "remove") {
+      const profile = await readJsonInput(file!, deps);
+      if (!editableProfile(profile)) throw new CliUsageError("Profile file must contain only editable routing fields with valid nested types; omit id, model and revision.", USAGE);
+      body = serializeManagementJson({ id, mode: sub, profile, ...(sub === "update" ? { expectedRevision: revision } : {}) });
+    }
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    const result = await runtimeRequest(sub === "remove" ? `/api/routing-profiles?id=${encodeURIComponent(id)}` : "/api/routing-profiles", {
+      method: sub === "remove" ? "DELETE" : "PUT", redirect: "error",
+      ...(body !== undefined ? { headers: { "content-type": "application/json" }, body } : {}),
+    }, pinned);
+    return printResult(result, id, sub === "remove", wantsJson);
+  }, ERRORS);
+}

package/src/cli/route-policy.ts

@@ -11,6 +11,9 @@ import {
 } from "./runtime-api";
 
 const USAGE = `Usage:
+  ocx route policy create <id> --file <FILE|-> [--json]
+  ocx route policy update <id> --file <FILE|-> --expected-revision <revision> [--json]
+  ocx route policy remove <id> --yes [--json]
   ocx route policy list [--json]
   ocx route policy show <id> [--json]
   ocx route policy dry-run <id> [--model-context <tokens>] [--tools]
@@ -83,6 +86,11 @@ async function dryRun(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 }
 
 export async function handleRoutePolicyCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  const [write, ...rest] = argv;
+  if (write === "create" || write === "update" || write === "remove") {
+    const { handleRoutePolicyWriteCommand } = await import("./route-policy-write");
+    return handleRoutePolicyWriteCommand(write, rest, deps);
+  }
   return runCliAction(async () => {
     const [sub, ...rest] = argv;
     if (!sub) throw new CliUsageError("route policy requires a subcommand (list, show, dry-run, evaluate)", USAGE);

package/src/cli/runtime-api.ts

@@ -11,6 +11,8 @@
  */
 import { findLiveProxy, probeHostname, type LivenessIo, type LiveProxy } from "../server/proxy-liveness";
 import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+import { redactSecretArgs } from "./secret-args";
+export { redactSecretArgs };
 
 export type CliStdin = NodeJS.ReadableStream & { isTTY?: boolean; readableEnded?: boolean };
 
@@ -22,6 +24,8 @@ export interface RuntimeApiDeps {
   /** Test injection for commands that read a secret from stdin instead of argv. */
   stdinImpl?: CliStdin;
   stdinTimeoutMs?: number;
+  /** Cancellation for bounded secret-byte reads; line readers retain their contract. */
+  stdinSignal?: AbortSignal;
   /** Optional proxy liveness probe injection for commands that check or fall back around live runtime state. */
   findLiveProxy?: (io?: LivenessIo) => Promise<LiveProxy | null>;
 }
@@ -33,11 +37,15 @@ export class CliUsageError extends Error {
   }
 }
 
+export const PROXY_NOT_RUNNING_MESSAGE = "Proxy is not running. Start the intended proxy with: ocx start. No request was sent.";
+
 export class RuntimeApiError extends Error {
   constructor(
     message: string,
     readonly status: number,
     readonly body: unknown,
+    /** Local discovery refusals occur before the management request is sent. */
+    readonly code?: "proxy_not_running" | "client_role_management_unavailable",
   ) {
     super(message);
     this.name = "RuntimeApiError";
@@ -70,12 +78,12 @@ function clientRoleManagementRefusal(port: number): string {
 export async function runtimeBaseUrl(deps: RuntimeApiDeps = {}): Promise<string> {
   if (deps.baseUrl) return deps.baseUrl.replace(/\/$/, "");
   const live = await (deps.findLiveProxy ?? findLiveProxy)();
-  if (!live) throw new RuntimeApiError("Proxy is not running. Start it with: ocx start", 503, null);
+  if (!live) throw new RuntimeApiError(PROXY_NOT_RUNNING_MESSAGE, 503, null, "proxy_not_running");
   // The role comes from the same identity-checked /healthz body liveness already parsed, so
   // this costs no extra request. Only the client role is refused: an absent role is a
   // standalone or hub proxy (or a legacy body that predates the field), and both serve /api/*.
   if (live.role === "client") {
-    throw new RuntimeApiError(clientRoleManagementRefusal(live.port), 503, null);
+    throw new RuntimeApiError(clientRoleManagementRefusal(live.port), 503, null, "client_role_management_unavailable");
   }
   return `http://${probeHostname(live.hostname)}:${live.port}`;
 }
@@ -85,6 +93,33 @@ function stringField(record: Record<string, unknown>, key: string): string | und
   return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 
+function integrationRecoveryMessage(reason: string | undefined): string | undefined {
+  switch (reason) {
+    case "not_installed": return "The client is not installed. Run: ocx integration client status.";
+    case "non_loopback": return "The integration requires a loopback destination. Run: ocx integration client status.";
+    case "drift_requires_confirm": return "The client configuration changed. Run `ocx integration client status` before explicitly confirming restore.";
+    case "snapshot_expired": return "The recovery snapshot expired. Run `ocx integration client status` before creating a new change.";
+    case "superseded_store": return "The client uses a different configuration store. Run `ocx integration client status`, then disable and enable the selected client.";
+    case "unsafe": return "The client config path is unsafe to edit (for example a link or a competing file). Run `ocx integration client status` to see the affected path.";
+    case "conflict": return "The client config no longer matches the recorded ownership. Run `ocx integration client status`; add --overwrite-conflict to enable only if replacing it is intended.";
+    case "write_failed": return "The client config write failed. Run `ocx integration client status` before retrying.";
+    default: return undefined;
+  }
+}
+
+/**
+ * Integration writer detail is the only server prose this client appends beside the primary
+ * error. Scope it to the normalized request pathname (dot segments resolved, no query) and to
+ * an unredirected response so no other route's body can ride along.
+ */
+function isIntegrationRoute(path: string, response: Response): boolean {
+  if (response.redirected) return false;
+  let pathname: string;
+  try { pathname = new URL(path.startsWith("/") ? path : "/" + path, "http://cli.invalid").pathname; }
+  catch { return false; }
+  return /^\/api\/client-integrations(?:\/|$)/.test(pathname);
+}
+
 /**
  * Compose the operator-facing message from a management error body.
  *
@@ -102,7 +137,7 @@ function stringField(record: Record<string, unknown>, key: string): string | und
  * (#4662). Name the route instead, so any listener that does not serve a path stays legible
  * even if another one starts answering this way.
  */
-function responseMessage(body: unknown, status: number): string {
+function responseMessage(body: unknown, status: number, integrationRoute = false): string {
   if (typeof body === "string" && body.trim()) return body.trim().slice(0, 400);
   if (!body || typeof body !== "object") return `Management request failed (${status})`;
   const record = body as Record<string, unknown>;
@@ -119,6 +154,13 @@ function responseMessage(body: unknown, status: number): string {
     if (primary) break;
   }
   const parts = [primary ?? `Management request failed (${status})`];
+  // Integration mutation routes carry a writer explanation beside a generic error. Its prose is
+  // server text (paths, upstream errors), so render fixed guidance keyed on the closed reason
+  // code instead of echoing it; other management bodies keep their presentation contract.
+  if (integrationRoute && stringField(record, "message") && stringField(record, "message") !== primary) {
+    const fixed = integrationRecoveryMessage(stringField(record, "reason"));
+    if (fixed) parts.push(`Details: ${fixed}`);
+  }
   const reason = stringField(record, "reason");
   // A body of {ok:false, reason:"…"} with no `error` key used to degrade to the
   // generic line, discarding the only actionable field.
@@ -158,7 +200,9 @@ export async function runtimeRequest<T = unknown>(
     try { body = JSON.parse(text); }
     catch { body = text; }
   }
-  if (!response.ok) throw new RuntimeApiError(responseMessage(body, response.status), response.status, body);
+  if (!response.ok) {
+    throw new RuntimeApiError(responseMessage(body, response.status, isIntegrationRoute(path, response)), response.status, body);
+  }
   return body as T;
 }
 
@@ -226,79 +270,6 @@ export function csv(value: string | undefined): string[] | undefined {
   return [...new Set(value.split(",").map(item => item.trim()).filter(Boolean))];
 }
 
-/**
- * Options whose VALUE is a credential (or can carry one), listed here so a parse
- * error never prints one. `--headers` belongs on the list defensively: custom
- * headers are documented as non-secret metadata and the validator rejects the
- * standard credential names, but it cannot recognize an arbitrary one such as
- * `X-My-Token`, so a parse error must not echo the value back either way.
- *
- * `takeOption` only understands `--flag value`. `--flag=value` therefore falls
- * through to `rejectArgs`, which reports the offending argument verbatim — for
- * `--code=https://…?code=SECRET` that writes the authorization code to stderr,
- * which is the exact exposure the stdin path exists to avoid.
- */
-const SECRET_OPTIONS = [
-  "--code",
-  "--headers",
-  "--token",
-  "--admin-token",
-  "--pairing-code",
-  "--credential-env",
-  "--admin-token-env",
-  "--pairing-code-env",
-];
-
-/**
- * Replace credential values before they are reported back.
- *
- * Both spellings have to be covered, and the space-separated one spans two
- * tokens: mistyping `ocx account cancel <p> --code <secret>` on a command that
- * does not parse `--code` leaves the flag AND its value in the leftovers, and
- * reporting them verbatim writes the credential to stderr. Repeating the
- * option does the same with the second value, since the parser takes only the
- * first occurrence.
- *
- * The token after the option is redacted whatever it looks like. Skipping
- * `--`-prefixed tokens read as "that is a flag, not a value", but the shell
- * hands over whatever was typed: `--code --SUPERSECRET` and
- * `--code -- SUPERSECRET` both put the credential straight in the message. A
- * mistaken `--code --json` now reads `--code <redacted>`, which is worse
- * diagnostics for a case that already prints the usage text, and better than
- * printing a credential.
- *
- * `redactValues` extends that to bare leftovers, for commands whose positional
- * argument is itself a credential.
- */
-function redactSecretArgs(args: string[], redactValues = false): string[] {
-  const out: string[] = [];
-  for (let index = 0; index < args.length; index++) {
-    const arg = args[index] as string;
-    const inline = SECRET_OPTIONS.find(option => arg.startsWith(`${option}=`));
-    if (inline) {
-      out.push(`${inline}=<redacted>`);
-      continue;
-    }
-    if (SECRET_OPTIONS.includes(arg)) {
-      out.push(arg);
-      // Swallow the value that belongs to it. `--` is an end-of-options
-      // separator, so the value is the token after it.
-      let valueIndex = index + 1;
-      if (args[valueIndex] === "--") {
-        out.push("--");
-        valueIndex++;
-      }
-      if (args[valueIndex] !== undefined) {
-        out.push("<redacted>");
-        index = valueIndex;
-      }
-      continue;
-    }
-    out.push(redactValues && !arg.startsWith("-") ? "<redacted>" : arg);
-  }
-  return out;
-}
-
 export interface RejectArgsOptions {
   /**
    * Report bare leftovers as `<redacted>`. Set by commands where a stray
@@ -399,16 +370,19 @@ export async function readSecretBytes(
   deps: RuntimeApiDeps,
   label: string,
   maxBytes = MAX_LINK_CREDENTIAL_BYTES,
-): Promise<Uint8Array> {
+): Promise<Uint8Array<ArrayBuffer>> {
   const input: CliStdin = deps.stdinImpl ?? process.stdin;
   const timeoutMs = deps.stdinTimeoutMs ?? 120_000;
+  const signal = deps.stdinSignal;
+  signal?.throwIfAborted();
   if (input.readableEnded === true) throw new CliUsageError(`${label} input was empty`);
-  return await new Promise<Uint8Array>((resolve, reject) => {
+  return await new Promise<Uint8Array<ArrayBuffer>>((resolve, reject) => {
     const chunks: Uint8Array[] = [];
     let total = 0;
     let settled = false;
     const cleanup = () => {
       clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
       input.removeListener("data", onData);
       input.removeListener("end", onEnd);
       input.removeListener("error", onError);
@@ -459,6 +433,7 @@ export async function readSecretBytes(
       resolve(result);
     });
     const onError = (error: Error) => finish(() => reject(error));
+    const onAbort = () => finish(() => reject(signal?.reason));
     const timer = setTimeout(
       () => finish(() => reject(new CliUsageError(`timed out waiting for ${label} on stdin`))),
       timeoutMs,
@@ -466,12 +441,14 @@ export async function readSecretBytes(
     input.on("data", onData);
     input.on("end", onEnd);
     input.on("error", onError);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) onAbort();
   });
 }
 
 export function printData(value: unknown, wantsJson: boolean, lines?: string[]): void {
   if (wantsJson || !lines) console.log(JSON.stringify(value, null, 2));
-  else for (const line of lines) console.log(line);
+  else for (const line of lines) console.log(terminalSafeText(line));
 }
 
 /**