@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/cli/update-restart.ts

@@ -7,21 +7,23 @@ import { isRealBunBinary } from "../lib/bun-binary-validator.mjs";
 import { isProcessAlive } from "../lib/process-control";
 import { parseStrictSemver } from "../lib/strict-semver";
 import { startArgv } from "../lib/self-launch-argv";
-import { diagnoseService } from "../service/diagnostics";
-import { inspectGuardedManagerTarget } from "../service/guarded-manager-target";
+import { inspectGuardedManagerTarget, type GuardedManagerDeps } from "../service/guarded-manager-target";
 import { acquireOwnershipMutationLease, unprivilegedOwnershipMutationEnvironment } from "../service/ownership-mutation-lease.mjs";
 import { serviceStatePaths } from "../service/state";
 import { findLiveProxy, probeEndpointLiveness, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { waitForPortAvailable } from "../server/ports";
 import { UPDATE_RESTART_CHILD_ENV, type UpdateRestartChildMarker } from "./update-restart-child";
-import { assertUpdateRestartConfiguration, assertUpdateRestartHome, readUpdateRestartHome, type UpdateRestartHome } from "./update-restart-home";
+import { assertUpdateRestartConfiguration, assertUpdateRestartHome, readUpdateRestartHome, type UpdateRestartHome, type UpdateRestartHomeDeps } from "./update-restart-home";
 import { observeAttestedUpdateReplacement, stopAttestedUpdateTarget } from "./update-restart-transport";
 import type { UpdateRestartCandidate } from "./update-restart-candidate";
 import { INCOMPLETE_INSTALL_RECOVERY } from "./restart-failure";
 import { computeVersionSkew } from "./version-skew";
+import { createSupervisionLatch, inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import { classifyUpdateRestartSystemdSupervision, probeUpdateRestartSupervision, resolveUpdateRestartSupervisor, runBoundedUpdateRestartSupervisor, UPDATE_RESTART_SYSTEMD_ARGS, type UpdateRestartSupervisionDeps } from "./update-restart-supervision";
 
 export interface UpdateRestartChild { pid?: number; exitCode: number | null; signalCode: string | null }
 export interface UpdateRestartIo {
+  inspectSupervision?: typeof inspectDesktopSupervision;
   now(): number;
   acquire(): { release(): void };
   home(): UpdateRestartHome;
@@ -37,7 +39,7 @@ export interface UpdateRestartIo {
   wait(ms: number): Promise<void>;
 }
 const ELIGIBILITY_REASONS = ["windows", "unsupported_platform", "foreground", "service", "shared_or_client",
-  "package_tree_fenced", "unverifiable_ancestry", "target_changed", "configuration_changed"] as const;
+  "package_tree_fenced", "unverifiable_ancestry", "target_changed", "configuration_changed", "desktop"] as const;
 export type UpdateRestartEligibilityReason = (typeof ELIGIBILITY_REASONS)[number];
 
 /** Carries only a closed reason code across the eligibility/transport boundary. */
@@ -56,6 +58,7 @@ function sameRuntime(candidate: UpdateRestartCandidate, current: RuntimePortStat
 
 /** A terminal update transaction: it never enters generic restart recovery. */
 export async function runUpdateRestart(candidate: UpdateRestartCandidate, deadlineAt: number, io: UpdateRestartIo): Promise<UpdateRestartResult> {
+  const latch = createSupervisionLatch();
   let phase = "eligibility";
   let lease: { release(): void } | undefined;
   // Recorded here because the stop transport sanitizes anything thrown by beforeStop.
@@ -79,6 +82,13 @@ export async function runUpdateRestart(candidate: UpdateRestartCandidate, deadli
         eligibilityReason = currentRuntime?.siblingOfPort !== undefined ? "shared_or_client" : "target_changed";
         throw new Error("target");
       }
+      const supervision = (io.inspectSupervision ?? inspectDesktopSupervision)({ targetPid: candidate.target.pid });
+      const evidence = supervision.kind === "desktop" && supervision.runtimePid !== candidate.target.pid
+        ? { kind: "unknown" as const, reason: "unrelated-target", desktopSeen: false } : supervision;
+      if (latch.observe(evidence)) {
+        eligibilityReason = "desktop";
+        throw new UpdateRestartEligibilityError("desktop");
+      }
       try {
         if (!io.standalone(candidate.target)) throw new Error("target");
       } catch (error) {
@@ -147,6 +157,7 @@ export function describeUpdateRestartFailure(code: string, reason?: UpdateRestar
       switch (reason) {
         case "windows": return "Restart from a newer CLI is unavailable on Windows. Run `ocx status`, then restart through the owning service or desktop app.";
         case "unsupported_platform": return "Restart from a newer CLI requires macOS or Linux. Run `ocx status`, then use the owning lifecycle manager.";
+        case "desktop": return "OpenCodex Desktop supervises this proxy. Use the app's updater (tray → Check for Updates), or quit OpenCodex before updating and restarting from this CLI.";
         case "service": return "An installed or active service owns lifecycle control. Run `ocx status`, then use the owning installation's `ocx service restart`.";
         case "foreground": return "The proxy is attached to a parent process. Run `ocx status`; if it runs in a terminal, restart it in that terminal, otherwise use its owning app or supervisor.";
         case "shared_or_client": return "This is a shared or connected-client runtime. Run `ocx status` and restart through its owning Hub, service or desktop app.";
@@ -180,29 +191,64 @@ export function describeUpdateRestartFailure(code: string, reason?: UpdateRestar
   }
 }
 
-function standalone(target: UpdateRestartCandidate["target"]): boolean {
-  try { assertUpdateRestartConfiguration(target.hostname ?? ""); }
+export interface UpdateRestartStandaloneDeps {
+  platform?: NodeJS.Platform;
+  expectedHome?: UpdateRestartHome;
+  checkConfiguration?: typeof assertUpdateRestartConfiguration;
+  command?: typeof readProcessCommandLine;
+  parent?: (pid: number) => string;
+  home?: UpdateRestartHomeDeps;
+  supervision?: UpdateRestartSupervisionDeps;
+  manager?: GuardedManagerDeps;
+}
+
+export function standalone(target: UpdateRestartCandidate["target"], deadlineAt: number, deps: UpdateRestartStandaloneDeps = {}): boolean {
+  const platform = deps.platform ?? process.platform;
+  try { (deps.checkConfiguration ?? assertUpdateRestartConfiguration)(target.hostname ?? ""); }
   catch { throw new UpdateRestartEligibilityError("configuration_changed"); }
-  if (process.platform !== "darwin" && process.platform !== "linux") {
-    throw new UpdateRestartEligibilityError(process.platform === "win32" ? "windows" : "unsupported_platform");
+  if (platform !== "darwin" && platform !== "linux") {
+    throw new UpdateRestartEligibilityError(platform === "win32" ? "windows" : "unsupported_platform");
   }
   const host = probeHostname(target.hostname).replace(/^\[|\]$/g, "");
   if (target.role === "client") throw new UpdateRestartEligibilityError("shared_or_client");
   if (target.packageTreeFenced) throw new UpdateRestartEligibilityError("package_tree_fenced");
   if (!isIP(host) || target.source !== "runtime") throw new UpdateRestartEligibilityError("unverifiable_ancestry");
-  const command = readProcessCommandLine(target.pid);
+  const command = (deps.command ?? readProcessCommandLine)(target.pid);
   if (!command || !isOcxStartCommandLine(command)) throw new UpdateRestartEligibilityError("unverifiable_ancestry");
-  if (diagnoseService().installed) throw new UpdateRestartEligibilityError("service");
-  const manager = inspectGuardedManagerTarget(target.pid, target.port);
+  let home: UpdateRestartHome;
+  try {
+    home = readUpdateRestartHome(deps.home);
+    if (deps.expectedHome && JSON.stringify(home) !== JSON.stringify(deps.expectedHome)) throw new Error("changed");
+  }
+  catch { throw new UpdateRestartEligibilityError("service"); }
+  const supervision = { ...deps.supervision, platform };
+  const managerCommand = resolveUpdateRestartSupervisor(supervision);
+  if (!managerCommand) throw new UpdateRestartEligibilityError("service");
+  if (probeUpdateRestartSupervision(deadlineAt, supervision, managerCommand) !== "inactive") throw new UpdateRestartEligibilityError("service");
+  const manager = inspectGuardedManagerTarget(target.pid, target.port, {
+    ...deps.manager, platform,
+    launchctl: args => {
+      const result = runBoundedUpdateRestartSupervisor(managerCommand, args, deadlineAt, supervision);
+      return { ...result, ok: result.status === 0 };
+    },
+    systemdShow: () => {
+      const result = runBoundedUpdateRestartSupervisor(managerCommand, UPDATE_RESTART_SYSTEMD_ARGS, deadlineAt, supervision);
+      if (classifyUpdateRestartSystemdSupervision(result) !== "inactive") throw new Error("update_restart_supervision_unverified");
+      return result.stdout;
+    },
+  });
   if (manager.kind !== "absent") throw new UpdateRestartEligibilityError(manager.kind === "bound" ? "service" : "unverifiable_ancestry");
   let parent: string;
   try {
-    parent = execFileSync("ps", ["-o", "ppid=", "-p", String(target.pid)], {
+    parent = deps.parent ? deps.parent(target.pid) : execFileSync("ps", ["-o", "ppid=", "-p", String(target.pid)], {
       encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"],
     }).trim();
   } catch { throw new UpdateRestartEligibilityError("unverifiable_ancestry"); }
   if (!/^[1-9]\d*$/.test(parent)) throw new UpdateRestartEligibilityError("unverifiable_ancestry");
   if (parent !== "1") throw new UpdateRestartEligibilityError("foreground");
+  try {
+    if (JSON.stringify(readUpdateRestartHome(deps.home)) !== JSON.stringify(home)) throw new Error("changed");
+  } catch { throw new UpdateRestartEligibilityError("service"); }
   return true;
 }
 
@@ -213,7 +259,7 @@ export function restartFromCurrentInstallation(candidate: UpdateRestartCandidate
   return runUpdateRestart(candidate, deadlineAt, {
     now: Date.now,
     acquire: () => acquireOwnershipMutationLease(serviceStatePaths(), { waitMs: Math.max(0, Math.min(2000, deadlineAt - Date.now())) }),
-    home: readUpdateRestartHome, checkHome: assertUpdateRestartHome, runtime: readRuntimePort, standalone,
+    home: readUpdateRestartHome, checkHome: home => assertUpdateRestartHome(home, deadlineAt), runtime: readRuntimePort, standalone: target => standalone(target, deadlineAt, { expectedHome: candidate.home }),
     runtimeReady: () => isRealBunBinary(executable),
     stop: async (target, deadline, beforeStop) => {
       const token = configuredAdminToken();

package/src/cli/v2.ts

@@ -15,15 +15,14 @@ import { parseV2Command, V2_USAGE, type V2ParsedCommand } from "./v2-input";
 import { handleV2RuntimeCommand } from "./v2-runtime";
 import { localV2State, v2LocalSyncResult, type V2LocalSync } from "./v2-local-output";
 import { execFileSync } from "node:child_process";
-import { dirname } from "node:path";
-import { activeCodexConfigPath, getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
+import { getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
 
 import { commandInvocation, type SpawnInvocation } from "../lib/win-exec";
 import { deleteConfigTopLevelKey, loadConfig, saveConfig } from "../config";
 import { resolveAndPersistCodexRuntime, type ResolveCodexRuntimeDeps } from "../codex/runtime";
 
 export interface V2CliDeps {
-  execFile?: (file: string, args: string[], options?: SpawnInvocation["options"]) => void;
+  execFile?: (file: string, args: string[], options?: SpawnInvocation["options"] & { env?: NodeJS.ProcessEnv }) => void;
   isEnabled?: typeof isMultiAgentV2Enabled;
   hasMaxThreads?: typeof hasAgentsMaxThreads;
   sync?: (port?: number) => Promise<unknown>;
@@ -35,7 +34,8 @@ export interface V2CliDeps {
 
 export type CodexFeaturesInvocationDeps =
   & Parameters<typeof commandInvocation>[3]
-  & Pick<ResolveCodexRuntimeDeps, "existsSync" | "execFileSync" | "configDir" | "readFileSync">;
+  & Pick<ResolveCodexRuntimeDeps, "existsSync" | "execFileSync" | "configDir" | "readFileSync">
+  & { requireAvailable?: boolean };
 
 /**
  * Shared invocation for `codex features enable|disable <feature>` — the single
@@ -51,14 +51,18 @@ export function codexFeaturesInvocation(
   platform: NodeJS.Platform = process.platform,
   deps: CodexFeaturesInvocationDeps = {},
 ): SpawnInvocation {
-  const command = resolveAndPersistCodexRuntime({
+  const resolved = resolveAndPersistCodexRuntime({
     env: deps.env ?? process.env,
     platform,
     existsSync: deps.existsSync,
     execFileSync: deps.execFileSync,
     configDir: deps.configDir,
     readFileSync: deps.readFileSync,
-  }).runtime.command || "codex";
+  });
+  if (deps.requireAvailable && resolved.runtime.source === "fallback" && resolved.runtime.version === null) {
+    throw Object.assign(new Error("spawn codex ENOENT"), { code: "ENOENT" });
+  }
+  const command = resolved.runtime.command || "codex";
   return commandInvocation(command, ["features", action, feature], platform, deps);
 }
 
@@ -70,27 +74,30 @@ export function codexFeaturesInvocation(
  */
 export function runCodexFeaturesCommand(
   action: "enable" | "disable",
-  feature: string = "multi_agent_v2",
+  feature: string,
+  env: NodeJS.ProcessEnv,
+  validateBeforeSpawn: () => void,
+  preparedInvocation?: SpawnInvocation,
 ): void {
-  const inv = codexFeaturesInvocation(action, feature);
+  const inv = preparedInvocation ?? codexFeaturesInvocation(action, feature, process.platform, { env });
+  validateBeforeSpawn();
   execFileSync(inv.file, inv.args,
     {
       stdio: ["ignore", "pipe", "pipe"], timeout: 15_000, windowsHide: true, encoding: "utf8",
-      // The reader resolves $CODEX_HOME at call time (including the WSL Windows-home
-      // detection); force the same home on the child so it never toggles a different
-      // config than the one the postcondition re-reads.
-      env: { ...process.env, CODEX_HOME: dirname(activeCodexConfigPath()) },
       ...inv.options,
+      env,
     });
 }
 
-function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps): void {
+function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps, env: NodeJS.ProcessEnv, validateBeforeSpawn: () => void): void {
   if (deps.execFile) {
-    const inv = (deps.featuresInvocation ?? codexFeaturesInvocation)(action);
-    deps.execFile(inv.file, inv.args, inv.options);
+    const inv = deps.featuresInvocation ? deps.featuresInvocation(action)
+      : codexFeaturesInvocation(action, "multi_agent_v2", process.platform, { env });
+    validateBeforeSpawn();
+    deps.execFile(inv.file, inv.args, { ...inv.options, env });
     return;
   }
-  runCodexFeaturesCommand(action);
+  runCodexFeaturesCommand(action, "multi_agent_v2", env, validateBeforeSpawn);
 }
 
 export function v2StatusLine(enabled: boolean): string {
@@ -182,7 +189,7 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     }
     if (parsed.verb === "threads") {
       const enabled = (deps.isEnabled ?? isMultiAgentV2Enabled)();
-      const result = transitionMultiAgentV2(enabled, next => runCodexFeatures(next ? "enable" : "disable", deps), { threadLimit: parsed.value });
+      const result = transitionMultiAgentV2(enabled, (next, env, validate) => runCodexFeatures(next ? "enable" : "disable", deps, env, validate), { threadLimit: parsed.value });
       if (!result.ok) return emit(false, ["Unable to update the native thread limit. Read ocx v2 status before retrying."]);
       changed = result.changed;
       return emit(true, [changed ? `max_threads = ${parsed.value} (${enabled ? "v2" : "v1"}) — applies to new sessions.` : `max_threads already ${parsed.value} — nothing to do.`]);
@@ -194,7 +201,7 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       changed = (config.multiAgentMode ?? "default") !== parsed.value;
       if (parsed.value !== "default") {
         const target = parsed.value === "v2" && config.keepNativeChatGptOnV1 !== true;
-        const transition = transitionMultiAgentV2(target, next => runCodexFeatures(next ? "enable" : "disable", deps));
+        const transition = transitionMultiAgentV2(target, (next, env, validate) => runCodexFeatures(next ? "enable" : "disable", deps, env, validate));
         if (!transition.ok) { changed = false; return emit(false, ["Native mode transition failed. Read ocx v2 status before retrying."]); }
         changed ||= transition.changed;
       }
@@ -207,7 +214,7 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       unchangedKeep = (config.keepNativeChatGptOnV1 === true) === parsed.value;
       changed = !unchangedKeep;
       if (parsed.value && requiresGlobalV2Disabled(config.multiAgentMode, true)) {
-        const transition = transitionMultiAgentV2(false, next => runCodexFeatures(next ? "enable" : "disable", deps));
+        const transition = transitionMultiAgentV2(false, (next, env, validate) => runCodexFeatures(next ? "enable" : "disable", deps, env, validate));
         if (!transition.ok) { changed = false; return emit(false, ["Native hybrid-mode transition failed. Read ocx v2 status before retrying."]); }
         changed ||= transition.changed;
       }
@@ -222,7 +229,7 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       if (want && requiresGlobalV2Disabled(config.multiAgentMode, config.keepNativeChatGptOnV1 === true)) {
         return emit(false, ["v2 on: incompatible with keep-native-v1 while mode is v2 — Codex's global multi_agent_v2 overrides the native v1 catalog pin. Run 'ocx v2 keep-native-v1 off' first."]);
       }
-      const transition = transitionMultiAgentV2(want, next => runCodexFeatures(next ? "enable" : "disable", deps));
+      const transition = transitionMultiAgentV2(want, (next, env, validate) => runCodexFeatures(next ? "enable" : "disable", deps, env, validate));
       if (!transition.ok) return emit(false, ["Native feature transition failed. Read ocx v2 status before retrying."]);
       changed = transition.changed;
       if (!changed) return emit(true, [`multi_agent_v2 already ${want ? "ON" : "OFF"} — nothing to do.`]);

package/src/cli/version-skew-notice.ts

@@ -0,0 +1,77 @@
+import { readConfigDiagnostics } from "../config/diagnostics";
+import { readRuntimePort } from "../config/process-state";
+import { packageVersion } from "./help";
+import { proxyIdentityAt } from "../server/proxy-liveness";
+import { computeVersionSkew } from "./version-skew";
+
+const LIFECYCLE = new Set(["start", "stop", "restart", "update", "service"]);
+const NOTICE_DEADLINE_MS = 200;
+let printed = false;
+
+export function shouldNoticeVersionSkew(command: string | undefined, args: string[]): boolean {
+  const boundary = args.indexOf("--");
+  const prefix = boundary < 0 ? args : args.slice(0, boundary);
+  return LIFECYCLE.has(command ?? "")
+    && !prefix.some(arg => arg === "--json" || arg === "--help" || arg === "-h")
+    && prefix[1] !== "help";
+}
+
+export interface VersionSkewNoticeIo {
+  readRuntime?: typeof readRuntimePort;
+  readConfig?: typeof readConfigDiagnostics;
+  probe?: typeof proxyIdentityAt;
+  cliVersion?: () => string;
+  now?: () => number;
+  warn?: (message: string) => void;
+}
+
+/**
+ * One proxyIdentityAt (src/server/proxy-liveness.ts) call validates /healthz identity,
+ * expected PID and terminal-safe version within the total diagnostic budget.
+ */
+export async function maybeNoticeVersionSkew(
+  command: string | undefined, args: string[], io: VersionSkewNoticeIo = {},
+): Promise<void> {
+  if (printed || !shouldNoticeVersionSkew(command, args)) return;
+  const now = io.now ?? Date.now;
+  const deadlineAt = now() + NOTICE_DEADLINE_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const runtime = (io.readRuntime ?? readRuntimePort)();
+    let port: number;
+    let hostname: string | undefined;
+    let expectedPid: number | undefined;
+    if (runtime) {
+      ({ port, hostname } = runtime);
+      expectedPid = runtime.pid;
+    } else {
+      const diagnostics = (io.readConfig ?? readConfigDiagnostics)();
+      if (diagnostics.error) return;
+      port = diagnostics.config.port ?? 10100;
+      hostname = diagnostics.config.hostname;
+    }
+    const remaining = Math.floor(deadlineAt - now());
+    if (remaining <= 0) return;
+    const cliVersion = (io.cliVersion ?? packageVersion)();
+    if (now() >= deadlineAt) return;
+    const identity = await Promise.race([
+      (io.probe ?? proxyIdentityAt)(port, { hostname, expectedPid }, {
+        timeoutMs: Math.max(1, Math.floor(deadlineAt - now())),
+        attempts: 1, deadlineAt, nowFn: now,
+      }),
+      new Promise<null>(resolve => {
+        timer = setTimeout(() => resolve(null), Math.max(1, deadlineAt - now()));
+      }),
+    ]);
+    if (printed || !identity || now() >= deadlineAt) return;
+    const skew = computeVersionSkew(cliVersion, identity.version);
+    if (!skew.skewed) return;
+    printed = true;
+    (io.warn ?? console.error)(`ocx ${cliVersion} does not match the running proxy ${identity.version}. `
+      + "Check which opencodex installation you meant to use (`ocx status` shows both).");
+  } catch {
+    // Best-effort diagnostics must not fail a lifecycle command or change its exit code.
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}

package/src/clients/config-export/model-metadata.ts

@@ -2,6 +2,7 @@
 import { getModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { SCHEMA_REQUIRED_OUTPUT_BUDGET } from "./constants";
 import { expandFastExportModels } from "./fast-models";
+import { sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
 import type { OpencodeCatalogModel, ExportModel, ExportClientId, ManagedContribution } from "./contracts";
 import type { OcxConfig } from "../../types";
 import { shouldInjectApiAuthHeader } from "../../codex/inject";
@@ -84,6 +85,21 @@ export function inputModalitiesForClient(
   return kept.length > 0 ? kept : null;
 }
 
+/**
+ * Effort ladder a ZCode surface can offer as picker values, or undefined when the row
+ * has nothing selectable.
+ *
+ * Both ZCode exports — the legacy `v2/config.json` block's `reasoning.variants` and the
+ * `v2/provider_config.json` store's `optionSpecs.reasoningLevel.values` — carry the same
+ * Codex vocabulary: the client validates the chosen level against the emitted list and
+ * forwards it verbatim, and `/v1/responses` reads that vocabulary natively. `none` is a
+ * Codex omit-sentinel, not a picker option, so it never survives into the values.
+ */
+export function zcodeSelectableEfforts(efforts: readonly string[] | undefined): string[] | undefined {
+  const selectable = sanitizeCodexReasoningEfforts(efforts)?.filter(effort => effort !== "none");
+  return selectable && selectable.length > 0 ? selectable : undefined;
+}
+
 /**
  * Input modalities opencode's model schema accepts (opencode.ai/config.json, both
  * `modalities.input` and `modalities.output`). Wider than our internal `text | image | audio`

package/src/clients/config-export/zcode-store.ts

@@ -1,6 +1,6 @@
 // ZCode personal provider store export.
 import type { ExportContext, ManagedContribution, ManagedFragment } from "./contracts";
-import { authoritativeContextWindow, inputModalitiesForClient, normalizeExportModels } from "./model-metadata";
+import { authoritativeContextWindow, inputModalitiesForClient, normalizeExportModels, zcodeSelectableEfforts } from "./model-metadata";
 import { OPENCODE_PROVIDER_ID, LOOPBACK_API_KEY_PLACEHOLDER } from "./constants";
 import { formatSelectorConjunction } from "../../integrations/merge";
 
@@ -49,10 +49,30 @@ export interface ZcodeStoreProviderRule {
   };
 }
 
+/**
+ * One model rule, as the client's own store loader accepts it.
+ *
+ * The capability fields are the client's schema, not ours: ZCode 3.14's CLI
+ * bundle parses each `providerModelRules` entry with a strict object whose
+ * `config.properties` admits `inputFormat.{supportsText..supportsPdf}` (booleans)
+ * and whose `config.optionSpecs` admits `reasoningLevel.values` (non-empty,
+ * deduplicated) plus an optional compiled `map`. With no `map`, the chosen level
+ * is validated against `values` and forwarded verbatim to the wire field the
+ * `openai-responses` api type uses — `reasoning.effort`, which is exactly the
+ * Codex vocabulary our ladder already carries, so no mapping is emitted.
+ */
 export interface ZcodeStoreModelRule {
   providerId: string;
   modelId: string;
-  config: { properties: { contextWindow: number } };
+  config: {
+    properties: {
+      contextWindow?: number;
+      inputFormat?: { supportsImage: true };
+    };
+    optionSpecs?: {
+      reasoningLevel: { values: string[] };
+    };
+  };
 }
 
 /**
@@ -77,7 +97,7 @@ export function zcodeStoreSchemaEstablished(parsed: unknown): boolean {
  * carrying only the model would match another provider's rule for the same
  * model. The conjunction grammar reserves `,` and `]`, and a model id holding
  * either cannot be addressed unambiguously — that row ships without its
- * context window rather than with a selector that points somewhere else.
+ * model rule rather than with a selector that points somewhere else.
  */
 function modelRuleSelector(modelId: string): string | null {
   return formatSelectorConjunction([
@@ -128,12 +148,18 @@ export function buildZcodeStoreProviderRule(ctx: ExportContext): ZcodeStoreProvi
 
 /**
  * Everything this project owns inside the store: one provider rule, plus one
- * model rule per row that has an authoritative context window.
+ * model rule per row that has anything authoritative to assert.
  *
- * A row without one ships no model rule at all, which is the same
- * authoritative-window rule the legacy block follows — an emitted stand-in
- * would be a guessed capability. Reasoning ladders have no counterpart here
- * that this project has observed the client produce, so none is written.
+ * A model rule now exists when the row has any of: an authoritative context
+ * window, image input, or a selectable effort ladder. A row with none of the
+ * three ships no rule at all, which is the same no-guessed-capability rule the
+ * legacy block follows. Image input is asserted only when the catalog declares
+ * it — `supportsImage: true` is what gates the client's attachment UI, and a
+ * text-only row keeps the client's own defaults rather than being pinned to
+ * `false`. `reasoningLevel.values` carries the same ladder (minus the `none`
+ * sentinel) the legacy block's `reasoning.variants` carries, so both surfaces
+ * offer the picker the catalog declared instead of the store silently losing
+ * reasoning and vision the way #5348 lost the provider itself.
  */
 export function buildZcodeStoreContribution(ctx: ExportContext): ManagedContribution {
   const fragments: ManagedFragment[] = [{
@@ -141,15 +167,24 @@ export function buildZcodeStoreContribution(ctx: ExportContext): ManagedContribu
     value: buildZcodeStoreProviderRule(ctx),
   }];
   for (const model of normalizeExportModels(ctx.models)) {
-    if (inputModalitiesForClient("pi", model.inputModalities) === null) continue;
+    const input = inputModalitiesForClient("pi", model.inputModalities);
+    if (input === null) continue;
     const contextWindow = authoritativeContextWindow(model.contextWindow);
-    if (contextWindow === undefined) continue;
+    const supportsImage = input.includes("image");
+    const efforts = zcodeSelectableEfforts(model.reasoningEfforts);
+    if (contextWindow === undefined && !supportsImage && efforts === undefined) continue;
     const selector = modelRuleSelector(model.namespaced);
     if (selector === null) continue;
     const rule: ZcodeStoreModelRule = {
       providerId: OPENCODE_PROVIDER_ID,
       modelId: model.namespaced,
-      config: { properties: { contextWindow } },
+      config: {
+        properties: {
+          ...(contextWindow !== undefined ? { contextWindow } : {}),
+          ...(supportsImage ? { inputFormat: { supportsImage: true } } : {}),
+        },
+        ...(efforts !== undefined ? { optionSpecs: { reasoningLevel: { values: efforts } } } : {}),
+      },
     };
     fragments.push({ path: [...ZCODE_STORE_MODEL_RULES_PATH, selector], value: rule });
   }

package/src/clients/config-export/zcode.ts

@@ -1,7 +1,6 @@
 // ZCode config export.
 import type { ExportContext, ManagedContribution } from "./contracts";
-import { normalizeExportModels, inputModalitiesForClient, exportModelLabel, authoritativeContextWindow, singleFragment } from "./model-metadata";
-import { sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
+import { normalizeExportModels, inputModalitiesForClient, exportModelLabel, authoritativeContextWindow, singleFragment, zcodeSelectableEfforts } from "./model-metadata";
 import { OPENCODE_PROVIDER_ID, LOOPBACK_API_KEY_PLACEHOLDER } from "./constants";
 
 
@@ -86,9 +85,8 @@ export function buildZcodeClientConfig(ctx: ExportContext): ZcodeGeneratedConfig
     // `ultra` when present: ZCode forwards the selected variant to the wire field its
     // kind uses — `reasoning.effort` on `openai`, which is what `/v1/responses` reads
     // natively. Set `defaultVariant` only when it survives that filter.
-    const efforts = sanitizeCodexReasoningEfforts(model.reasoningEfforts)
-      ?.filter(effort => effort !== "none");
-    if (efforts && efforts.length > 0) {
+    const efforts = zcodeSelectableEfforts(model.reasoningEfforts);
+    if (efforts !== undefined) {
       const defaultVariant = model.defaultReasoningEffort?.trim().toLowerCase();
       entry.reasoning = {
         enabled: true,

package/src/clients/config-export.ts

@@ -1367,7 +1367,7 @@ function buildAsideContribution(ctx: ExportContext): ManagedContribution {
  * the keyed `providers`, the `models` ARRAY whose identity is `id`, the
  * `openai-completions` dialect, the loopback placeholder, and the
  * `thinkingLevelMap` levels. Evidence:
- * `devlog/_plan/260912_omo_client_integration/001_omo_contract.md`.
+ * `devlog/_fin/260912_omo_client_integration/001_omo_contract.md`.
  *
  * The flag is passed HERE as well as in the spec's `build`, which is the one
  * thing Prime and Aside do not do. They pass the default on both paths, so they

package/src/clients/lazycodex.ts

@@ -1,6 +1,6 @@
 /**
  * Detection of Codex-based omo (LazyCodex), the variant that reads Codex role files and
- * `codex.agents.<role>.model` in `~/.omo/omo.jsonc`.
+ * `"[codex]".agents.<role>.model` in `~/.omo/omo.jsonc`.
  *
  * "omo" names three products. Pi-based omo (senpi) owns `~/.omo/agent` and is the omo file
  * integration in `src/integrations/registry.ts`; OpenCode-based omo (oh-my-opencode) keeps its

package/src/clients/omo-role-models.ts

@@ -1,5 +1,7 @@
 /**
- * omo (Codex / LazyCodex)'s per-role model setting, `codex.agents.<role>.model` in `~/.omo/omo.jsonc`.
+ * omo (Codex / LazyCodex)'s per-role model setting, `"[codex]".agents.<role>.model` in `~/.omo/omo.jsonc`.
+ * The section name carries its brackets: LazyCodex reads `[codex]`, and its strict loader drops a
+ * bare `codex` key as unknown, so a pick written there never reaches a role.
  *
  * LazyCodex 5.1.1 and later reads it, and callers reach this only after `detectLazyCodex`
  * says LazyCodex is installed. The file is omo's, so this writes only on an explicit
@@ -30,6 +32,17 @@ export function omoJsoncPath(env: NodeJS.ProcessEnv = process.env, home: string
 
 type JsonObject = Record<string, unknown>;
 
+const CODEX_SECTION = "[codex]";
+
+/** The reasoning levels LazyCodex accepts for a role; it names Codex's `none` `off`. */
+const LAZYCODEX_REASONING = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+/** The `reasoning` value LazyCodex reads for a Codex effort, or null when it has no such level. */
+export function omoReasoningFor(effort: string): string | null {
+  const level = effort === "none" ? "off" : effort;
+  return LAZYCODEX_REASONING.has(level) ? level : null;
+}
+
 function isObject(value: unknown): value is JsonObject {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -71,7 +84,7 @@ function load(path: string): Loaded {
 }
 
 function agentsOf(doc: JsonObject): JsonObject | null | undefined {
-  const codex = doc.codex;
+  const codex = doc[CODEX_SECTION];
   if (codex === undefined) return undefined;
   if (!isObject(codex)) return null;
   const agents = codex.agents;
@@ -104,21 +117,33 @@ function serialize(text: string, doc: JsonObject): string {
   return text.startsWith("\ufeff") ? `\ufeff${out}` : out;
 }
 
-export function writeOmoRoleModel(role: string, model: string, path: string = omoJsoncPath()): OmoRoleModelWriteStatus {
+/**
+ * `reasoning` left undefined keeps the entry's level; null removes it, so a level LazyCodex cannot
+ * express does not leave a stale one behind for its next install to apply.
+ */
+export function writeOmoRoleModel(
+  role: string,
+  model: string,
+  path: string = omoJsoncPath(),
+  reasoning?: string | null,
+): OmoRoleModelWriteStatus {
   const loaded = load(path);
   if (loaded.kind !== "document") return loaded.kind === "comments" ? "skipped_comments" : loaded.kind;
   const { doc, text } = loaded;
   // Only an absent key is created; an explicit null is a value the reader calls invalid.
-  const codex = doc.codex === undefined ? {} : doc.codex;
+  const codex = doc[CODEX_SECTION] === undefined ? {} : doc[CODEX_SECTION];
   if (!isObject(codex)) return "invalid";
   const agents = codex.agents === undefined ? {} : codex.agents;
   if (!isObject(agents)) return "invalid";
   const entry = agents[role] === undefined ? {} : agents[role];
   if (!isObject(entry)) return "invalid";
-  if (entry.model === model) return "unchanged";
-  agents[role] = { ...entry, model };
+  const next: JsonObject = { ...entry, model };
+  if (reasoning === null) delete next.reasoning;
+  else if (reasoning !== undefined) next.reasoning = reasoning;
+  if (entry.model === model && entry.reasoning === next.reasoning) return "unchanged";
+  agents[role] = next;
   codex.agents = agents;
-  doc.codex = codex;
+  doc[CODEX_SECTION] = codex;
   assertIntegrationWriteOwnership(path);
   atomicWriteFileNoFollowUnclaimed(path, serialize(text, doc));
   return "written";