@bitkyc08/opencodex 2.81.0 → 2.82.0

package/src/claude/outbound.ts

@@ -20,7 +20,7 @@ import {
   type TranslatorBudget,
 } from "../lib/translator-budget";
 import { sseFieldOffset, sseFieldValue } from "../lib/sse-decoder";
-import { decodeReasoningEnvelope, encodeReasoningEnvelope } from "../responses/reasoning-envelope";
+import { decodeReasoningEnvelope, encodeReasoningEnvelope, OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
 
 type Rec = Record<string, unknown>;
 
@@ -70,8 +70,67 @@ export function anthropicErrorType(status: number): string {
   }
 }
 
+/**
+ * Claude Code compacts reactively only when an oversized-prompt refusal is worded the way the
+ * Anthropic API words it: it looks for `prompt is too long` (or `input is too long for requested
+ * model`) in the message and reads `prompt is too long: <actual> tokens > <limit> maximum` for the
+ * gap (2.1.288 binary). Routed providers word the same refusal differently, so a
+ * context_length_exceeded envelope is rewritten into that form. Counts are carried over only when
+ * the upstream states both of them; otherwise the original text is prefixed and no number is
+ * guessed. Without this the client ends the turn on a fatal error instead of compacting
+ * (devlog/_plan/261009_claude_1m_default/010).
+ */
+const CLAUDE_PROMPT_TOO_LONG_RE = /prompt is too long|input is too long for requested model/i;
+const STATED_CONTEXT_COUNTS_RE = /maximum context length is (\d+) tokens[\s\S]*?(?:resulted in|you requested) (\d+) tokens/i;
+
+export function claudePromptTooLongMessage(message: string): string {
+  if (CLAUDE_PROMPT_TOO_LONG_RE.test(message)) return message;
+  const counts = STATED_CONTEXT_COUNTS_RE.exec(message);
+  if (counts) return `prompt is too long: ${counts[2]} tokens > ${counts[1]} maximum`;
+  return `prompt is too long: ${message}`;
+}
+
+/** Provider wordings of an oversized-input refusal, for lanes that relay a provider's own error text. */
+const CONTEXT_OVERFLOW_TEXT_RE = /prompt is too long|input is too long|context window|context length|maximum context|too many tokens|model token limit/i;
+
+export function isContextOverflowText(message: string): boolean {
+  return CONTEXT_OVERFLOW_TEXT_RE.test(message);
+}
+
+/**
+ * SSE payload rewrite for the native Messages lane: an `error` event that refuses an oversized
+ * input gets the Anthropic wording; every other payload passes through byte-identical. The type
+ * gate keeps a rate limit that happens to mention the context window untouched.
+ */
+export function claudeOverflowSsePayload(payload: string): string {
+  if (!payload.includes("\"error\"")) return payload;
+  let parsed: unknown;
+  try { parsed = JSON.parse(payload); } catch { return payload; }
+  if (!isRec(parsed) || parsed.type !== "error" || !isRec(parsed.error)) return payload;
+  const error = parsed.error;
+  const message = typeof error.message === "string" ? error.message : "";
+  const sized = error.type === "invalid_request_error" || error.type === "request_too_large";
+  if (!sized || isThroughputLimitText(message)) return payload;
+  if (!(error.code === "context_length_exceeded" || isContextOverflowText(message))) return payload;
+  const next = claudePromptTooLongMessage(message);
+  return next === message ? payload : JSON.stringify({ ...parsed, error: { ...error, message: next } });
+}
+
+/**
+ * A throughput limit that the shared classifier files under context_length_exceeded (its "too many
+ * tokens" match also catches "too many tokens per minute"). Worded as an overflow it would make
+ * Claude Code compact a conversation that only needs to wait, so it keeps its own text.
+ */
+const THROUGHPUT_LIMIT_TEXT_RE = /\bper (?:second|minute|hour|day)\b|\brate limit|\bquota\b|\btpm\b/i;
+
+export function isThroughputLimitText(message: string): boolean {
+  return THROUGHPUT_LIMIT_TEXT_RE.test(message);
+}
+
 export function anthropicErrorBody(status: number, message: string, type?: string, code?: string): Rec {
-  return { type: "error", error: { type: type ?? anthropicErrorType(status), message, ...(code ? { code } : {}) } };
+  const overflow = code === "context_length_exceeded" && !isThroughputLimitText(message);
+  const text = overflow ? claudePromptTooLongMessage(message) : message;
+  return { type: "error", error: { type: type ?? anthropicErrorType(status), message: text, ...(code ? { code } : {}) } };
 }
 
 export function anthropicErrorResponse(status: number, message: string, type?: string, code?: string): Response {
@@ -280,6 +339,13 @@ interface OpenBlock {
   thinkingBuf?: string;
   thinkingBufBytes?: number;
   reasoningSig?: string;
+  /** The provider's own encrypted reasoning for this item; signed into the block on close. */
+  reasoningNative?: { enc: string; id?: string };
+}
+
+/** A provider-minted (not ocxr1) `encrypted_content`, or `""`. */
+function nativeEncryptedReasoning(encrypted: string): string {
+  return encrypted.length > 0 && !encrypted.startsWith(OCX_REASONING_PREFIX) ? encrypted : "";
 }
 
 /** Streaming: Responses SSE bytes -> Anthropic Messages SSE bytes. */
@@ -294,6 +360,7 @@ export function responsesSseToAnthropicSse(
      * upstream sent no confirmed usage before the first frame. See `messageSnapshot` (#4857).
      */
     inputTokenFloor?: number;
+    nativeReasoningTagFor?: (blob: string) => string | undefined;
   },
 ): ReadableStream<Uint8Array> {
   const translatorBudget = opts.translatorBudget;
@@ -382,6 +449,13 @@ export function responsesSseToAnthropicSse(
           open.webSearchArgsEmitted = true;
         }
         if (open.kind === "thinking") {
+          const native = open.reasoningNative;
+          const tag = native && opts.nativeReasoningTagFor?.(native.enc);
+          if (!open.thinkingBuf && !open.reasoningSig && !tag) {
+            releaseThinkingBuffer(open);
+            open = null;
+            return;
+          }
           // Delay the index and all thinking frames until closure so a matching
           // done envelope can put its redacted blocks first. The existing buffer
           // remains charged through signature emission, including queued frames.
@@ -396,7 +470,10 @@ export function responsesSseToAnthropicSse(
               delta: { type: "thinking_delta", thinking: open.thinkingBuf },
             });
           }
-          const signature = open.reasoningSig ?? encodeReasoningEnvelope({ txt: open.thinkingBuf ?? "" }, translatorBudget);
+          const signature = open.reasoningSig ?? encodeReasoningEnvelope({
+            txt: open.thinkingBuf ?? "",
+            ...(tag ? { nat: { ...native, model, tag } } : {}),
+          }, translatorBudget);
           emit("content_block_delta", {
             type: "content_block_delta", index: open.index,
             delta: { type: "signature_delta", signature },
@@ -684,11 +761,15 @@ export function responsesSseToAnthropicSse(
                 emit("content_block_start", { type: "content_block_start", index: idx, content_block: { type: "redacted_thinking", data } });
                 emit("content_block_stop", { type: "content_block_stop", index: idx });
               }
-              if (env?.sig && open?.kind !== "thinking") {
+              // A provider's own blob is the only copy of its reasoning the client can hold, so
+              // it gets a thinking block even when no summary text arrived.
+              const native = nativeEncryptedReasoning(encrypted);
+              if ((env?.sig || native) && open?.kind !== "thinking") {
                 ensureBlock("thinking");
               }
               if (open?.kind === "thinking") {
                 if (env?.sig) open.reasoningSig = env.sig;
+                if (native) open.reasoningNative = typeof item.id === "string" && item.id.length > 0 ? { enc: native, id: item.id } : { enc: native };
                 closeOpenBlock();
               }
             }
@@ -881,7 +962,7 @@ export function responsesSseToAnthropicSse(
 }
 
 /** Non-streaming: /v1/responses JSON -> Anthropic message JSON. */
-export function responsesJsonToAnthropicMessage(json: unknown, model: string, translatorBudget?: TranslatorBudget): Rec {
+export function responsesJsonToAnthropicMessage(json: unknown, model: string, translatorBudget?: TranslatorBudget, nativeReasoningTagFor?: (blob: string) => string | undefined): Rec {
   const body = isRec(json) ? json : {};
   const output = Array.isArray(body.output) ? body.output : [];
   const content: Rec[] = [];
@@ -917,10 +998,14 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string, tr
         // Legacy combined envelopes place redacted blocks before the signed block,
         // matching the Anthropic adapter. New bridge output uses separate items.
         for (const data of env?.red ?? []) content.push({ type: "redacted_thinking", data });
-        // env.txt may be locally hidden text. Do not expose it here or manufacture
-        // a new signed continuity carrier; hidden-summary replay remains limited.
-        if (parts.length > 0 || env?.sig) {
-          content.push({ type: "thinking", thinking: parts.join("\n\n"), signature: env?.sig ?? encodeReasoningEnvelope({ txt: parts.join("\n\n") }, translatorBudget) });
+        // env.txt may be locally hidden text. Do not expose it here. A provider's own blob is
+        // carried in the envelope so the next request can hand it back (see inbound.ts).
+        const native = nativeEncryptedReasoning(encrypted);
+        const tag = native && nativeReasoningTagFor?.(native);
+        if (parts.length > 0 || env?.sig || tag) {
+          const text = parts.join("\n\n");
+          const nat = tag ? { enc: native, model, tag, ...(typeof raw.id === "string" && raw.id.length > 0 ? { id: raw.id } : {}) } : undefined;
+          content.push({ type: "thinking", thinking: text, signature: env?.sig ?? encodeReasoningEnvelope({ txt: text, ...(nat ? { nat } : {}) }, translatorBudget) });
         }
         break;
       }

package/src/claude/subagent-model.ts

@@ -1,6 +1,7 @@
 import type { OcxConfig } from "../types";
 import { claudeCodeAlias, claudeCodeNativeAlias, resolveAlias } from "./alias";
-import { AUTO_CONTEXT_OFF, shouldMarkOneMillion, stripOneMillionMarker, withOneMillionMarker } from "./context-windows";
+import { AUTO_CONTEXT_OFF, shouldMarkOneMillion, stripOneMillionMarker, UNPAIRED_AUTO_CONTEXT, withOneMillionMarker, type AutoContextMode } from "./context-windows";
+import { isAnthropicClaudeRoute } from "./long-context";
 import { hasOwnProvider } from "../config";
 import { knownModelIdsForProvider } from "../router";
 import { decodeRoutedModelIdOrThrow } from "../providers/slug-codec";
@@ -14,20 +15,43 @@ export { SAFE_AGENT_MODEL_ID } from "../config/subagent-models";
 
 /**
  * Generated subagent defs cannot rely on the parent's auto-context compaction
- * pairing, so their [1m] marker follows the AUTHORITATIVE window only: mark when
- * the effective window (exact selector, then the canonical [1m] form, then bare)
- * is genuinely >= 1M; strip an inherited unsafe marker back to the bare selector;
- * with no window information, keep the selector as it was. Genuine routed [1m]
- * ids are preserved through the canonical-exact lookup. (#854)
+ * pairing, so their [1m] marker follows the unpaired long-context rule
+ * (long-context.ts): mark when the effective window (exact selector, then the
+ * canonical [1m] form, then bare) is >= 1M or can host the default compact window,
+ * whose overflow Claude Code compacts on as `prompt is too long`; strip an inherited
+ * marker the window cannot carry; with no window information, keep the selector as it
+ * was. Genuine routed [1m] ids are preserved through the canonical-exact lookup.
+ * (#854; devlog/_plan/261009_claude_1m_default/020)
  */
-export function withSubagentContextMarker(selector: string, windows: Record<string, number>): string {
+/**
+ * The marking mode a subagent selector gets: real Anthropic models (a bare `claude-*` passthrough
+ * id, or a Claude row on either Anthropic pool) need a genuine 1M; everything else follows the
+ * unpaired long-context rule. Connected launches read windows from the published catalog, which
+ * does not drop capped Anthropic rows, so this cannot rely on the window map alone.
+ */
+function subagentSelectorMode(bare: string): AutoContextMode {
+  const route = resolveAlias(bare) ?? resolveDesktop3pAlias(bare) ?? bare;
+  const slash = route.indexOf("/");
+  const anthropic = slash < 0
+    ? route.startsWith("claude-")
+    : isAnthropicClaudeRoute(route.slice(0, slash), route.slice(slash + 1));
+  return anthropic ? AUTO_CONTEXT_OFF : UNPAIRED_AUTO_CONTEXT;
+}
+
+/**
+ * `accounting200k` (claudeCode.contextAccounting "200k") stops automatic marking only: an unmarked
+ * selector stays bare, while an explicit [1m] still follows its selector's safety rule.
+ */
+export function withSubagentContextMarker(selector: string, windows: Record<string, number>, accounting200k = false): string {
   const bare = stripOneMillionMarker(selector);
   const wasMarked = selector !== bare;
   const canonicalExact = wasMarked ? `${bare}[1m]` : selector;
   const authoritativeWindow = windows[selector] ?? windows[canonicalExact] ?? windows[bare];
   if (typeof authoritativeWindow === "number" && authoritativeWindow > 0) {
-    return shouldMarkOneMillion(authoritativeWindow, AUTO_CONTEXT_OFF)
-      ? (withOneMillionMarker(selector, windows) ?? selector)
+    if (accounting200k && !wasMarked) return bare;
+    const mode = subagentSelectorMode(bare);
+    return shouldMarkOneMillion(authoritativeWindow, mode)
+      ? (withOneMillionMarker(selector, windows, mode) ?? selector)
       : bare;
   }
   return wasMarked ? selector : bare;
@@ -56,6 +80,11 @@ function selectorIdentity(selector: string): string {
   return fullSelectorIdentity(stripOneMillionMarker(selector));
 }
 
+/** Whether the config opted into 200k accounting (shared by roster, self and force markers). */
+export function accountsAt200k(config: OcxConfig): boolean {
+  return config.claudeCode?.contextAccounting === "200k";
+}
+
 /** Resolve only currently exposed entries; retained roster rows are not exposure proof. */
 export function resolveSubagentForceModel(config: OcxConfig, windows: Record<string, number>, available: SubagentForceExposure): string | null {
   const entry = config.claudeCode?.subagentModelForce;
@@ -77,8 +106,8 @@ export function resolveSubagentForceModel(config: OcxConfig, windows: Record<str
     const window = windows[parts.alias] ?? windows[`${bare}[1m]`] ?? windows[bare];
     // Identity admission must not let an appended context promise ride on an
     // ordinary exposed model. Exact catalog ids such as kimi/k3[1m] remain literal.
-    if (requestedMarker && !exactMarkedExposure && !(typeof window === "number" && Number.isFinite(window) && window >= 1_000_000)) return null;
-    const marked = exactMarkedExposure ? parts.alias : withSubagentContextMarker(parts.alias, windows);
+    if (requestedMarker && !exactMarkedExposure && !(typeof window === "number" && Number.isFinite(window) && shouldMarkOneMillion(window, subagentSelectorMode(bare)))) return null;
+    const marked = exactMarkedExposure ? parts.alias : withSubagentContextMarker(parts.alias, windows, accountsAt200k(config));
     // Bare Anthropic names are indistinguishable from the old CLI's fallback.
     // Encode only the force selector; handlers restore native identity before
     // their existing credential/model-map checks. Roster generation is unchanged.

package/src/cli/agent.ts

@@ -30,7 +30,7 @@ const USAGE = `Usage:
   ocx agent subagents <status|set|clear> [model,model...] [--json]
   ocx agent subagents force <model|-> [--json]
   ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
-  ocx agent roles [status|set <role> <model>|suggest [--model <id>] [--apply]] [--json]
+  ocx agent roles [status|set <role> <model> [--effort <level>]|suggest [--model <id>] [--apply]] [--json]
   ocx agent sidecar <status|web|vision> [--list] [--model <id|->]
       [--backend web:<openai|anthropic|xai|gemini|exa|-> vision:<openai|anthropic|routed|->]
       [--reasoning <level>] [--max-descriptions <n> (vision)] [--enabled <on|off>]
@@ -311,7 +311,7 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 interface CodexAgentRolesStatus {
   lazycodex?: { detected?: boolean };
   omoJsonc?: { state?: string } | null;
-  roles?: Array<{ role: string; model: string | null; omoJsoncModel: string | null }>;
+  roles?: Array<{ role: string; model: string | null; effort?: string | null; omoJsoncModel: string | null }>;
 }
 
 interface CodexRoleProposal {
@@ -393,7 +393,7 @@ async function roles(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     const rows = result.roles ?? [];
     printData(result, wantsJson, [
       "omo (Codex / LazyCodex): detected",
-      ...(rows.length === 0 ? ["No Codex agent roles found."] : rows.map(row => `${row.role}: ${row.model ?? "(no model pin)"}`)),
+      ...(rows.length === 0 ? ["No Codex agent roles found."] : rows.map(row => `${row.role}: ${row.model ?? "(no model pin)"}${row.effort ? ` (${row.effort})` : ""}`)),
       `omo.jsonc: ${result.omoJsonc?.state ?? "unknown"}`,
     ]);
     return;
@@ -403,18 +403,22 @@ async function roles(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     return;
   }
   if (action !== "set") throw new CliUsageError(`unknown roles action ${action}`, USAGE);
+  const effort = takeOption(args, "--effort");
+  // An empty value is a supplied flag, not an absent one: dropping it would change the model and
+  // silently ignore the effort the operator asked for.
+  if (effort !== undefined && effort.trim() === "") throw new CliUsageError("--effort needs a reasoning level", USAGE);
   const role = args.shift();
   const model = args.shift();
   if (!role || !model) throw new CliUsageError("a role and a model are required", USAGE);
   rejectArgs(args, USAGE);
   const result = await runtimeRequest<{ toml?: { status?: string }; omoJsonc?: { status?: string } }>(
     `/api/codex-agent-roles/${encodeURIComponent(role)}`,
-    { method: "PUT", body: JSON.stringify({ model }) },
+    { method: "PUT", body: JSON.stringify(effort !== undefined ? { model, effort } : { model }) },
     deps,
   );
   const omo = result.omoJsonc?.status;
   printData(result, wantsJson, [
-    `${role}: ${model} (role TOML ${result.toml?.status ?? "unknown"})`,
+    `${role}: ${model}${effort ? ` (${effort})` : ""} (role TOML ${result.toml?.status ?? "unknown"})`,
     omo === "skipped_comments"
       ? "omo.jsonc: not written, because it contains comments that a rewrite would lose."
       : `omo.jsonc: ${omo ?? "unknown"}`,

package/src/cli/aside-profile-recovery.ts

@@ -0,0 +1,33 @@
+/**
+ * Recovery guidance for Aside profiles whose sync preference is off while their managed block is stale (#6757).
+ *
+ * Sync refreshes only profiles whose preference is on, and an OFF preference is the operator's decision, so an
+ * "off (stale)" profile needs an explicit, reviewed enable. This module renders text only: it issues no request,
+ * reads no state and never changes a preference. Sync cannot name real profile IDs without a status read that may
+ * run integration maintenance, so its empty result points at status, which already holds the rows.
+ */
+export const ASIDE_SYNC_EMPTY_LINES: readonly string[] = [
+  "No eligible Aside profiles to synchronize. Sync refreshes only profiles whose sync preference is on.",
+  "List profiles with: ocx integration client status --client aside",
+  "For a profile shown as off (stale), review: ocx integration client preview --client aside --operation apply --profile <N>",
+  "Then, if the preview permits the change and you accept it: ocx integration client enable --client aside --profile <N>",
+];
+
+function recoveryProfileId(row: unknown): number | null {
+  if (!row || typeof row !== "object") return null;
+  const { profileId, enabled, state } = row as Record<string, unknown>;
+  // Only an explicit OFF beside a stale block qualifies. Conflict and unsafe blocks need inspection, not an enable.
+  if (enabled !== false || state !== "stale") return null;
+  return typeof profileId === "number" && Number.isSafeInteger(profileId) && profileId >= 0 && !Object.is(profileId, -0)
+    ? profileId : null;
+}
+
+/** Per-profile preview-then-enable commands for status rows that are off with a stale managed block. */
+export function asideProfileRecoveryLines(rows: readonly unknown[]): string[] {
+  const ids = [...new Set(rows.map(recoveryProfileId).filter((id): id is number => id !== null))];
+  return ids.flatMap(id => [
+    `Aside profile ${id} is off (stale). To reconnect it, review: ocx integration client preview --client aside --operation apply --profile ${id}`,
+    `Then, if the preview permits the change and you accept it: ocx integration client enable --client aside --profile ${id}`,
+  ]);
+}
+

package/src/cli/capabilities-base.ts

@@ -571,11 +571,11 @@ export const CAPABILITIES: readonly Capability[] = [
     command: ["claude","config"],
     summary: "Read or update Claude Code settings, including independent CLI first-party routing.",
     routes: [{"method":"GET","path":"/api/claude-code"},{"method":"PUT","path":"/api/claude-code"}],
-    flags: [{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--auth-mode","value":"string","summary":"auto, proxy or subscription."},{"name":"--system-env","value":"string","summary":"on or off."},{"name":"--fast-mode","value":"string","summary":"on or off."},{"name":"--auto-context","value":"string","summary":"on or off."},{"name":"--compact-window","value":"string","summary":"Positive token count or default to clear."},{"name":"--inject-agents","value":"string","summary":"on or off."},{"name":"--small-fast-model","value":"string","summary":"Model ID; - clears."},{"name":"--model-map","value":"string","summary":"Comma-separated from=to mappings; - clears."},{"name":"--blocked-skills","value":"string","summary":"Comma-separated names; - clears."},{"name":"--web-model","value":"string","summary":"Model ID; - clears."},{"name":"--web-backend","value":"string","summary":"openai, anthropic, xai, gemini, exa or -."},{"name":"--vision-model","value":"string","summary":"Model ID; - clears."},{"name":"--vision-backend","value":"string","summary":"openai, anthropic or -."},{"name":"--first-party","value":"string","summary":"on or off; must be the only setting."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."}],
+    flags: [{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--auth-mode","value":"string","summary":"auto, proxy or subscription."},{"name":"--system-env","value":"string","summary":"on or off."},{"name":"--fast-mode","value":"string","summary":"on or off."},{"name":"--auto-context","value":"string","summary":"on or off."},{"name":"--compact-window","value":"string","summary":"Positive token count or default to clear."},{"name":"--context-accounting","value":"string","summary":"1m (default) or 200k."},{"name":"--inject-agents","value":"string","summary":"on or off."},{"name":"--small-fast-model","value":"string","summary":"Model ID; - clears."},{"name":"--model-map","value":"string","summary":"Comma-separated from=to mappings; - clears."},{"name":"--blocked-skills","value":"string","summary":"Comma-separated names; - clears."},{"name":"--web-model","value":"string","summary":"Model ID; - clears."},{"name":"--web-backend","value":"string","summary":"openai, anthropic, xai, gemini, exa or -."},{"name":"--vision-model","value":"string","summary":"Model ID; - clears."},{"name":"--vision-backend","value":"string","summary":"openai, anthropic or -."},{"name":"--first-party","value":"string","summary":"on or off; must be the only setting."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."}],
     mutates: true,
     json: "payload",
     details: ["At least one setting is required. --first-party must be set alone and writes Claude settings immediately.","Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings."],
-    usage: "ocx claude config status [--json]; ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
+    usage: "ocx claude config status [--json]; ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--context-accounting <1m|200k>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
   },
   {
     command: ["claude","intercept","start"],
@@ -714,11 +714,11 @@ export const CAPABILITIES: readonly Capability[] = [
     command: ["agent","roles"],
     summary: "omo (Codex / LazyCodex): show each Codex agent role's model pin, set one role's model in its TOML and in omo.jsonc, or suggest a model for every role.",
     routes: [{"method":"GET","path":"/api/codex-agent-roles"},{"method":"PUT","path":"/api/codex-agent-roles/{role}"},{"method":"POST","path":"/api/codex-agent-roles/auto-assign"}],
-    flags: [{"name":"--json","value":"boolean","summary":"Emit the role list, the write result or the proposals as JSON."},{"name":"--model","value":"string","summary":"suggest: size the roles with this model instead of the Codex default model."},{"name":"--apply","value":"boolean","summary":"suggest: write every proposal through the role model write."}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the role list, the write result or the proposals as JSON."},{"name":"--effort","value":"string","summary":"set: also write the role's reasoning effort."},{"name":"--model","value":"string","summary":"suggest: size the roles with this model instead of the Codex default model."},{"name":"--apply","value":"boolean","summary":"suggest: write every proposal through the role model write."}],
     mutates: true,
     json: "payload",
-    details: ["A bare invocation reads and never writes.","Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.","set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml; omo.jsonc is skipped when absent or when it contains comments.","suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort."],
-    usage: "ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]",
+    details: ["A bare invocation reads and never writes.","Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.","set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml, plus model_reasoning_effort with --effort; omo.jsonc gets the same model and, when LazyCodex has that level, the effort as reasoning; it is skipped when absent or when it contains comments.","suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort."],
+    usage: "ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--effort <level>] [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]",
   },
   {
     command: ["agent","injection"],

package/src/cli/capabilities-integrations.ts

@@ -139,10 +139,10 @@ export const INTEGRATION_CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["claude", "config", "set"],
-    usage: "ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
+    usage: "ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--context-accounting <1m|200k>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
     summary: "Change Claude Code settings through the runtime owner.",
     routes: [{"method": "PUT", "path": "/api/claude-code"}],
-    flags: [{"name": "--enabled", "value": "string", "summary": "on or off."}, {"name": "--auth-mode", "value": "string", "summary": "auto, proxy or subscription."}, {"name": "--system-env", "value": "string", "summary": "on or off."}, {"name": "--fast-mode", "value": "string", "summary": "on or off."}, {"name": "--auto-context", "value": "string", "summary": "on or off."}, {"name": "--compact-window", "value": "string", "summary": "Positive token count or default to clear."}, {"name": "--inject-agents", "value": "string", "summary": "on or off."}, {"name": "--small-fast-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--model-map", "value": "string", "summary": "Comma-separated from=to mappings; - clears."}, {"name": "--blocked-skills", "value": "string", "summary": "Comma-separated names; - clears."}, {"name": "--web-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--web-backend", "value": "string", "summary": "openai, anthropic, xai, gemini, exa or -."}, {"name": "--vision-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--vision-backend", "value": "string", "summary": "openai, anthropic or -."}, {"name": "--first-party", "value": "string", "summary": "on or off; must be the only setting."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    flags: [{"name": "--enabled", "value": "string", "summary": "on or off."}, {"name": "--auth-mode", "value": "string", "summary": "auto, proxy or subscription."}, {"name": "--system-env", "value": "string", "summary": "on or off."}, {"name": "--fast-mode", "value": "string", "summary": "on or off."}, {"name": "--auto-context", "value": "string", "summary": "on or off."}, {"name": "--compact-window", "value": "string", "summary": "Positive token count or default to clear."}, {"name": "--context-accounting", "value": "string", "summary": "1m (default) or 200k."}, {"name": "--inject-agents", "value": "string", "summary": "on or off."}, {"name": "--small-fast-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--model-map", "value": "string", "summary": "Comma-separated from=to mappings; - clears."}, {"name": "--blocked-skills", "value": "string", "summary": "Comma-separated names; - clears."}, {"name": "--web-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--web-backend", "value": "string", "summary": "openai, anthropic, xai, gemini, exa or -."}, {"name": "--vision-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--vision-backend", "value": "string", "summary": "openai, anthropic or -."}, {"name": "--first-party", "value": "string", "summary": "on or off; must be the only setting."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
     mutates: true,
     json: "payload",
     details: ["At least one setting is required. --first-party must be set alone and writes Claude settings immediately.", "Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings."],

package/src/cli/cli-path-diagnostics.ts

@@ -0,0 +1,132 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { readDesktopCliRecord, type DesktopCliRecordRead, desktopCliRecordPath, DESKTOP_CLI_RECORD_MAX_BYTES } from "../lib/desktop-cli-record.mjs";
+import { redactUserPath } from "../lib/redact";
+
+export type CliCommandIssue = Extract<DesktopCliRecordRead, { issue: string }>["issue"]
+  | "cleanup-pending"
+  | "desktop-target-missing" | "desktop-target-unusable"
+  | "expected-command-missing" | "expected-command-unusable"
+  | "path-missing" | "path-first-not-desktop" | "path-unreadable"
+  | "path-scan-truncated" | "windows-current-directory-shadow";
+export type CliPathCandidate = {
+  path: string; realpath: string; pathIndex: number; extension: string;
+};
+export type CliPathDiagnostics = {
+  configured: boolean;
+  recordPath: string;
+  packageHandoff: "enabled" | "disabled-on-windows";
+  recordState: DesktopCliRecordRead["state"];
+  expectedExecutable: string | null;
+  handoffTarget: string | null;
+  candidates: CliPathCandidate[];
+  pathFirst: CliPathCandidate | null;
+  desktopFirstOnPath: boolean | null;
+  currentDirectoryCandidate: CliPathCandidate | null;
+  shellResolution: "unobserved";
+  issues: CliCommandIssue[];
+};
+export type CliPathObservation =
+  | { kind: "usable"; realpath: string }
+  | { kind: "missing" | "unusable" | "unreadable" };
+export type CliPathDiagnosticOptions = {
+  platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; cwd?: string; home?: string;
+  recordRead?: DesktopCliRecordRead;
+  observe?: (path: string) => CliPathObservation;
+};
+
+export function collectCliPathDiagnostics(options: CliPathDiagnosticOptions = {}): CliPathDiagnostics {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const api = platform === "win32" ? win32 : posix;
+  const cwd = options.cwd ?? process.cwd();
+  const home = options.home ?? (platform === "win32" ? env.USERPROFILE || homedir() : homedir());
+  const read = options.recordRead ?? readDesktopCliRecord({ platform, env, home, recordPath: desktopCliRecordPath({ platform, env, home }) });
+  const configured = read.state === "ready";
+  const target = configured && read.state === "ready" ? read.record.cliExecutable : null;
+  const expected = configured ? (platform === "win32" ? target : api.join(home, ".opencodex-desktop", "bin", "ocx")) : null;
+  const issues: CliCommandIssue[] = [];
+  const add = (issue: CliCommandIssue): void => { if (!issues.includes(issue)) issues.push(issue); };
+  if (read.state === "invalid" || read.state === "unreadable") add(read.issue);
+  if (read.state === "disabled" && read.cleanupPending) add("cleanup-pending");
+  const observe = options.observe ?? ((path: string): CliPathObservation => {
+    try {
+      if (!statSync(path).isFile()) return { kind: "unusable" };
+      accessSync(path, platform === "win32" ? constants.F_OK : constants.X_OK);
+      return { kind: "usable", realpath: realpathSync(path) };
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      return { kind: code === "ENOENT" || code === "ENOTDIR" ? "missing" : code === "EACCES" ? "unusable" : "unreadable" };
+    }
+  });
+  const key = (path: string): string => platform === "win32" ? path.toLowerCase() : path;
+  const same = (a: string, b: string): boolean => key(a) === key(b);
+  const envValue = (name: string): string | undefined => platform === "win32"
+    ? env[Object.keys(env).find(key => key.toLowerCase() === name.toLowerCase()) ?? name] : env[name];
+  const path = envValue("PATH");
+  const rawExtensions = platform === "win32"
+    ? (envValue("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(ext => /^\.[A-Za-z0-9]+$/.test(ext)) : [];
+  const uniqueExtensions = [...new Set(rawExtensions.map(ext => ext.toLowerCase()))];
+  const extensions = platform === "win32" ? [...uniqueExtensions.slice(0, 32), ""] : [""];
+  if (uniqueExtensions.length > 32) add("path-scan-truncated");
+  const directories = path === undefined ? [] : path.split(platform === "win32" ? ";" : ":");
+  if (directories.length > 256) add("path-scan-truncated");
+  const candidates: CliPathCandidate[] = [];
+  const scan = (directory: string, pathIndex: number): CliPathCandidate[] => {
+    const result: CliPathCandidate[] = [];
+    const unquoted = platform === "win32" && directory.startsWith('"') && directory.endsWith('"') ? directory.slice(1, -1) : directory;
+    for (const extension of extensions) {
+      const candidate = api.resolve(cwd, unquoted || ".", `ocx${extension}`);
+      const found = observe(candidate);
+      if (found.kind === "unreadable") add("path-unreadable");
+      if (found.kind === "usable") result.push({ path: candidate, realpath: found.realpath, pathIndex, extension });
+    }
+    return result;
+  };
+  for (const [index, directory] of directories.slice(0, 256).entries()) candidates.push(...scan(directory, index));
+  const pathFirst = candidates[0] ?? null;
+  const currentDirectoryCandidate = platform === "win32" ? scan(cwd, -1)[0] ?? null : null;
+  let expectedRealpath: string | null = null;
+  if (target) {
+    const found = observe(target);
+    if (found.kind === "missing") add("desktop-target-missing");
+    else if (found.kind !== "usable") add("desktop-target-unusable");
+  }
+  if (expected) {
+    const found = observe(expected);
+    if (found.kind === "missing") add("expected-command-missing");
+    else if (found.kind !== "usable") add("expected-command-unusable");
+    else expectedRealpath = found.realpath;
+    if (!pathFirst) add("path-missing");
+    else if (!same(pathFirst.path, expected) && (!expectedRealpath || !same(pathFirst.realpath, expectedRealpath))) add("path-first-not-desktop");
+    if (currentDirectoryCandidate && !same(currentDirectoryCandidate.path, expected)
+      && (!expectedRealpath || !same(currentDirectoryCandidate.realpath, expectedRealpath))) add("windows-current-directory-shadow");
+  }
+  return {
+    configured, recordPath: read.path, packageHandoff: platform === "win32" ? "disabled-on-windows" : "enabled",
+    recordState: read.state, expectedExecutable: expected, handoffTarget: platform === "win32" ? null : target,
+    candidates, pathFirst,
+    desktopFirstOnPath: configured && !issues.includes("path-unreadable") && !issues.includes("path-scan-truncated")
+      ? Boolean(pathFirst && expected && expectedRealpath
+        && (same(pathFirst.path, expected) || same(pathFirst.realpath, expectedRealpath))) : null,
+    currentDirectoryCandidate, shellResolution: "unobserved", issues,
+  };
+}
+
+export function formatCliCommandLine(value: CliPathDiagnostics): string {
+  const first = value.pathFirst ? redactUserPath(value.pathFirst.path).replace(/[\x00-\x1f\x7f]/g, "?") : "none observed";
+  return `ocx command: PATH first=${first}; Desktop=${!value.configured ? "not configured" : value.desktopFirstOnPath === null ? "unobserved" : value.desktopFirstOnPath ? "first" : "not first"}; ${value.packageHandoff === "disabled-on-windows" ? "package handoff=disabled on Windows (user Path selects Desktop); " : ""}shell=unobserved${value.issues.length ? `; issues=${value.issues.join(",")}` : ""}`;
+}
+
+export function formatCliStatusHealthLabel(health: string, value: CliPathDiagnostics, local: boolean): string {
+  return `${health}${local ? " (local)" : ""}\n   ${formatCliCommandLine(value)}`;
+}
+
+export function cliCommandDoctorChecks(value: CliPathDiagnostics): { level: "OK" | "WARN" | "FAIL"; message: string }[] {
+  const hard = value.issues.some(issue => issue.startsWith("record-") || issue.startsWith("desktop-target-") || issue.startsWith("expected-command-"));
+  const recovery = value.issues.some(issue => issue.startsWith("record-"))
+    ? ` The terminal-command record at ${redactUserPath(value.recordPath).replace(/[\x00-\x1f\x7f]/g, "?")} could not be used. Open OpenCodex Desktop to repair the terminal command.${value.packageHandoff === "disabled-on-windows" ? "" : " Or run with OCX_NO_DESKTOP_HANDOFF=1."}${value.issues.includes("record-too-large") ? ` The record limit is ${DESKTOP_CLI_RECORD_MAX_BYTES} bytes.` : ""}`
+    : value.issues.includes("cleanup-pending") ? " Open OpenCodex Desktop to finish terminal-command cleanup." : "";
+  return [{ level: hard ? "FAIL" : value.issues.length ? "WARN" : "OK", message: formatCliCommandLine(value) + recovery }];
+}

package/src/cli/desktop-runtime-guidance.ts

@@ -0,0 +1,65 @@
+import { createSupervisionLatch, inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import type { DesktopSupervision, SupervisionInspector } from "../service/desktop-command-guard";
+import { UpdateRestartRequired } from "./update-restart-candidate";
+import { runProxyRestart, type ProxyRestartIo } from "./tray-proxy";
+
+function evidenceForTarget(evidence: DesktopSupervision, pid: number | null | undefined): DesktopSupervision {
+  // Injected inspectors must obey the same target binding as the production inspector.
+  return evidence.kind === "desktop" && pid != null && evidence.runtimePid !== pid
+    ? { kind: "unknown", reason: "unrelated-target", desktopSeen: false } : evidence;
+}
+
+export function duplicateRuntimeMessage(
+  pid: number | null | undefined,
+  port: number,
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+): string {
+  const latch = createSupervisionLatch();
+  const evidence = evidenceForTarget(inspect({ targetPid: pid ?? undefined }), pid);
+  if (pid != null && latch.observe(evidence)) {
+    const supervisor = evidence.kind === "desktop" ? `, ${evidence.app}` : "";
+    return `OpenCodex Desktop supervises the running proxy (pid ${pid}${supervisor}, port ${port}). `
+      + "Use the running proxy, or quit OpenCodex before starting it from this CLI.";
+  }
+  return `⚠️  Proxy already running (PID ${pid ?? "unknown"}, port ${port}). Use 'ocx stop' first.`;
+}
+
+export function desktopStopNotice(evidence: DesktopSupervision): string | null {
+  const latch = createSupervisionLatch();
+  return latch.observe(evidence)
+    ? "OpenCodex Desktop may start this proxy again after a short backoff. Use Stop Proxy or Quit in the OpenCodex menu to keep it stopped."
+    : null;
+}
+
+export function runDesktopAwareProxyRestart(
+  io: ProxyRestartIo,
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+  info: (line: string) => void = console.log,
+) {
+  const latch = createSupervisionLatch();
+  let targetPid: number | undefined;
+  let supervisedRequest = false;
+  return runProxyRestart({
+    ...io,
+    requestInPlaceRestart: async previous => {
+      targetPid = previous.pid ?? undefined;
+      const evidence = evidenceForTarget(inspect({ targetPid }), targetPid);
+      supervisedRequest = latch.observe(evidence);
+      const result = await io.requestInPlaceRestart(previous);
+      if (evidence.kind === "desktop" && result.accepted) {
+        info("Restart requested; OpenCodex Desktop starts the replacement.");
+      }
+      if (supervisedRequest && !result.accepted && !result.uncertain && result.error instanceof UpdateRestartRequired) {
+        info("OpenCodex Desktop supervises this proxy. Use the app's updater (tray → Check for Updates), or quit OpenCodex before updating and restarting from this CLI.");
+        return { accepted: false as const, uncertain: false, error: new Error("restart_desktop_update_required") };
+      }
+      return result;
+    },
+    startWhenStopped: async recovering => {
+      const blocked = latch.observe(evidenceForTarget(inspect({ targetPid }), targetPid));
+      // An accepted supervised handoff keeps its replacement intent through temporary absence.
+      if (supervisedRequest || blocked) return { status: "skipped" as const };
+      return io.startWhenStopped(recovering);
+    },
+  });
+}