@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/integration-plan-dto.ts

@@ -0,0 +1,156 @@
+/** Value-free wire boundary. Canonical DTO imports erase at runtime; no GUI or writer dependency. */
+import type {
+  IntegrationMutationPlan, IntegrationPlanOperation, IntegrationPlanChangeKind,
+  IntegrationPlanForeignEdit, IntegrationPlanChange, RefusalReason as IntegrationRefusalReason,
+} from "../integrations/mutation-plan";
+import type { IntegrationClientId as FileIntegrationClientId } from "../integrations/registry";
+import type { IntegrationState } from "../integrations/state";
+import type { IneffectiveWriteReason } from "../integrations/target";
+
+export const FILE_INTEGRATION_CLIENTS = [
+  "opencode",
+  "pi",
+  "omp",
+  "hermes",
+  "openclaw",
+  "kimi",
+  "gajae",
+  "dsh",
+  "mcode",
+  "zcode",
+  "prime",
+  "aside",
+  "raycast",
+  "omo",
+  "cline",
+  "kilo",
+  "droid",
+] as const;
+
+export const INTEGRATION_REFUSAL_REASONS: ReadonlySet<string> = new Set<IntegrationRefusalReason>([
+  "not_installed",
+  "conflict",
+  "unsafe",
+  "non_loopback",
+  "superseded_store",
+  "drift_requires_confirm",
+  "snapshot_expired",
+  "write_failed",
+]);
+export const INTEGRATION_STATES: ReadonlySet<string> = new Set<IntegrationState>([
+  "absent",
+  "current",
+  "stale",
+  "conflict",
+  "unsafe",
+]);
+const PLAN_OPERATIONS: readonly IntegrationPlanOperation[] = ["apply", "overwrite", "disable", "restore"];
+const PLAN_CHANGE_KINDS: readonly IntegrationPlanChangeKind[] = ["add", "replace", "remove", "snapshot", "ownership", "journal"];
+const PLAN_FOREIGN_EDITS: readonly IntegrationPlanForeignEdit[] = ["none", "unowned", "foreign-edit", "drift"];
+const PLAN_KEYS = new Set(["version", "clientId", "operation", "state", "foreignEdit", "changes", "fingerprint", "canApply", "willChange", "refusalReason", "supersededReason", "missingStoreDocument", "profileId"]);
+const SUPERSEDED_REASONS: ReadonlySet<string> = new Set<IneffectiveWriteReason>(["owned-config-file", "unestablished-schema", "missing-store"]);
+/** What to create a missing store with: echoed to a terminal, so one short printable-ASCII line. */
+const MISSING_STORE_DOCUMENT = /^[\x20-\x7e]{1,64}$/;
+const PLAN_CHANGE_KEYS = new Set(["kind", "path"]);
+const PLAN_PSEUDO_PATHS = new Set(["$snapshot", "$ownership", "$journal"]);
+const PLAN_SCHEMA_PATHS = new Set([
+  "provider.opencodex",
+  "providers.opencodex",
+  "models.providers.opencodex",
+  "models.*",
+  "llm-pi-ai.providers.opencodex",
+  "custom_provider.opencodex",
+  "providers.[id=opencodex]",
+  "settings.providers.opencodex",
+  "catalog.providers.opencodex",
+  "customModels.*",
+  // ZCode reads its providers from a second file; a plan for it publishes that
+  // file's templates, and a path missing here is rejected as an invalid preview.
+  "config.providerConfigRules.providerRules.[providerId=opencodex]",
+  "config.modelConfigRules.providerModelRules.*",
+  // DSH 0.1.7+ reads routes from the `llm-pi-ai` row of its Desktop profile patch.
+  "[id=llm-pi-ai].config.providers.opencodex",
+]);
+const PLAN_CHANGE_LIMIT = 256;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>): boolean {
+  return Object.keys(value).every(key => allowed.has(key));
+}
+
+function isSafePlanPath(path: string): boolean {
+  return PLAN_PSEUDO_PATHS.has(path) || PLAN_SCHEMA_PATHS.has(path);
+}
+
+function invalidPreviewResponse(): Error {
+  return new Error("Invalid integration preview response");
+}
+
+export function decodeIntegrationPlan(value: unknown): IntegrationMutationPlan {
+  if (!isRecord(value) || !hasOnlyKeys(value, PLAN_KEYS)
+    || value.version !== 1
+    || !FILE_INTEGRATION_CLIENTS.includes(value.clientId as FileIntegrationClientId)
+    || !PLAN_OPERATIONS.includes(value.operation as IntegrationPlanOperation)
+    || (typeof value.state !== "string" || !INTEGRATION_STATES.has(value.state))
+    || !PLAN_FOREIGN_EDITS.includes(value.foreignEdit as IntegrationPlanForeignEdit)
+    /*
+     * The version is matched as a version, not as `p1`. The server calls this
+     * token opaque and bumps its prefix whenever the inputs it binds change; a
+     * literal here made that bump a silent client-side rejection of every
+     * preview, which is a worse failure than the drift it was meant to catch.
+     */
+    || typeof value.fingerprint !== "string" || !/^p[0-9]+:(?:[0-9a-f]{32}|unbound)$/.test(value.fingerprint)
+    || typeof value.canApply !== "boolean" || typeof value.willChange !== "boolean"
+    || !Array.isArray(value.changes) || value.changes.length > PLAN_CHANGE_LIMIT
+    || (value.profileId !== undefined && (typeof value.profileId !== "number" || !Number.isSafeInteger(value.profileId) || value.profileId < 0))
+    || (value.profileId !== undefined && value.clientId !== "aside")
+    || (value.refusalReason !== undefined && (typeof value.refusalReason !== "string" || !INTEGRATION_REFUSAL_REASONS.has(value.refusalReason)))
+    // Descriptive fields of a superseded-store refusal; anywhere else they are a malformed plan.
+    || (value.supersededReason !== undefined && (value.refusalReason !== "superseded_store"
+      || typeof value.supersededReason !== "string" || !SUPERSEDED_REASONS.has(value.supersededReason)))
+    || (value.missingStoreDocument !== undefined && (value.supersededReason !== "missing-store"
+      || typeof value.missingStoreDocument !== "string" || !MISSING_STORE_DOCUMENT.test(value.missingStoreDocument)))) {
+    throw invalidPreviewResponse();
+  }
+  const changes: IntegrationPlanChange[] = [];
+  let previousOrder = -1;
+  let previousPath = "";
+  const seenByKind = new Map<IntegrationPlanChangeKind, Set<string>>();
+  for (const item of value.changes) {
+    if (!isRecord(item) || !hasOnlyKeys(item, PLAN_CHANGE_KEYS)
+      || !PLAN_CHANGE_KINDS.includes(item.kind as IntegrationPlanChangeKind)
+      || typeof item.path !== "string" || !isSafePlanPath(item.path)) throw invalidPreviewResponse();
+    const order = PLAN_CHANGE_KINDS.indexOf(item.kind as IntegrationPlanChangeKind);
+    if (order < previousOrder || (order === previousOrder && item.path <= previousPath)) throw invalidPreviewResponse();
+    const kind = item.kind as IntegrationPlanChangeKind;
+    const paths = seenByKind.get(kind) ?? new Set<string>();
+    if (paths.has(item.path)) throw invalidPreviewResponse();
+    paths.add(item.path);
+    seenByKind.set(kind, paths);
+    previousOrder = order;
+    previousPath = item.path;
+    changes.push({ kind, path: item.path });
+  }
+  if ((value.willChange && (!value.canApply || changes.length === 0))
+    || (!value.willChange && changes.length !== 0)
+    || ((value.fingerprint as string).endsWith(":unbound") && value.canApply)
+    || (value.canApply === (value.refusalReason !== undefined))) throw invalidPreviewResponse();
+  return {
+    version: 1,
+    clientId: value.clientId as FileIntegrationClientId,
+    operation: value.operation as IntegrationPlanOperation,
+    state: value.state as IntegrationState,
+    foreignEdit: value.foreignEdit as IntegrationPlanForeignEdit,
+    changes,
+    fingerprint: value.fingerprint,
+    canApply: value.canApply,
+    willChange: value.willChange,
+    ...(value.refusalReason === undefined ? {} : { refusalReason: value.refusalReason as IntegrationRefusalReason }),
+    ...(value.supersededReason === undefined ? {} : { supersededReason: value.supersededReason as IneffectiveWriteReason }),
+    ...(value.missingStoreDocument === undefined ? {} : { missingStoreDocument: value.missingStoreDocument as string }),
+    ...(value.profileId === undefined ? {} : { profileId: Number(value.profileId) }),
+  };
+}

