@bitkyc08/opencodex 2.77.0 → 2.78.0

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,6 +441,8 @@ 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();
   });
 }
 

package/src/cli/secret-args.ts

@@ -0,0 +1,149 @@
+/** Credential-option redaction for CLI argument errors. Kept dependency-free so the CLI head can use it. */
+/**
+ * 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",
+  "--api-key",
+  "--key",
+  "--secret",
+  "--password",
+  "--token",
+  "--admin-token",
+  "--pairing-code",
+  "--credential-env",
+  "--admin-token-env",
+  "--pairing-code-env",
+];
+
+function isSecretOptionToken(token: string): boolean {
+  return SECRET_OPTIONS.includes(token) || SECRET_OPTIONS.some(option => token.startsWith(`${option}=`));
+}
+
+let credentialArgvSeen = false;
+let credentialValues: string[] = [];
+let consoleScrubInstalled = false;
+
+/** Operands of credential options in argv, longest first; very short values are not scrubbed. */
+function credentialOperands(argv: readonly string[]): string[] {
+  const values = new Set<string>();
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index] as string;
+    const inline = SECRET_OPTIONS.find(option => token.startsWith(`${option}=`));
+    let value: string | undefined;
+    if (inline) value = token.slice(inline.length + 1);
+    else if (SECRET_OPTIONS.includes(token)) {
+      value = argv[argv[index + 1] === "--" ? index + 2 : index + 1];
+      // A following bare credential option is not this option's operand; its own operand is
+      // collected on its turn. An inline value is always an operand, whatever it looks like.
+      if (value !== undefined && SECRET_OPTIONS.includes(value)) value = undefined;
+    }
+    if (value !== undefined && value.length >= 4) values.add(value);
+  }
+  return [...values].sort((a, b) => b.length - a.length);
+}
+
+/** Replace every argv credential operand in text printed by this process. */
+export function scrubCredentialOperands(text: string): string {
+  let out = text;
+  // Case-insensitive: some parsers lowercase an action before echoing it.
+  for (const value of credentialValues) out = out.replace(new RegExp(value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi"), "<redacted>");
+  return out;
+}
+
+/**
+ * Last-line guard for console diagnostics (stderr): parsers that echo a selector, an unknown
+ * subcommand or a leftover before any redaction would otherwise print an operand typed after
+ * a credential option. Installed once; it reads the operands recorded for the current argv.
+ */
+function installConsoleScrub(): void {
+  if (consoleScrubInstalled) return;
+  consoleScrubInstalled = true;
+  // Diagnostics only: stdout carries JSON documents whose primitives must not be rewritten.
+  for (const method of ["warn", "error"] as const) {
+    const original = console[method].bind(console);
+    console[method] = (...args: unknown[]) => {
+      if (credentialValues.length === 0) return original(...args);
+      return original(...args.map(arg => typeof arg === "string" ? scrubCredentialOperands(arg)
+        : arg instanceof Error ? scrubCredentialOperands(arg.stack ?? arg.message) : arg));
+    };
+  }
+}
+
+/**
+ * Record whether the process argv carried any credential option. Parsers that take
+ * positionals can consume the option token itself (`ocx account use openai --token X`
+ * makes `--token` the id), leaving only its operand as a "leftover"; once a credential
+ * option was present anywhere, every bare leftover is reported as `<redacted>`.
+ */
+export function noteCredentialArgv(argv: readonly string[]): void {
+  credentialArgvSeen = argv.some(isSecretOptionToken);
+  credentialValues = credentialOperands(argv);
+  if (credentialValues.length > 0) installConsoleScrub();
+}
+
+/**
+ * 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.
+ */
+export function redactSecretArgs(args: string[], redactValues = false): string[] {
+  redactValues ||= credentialArgvSeen;
+  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++;
+      }
+      const next = args[valueIndex];
+      // A following credential option is not this option's value: leave it for the
+      // next iteration so its own operand is redacted too (`--code --token SECRET`).
+      if (next !== undefined && !isSecretOptionToken(next)) {
+        out.push("<redacted>");
+        index = valueIndex;
+      } else if (next !== undefined) {
+        index = valueIndex - 1;
+      }
+      continue;
+    }
+    out.push(redactValues && !arg.startsWith("-") ? "<redacted>" : arg);
+  }
+  return out;
+}

