@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/index.ts

@@ -8,6 +8,9 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { currentServingCommand, deferServiceChildToNewerRuntime, markDelegatedServiceReady, recordServingRuntime } from "../config/serving-runtimes";
 import { packageVersion } from "../lib/package-version";
+import { admitUpdateRestartChild } from "./update-restart-child";
+import { UpdateRestartRequired } from "./update-restart-candidate";
+import { describeUpdateRestartFailure, restartFromCurrentInstallation } from "./update-restart";
 import { findGuiDist } from "../server/gui-static";
 import { inspectGuiBundleFreshness, staleGuiBundleLines } from "../server/gui-freshness";
 
@@ -85,9 +88,9 @@ import {
   runProxyRestart,
   runTrayProxyStart,
   type ProxyRestartLive,
-  type ProxyRestartResult,
   type ProxyRestartStartOutcome,
 } from "./tray-proxy";
+import { reportRestartFailure } from "./restart-failure";
 import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
 import { SpendLedgerOwnerError } from "../lib/spend-ledger-owner";
@@ -142,6 +145,7 @@ import { honorSiblingMarker, markSiblingStart, siblingOfLivePort, siblingRuntime
 import { consumeSiblingHandoff } from "../codex/sibling-handoff";
 import {
   reconcileClientStartupBeforeReady,
+  syncCodexBeforeCatalogObservation,
   syncClaudeAgentDefsAtProxyStartup,
 } from "./claude-agent-startup-sync";
 import {
@@ -200,6 +204,7 @@ async function refreshOwnedRaycastCatalog(
   }
 }
 
+const updateRestartChild = admitUpdateRestartChild(process.argv.slice(2));
 initializeNodeLauncherContext();
 // The compiled executable is also the capture-only MCP server's launcher.
 // Handle this private entrypoint before CLI preflight or command dispatch.
@@ -371,6 +376,7 @@ async function findProxyOwnerBeforeJournalRecovery(
 }
 
 async function handleStart(options: { block?: boolean } = {}) {
+  updateRestartChild?.check();
   // A supervised service child defers to a foreign recorded owner before doing
   // anything else. 'ocx service start' refuses this activation path already, but
   // the process managers below it — the Windows boot wrapper's restart loop and
@@ -466,6 +472,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     },
   });
 
+  updateRestartChild?.check();
   const clientState = readClientConnectionState();
   if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
     throw new Error(`client startup refused: ${clientState.reason}`);