package/src/cli/integration-preview.ts

@@ -0,0 +1,215 @@
+/** Preview and explicitly bound mutations use the existing management authority. */
+import type { IntegrationMutationPlan, IntegrationPlanOperation } from "../integrations/mutation-plan";
+import { redactSecretString, redactUserPath } from "../lib/redact";
+import {
+  CliUsageError, RuntimeApiError, printData, runtimeRequest, terminalSafeText,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+import {
+  clientIntegrationPath, validateAsideProfile, integrationOption, integrationFlag,
+  integrationFingerprint, integrationDroidDefaults,
+} from "./integration-input";
+import { decodeIntegrationPlan, FILE_INTEGRATION_CLIENTS, INTEGRATION_STATES, INTEGRATION_REFUSAL_REASONS } from "./integration-plan-dto";
+
+const USAGE = `Usage:
+  ocx integration client preview --client ID --operation <apply|overwrite|disable> [--profile N] [--json]
+  ocx integration client restore --op ID --preview [--client aside --profile N] [--confirm-drift] [--json]
+  ocx integration client <enable|disable> --client ID [--profile N] [--overwrite-conflict] [--plan-fingerprint TOKEN] [--json]
+  ocx integration client restore --op ID [--client aside --profile N] [--confirm-drift] [--plan-fingerprint TOKEN] [--json]
+  Droid apply/overwrite: [--reasoning-default MODEL=EFFORT ... | --clear-reasoning-defaults]`;
+
+type Intent = {
+  preview: boolean; json: boolean; client?: string; profile?: string;
+  operation: IntegrationPlanOperation; path: string; body: Record<string, unknown>;
+};
+
+function parseIntent(argv: string[]): Intent {
+  const args = [...argv];
+  const action = args.shift();
+  if (!["preview", "enable", "disable", "restore"].includes(action ?? "")) throw new CliUsageError("Expected preview, enable, disable or restore", USAGE);
+  const json = integrationFlag(args, "--json");
+  const client = integrationOption(args, "--client");
+  const profile = integrationOption(args, "--profile");
+  validateAsideProfile(profile, client, USAGE);
+  if (client !== undefined && !FILE_INTEGRATION_CLIENTS.some(id => id === client)) throw new CliUsageError("Unknown integration client", USAGE);
+  const previewFlag = integrationFlag(args, "--preview");
+  const token = integrationFingerprint(args);
+  const defaults = integrationDroidDefaults(args);
+  const overwrite = integrationFlag(args, "--overwrite-conflict");
+  const confirmDrift = integrationFlag(args, "--confirm-drift");
+  const op = integrationOption(args, "--op");
+  const opAlias = integrationOption(args, "--op-id");
+  const selectedOperation = integrationOption(args, "--operation");
+  if (args.length) throw new CliUsageError("Unexpected integration argument(s)", USAGE);
+  if (op !== undefined && opAlias !== undefined) throw new CliUsageError("Use only one of --op and --op-id", USAGE);
+  const opId = op ?? opAlias;
+  if (previewFlag && action !== "restore") throw new CliUsageError("--preview applies only to restore; use the preview command", USAGE);
+  const preview = action === "preview" || previewFlag;
+  if (preview && token !== undefined) throw new CliUsageError("Preview cannot be combined with --plan-fingerprint", USAGE);
+  if (selectedOperation !== undefined && action !== "preview") throw new CliUsageError("--operation applies only to preview", USAGE);
+  if (overwrite && action !== "enable") throw new CliUsageError("--overwrite-conflict applies only to enable", USAGE);
+  if ((opId !== undefined || confirmDrift) && action !== "restore") throw new CliUsageError("--op and --confirm-drift apply only to restore", USAGE);
+  let operation: IntegrationPlanOperation;
+  if (action === "preview") {
+    if (selectedOperation !== "apply" && selectedOperation !== "overwrite" && selectedOperation !== "disable") throw new CliUsageError("--operation must be apply, overwrite or disable", USAGE);
+    operation = selectedOperation;
+  } else operation = action === "restore" ? "restore" : action === "disable" ? "disable" : overwrite ? "overwrite" : "apply";
+  if (action !== "restore" && !client) throw new CliUsageError("--client is required", USAGE);
+  if (action === "restore" && (!opId?.trim() || (client !== undefined && (client !== "aside" || profile === undefined)))) {
+    throw new CliUsageError("restore requires --op; its optional target is --client aside --profile N", USAGE);
+  }
+  if (client === "aside" && profile === undefined) throw new CliUsageError("A preview or bound operation requires one Aside --profile", USAGE);
+  if (defaults !== undefined && (client !== "droid" || !["apply", "overwrite"].includes(operation))) throw new CliUsageError("Reasoning defaults apply only to Droid apply or overwrite", USAGE);
+  let path: string;
+  let body: Record<string, unknown>;
+  if (action === "restore") {
+    path = profile === undefined ? `/api/client-integrations/restore${preview ? "/preview" : ""}`
+      : `${clientIntegrationPath("aside", profile)}/${preview ? "preview" : "restore"}`;
+    body = { opId, confirmDrift, ...(preview && profile !== undefined ? { operation } : {}) };
+  } else if (preview) {
+    path = client === "aside" ? `${clientIntegrationPath(client, profile)}/preview` : "/api/client-integrations/preview";
+    body = { ...(client === "aside" ? {} : { clientId: client }), operation };
+  } else {
+    path = clientIntegrationPath(client!, profile);
+    body = { enabled: action === "enable", ...(overwrite ? { overwriteConflict: true } : {}) };
+  }
+  if (defaults !== undefined) body.droidReasoningDefaults = defaults;
+  if (token !== undefined) { body.operation = operation; body.planFingerprint = token; }
+  return { preview, json, client, profile, operation, path, body };
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function checkIdentity(value: { clientId: string; profileId?: number }, intent: Intent): void {
+  if ((intent.client !== undefined && value.clientId !== intent.client)
+    || (intent.client === undefined && value.clientId === "aside")
+    || (intent.profile === undefined ? value.profileId !== undefined : value.profileId !== Number(intent.profile))) {
+    throw new Error("Invalid integration target response");
+  }
+}
+
+interface Receipt {
+  ok: boolean; clientId: string; state: string; operation: IntegrationPlanOperation;
+  profileId?: number; changed?: boolean; opId?: string; reason?: string; residual?: boolean; snapshotPath?: string;
+}
+
+function recoveryFields(value: Record<string, unknown>): { residual?: boolean; snapshotPath?: string } {
+  if ((value.residual !== undefined && typeof value.residual !== "boolean")
+    || (value.snapshotPath !== undefined && (typeof value.snapshotPath !== "string" || value.snapshotPath.length > 32768))) {
+    throw new Error("Invalid integration recovery response");
+  }
+  return {
+    ...(typeof value.residual === "boolean" ? { residual: value.residual } : {}),
+    ...(typeof value.snapshotPath === "string" ? { snapshotPath: redactSecretString(redactUserPath(value.snapshotPath)) } : {}),
+  };
+}
+
+function mutationReceipt(value: unknown, intent: Intent): Receipt {
+  if (!record(value) || typeof value.ok !== "boolean" || !FILE_INTEGRATION_CLIENTS.some(id => id === value.clientId)
+    || typeof value.state !== "string" || !INTEGRATION_STATES.has(value.state)
+    || (value.ok ? typeof value.changed !== "boolean" : typeof value.reason !== "string" || !INTEGRATION_REFUSAL_REASONS.has(value.reason))
+    || (value.profileId !== undefined && (typeof value.profileId !== "number" || !Number.isSafeInteger(value.profileId) || value.profileId < 0))
+    || (value.opId !== undefined && (typeof value.opId !== "string" || !/^[A-Za-z0-9_-]{1,256}$/.test(value.opId)))) {
+    throw new Error("Invalid integration mutation response");
+  }
+  const result: Receipt = {
+    ok: value.ok, clientId: value.clientId as string, state: value.state, operation: intent.operation,
+    ...(typeof value.profileId === "number" ? { profileId: value.profileId } : {}),
+    ...(typeof value.changed === "boolean" ? { changed: value.changed } : {}),
+    ...(typeof value.opId === "string" ? { opId: value.opId } : {}),
+    ...(typeof value.reason === "string" && INTEGRATION_REFUSAL_REASONS.has(value.reason) ? { reason: value.reason } : {}),
+    ...recoveryFields(value),
+  };
+  checkIdentity(result, intent);
+  return result;
+}
+
+function recoveryLines(value: { residual?: boolean; snapshotPath?: string }): string[] {
+  return [
+    ...(value.residual === true ? ["Automatic recovery did not finish; inspect the client configuration before retrying."] : []),
+    ...(value.snapshotPath ? [`Backup (redacted path): ${value.snapshotPath}`] : []),
+  ];
+}
+
+const REFUSAL_GUIDANCE: Readonly<Record<string, string>> = {
+  not_installed: "Install or locate the client before applying its integration.",
+  conflict: "Inspect the conflicting client configuration; review an overwrite preview before choosing --overwrite-conflict.",
+  unsafe: "Inspect the client configuration and resolve its unsafe path or contents before retrying.",
+  non_loopback: "This integration requires a loopback proxy listener.",
+  superseded_store: "Inspect integration status for the configuration store the client now reads.",
+  drift_requires_confirm: "The client file changed. Review restore --preview --confirm-drift before explicitly confirming drift.",
+  snapshot_expired: "The operation backup is no longer available; inspect integration history for another recovery point.",
+  write_failed: "Inspect the client configuration and any recovery backup before retrying.",
+};
+
+/** A missing store is fixed by hand, so its refusal says with what; the path is on the status row. */
+function refusalGuidance(plan: IntegrationMutationPlan): string {
+  if (plan.supersededReason === "missing-store" && plan.missingStoreDocument !== undefined) {
+    return `The provider store this client reads is missing. Create it containing \`${plan.missingStoreDocument}\` `
+      + `(its path is supersededBy in \`ocx integration client status --client ${plan.clientId}\`), then apply again.`;
+  }
+  return REFUSAL_GUIDANCE[plan.refusalReason!]!;
+}
+
+function reportError(error: unknown): number {
+  if (error instanceof CliUsageError) {
+    console.error(`Error: ${error.message}`);
+    console.error(USAGE);
+    return 2;
+  }
+  if (error instanceof RuntimeApiError) {
+    const body = record(error.body) ? error.body : {};
+    const stale = body.code === "integration_preview_stale";
+    const unavailable = body.code === "integration_preview_unavailable";
+    // Local discovery found no proxy: nothing was sent, so name the start command instead of
+    // the generic management-host guidance. Server 503s always carry a body; this one has none.
+    const stopped = error.status === 503 && error.body === null && error.message.startsWith("Proxy is not running");
+    console.error(stale ? "Error: Integration preview is stale. Run the explicit preview again and review its changes before retrying."
+      : unavailable ? "Error: Integration preview is unavailable. Load the model catalog, then run the preview again."
+      : stopped ? "Error: Proxy is not running. Start the intended proxy with: ocx start. No request was sent."
+      : error.status === 404 ? "Error: Integration operation or profile was not found. Inspect integration history and the selected profile."
+      : error.status === 409 ? "Error: Integration change was refused. Inspect integration status and preview before retrying."
+      : error.status === 503 ? "Error: Management API is unavailable. Check the proxy and run this command on its management host."
+      : "Error: Integration request failed. Inspect integration status before retrying.");
+    if (!stale) {
+      if (typeof body.reason === "string" && INTEGRATION_REFUSAL_REASONS.has(body.reason)) {
+        console.error(`Refused (${body.reason}): ${REFUSAL_GUIDANCE[body.reason]}`);
+      }
+      // Recovery is separate from arbitrary server messages and nested replacement plans.
+      try { for (const line of recoveryLines(recoveryFields(body))) console.error(terminalSafeText(line)); } catch { /* Invalid recovery data is not printable. */ }
+    }
+    return error.status === 404 ? 4 : error.status === 409 ? 5 : 1;
+  }
+  console.error("Error: Invalid integration response. Check the proxy version and inspect integration status.");
+  return 1;
+}
+
+export async function handleIntegrationPreviewCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  try {
+    const intent = parseIntent(argv);
+    const result = await runtimeRequest(intent.path, {
+      method: intent.preview || intent.operation === "restore" ? "POST" : "PUT",
+      redirect: "error", body: JSON.stringify(intent.body),
+    }, deps);
+    if (intent.preview) {
+      const plan = decodeIntegrationPlan(result);
+      checkIdentity(plan, intent);
+      if (plan.operation !== intent.operation) throw new Error("Invalid integration operation response");
+      printData(plan, intent.json, [
+        `${plan.clientId}${plan.profileId === undefined ? "" : `:${plan.profileId}`} ${plan.operation}: ${!plan.canApply ? `refused (${plan.refusalReason})` : !plan.willChange ? "no changes needed" : "ready for review"}`,
+        ...plan.changes.map(change => `  ${change.kind} ${change.path}`),
+        ...(plan.canApply ? [`Fingerprint: ${plan.fingerprint}`] : [refusalGuidance(plan)]),
+      ]);
+      return 0;
+    }
+    const receipt = mutationReceipt(result, intent);
+    printData(receipt, intent.json, [
+      `${receipt.clientId}${receipt.profileId === undefined ? "" : `:${receipt.profileId}`} ${receipt.operation}: ${!receipt.ok ? `refused (${receipt.reason})` : receipt.changed ? "updated" : "no changes needed"}.`,
+      ...(receipt.opId ? [`Operation: ${receipt.opId}`] : []),
+      ...(receipt.reason ? [REFUSAL_GUIDANCE[receipt.reason]!] : []), ...recoveryLines(receipt),
+    ]);
+    return receipt.ok ? 0 : 1;
+  } catch (error) { return reportError(error); }
+}

package/src/cli/integrations.ts

@@ -12,6 +12,7 @@ import {
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import { clientIntegrationPath, validateAsideProfile } from "./integration-input";
 
 const CLAUDE_USAGE = `Usage:
   ocx claude config [status] [--json]
@@ -34,22 +35,14 @@ const CLIENT_USAGE = `Usage:
   ocx integration client <enable|disable> --client <id> [--profile <id>] [--overwrite-conflict] [--json]
   ocx integration client history [--client <id>] [--profile <id>] [--json]
   ocx integration client restore --op <opId> [--client aside --profile <id>] [--confirm-drift] [--json]
+  ocx integration client preview --client <id> --operation <apply|overwrite|disable> [--profile <id>] [--json]
+  ocx integration client restore --op <opId> --preview [--client aside --profile <id>] [--confirm-drift] [--json]
+  ocx integration client history remove --op <opId> --yes [--client aside] [--profile <id>] [--json]
+  ocx integration client sync --client aside [--json]
+  enable/disable/restore accept --plan-fingerprint <token>; bound Aside operations require one profile.
+  Droid enable/preview accept repeatable --reasoning-default <model=effort> or --clear-reasoning-defaults.
   --profile selects one Aside account-backed profile; omitted Aside toggles affect all profiles.`;
 
-function validateAsideProfile(profile: string | undefined, client: string | undefined): void {
-  if (profile === undefined) return;
-  if (client !== "aside") throw new CliUsageError("--profile requires --client aside", CLIENT_USAGE);
-  if (!/^(0|[1-9][0-9]*)$/.test(profile) || !Number.isSafeInteger(Number(profile))) {
-    throw new CliUsageError("--profile must be a nonnegative integer account ID", CLIENT_USAGE);
-  }
-
-}
-
-function clientIntegrationPath(client: string, profile?: string): string {
-  const base = `/api/client-integrations/${encodeURIComponent(client)}`;
-  return client === "aside" ? `${base}/profiles${profile === undefined ? "" : `/${encodeURIComponent(profile)}`}` : base;
-}
-
 function parseMap(raw: string): Record<string, string> {
   if (raw === "-") return {};
   const map: Record<string, string> = {};
@@ -223,6 +216,19 @@ export async function handleClientIntegrationCommand(
   argv: string[],
   deps: RuntimeApiDeps = {},
 ): Promise<number> {
+  if ((argv[0] === "history" || argv[0] === "journal") && argv[1] === "remove") {
+    const { handleIntegrationJournalRemove } = await import("./integration-journal");
+    return handleIntegrationJournalRemove(argv.slice(2), deps);
+  }
+  if (argv[0] === "sync") {
+    const { handleIntegrationAsideSync } = await import("./integration-aside-sync");
+    return handleIntegrationAsideSync(argv.slice(1), deps);
+  }
+  if (argv[0] === "preview" || argv.some(arg => ["--preview", "--plan-fingerprint", "--reasoning-default", "--clear-reasoning-defaults"]
+    .some(flag => arg === flag || arg.startsWith(`${flag}=`)))) {
+    const { handleIntegrationPreviewCommand } = await import("./integration-preview");
+    return handleIntegrationPreviewCommand(argv, deps);
+  }
   return runCliAction(async () => {
     const args = [...argv];
     const action = (args.shift() ?? "status").toLowerCase();
@@ -231,7 +237,7 @@ export async function handleClientIntegrationCommand(
 
     if (action === "status" || action === "show" || action === "list") {
       const client = takeOption(args, "--client");
-      validateAsideProfile(profile, client);
+      validateAsideProfile(profile, client, CLIENT_USAGE);
       rejectArgs(args, CLIENT_USAGE);
       const path = client
         ? clientIntegrationPath(client, profile)
@@ -257,7 +263,7 @@ export async function handleClientIntegrationCommand(
 
     if (action === "history" || action === "journal") {
       const client = takeOption(args, "--client");
-      validateAsideProfile(profile, client);
+      validateAsideProfile(profile, client, CLIENT_USAGE);
       rejectArgs(args, CLIENT_USAGE);
       const path = client === "aside" ? `${clientIntegrationPath(client, profile)}/journal`
         : `/api/client-integrations/journal${client ? `?client=${encodeURIComponent(client)}` : ""}`;
@@ -279,7 +285,7 @@ export async function handleClientIntegrationCommand(
       const opId = takeOption(args, "--op") ?? takeOption(args, "--op-id");
       const confirmDrift = takeFlag(args, "--confirm-drift");
       const client = takeOption(args, "--client");
-      validateAsideProfile(profile, client);
+      validateAsideProfile(profile, client, CLIENT_USAGE);
       if (client !== undefined && profile === undefined) throw new CliUsageError("restore --client requires --profile", CLIENT_USAGE);
       rejectArgs(args, CLIENT_USAGE);
       if (!opId) throw new CliUsageError("--op <opId> is required", CLIENT_USAGE);
@@ -295,7 +301,7 @@ export async function handleClientIntegrationCommand(
       throw new CliUsageError(`unknown client integration command ${action}`, CLIENT_USAGE);
     }
     const client = takeOption(args, "--client");
-    validateAsideProfile(profile, client);
+    validateAsideProfile(profile, client, CLIENT_USAGE);
     /*
      * The conflict escape hatch, spelled the way `restore --confirm-drift` is: the
      * refusal is the default and the waiver has to be typed.

package/src/cli/json-input.ts

@@ -0,0 +1,134 @@
+/** Bounded JSON ingress for management commands; domain validation stays with the caller. */
+import { constants } from "node:fs";
+import { open, stat, type FileHandle } from "node:fs/promises";
+import { MANAGEMENT_JSON_BODY_MAX_BYTES } from "../server/management/body";
+import { CliUsageError, readSecretBytes, type CliStdin, type RuntimeApiDeps } from "./runtime-api";
+
+const INPUT_TIMEOUT_MS = 30_000;
+const INPUT_LABEL = "JSON input";
+const TOO_LARGE = "JSON input exceeds the 4 MiB management body limit";
+const TIMED_OUT = "Timed out reading JSON input";
+
+// Only errors created here may cross the boundary. Files, streams and parsers can
+// throw arbitrary objects, including CliUsageError instances containing secrets.
+class JsonInputFailure extends CliUsageError {}
+
+function inputTimeout(deps: RuntimeApiDeps): number {
+  const value = deps.stdinTimeoutMs ?? INPUT_TIMEOUT_MS;
+  if (!Number.isFinite(value) || value <= 0 || value > INPUT_TIMEOUT_MS) {
+    throw new JsonInputFailure("JSON input deadline must be within 30 seconds");
+  }
+  return value;
+}
+
+async function boundedStdin(input: CliStdin, timeoutMs: number): Promise<Uint8Array> {
+  if (input.isTTY) throw new JsonInputFailure("JSON input requires a file or piped stdin");
+  if ("readableEncoding" in input && input.readableEncoding != null) {
+    throw new JsonInputFailure("JSON input requires byte-oriented stdin");
+  }
+  try {
+    return await readSecretBytes({ stdinImpl: input, stdinTimeoutMs: timeoutMs }, INPUT_LABEL, MANAGEMENT_JSON_BODY_MAX_BYTES);
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      if (error.message === `${INPUT_LABEL} exceeds ${MANAGEMENT_JSON_BODY_MAX_BYTES} bytes`) throw new JsonInputFailure(TOO_LARGE);
+      if (error.message === `timed out waiting for ${INPUT_LABEL} on stdin`) throw new JsonInputFailure(TIMED_OUT);
+      if (error.message === `${INPUT_LABEL} input was empty`) throw new JsonInputFailure("JSON input was empty");
+    }
+    throw new JsonInputFailure("Unable to read JSON input");
+  } finally {
+    // readSecretBytes owns its listeners/timer; it does not stop a still-flowing
+    // stream after size, error or timeout refusal. We never close caller stdin.
+    input.pause();
+  }
+}
+
+async function beforeDeadline<T>(operation: Promise<T>, deadline: number, late?: (value: T) => Promise<void>): Promise<T> {
+  let expired = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => { expired = true; reject(new JsonInputFailure(TIMED_OUT)); }, Math.max(0, deadline - performance.now()));
+  });
+  try {
+    return await Promise.race([operation.then(async value => {
+      // An open can finish after the deadline: its descriptor is still ours.
+      if (expired) {
+        await late?.(value);
+        throw new JsonInputFailure(TIMED_OUT);
+      }
+      return value;
+    }), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fileBytes(path: string, timeoutMs: number): Promise<Uint8Array> {
+  const deadline = performance.now() + timeoutMs;
+  let handle: FileHandle | undefined;
+  let stream: ReturnType<FileHandle["createReadStream"]> | undefined;
+  let bytes: Uint8Array | undefined;
+  try {
+    // Preflight avoids opening known devices/FIFOs. O_NONBLOCK plus fstat also
+    // refuses a FIFO substituted between the path check and the actual open.
+    const pathStat = await beforeDeadline(stat(path), deadline);
+    if (!pathStat.isFile()) throw new JsonInputFailure("JSON input must be a regular file");
+    if (pathStat.size > MANAGEMENT_JSON_BODY_MAX_BYTES) throw new JsonInputFailure(TOO_LARGE);
+    handle = await beforeDeadline(open(path, constants.O_RDONLY | constants.O_NONBLOCK), deadline, file => file.close());
+    const openedStat = await beforeDeadline(handle.stat(), deadline);
+    if (!openedStat.isFile()) throw new JsonInputFailure("JSON input must be a regular file");
+    if (openedStat.size > MANAGEMENT_JSON_BODY_MAX_BYTES) throw new JsonInputFailure(TOO_LARGE);
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) throw new JsonInputFailure(TIMED_OUT);
+    stream = handle.createReadStream({ autoClose: false });
+    // The stream can report a pending I/O error while teardown destroys it.
+    // readSecretBytes removes only its own error listener; retain this one
+    // through close to avoid an unhandled error after timeout/limit refusal.
+    const ignoreTeardownError = () => {};
+    stream.on("error", ignoreTeardownError);
+    stream.once("close", () => stream?.removeListener("error", ignoreTeardownError));
+    bytes = await boundedStdin(stream, remaining);
+    return bytes;
+  } finally {
+    stream?.destroy();
+    try { await handle?.close(); }
+    catch {
+      bytes?.fill(0);
+      throw new JsonInputFailure("Unable to close JSON input file");
+    }
+  }
+}
+
+/** Explicit '-' is the only stdin selector. The label is never treated as safe output. */
+export async function readJsonInput(pathOrDash: string, deps: RuntimeApiDeps = {}, _label = INPUT_LABEL): Promise<unknown> {
+  let bytes: Uint8Array | undefined;
+  try {
+    if (!pathOrDash) throw new JsonInputFailure("JSON input requires an explicit file or '-'");
+    const timeoutMs = inputTimeout(deps);
+    bytes = pathOrDash === "-"
+      ? await boundedStdin(deps.stdinImpl ?? process.stdin, timeoutMs)
+      : await fileBytes(pathOrDash, timeoutMs);
+    let text: string;
+    try { text = new TextDecoder("utf-8", { fatal: true }).decode(bytes); }
+    catch { throw new JsonInputFailure("JSON input must be valid UTF-8"); }
+    if (!text.trim()) throw new JsonInputFailure("JSON input was empty");
+    try { return JSON.parse(text) as unknown; }
+    catch { throw new JsonInputFailure("JSON input must contain valid JSON"); }
+  } catch (error) {
+    if (error instanceof JsonInputFailure) throw error;
+    throw new JsonInputFailure("Unable to read JSON input");
+  } finally {
+    // Decoded strings and parsed values are immutable/consumer-owned; only
+    // mutable byte buffers can be erased, without promising string erasure.
+    bytes?.fill(0);
+  }
+}
+
+/** Serialize once, bounding the complete UTF-8 wire body, including envelope keys. */
+export function serializeManagementJson(value: unknown): string {
+  let serialized: string | undefined;
+  try { serialized = JSON.stringify(value); }
+  catch { throw new JsonInputFailure("Management body must be JSON serializable"); }
+  if (serialized === undefined) throw new JsonInputFailure("Management body must be JSON serializable");
+  if (Buffer.byteLength(serialized, "utf8") > MANAGEMENT_JSON_BODY_MAX_BYTES) throw new JsonInputFailure(TOO_LARGE);
+  return serialized;
+}