package/src/cli/settings-result.ts

@@ -0,0 +1,30 @@
+import { printData } from "./runtime-api";
+import type { CodexDesktopSwitchApply, CodexDesktopSwitchApplyReason } from "../codex/desktop-switches";
+
+const APPLY_REASONS = {
+  not_requested: true, proxy_not_running: true, integration_disabled: true,
+  external_provider: true, ownership_undetermined: true, write_lock_busy: true, injection_refused: true,
+} satisfies Record<CodexDesktopSwitchApplyReason, true>;
+
+/** The shared native apply DTO, excluding exception/path detail. */
+export function projectSettingsApply(value: unknown): CodexDesktopSwitchApply | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const row = value as Record<string, unknown>;
+  if (row.applied === true) return { applied: true };
+  if (row.applied !== false || typeof row.reason !== "string" || !Object.hasOwn(APPLY_REASONS, row.reason)
+    || typeof row.retryable !== "boolean") return null;
+  return { applied: false, reason: row.reason as CodexDesktopSwitchApplyReason, retryable: row.retryable };
+}
+
+/** Caller rebuilds the relevant task DTO; settings pending is not a CatalogDisposition. */
+export function printSettingsResult(
+  data: Record<string, unknown>, pending: unknown, wantsJson: boolean, lines: readonly string[],
+): number {
+  const verified = typeof pending === "boolean";
+  const note = !verified ? "Settings were accepted; catalog status is unverified. Read back before retrying."
+    : pending ? "Settings saved; catalog refresh is pending."
+      : "Settings saved; this response reports no pending catalog refresh.";
+  printData({ ...data, catalogRefreshPending: verified ? pending : null,
+    ...(!verified ? { verification: "unverified" } : {}) }, wantsJson, [...lines, note]);
+  return verified && pending === false ? 0 : 1;
+}

package/src/cli/storage.ts