@@ -550,7 +557,17 @@ async function handleStart(options: { block?: boolean } = {}) {
         let server: ReturnType<typeof serverModule.startServer>;
         for (let attempt = 0; ; attempt++) {
           try {
+            if (updateRestartChild && siblingStart) throw new Error("update_restart_sibling_refused");
+            updateRestartChild?.check(port, loadConfig().hostname ?? "");
             server = serverModule.startServer(port, { localAttestationSecret, readinessGate });
+            if (updateRestartChild) {
+              try { updateRestartChild.check(port, server.hostname); }
+              catch (error) {
+                try { await server.stop(true); }
+                catch (rollback) { throw new StartOwnershipRollbackUncertainError([error, rollback]); }
+                throw error;
+              }
+            }
             break;
           } catch (err) {
             try { await serverModule.waitForFailedStartRollback(err); }
@@ -578,14 +595,14 @@ async function handleStart(options: { block?: boolean } = {}) {
         }
         return { server, serverModule, port, readinessGate, localAttestationSecret, config };
       },
-      writePid: () => writePid(process.pid),
-      writeRuntime: bound => writeRuntimePort({
+      writePid: () => { updateRestartChild?.check(); writePid(process.pid); },
+      writeRuntime: bound => { updateRestartChild?.check(bound.port, bound.config.hostname ?? ""); writeRuntimePort({
         pid: process.pid,
         port: bound.port,
         hostname: bound.config.hostname,
         attestationSecret: bound.localAttestationSecret,
         ...siblingRuntimeField(),
-      }),
+      }); updateRestartChild?.complete(); },
       stopBound: bound => bound.server.stop(true),
       removeRuntime: () => removeRuntimePortIfPidIs(process.pid),
       removePid: () => removePidIfValueIs(process.pid),
@@ -615,12 +632,14 @@ async function handleStart(options: { block?: boolean } = {}) {
   // Loopback-only (legacy mode still forward-tags) and respects syncResumeHistory opt-out.
   let historyGuardian: ReturnType<typeof startHistoryMigrationGuardian> | undefined;
   let routingHealer: { stop(): void } | undefined; // routing-healer.ts; stopped first in syncCleanup
+  let catalogHealer: { stop(): void } | undefined;
 
   let cleaned = false;
   let cleanupSucceeded = true;
   const syncCleanup = () => {
     if (cleaned) return cleanupSucceeded;
     cleaned = true;
+    try { catalogHealer?.stop(); } catch { /* best-effort */ }
     try { routingHealer?.stop(); } catch { /* best-effort */ }
     try { guardian.stop(); } catch { /* best-effort */ }
     try { historyGuardian?.stop(); } catch { /* best-effort */ }
@@ -703,9 +722,14 @@ async function handleStart(options: { block?: boolean } = {}) {
   // deferred until the best-effort Claude roster and Desktop registry settle. This
   // keeps /readyz closed across startup initialization without making an optional
   // Claude integration failure prevent the proxy from starting.
+  const catalogHealerModule = siblingStart ? null : await import("../codex/catalog-self-heal");
   const startupSync = await reconcileClientStartupBeforeReady(
     readinessGate,
-    gate => syncCodexOnStartIfEnabled(port, config, undefined, gate),
+    gate => syncCodexBeforeCatalogObservation(gate,
+      forwarding => syncCodexOnStartIfEnabled(port, config, undefined, forwarding),
+      () => {
+        if (catalogHealerModule && !siblingStart && !cleaned) catalogHealer = catalogHealerModule.startCodexCatalogSelfHeal({ port });
+      }),
     () => systemEnv.injected
       ? Promise.resolve(null)
       : syncClaudeAgentDefsAtProxyStartup(config, port),
@@ -895,28 +919,6 @@ const PROXY_RESTART_OBSERVE_MS = MEMORY_DRAIN_RESTART_MS + REPLACEMENT_READY_TIM
 
 /** Reserve confirmation time within the shared restart deadline. */
 const RESTART_REOBSERVE_RESERVE_MS = 10_000;
-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.");
-  } 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("❌ The running proxy reports a different OpenCodex version than this CLI; restarting in place would respawn the old installation.");
-      console.error("   Run `ocx stop` and then `ocx start` from this installation instead.");
-    } else if (code === "restart_package_tree_unsettled") {
-      console.error("❌ The proxy's package files are still being replaced; wait for the install to finish, then run `ocx restart` again.");
-    } else {
-      console.error("❌ Proxy restart request could not be confirmed; no fallback stop/start was attempted.");
-    }
-  } else if (result.phase === "replacement") {
-    console.error("❌ Proxy restart was accepted, but no identity-verified replacement became healthy in time.");
-  } else {
-    console.error("❌ Proxy was not running and the fallback start did not become healthy.");
-  }
-}
 async function handleProxyRestart(
   startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>,
 ): Promise<boolean> {
@@ -939,6 +941,15 @@ async function handleProxyRestart(
       findLive: () => findLiveProxy({ deadlineAt: end, attempts: 2, acceptPackageTreeFenced: true }), expired: () => Date.now() >= end,
     })),
   });
+  if (!result.ok && result.phase === "request" && result.error instanceof UpdateRestartRequired) {
+    const candidate = result.error.candidate();
+    console.log(`🔄 Running proxy ${candidate.target.version} is older than this CLI (${candidate.cliVersion}); restarting it from the current installation...`);
+    const update = await restartFromCurrentInstallation(candidate, deadlineAt, detachedStartEnvironment());
+    if (update.ok) console.log(`✅ Proxy updated to ${update.live.version} (PID ${update.live.pid}).`);
+    else console.error(`❌ ${describeUpdateRestartFailure(update.code, update.reason)} (${update.code})`);
+    process.exitCode = update.ok ? 0 : 1;
+    return update.ok;
+  }
   if (!result.ok) reportRestartFailure(result);
   process.exitCode = result.ok ? 0 : 1;
   return result.ok;

package/src/cli/injection-follow.ts

@@ -0,0 +1,35 @@
+import { printData } from "./runtime-api";
+import { ObservationError, withObserveStream, type ObserveStreamDeps } from "./observe-stream";
+import type { DebugLogEntry } from "../lib/debug-log-buffer";
+
+function parseRows(body: unknown, after: number, limit: number): DebugLogEntry[] {
+  if (!Array.isArray(body) || body.length > limit) throw new ObservationError("Invalid injection log window. Restart follow after checking the runtime.");
+  let previous = after;
+  return body.map(value => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new ObservationError("Invalid injection log row.");
+    const { seq, at, line } = value as Record<string, unknown>;
+    if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq <= previous || seq <= 0
+      || typeof at !== "number" || !Number.isFinite(at) || typeof line !== "string") {
+      throw new ObservationError("Invalid injection log order or row. Restart follow after checking the runtime.");
+    }
+    previous = seq;
+    return { seq, at, line };
+  });
+}
+
+export async function followInjection(limit: number, jsonl: boolean, deps: ObserveStreamDeps): Promise<number> {
+  return withObserveStream(deps, async stream => {
+    let after = 0;
+    while (true) {
+      const query = new URLSearchParams({ limit: String(limit), after: String(after) });
+      const rows = parseRows(await stream.get("/api/debug/injection-logs", query), after, limit);
+      for (const row of rows) {
+        stream.signal.throwIfAborted();
+        if (jsonl) console.log(JSON.stringify(row));
+        else printData(row, false, [`${row.seq}  ${row.at}  ${row.line}`]);
+        after = row.seq;
+      }
+      await stream.wait();
+    }
+  });
+}

package/src/cli/inspect.ts

@@ -35,6 +35,7 @@ const USAGE = `Usage:
   ocx inspect windows-tray [--json]
   ocx integration native [list] [--json]
   ocx integration native <claude|claude-desktop|codex|grok> <on|off> [--json]
+  ocx integration native cursor [status|local-installer] [--json]
   ocx agent request-user-input [on|off] [--json]`;
 
 /** A read that takes no arguments beyond `--json`. */