@@ -17,6 +17,7 @@
  */
 import {
   CliUsageError,
+  RuntimeApiError,
   printData,
   rejectArgs,
   runCliAction,
@@ -27,6 +28,7 @@ import {
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import type { StorageCleanupPolicy } from "../types/config";
 
 const USAGE = `Usage:
   ocx storage report [--json]
@@ -34,7 +36,8 @@ const USAGE = `Usage:
   ocx storage trash [list] [--json]
   ocx storage trash restore <entry-id> [--yes] [--json]
   ocx storage policy [show] [--json]
-  ocx storage policy set [--enabled <true|false>] [--percent <0-100>]
+  ocx storage policy set [--enabled <true|false>] [--archived-bytes-over <bytes>]
+      [--reduce-to-bytes <bytes> | --remove-oldest-percent <1-100> | --percent <1-100>]
       [--mode <quarantine|permanent>] [--schedule <startup|daily|weekly|manual>] [--json]
   ocx storage policy run [--yes] [--json]
 
@@ -146,6 +149,41 @@ async function trash(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, summaryLines(result));
 }
 
+/** New policy controls expose only observed settings and job status, never arbitrary API fields. */
+type ObservedPolicy = Omit<StorageCleanupPolicy, "target"> & { target: { reduceToBytes: number } | { removeOldestPercent: number } };
+function policyWriteReceipt(value: unknown): { ok: true; policy: ObservedPolicy; job: { status: "idle" | "running" } } {
+  const record = (item: unknown): item is Record<string, unknown> => item !== null && typeof item === "object" && !Array.isArray(item);
+  const count = (item: unknown): item is number => typeof item === "number" && Number.isInteger(item) && item >= 0;
+  const invalid = (): never => { throw new Error("Invalid storage policy response; inspect the policy before retrying."); };
+  if (!record(value) || value.ok !== true || !record(value.policy) || !record(value.job)) return invalid();
+  const source = value.policy;
+  if (typeof source.enabled !== "boolean" || !record(source.trigger) || !count(source.trigger.archivedBytesOver)
+    || !record(source.target) || (source.mode !== "quarantine" && source.mode !== "permanent")
+    || (source.schedule !== "startup" && source.schedule !== "daily" && source.schedule !== "weekly" && source.schedule !== "manual")
+    || (value.job.status !== "idle" && value.job.status !== "running")) return invalid();
+  const { reduceToBytes, removeOldestPercent } = source.target;
+  let target: ObservedPolicy["target"];
+  if (count(reduceToBytes) && removeOldestPercent === undefined) target = { reduceToBytes };
+  else if (count(removeOldestPercent) && removeOldestPercent >= 1 && removeOldestPercent <= 100 && reduceToBytes === undefined) target = { removeOldestPercent };
+  else return invalid();
+  const policy: ObservedPolicy = {
+    enabled: source.enabled,
+    trigger: { archivedBytesOver: source.trigger.archivedBytesOver },
+    target,
+    mode: source.mode,
+    schedule: source.schedule,
+  };
+  if (source.lastRun !== undefined) {
+    if (!record(source.lastRun) || !count(source.lastRun.at) || !count(source.lastRun.freedBytes) || !count(source.lastRun.removed)) return invalid();
+    policy.lastRun = { at: source.lastRun.at, freedBytes: source.lastRun.freedBytes, removed: source.lastRun.removed };
+  }
+  if (source.nextRun !== undefined) {
+    if (!count(source.nextRun)) return invalid();
+    policy.nextRun = source.nextRun;
+  }
+  return { ok: true, policy, job: { status: value.job.status } };
+}
+
 async function policy(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const action = argv[0] && !argv[0].startsWith("-") ? argv[0] : "show";
   const rest = argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv;
@@ -164,6 +202,9 @@ async function policy(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     const wantsJson = takeFlag(args, "--json");
     const enabled = takeOption(args, "--enabled");
     const percent = takeIntegerOption(args, "--percent", { min: 0 });
+    const removeOldestPercent = takeIntegerOption(args, "--remove-oldest-percent", { min: 0 });
+    const reduceToBytes = takeIntegerOption(args, "--reduce-to-bytes", { min: 0 });
+    const archivedBytesOver = takeIntegerOption(args, "--archived-bytes-over", { min: 0 });
     const mode = takeOption(args, "--mode");
     const schedule = takeOption(args, "--schedule");
     rejectArgs(args, USAGE);
@@ -171,8 +212,13 @@ async function policy(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     if (enabled !== undefined && enabled !== "true" && enabled !== "false") {
       throw new CliUsageError("--enabled must be true or false", USAGE);
     }
+    if ([percent, removeOldestPercent, reduceToBytes].filter(value => value !== undefined).length > 1) {
+      throw new CliUsageError("choose one target: --percent, --remove-oldest-percent or --reduce-to-bytes", USAGE);
+    }
+    const extended = archivedBytesOver !== undefined || reduceToBytes !== undefined || removeOldestPercent !== undefined;
     const body: Record<string, unknown> = {};
     if (enabled !== undefined) body.enabled = enabled === "true";
+    if (archivedBytesOver !== undefined) body.trigger = { archivedBytesOver };
     // The policy target is nested. A top-level `percent` is not part of the PUT contract:
     // `normalizeStorageCleanupPolicy` reads only `target`, so the field was dropped and the
     // previously stored target survived. `--percent 10` on a policy still holding the
@@ -183,20 +229,44 @@ async function policy(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     // vocabulary and answers with a named 400, which is a rejected write rather than the
     // silent wrong write this replaces.
     if (percent !== undefined) body.target = { removeOldestPercent: percent };
+    if (removeOldestPercent !== undefined) body.target = { removeOldestPercent };
+    if (reduceToBytes !== undefined) body.target = { reduceToBytes };
     if (mode !== undefined) body.mode = mode;
     if (schedule !== undefined) body.schedule = schedule;
     if (Object.keys(body).length === 0) {
-      throw new CliUsageError("policy set needs at least one of --enabled, --percent, --mode, --schedule", USAGE);
+      throw new CliUsageError("policy set needs at least one policy field", USAGE);
     }
     // Values are NOT re-validated here beyond --enabled's shape. The server owns the mode and
     // schedule vocabularies and returns a named 400; duplicating them is a second thing to
     // keep in sync. `enabled` is checked because "--enabled maybe" would otherwise be sent as
     // `false`, which is a wrong write rather than a rejected one.
-    const result = await runtimeRequest("/api/storage/cleanup-policy", {
-      method: "PUT",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-    }, deps);
+    let result: unknown;
+    try {
+      result = await runtimeRequest("/api/storage/cleanup-policy", {
+        method: "PUT",
+        ...(extended ? { redirect: "error" as const } : {}),
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      }, deps);
+    } catch (error) {
+      if (!extended) throw error;
+      if (error instanceof RuntimeApiError) {
+        throw new RuntimeApiError(`Storage policy request failed (${error.status}); inspect the policy before retrying.`, error.status, null);
+      }
+      throw new Error("Storage policy request failed; inspect the policy before retrying.");
+    }
+    if (extended) {
+      const receipt = policyWriteReceipt(result);
+      const saved = receipt.policy;
+      printData(receipt, wantsJson, [
+        "Policy saved. This command did not start cleanup.",
+        `Enabled: ${saved.enabled}`,
+        `Trigger: archived bytes over ${saved.trigger.archivedBytesOver}`,
+        "reduceToBytes" in saved.target ? `Target: reduce archives to ${saved.target.reduceToBytes} bytes` : `Target: remove oldest ${saved.target.removeOldestPercent}%`,
+        `Mode: ${saved.mode}; schedule: ${saved.schedule}; job: ${receipt.job.status}`,
+      ]);
+      return;
+    }
     printData(result, wantsJson, summaryLines(result));
     return;
   }

package/src/cli/system-command.ts

@@ -1,3 +1,4 @@
+import { runCatalogAction } from "./catalog-command-result";
 import {
   CliUsageError,
   desktopSwitchApplyReason,
@@ -14,8 +15,11 @@ import {
 
 const USAGE = `Usage:
   ocx system [status] [--json]
+  ocx system health [--json]
   ocx system settings [--auto-start <on|off>] [--stream-mode <auto|legacy-tee|eager-relay>]
-      [--desktop-authless <on|off>] [--client-compaction <on|off>] [--json]
+      [--desktop-authless <on|off>] [--client-compaction <on|off>]
+      [--show-codex-credits <on|off>] [--account-picker <on|off>] [--main-account-hard-lock <on|off>]
+      [--ultra-fast-tier <on|off>] [--fast-rows <on|off>] [--json]
   ocx system startup <health|install-service|install-shim> [--json]
   ocx system diagnostics [--json]
   ocx system sync [--json]
@@ -45,6 +49,46 @@ async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, summaryLines(result));
 }
 
+/** The management health observation is distinct from root liveness and aggregate status. */
+async function health(argv: string[], deps: RuntimeApiDeps): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv], wantsJson = takeFlag(args, "--json");
+    if (args.length) throw new CliUsageError("system health accepts only --json", USAGE);
+    const raw = await runtimeRequest("/api/system/health", { method: "GET", redirect: "error" }, deps);
+    const value = recordValue(raw), ledger = recordValue(value?.spendLedger);
+    const counter = (number: unknown): number => {
+      if (typeof number !== "number" || !Number.isSafeInteger(number) || number < 0 || number > 1_000_000) {
+        throw new Error("Invalid health counter");
+      }
+      return number;
+    };
+    if (!value || Array.isArray(raw) || !ledger || Array.isArray(value.spendLedger)
+      || value.status !== "ok" || value.service !== "opencodex"
+      || typeof value.version !== "string" || !value.version.trim()
+      || typeof value.uptime !== "number" || !Number.isFinite(value.uptime) || value.uptime < 0
+      || typeof value.pid !== "number" || !Number.isSafeInteger(value.pid) || value.pid <= 0
+      || (ledger.ownership !== "held" && ledger.ownership !== "unheld")
+      || typeof ledger.initialized !== "boolean" || typeof ledger.configured !== "boolean"
+      || typeof ledger.degraded !== "boolean") throw new Error("Invalid system health response");
+    const result = {
+      status: "ok", service: "opencodex", version: value.version, uptime: value.uptime, pid: value.pid,
+      spendLedger: {
+        ownership: ledger.ownership, initialized: ledger.initialized, configured: ledger.configured,
+        degraded: ledger.degraded, persistFailures: counter(ledger.persistFailures), corruptRecords: counter(ledger.corruptRecords),
+      },
+    };
+    printData(result, wantsJson, [
+      `Management endpoint: ${result.status} (${result.service} ${result.version}, PID ${result.pid})`,
+      `Uptime: ${result.uptime} seconds`,
+      `Spend ledger: ${ledger.degraded ? "degraded" : "no degradation reported"}; ownership ${ledger.ownership}`,
+      `Ledger initialized: ${ledger.initialized}; configured: ${ledger.configured}`,
+      `Ledger persistence failures: ${result.spendLedger.persistFailures}; corrupt records: ${result.spendLedger.corruptRecords}`,
+      "This observation does not certify every subsystem healthy.",
+      ...(ledger.degraded ? ["Next: inspect the proxy diagnostics and spend-ledger configuration before relying on spend limits."] : []),
+    ]);
+  });
+}
+
 function recordValue(value: unknown): Record<string, unknown> | undefined {
   return value !== null && typeof value === "object" ? value as Record<string, unknown> : undefined;
 }
@@ -187,11 +231,25 @@ async function update(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (!yes) throw new CliUsageError("update run requires --yes", USAGE);
   rejectArgs(args, USAGE);
   const result = await runtimeRequest("/api/update/run", { method: "POST", body: JSON.stringify({ tag: channel, restart }) }, deps);
-  printData(result, wantsJson, [`Update started (${channel}).`]);
+  const job = recordValue(recordValue(result)?.job);
+  const jobId = typeof job?.id === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(job.id) ? job.id : undefined;
+  const jobStatus = ["running", "restarting", "succeeded", "failed"].find(state => state === job?.status);
+  const lines = jobId ? [
+    `Update job ${jobId}: ${jobStatus ?? "status unconfirmed"} (${channel}).`,
+    `Check progress: ocx system update status ${jobId}`,
+  ] : ["Update request returned no usable job ID. Check: ocx system update check."];
+  printData(result, wantsJson, lines);
 }
 
 export async function handleSystemCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
   const [sub = "status", ...rest] = argv;
+  if (sub === "health") return health(rest, deps);
+  if (sub === "settings") {
+    const { SYSTEM_PARITY_OPTIONS, handleSystemSettingsParity } = await import("./system-settings-parity");
+    if (rest.some(arg => SYSTEM_PARITY_OPTIONS.some(flag => arg === flag || arg.startsWith(`${flag}=`)))) {
+      return handleSystemSettingsParity(rest, deps);
+    }
+  }
   if (sub === "codex-cli-update") {
     const { handleCodexCliUpdateCommand } = await import("./codex-cli-update");
     return await handleCodexCliUpdateCommand(rest);