@@ -220,6 +221,10 @@ export async function handleInspectCommand(argv: string[], deps: RuntimeApiDeps
 }
 
 export async function handleIntegrationCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  if (argv[0] === "native" && argv[1] === "cursor") {
+    const { handleCursorIntegrationCommand } = await import("./integration-cursor");
+    return handleCursorIntegrationCommand(argv.slice(2), deps);
+  }
   return runCliAction(async () => {
     const [sub, ...rest] = argv;
     if (sub === "native" || sub === undefined) await nativeIntegration(sub === undefined ? [] : rest, deps);

package/src/cli/integration-aside-sync.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { redactUserPath } from "../lib/redact";
+import type { RefusalReason } from "../integrations/mutation-plan";
+import { refreshAsideProfilesThroughServer } from "./aside-profiles";
+import { runCatalogAction } from "./catalog-command-result";
+import { CliUsageError, RuntimeApiError, printData, takeFlag, takeOption, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = "Usage: ocx integration client sync --client aside [--json]";
+const refusalText = {
+  not_installed: "Aside is not installed for this profile.",
+  conflict: "Profile configuration conflicts with the managed integration.",
+  unsafe: "Profile configuration cannot be changed safely.",
+  non_loopback: "The integration requires a loopback destination.",
+  superseded_store: "The client now uses a different configuration store.",
+  drift_requires_confirm: "Profile configuration changed; inspect it before an explicit restore.",
+  snapshot_expired: "The recovery snapshot has expired.",
+  write_failed: "The profile write failed. Inspect its state before retrying.",
+} satisfies Record<RefusalReason, string>;
+const profileId = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const text = z.string().max(32768);
+const resultSchema = z.discriminatedUnion("ok", [
+  z.object({ client: z.literal("aside"), profileId, ok: z.literal(true), changed: z.boolean(),
+    reason: text.optional().transform(value => value === undefined ? undefined
+      : value === "managed block is absent; refresh did not reconnect it"
+        ? "Managed block remains absent; synchronization did not reconnect it."
+        : "Profile synchronization returned a notice; inspect integration status."),
+  }),
+  z.object({ client: z.literal("aside"), profileId, ok: z.literal(false),
+    state: z.enum(["absent", "current", "stale", "conflict", "unsafe"]),
+    refusalReason: z.enum(["not_installed", "conflict", "unsafe", "non_loopback", "superseded_store", "drift_requires_confirm", "snapshot_expired", "write_failed"]),
+    reason: text.optional(), residual: z.boolean().optional(),
+    snapshotPath: text.min(1).transform(redactUserPath).optional(),
+  }).transform(row => ({ ...row, reason: refusalText[row.refusalReason] })),
+]);
+const resultsSchema = z.array(resultSchema).refine(rows => new Set(rows.map(row => row.profileId)).size === rows.length);
+
+/** Narrow owner seam: production always uses the established attested exchange. */
+export interface AsideSyncCliDeps extends RuntimeApiDeps {
+  refreshAsideProfilesImpl?: typeof refreshAsideProfilesThroughServer;
+}
+
+/** argv begins after sync. No local writer or base-URL pre-resolution. */
+export function handleIntegrationAsideSync(argv: string[], deps: AsideSyncCliDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const wantsJson = takeFlag(args, "--json");
+    const client = takeOption(args, "--client");
+    if (args.length || client !== "aside") throw new CliUsageError("Sync requires --client aside and accepts only --json", USAGE);
+    // Sync is an aggregate operation: every owner/transport failure is exit 1,
+    // not the record-not-found/conflict exits used by addressed journal writes.
+    const outcomes = await (deps.refreshAsideProfilesImpl ?? refreshAsideProfilesThroughServer)(deps)
+      .catch(error => {
+        if (error instanceof RuntimeApiError && error.code === "proxy_not_running") throw error;
+        throw new Error("Aside synchronization did not complete");
+      });
+    const parsed = resultsSchema.safeParse(outcomes);
+    if (!parsed.success) throw new Error("Invalid Aside synchronization outcome");
+    const results = parsed.data;
+    const lines = results.length === 0 ? ["No eligible Aside profiles to synchronize. Check integration status and profile sync preferences."]
+      : results.flatMap(row => [
+        `Aside profile ${row.profileId}: ${row.ok ? row.changed ? "updated" : "unchanged" : "failed"}.`,
+        ...(row.reason ? [row.reason] : []),
+        ...(!row.ok && row.residual ? ["Recovery is incomplete; inspect the profile before retrying."] : []),
+        ...(!row.ok && row.snapshotPath ? [`Backup (redacted path): ${row.snapshotPath}`] : []),
+      ]);
+    printData({ results }, wantsJson, lines);
+    return results.some(row => !row.ok) ? 1 : 0;
+  });
+}

package/src/cli/integration-cursor.ts

@@ -0,0 +1,106 @@
+/** Read-only Cursor integration observations; never downloads or configures Cursor. */
+import type { CursorIntegrationStatus } from "../server/management/cursor-integration-routes";
+import type { CursorLocalInstallerHint } from "../integrations/cursor-local-installer";
+import { runCatalogAction } from "./catalog-command-result";
+import { CliUsageError, printData, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = "Usage: ocx integration native cursor [status|local-installer] [--json]";
+const GUIDE_URL = "https://lidge-jun.github.io/opencodex/guides/cursor-private-inference/";
+const PLACEHOLDER = "opencodex-loopback";
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid Cursor response");
+  return value as Record<string, unknown>;
+}
+function text(value: unknown): string {
+  if (typeof value !== "string" || !value.length) throw new Error("Invalid Cursor text");
+  return value;
+}
+function nullableText(value: unknown): string | null { return value === null ? null : text(value); }
+function boolean(value: unknown): boolean {
+  if (typeof value !== "boolean") throw new Error("Invalid Cursor flag");
+  return value;
+}
+function integer(value: unknown): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error("Invalid Cursor number");
+  return value;
+}
+function strings(value: unknown): string[] {
+  if (!Array.isArray(value)) throw new Error("Invalid Cursor list");
+  return value.map(text);
+}
+
+function statusDto(raw: unknown): CursorIntegrationStatus {
+  const value = record(raw), privateInference = record(value.privateInference), regular = record(value.regularCursor);
+  const gateway = record(value.gateway), table = record(value.effortTable);
+  if (!Array.isArray(value.models) || (gateway.apiKeyMode !== "credential" && gateway.apiKeyMode !== "placeholder")
+    || gateway.placeholder !== PLACEHOLDER || (table.source !== "bundle" && table.source !== "static")
+    || value.guideUrl !== GUIDE_URL) throw new Error("Invalid Cursor status");
+  const baseUrl = text(gateway.baseUrl), parsedUrl = new URL(baseUrl);
+  if (!["http:", "https:"].includes(parsedUrl.protocol) || parsedUrl.username || parsedUrl.password
+    || parsedUrl.search || parsedUrl.hash || parsedUrl.pathname !== "/v1") throw new Error("Invalid Cursor gateway");
+  const last = value.lastSeen === null ? null : record(value.lastSeen);
+  return {
+    privateInference: { installed: boolean(privateInference.installed), path: nullableText(privateInference.path), version: nullableText(privateInference.version) },
+    regularCursor: { installed: boolean(regular.installed), path: nullableText(regular.path) },
+    gateway: { baseUrl, apiKeyMode: gateway.apiKeyMode, placeholder: PLACEHOLDER },
+    lastSeen: last === null ? null : { at: integer(last.at), userAgent: text(last.userAgent) },
+    effortTable: { source: table.source, version: nullableText(table.version), families: table.families === null ? null : integer(table.families) },
+    models: value.models.map(rawModel => {
+      const model = record(rawModel), context = model.context === null ? null : record(model.context);
+      return { id: text(model.id), reasoning: model.reasoning === null ? null : strings(model.reasoning), family: nullableText(model.family),
+        tableLess: boolean(model.tableLess), effortRows: strings(model.effortRows),
+        context: context === null ? null : { defaultWindow: integer(context.defaultWindow), longWindow: integer(context.longWindow) } };
+    }),
+    guideUrl: GUIDE_URL,
+  };
+}
+
+function installerDto(raw: unknown): CursorLocalInstallerHint {
+  const value = record(raw), available = boolean(value.available);
+  if (value.reason !== null && (typeof value.reason !== "string" || !["no-regular-install", "unsupported-platform", "unreachable", "unusable-response"].includes(value.reason))) {
+    throw new Error("Invalid Cursor installer reason");
+  }
+  const url = nullableText(value.url), version = nullableText(value.version);
+  if (available) {
+    if (url === null || version === null || value.reason !== null || url.length > 4096 || version.length > 256) throw new Error("Invalid Cursor installer");
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" || parsed.hostname !== "downloads.cursor.com" || parsed.port || parsed.username || parsed.password
+      || !parsed.pathname.startsWith("/local-mode/")) throw new Error("Invalid Cursor installer URL");
+  } else if (url !== null || version !== null) throw new Error("Invalid unavailable installer");
+  return { available, url, version, reason: value.reason as CursorLocalInstallerHint["reason"] };
+}
+
+/** Arguments start immediately after `integration native cursor`. */
+export async function handleCursorIntegrationCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv], wantsJson = takeFlag(args, "--json"), action = args.shift() ?? "status";
+    if (args.length || (action !== "status" && action !== "local-installer")) {
+      throw new CliUsageError("Cursor supports only status and local-installer reads.", USAGE);
+    }
+    const raw = await runtimeRequest(`/api/native-integrations/cursor${action === "local-installer" ? "/local-installer" : ""}`,
+      { method: "GET", redirect: "error" }, deps);
+    if (action === "local-installer") {
+      const result = installerDto(raw);
+      printData(result, wantsJson, result.available
+        ? [`Cursor installer available: ${result.version}`, `URL: ${result.url}`, "Nothing was downloaded or installed."]
+        : [`No installer advertised. Reason: ${result.reason ?? "none (Private Inference is already installed)"}.`, "Nothing was downloaded or installed."]);
+    } else {
+      const result = statusDto(raw);
+      printData(result, wantsJson, [
+        `Cursor Private Inference: ${result.privateInference.installed ? "installed" : "not found"}`,
+        `Regular Cursor: ${result.regularCursor.installed ? "installed" : "not found"}`,
+        `Gateway: ${result.gateway.baseUrl}`,
+        result.gateway.apiKeyMode === "credential"
+          ? "API key: an existing proxy credential is required. The placeholder is not an access credential."
+          : `API key placeholder: ${PLACEHOLDER} (not a secret).`,
+        `Last seen: ${result.lastSeen ? `${result.lastSeen.userAgent} at ${result.lastSeen.at}` : "no Cursor request observed since proxy startup"}`,
+        `Models: ${result.models.length}`,
+        ...result.models.map(model => `${model.id}: reasoning ${model.reasoning?.join(", ") ?? "not advertised"}`),
+        `Guide: ${result.guideUrl}`,
+        ...(!result.privateInference.installed ? ["Next: ocx integration native cursor local-installer"] : []),
+      ]);
+    }
+    return 0;
+  });
+}

package/src/cli/integration-input.ts

@@ -0,0 +1,60 @@
+/** Input shared by integration preview and journal commands; no writer imports. */
+import { CliUsageError, takeOptionWithSyntax } from "./runtime-api";
+
+export function validateAsideProfile(profile: string | undefined, client: string | undefined, usage: string): void {
+  if (profile === undefined) return;
+  if (client !== "aside") throw new CliUsageError("--profile requires --client aside", usage);
+  if (!/^(0|[1-9][0-9]*)$/.test(profile) || !Number.isSafeInteger(Number(profile))) {
+    throw new CliUsageError("--profile must be a nonnegative integer account ID", usage);
+  }
+}
+
+export function clientIntegrationPath(client: string, profile?: string): string {
+  const base = `/api/client-integrations/${encodeURIComponent(client)}`;
+  return client === "aside" ? `${base}/profiles${profile === undefined ? "" : `/${encodeURIComponent(profile)}`}` : base;
+}
+
+export function integrationOption(args: string[], flag: string): string | undefined {
+  return takeOptionWithSyntax(args, flag)?.value;
+}
+
+export function integrationFlag(args: string[], flag: string): boolean {
+  const occurrences = args.filter(arg => arg === flag || arg.startsWith(`${flag}=`));
+  if (occurrences.length > 1) throw new CliUsageError(`${flag} was given more than once`);
+  if (occurrences.length === 0) return false;
+  if (occurrences[0] !== flag) throw new CliUsageError(`${flag} does not take a value`);
+  args.splice(args.indexOf(flag), 1);
+  return true;
+}
+
+export function integrationFingerprint(args: string[]): string | undefined {
+  const value = integrationOption(args, "--plan-fingerprint");
+  if (value !== undefined && !/^p[0-9]+:[0-9a-f]{32}$/.test(value)) {
+    throw new CliUsageError("--plan-fingerprint requires a bound preview token");
+  }
+  return value;
+}
+
+/** Entries replace the map; omission preserves it; explicit clear sends {}. */
+export function integrationDroidDefaults(args: string[]): Record<string, string> | undefined {
+  const clear = integrationFlag(args, "--clear-reasoning-defaults");
+  const entries: Array<[string, string]> = [];
+  while (true) {
+    const index = args.findIndex(arg => arg === "--reasoning-default" || arg.startsWith("--reasoning-default="));
+    if (index < 0) break;
+    const token = args[index]!;
+    const inline = token.startsWith("--reasoning-default=");
+    const raw = inline ? token.slice("--reasoning-default=".length) : args[index + 1];
+    if (!raw || (!inline && raw.startsWith("--"))) throw new CliUsageError("--reasoning-default requires MODEL=EFFORT");
+    args.splice(index, inline ? 1 : 2);
+    const separator = raw.lastIndexOf("=");
+    if (separator < 1 || separator === raw.length - 1 || !raw.slice(0, separator).trim() || !raw.slice(separator + 1).trim()) {
+      throw new CliUsageError("--reasoning-default requires nonempty MODEL=EFFORT");
+    }
+    const model = raw.slice(0, separator);
+    if (entries.some(([key]) => key === model)) throw new CliUsageError("--reasoning-default contains a duplicate model");
+    entries.push([model, raw.slice(separator + 1)]);
+  }
+  if (clear && entries.length) throw new CliUsageError("--clear-reasoning-defaults cannot be combined with --reasoning-default");
+  return clear || entries.length ? Object.fromEntries(entries) : undefined;
+}

package/src/cli/integration-journal.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { isExportClientId } from "../clients/config-export";
+import { runCatalogAction } from "./catalog-command-result";
+import { clientIntegrationPath, validateAsideProfile } from "./integration-input";
+import { CliUsageError, printData, runtimeRequest, takeFlag, takeOption, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = "Usage: ocx integration client history remove --op <opId> --yes [--client aside [--profile <id>]] [--json]";
+const receiptSchema = z.object({
+  ok: z.literal(true), opId: z.string(),
+  clientId: z.string().refine(isExportClientId),
+  profileId: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+  snapshotRemoved: z.boolean(),
+});
+
+/** argv begins after history remove (also used by the journal alias). */
+export function handleIntegrationJournalRemove(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const wantsJson = takeFlag(args, "--json");
+    const confirmed = takeFlag(args, "--yes");
+    const opId = takeOption(args, "--op");
+    const client = takeOption(args, "--client");
+    const profile = takeOption(args, "--profile");
+    if (args.length) throw new CliUsageError("Unknown or repeated journal removal arguments", USAGE);
+    if (!opId?.trim() || opId !== opId.trim() || opId.length > 512 || /[\u0000-\u001f\u007f-\u009f]/u.test(opId)) {
+      throw new CliUsageError("--op requires a nonempty operation ID without control characters", USAGE);
+    }
+    if (!confirmed) throw new CliUsageError("Journal removal retires a recovery record; pass --yes to confirm", USAGE);
+    if (client !== undefined && client !== "aside") throw new CliUsageError("Journal removal accepts only --client aside or no client selector", USAGE);
+    validateAsideProfile(profile, client, USAGE);
+    const path = client === "aside" ? `${clientIntegrationPath(client, profile)}/journal` : "/api/client-integrations/journal";
+    const parsed = receiptSchema.safeParse(await runtimeRequest(`${path}?opId=${encodeURIComponent(opId)}`, {
+      method: "DELETE", redirect: "error",
+    }, deps));
+    if (!parsed.success) throw new Error("Invalid journal removal receipt");
+    const receipt = parsed.data;
+    if (receipt.opId !== opId || (client !== undefined && receipt.clientId !== client)
+      || (profile !== undefined && receipt.profileId !== Number(profile))
+      || (receipt.clientId !== "aside" && receipt.profileId !== undefined)) throw new Error("Journal removal identity mismatch");
+    printData(receipt, wantsJson, [
+      `Journal operation ${receipt.opId} retired (${receipt.clientId}${receipt.profileId === undefined ? "" : ` profile ${receipt.profileId}`}).`,
+      receipt.snapshotRemoved ? "Snapshot cleanup completed." : "Snapshot cleanup is incomplete. The record is already retired; inspect integration status before further cleanup.",
+    ]);
+    return receipt.snapshotRemoved ? 0 : 1;
+  }, {
+    integration_journal_newest_protected: "The newest recovery record cannot be removed. Keep it available for restore.",
+    integration_operation_not_found: "The operation was not found in the selected journal. Read integration history before retrying.",
+  });
+}