@bitkyc08/opencodex 2.6.26-preview.20260705 → 2.6.28-preview.20260707

package/src/adapters/openai-responses.ts

@@ -1,5 +1,7 @@
 import type { IncomingMeta, ProviderAdapter } from "./base";
 import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../types";
+import { decodeCompactionSummary, SUMMARY_PREFIX } from "../responses/compaction";
+import { OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
 
 // Headers relayed verbatim from the caller in OAuth-passthrough ("forward") mode.
 // Exported so the web-search sidecar reuses the exact same forwarded-auth set for its ChatGPT call.
@@ -31,17 +33,50 @@ function sanitizeReasoningInputContent(body: unknown): unknown {
   const input = raw.input.map(item => {
     if (!item || typeof item !== "object" || Array.isArray(item)) return item;
     const rec = item as Record<string, unknown>;
-    if (rec.type !== "reasoning" || !Array.isArray(rec.content) || rec.content.length === 0) return item;
+    if (rec.type !== "reasoning") return item;
+    const hasRawContent = Array.isArray(rec.content) && rec.content.length > 0;
+    // ocxr1 envelopes are proxy-minted (Anthropic signatures), not OpenAI encryption — the native
+    // backend cannot decrypt them and would reject the request. Strip regardless of content shape.
+    const hasOcxEnvelope = typeof rec.encrypted_content === "string" && rec.encrypted_content.startsWith(OCX_REASONING_PREFIX);
+    if (!hasRawContent && !hasOcxEnvelope) return item;
     changed = true;
     // Routed models can produce raw `reasoning_text` output items. Codex echoes those in later
     // native GPT requests, but ChatGPT's Responses backend accepts reasoning input only with empty
     // `content`; keep summaries/ids and drop the raw content so native passthrough does not 400.
-    return { ...rec, content: [] };
+    const next: Record<string, unknown> = { ...rec, content: [] };
+    if (hasOcxEnvelope) delete next.encrypted_content;
+    return next;
   });
 
   return changed ? { ...raw, input } : body;
 }
 
+/**
+ * Replace proxy-minted compaction items (`encrypted_content` starting with `ocx1:`) with plain
+ * user messages before forwarding to the ChatGPT backend. Our envelope is transparent base64, not
+ * OpenAI encryption — the native backend cannot decrypt it and would reject the request. Real
+ * OpenAI-encrypted compaction items are forwarded untouched.
+ */
+function scrubOcxCompactionItems(body: unknown): unknown {
+  if (!isPlainObject(body) || !Array.isArray(body.input)) return body;
+
+  let changed = false;
+  const input = body.input.map(item => {
+    if (!isPlainObject(item)) return item;
+    if (item.type !== "compaction" && item.type !== "compaction_summary" && item.type !== "context_compaction") return item;
+    const decoded = typeof item.encrypted_content === "string" ? decodeCompactionSummary(item.encrypted_content) : null;
+    if (decoded === null) return item;
+    changed = true;
+    return {
+      type: "message",
+      role: "user",
+      content: [{ type: "input_text", text: `${SUMMARY_PREFIX}\n\n${decoded}` }],
+    };
+  });
+
+  return changed ? { ...body, input } : body;
+}
+
 /**
  * Hosted (OpenAI-executed) tool types that specific native slugs reject at request time. Codex
  * attaches these for app skills (e.g. `image_generation` for imagegen) regardless of the target
@@ -58,6 +93,87 @@ function isPlainObject(v: unknown): v is Record<string, unknown> {
   return !!v && typeof v === "object" && !Array.isArray(v);
 }
 
+/** Flatten a Responses tool-output `output` value (string or content-part array) to plain text. */
+function toolOutputText(output: unknown): string {
+  if (typeof output === "string") return output;
+  if (!Array.isArray(output)) return JSON.stringify(output ?? "");
+  return output.map(part => {
+    if (!isPlainObject(part)) return "";
+    if (typeof part.text === "string") return part.text;
+    if (part.type === "refusal" && typeof part.refusal === "string") return `[refusal] ${part.refusal}`;
+    return "";
+  }).filter(Boolean).join("\n");
+}
+
+/**
+ * Repair a forward-mode input array whose continuation context was lost. When the replay
+ * expansion misses (proxy restart, unrecorded prior turn), previous_response_id is stripped
+ * (the ChatGPT backend rejects it), so the delta may carry items that reference now-absent
+ * prior items and 400 upstream:
+ * - `function_call_output`/`custom_tool_call_output` without their paired call item
+ *   ("No tool call found for function call output with call_id ..."). Converted to user
+ *   messages so the result text survives. `function_call_output` also pairs with
+ *   `local_shell_call` (codex-rs emits shell outputs as function_call_output).
+ * - `reasoning` items ("Item 'rs_*' ... was provided without its required following item").
+ *   Dropped, but only when `dropReasoning` (unexpanded miss): on a replay hit the prior
+ *   reasoning chain is intact and must be preserved.
+ * Runs on every forward request; with intact pairs it returns the original reference.
+ */
+function repairOrphanedInputItems(body: unknown, dropReasoning: boolean): unknown {
+  if (!isPlainObject(body) || !Array.isArray(body.input)) return body;
+  const input = body.input;
+
+  const functionCallIds = new Set<string>();
+  const customCallIds = new Set<string>();
+  for (const item of input) {
+    if (!isPlainObject(item) || typeof item.call_id !== "string") continue;
+    if (item.type === "function_call" || item.type === "local_shell_call") functionCallIds.add(item.call_id);
+    else if (item.type === "custom_tool_call") customCallIds.add(item.call_id);
+  }
+
+  let changed = false;
+  const repaired: unknown[] = [];
+  for (const item of input) {
+    if (!isPlainObject(item)) { repaired.push(item); continue; }
+    if (dropReasoning && item.type === "reasoning") { changed = true; continue; }
+    const isFnOutput = item.type === "function_call_output";
+    const isCustomOutput = item.type === "custom_tool_call_output";
+    if (isFnOutput || isCustomOutput) {
+      const callId = typeof item.call_id === "string" ? item.call_id : "";
+      const paired = isFnOutput ? functionCallIds.has(callId) : customCallIds.has(callId);
+      if (!paired) {
+        changed = true;
+        repaired.push({
+          type: "message",
+          role: "user",
+          content: [{ type: "input_text", text: `[tool output for ${callId || "unknown call"}]\n${toolOutputText(item.output)}` }],
+        });
+        continue;
+      }
+    }
+    repaired.push(item);
+  }
+
+  return changed ? { ...body, input: repaired } : body;
+}
+
+/**
+ * Remove `previous_response_id` before forwarding. Two triggers:
+ * - the proxy expanded the request into a full input replay (the id is now redundant), or
+ * - the target is the ChatGPT backend (`authMode: "forward"`), whose Codex REST endpoint
+ *   categorically rejects the parameter with `{"detail":"Unsupported parameter:
+ *   previous_response_id"}` (strict allowlist; it also rejects `metadata` and
+ *   `max_output_tokens`). Codex only sends the id on WS turns, and ocx converts those to
+ *   internal HTTP requests, so forwarding it upstream is a guaranteed 400 — stripping is
+ *   strictly better even when the local replay state missed. API-key mode keeps the field on
+ *   unexpanded requests: the platform `/v1/responses` supports real server-side storage.
+ */
+function stripPreviousResponseId(body: unknown, strip: boolean): unknown {
+  if (!strip || !isPlainObject(body) || !Object.prototype.hasOwnProperty.call(body, "previous_response_id")) return body;
+  const { previous_response_id: _previousResponseId, ...rest } = body;
+  return rest;
+}
+
 /**
  * Remove hosted tool entries the target native slug rejects, so the OAuth-passthrough body never
  * carries a tool the upstream model 400s on. No-op (returns the original reference) when nothing
@@ -113,11 +229,18 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         if (provider.headers) Object.assign(headers, provider.headers);
       }
 
+      const forward = provider.authMode === "forward";
+      const unexpandedMiss = !!parsed.previousResponseId && parsed._previousResponseInputExpanded !== true;
+      let outBody = stripPreviousResponseId(
+        parsed._rawBody,
+        forward || parsed._previousResponseInputExpanded === true,
+      );
+      if (forward) outBody = repairOrphanedInputItems(outBody, unexpandedMiss);
       return {
         url,
         method: "POST",
         headers,
-        body: JSON.stringify(stripUnsupportedHostedTools(sanitizeReasoningInputContent(parsed._rawBody))),
+        body: JSON.stringify(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(outBody)))),
       };
     },
 

package/src/bridge.ts

@@ -1,6 +1,8 @@
 import type { AdapterEvent, OcxUsage } from "./types";
-import { classifyError, type OcxErrorPayload } from "./errors";
-import { usageDisplayTotalTokens, usageInputTokensWithCacheDetail } from "./usage-totals";
+import { classifyError, type OcxErrorPayload } from "./lib/errors";
+import { encodeCompactionSummary } from "./responses/compaction";
+import { encodeReasoningEnvelope, type ReasoningEnvelope } from "./responses/reasoning-envelope";
+import { usageDisplayTotalTokens, usageInputTokensWithCacheDetail } from "./usage/totals";
 
 function uuid(): string {
   return crypto.randomUUID().replace(/-/g, "");
@@ -62,6 +64,12 @@ export function bridgeToResponsesSSE(
     responseId?: string;
     stallTimeoutSec?: number;
     hideThinkingSummary?: boolean;
+    /**
+     * Remote compaction v2 turn: accumulate all assistant text and, on done, emit ONE synthetic
+     * `{type:"compaction", encrypted_content:"ocx1:"+base64(text)}` output item before
+     * response.completed — codex-rs collect_compaction_output requires exactly one.
+     */
+    compaction?: boolean;
     onTerminal?: (status: ResponsesTerminalStatus) => void;
     onCompletedResponse?: (response: Record<string, unknown>) => void;
   },
@@ -72,6 +80,34 @@ export function bridgeToResponsesSSE(
     try { const o = JSON.parse(args); if (o && typeof o.input === "string") return o.input; } catch { /* raw */ }
     return args;
   };
+  // Best-effort unwrap of a PARTIAL freeform arg buffer for live input streaming
+  // (`response.custom_tool_call_input.delta` — codex-rs uses it for UI preview only;
+  // the completed custom_tool_call item stays authoritative). Compact `{"input":"...`
+  // buffers get their string value progressively unescaped; anything else streams raw.
+  const FREEFORM_WRAP_PREFIX = '{"input":"';
+  const freeformPartialInput = (args: string): string => {
+    if (!args.startsWith(FREEFORM_WRAP_PREFIX)) return args;
+    const body = args.slice(FREEFORM_WRAP_PREFIX.length);
+    let out = "";
+    for (let i = 0; i < body.length; i++) {
+      const c = body[i];
+      if (c === '"') break; // unescaped closing quote: value complete
+      if (c === "\\") {
+        const n = body[i + 1];
+        if (n === undefined) break; // escape split across chunks: wait for more
+        i++;
+        if (n === "n") out += "\n";
+        else if (n === "t") out += "\t";
+        else if (n === "r") out += "\r";
+        else if (n === "u") {
+          const hex = body.slice(i + 1, i + 5);
+          if (hex.length === 4 && /^[0-9a-fA-F]{4}$/.test(hex)) { out += String.fromCharCode(parseInt(hex, 16)); i += 4; }
+          else break; // incomplete \uXXXX: wait for more
+        } else out += n; // \" \\ \/ etc.
+      } else out += c;
+    }
+    return out;
+  };
   // tool_search_call carries arguments as a JSON object ({query, limit}); parse the model's arg string.
   const parseArgsObj = (args: string): Record<string, unknown> => {
     try { const o = JSON.parse(args); return o && typeof o === "object" ? o : {}; } catch { return {}; }
@@ -163,7 +199,40 @@ export function bridgeToResponsesSSE(
       let currentMsg: { itemId: string; outputIndex: number; text: string } | null = null;
       let currentReasoning: { itemId: string; outputIndex: number; text: string } | null = null;
       let currentRawReasoning: { itemId: string; outputIndex: number; text: string } | null = null;
-      let currentToolCall: { itemId: string; outputIndex: number; callId: string; name: string; args: string; namespace?: string; freeform?: boolean; toolSearch?: boolean } | null = null;
+      // Anthropic extended-thinking round-trip state: the signature signs the CURRENT thinking
+      // block; redacted blocks are opaque payloads replayed verbatim. Attached to the reasoning
+      // item as an ocxr1 encrypted_content envelope on close. hiddenThinkingText collects the
+      // suppressed text under hideThinkingSummary so the signed text still round-trips.
+      let pendingSignature: string | undefined;
+      let pendingRedacted: string[] = [];
+      let hiddenThinkingText = "";
+      const takeReasoningEnvelope = (hiddenText?: string): string | undefined => {
+        if (!pendingSignature && pendingRedacted.length === 0) return undefined;
+        const envelope: ReasoningEnvelope = {};
+        if (pendingSignature) envelope.sig = pendingSignature;
+        if (pendingRedacted.length > 0) envelope.red = pendingRedacted;
+        if (hiddenText) envelope.txt = hiddenText;
+        pendingSignature = undefined;
+        pendingRedacted = [];
+        return encodeReasoningEnvelope(envelope);
+      };
+      // hideThinkingSummary path: no visible reasoning item exists, but a signed thinking block
+      // must still round-trip — emit an envelope-only reasoning item (empty summary, no text leak).
+      const flushHiddenReasoningEnvelope = () => {
+        const encrypted = takeReasoningEnvelope(hiddenThinkingText || undefined);
+        hiddenThinkingText = "";
+        if (!encrypted) return;
+        const itemId = `rs_${uuid()}`;
+        const item = { type: "reasoning", id: itemId, summary: [] as never[], encrypted_content: encrypted };
+        emit("response.output_item.added", { output_index: outputIndex, item });
+        emit("response.output_item.done", { output_index: outputIndex, item });
+        finishedItems.push(item as OutputItem);
+        outputIndex++;
+      };
+      // Full assistant text of a compaction turn (across message boundaries) — becomes the
+      // synthetic compaction item's payload on done.
+      let compactionText = "";
+      let currentToolCall: { itemId: string; outputIndex: number; callId: string; name: string; args: string; namespace?: string; freeform?: boolean; toolSearch?: boolean; inputEmitted?: string } | null = null;
       // Open native web-search cell (between begin and end). Holds the output index allocated on
       // begin so the matching done reuses it; closed as `failed` if the stream terminates early.
       let currentWebSearch: { itemId: string; outputIndex: number } | null = null;
@@ -212,9 +281,11 @@ export function bridgeToResponsesSSE(
           item_id: currentReasoning.itemId, output_index: currentReasoning.outputIndex, summary_index: 0,
           part: { type: "summary_text", text: currentReasoning.text },
         });
+        const encrypted = takeReasoningEnvelope();
         const item = {
           type: "reasoning", id: currentReasoning.itemId,
           summary: [{ type: "summary_text", text: currentReasoning.text }],
+          ...(encrypted ? { encrypted_content: encrypted } : {}),
         };
         emit("response.output_item.done", { output_index: currentReasoning.outputIndex, item });
         finishedItems.push(item as OutputItem);
@@ -246,6 +317,12 @@ export function bridgeToResponsesSSE(
             item_id: currentToolCall.itemId, output_index: currentToolCall.outputIndex, arguments: argsStr,
           });
         }
+        if (currentToolCall.freeform) {
+          emit("response.custom_tool_call_input.done", {
+            item_id: currentToolCall.itemId, output_index: currentToolCall.outputIndex,
+            input: freeformInput(currentToolCall.args),
+          });
+        }
         const item = currentToolCall.toolSearch
           ? {
               type: "tool_search_call", id: currentToolCall.itemId,
@@ -295,6 +372,15 @@ export function bridgeToResponsesSSE(
         for await (const event of events) {
           activity = true;
           stallTicks = 0;
+          // Compaction turns emit ONLY the synthetic compaction item + response.completed. The
+          // summary text is accumulated silently: emitting it as a normal assistant message would
+          // duplicate the summary if this response is ever replayed via previous_response_id
+          // expansion (rememberResponseState stores input + output). Codex ignores extra items but
+          // its compaction UI renders nothing mid-turn, so nothing is lost visually.
+          if (options?.compaction) {
+            if (event.type === "text_delta") { compactionText += event.text; continue; }
+            if (event.type !== "done" && event.type !== "error") continue;
+          }
           switch (event.type) {
             case "text_delta": {
               if (currentReasoning) closeCurrentReasoning();
@@ -321,7 +407,7 @@ export function bridgeToResponsesSSE(
               break;
             }
             case "thinking_delta": {
-              if (options?.hideThinkingSummary) break;
+              if (options?.hideThinkingSummary) { hiddenThinkingText += event.thinking; break; }
               if (currentMsg) closeCurrentMessage();
               if (currentRawReasoning) closeCurrentRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
@@ -342,6 +428,18 @@ export function bridgeToResponsesSSE(
               });
               break;
             }
+            case "thinking_signature": {
+              pendingSignature = event.signature;
+              // Signature arrives at the end of the thinking block. With a visible reasoning item
+              // open, closeCurrentReasoning attaches the envelope; hidden/suppressed blocks flush
+              // an envelope-only reasoning item now.
+              if (!currentReasoning) flushHiddenReasoningEnvelope();
+              break;
+            }
+            case "redacted_thinking": {
+              pendingRedacted.push(event.data);
+              break;
+            }
             case "reasoning_raw_delta": {
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
@@ -388,6 +486,21 @@ export function bridgeToResponsesSSE(
                     delta: event.arguments,
                   });
                 }
+                if (currentToolCall.freeform) {
+                  // Hold while the buffer is still an ambiguous prefix of the JSON wrapper,
+                  // then stream only the unwrapped input suffix (never rewind on mode flips).
+                  if (!FREEFORM_WRAP_PREFIX.startsWith(currentToolCall.args)) {
+                    const full = freeformPartialInput(currentToolCall.args);
+                    const emitted = currentToolCall.inputEmitted ?? "";
+                    if (full.startsWith(emitted) && full.length > emitted.length) {
+                      emit("response.custom_tool_call_input.delta", {
+                        item_id: currentToolCall.itemId, output_index: currentToolCall.outputIndex,
+                        delta: full.slice(emitted.length),
+                      });
+                      currentToolCall.inputEmitted = full;
+                    }
+                  }
+                }
               }
               break;
             }
@@ -438,6 +551,19 @@ export function bridgeToResponsesSSE(
               if (currentRawReasoning) closeCurrentRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (currentWebSearch) closeCurrentWebSearch("completed", []);
+              // Redacted-only turns (or hidden thinking without a trailing signature event) still
+              // need their envelope-only reasoning item so the blocks replay next turn.
+              flushHiddenReasoningEnvelope();
+              if (options?.compaction) {
+                // Exactly one compaction item per turn; codex-rs takes the first and fatals on 0.
+                const item = {
+                  type: "compaction", id: `cmp_${uuid()}`,
+                  encrypted_content: encodeCompactionSummary(compactionText),
+                };
+                emit("response.output_item.done", { output_index: outputIndex, item });
+                finishedItems.push(item as OutputItem);
+                outputIndex++;
+              }
               const response = { ...responseSnapshot("completed", finishedItems), usage: responsesUsage(event.usage) };
               options?.onCompletedResponse?.(response);
               emit("response.completed", {
@@ -528,16 +654,22 @@ export function buildResponseJSON(
     toolNsMap?: Map<string, { namespace: string; name: string }>;
     freeformToolNames?: Set<string>;
     toolSearchToolNames?: Set<string>;
+    /** Remote compaction v2 turn — append one synthetic compaction output item (see bridgeToResponsesSSE). */
+    compaction?: boolean;
   },
 ): Record<string, unknown> {
   const responseId = `resp_${uuid()}`;
   const output: OutputItem[] = [];
   let usage: OcxUsage | undefined;
   let errorMessage: string | undefined;
+  let compactionText = "";
 
   let currentText = "";
   let currentSummaryReasoning = "";
   let currentRawReasoning = "";
+  // Anthropic extended-thinking round-trip (batch): see bridgeToResponsesSSE counterpart.
+  let batchSignature: string | undefined;
+  let batchRedacted: string[] = [];
   let currentToolCallId = "";
   let currentToolCallName = "";
   let currentToolCallArgs = "";
@@ -565,10 +697,20 @@ export function buildResponseJSON(
     currentText = "";
   };
   const flushSummaryReasoning = () => {
-    if (!currentSummaryReasoning || options?.hideThinkingSummary) { currentSummaryReasoning = ""; return; }
+    if (!currentSummaryReasoning && !batchSignature && batchRedacted.length === 0) return;
+    const envelope: ReasoningEnvelope = {};
+    if (batchSignature) envelope.sig = batchSignature;
+    if (batchRedacted.length > 0) envelope.red = batchRedacted;
+    const hidden = options?.hideThinkingSummary === true;
+    if (hidden && currentSummaryReasoning && (envelope.sig || envelope.red)) envelope.txt = currentSummaryReasoning;
+    const encrypted = envelope.sig || envelope.red || envelope.txt ? encodeReasoningEnvelope(envelope) : undefined;
+    batchSignature = undefined;
+    batchRedacted = [];
+    if (hidden && !encrypted) { currentSummaryReasoning = ""; return; }
     output.push({
       type: "reasoning", id: `rs_${uuid()}`,
-      summary: [{ type: "summary_text", text: currentSummaryReasoning }],
+      summary: !hidden && currentSummaryReasoning ? [{ type: "summary_text", text: currentSummaryReasoning }] : [],
+      ...(encrypted ? { encrypted_content: encrypted } : {}),
     });
     currentSummaryReasoning = "";
   };
@@ -618,7 +760,10 @@ export function buildResponseJSON(
         if (currentSummaryReasoning) flushSummaryReasoning();
         if (currentRawReasoning) flushRawReasoning();
         if (currentToolCallId) flushToolCall();
-        currentText += e.text;
+        // Compaction turns keep the summary out of normal message output (replay dedup — see
+        // bridgeToResponsesSSE); it ships only inside the synthetic compaction item below.
+        if (options?.compaction) compactionText += e.text;
+        else currentText += e.text;
         break;
       case "thinking_delta":
         if (currentText) flushText();
@@ -626,6 +771,15 @@ export function buildResponseJSON(
         if (currentToolCallId) flushToolCall();
         currentSummaryReasoning += e.thinking;
         break;
+      case "thinking_signature":
+        // End of the current thinking block — flush it WITH the signature envelope so the
+        // block/signature pairing survives multi-block turns.
+        batchSignature = e.signature;
+        flushSummaryReasoning();
+        break;
+      case "redacted_thinking":
+        batchRedacted.push(e.data);
+        break;
       case "reasoning_raw_delta":
         if (currentText) flushText();
         if (currentSummaryReasoning) flushSummaryReasoning();
@@ -679,6 +833,9 @@ export function buildResponseJSON(
   flushSummaryReasoning();
   flushRawReasoning();
   flushToolCall();
+  if (options?.compaction && !errorMessage) {
+    output.push({ type: "compaction", id: `cmp_${uuid()}`, encrypted_content: encodeCompactionSummary(compactionText) });
+  }
 
   return {
     id: responseId, object: "response",

package/src/{doctor.ts → cli/doctor.ts}

@@ -9,10 +9,11 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getConfigDir, getConfigPath, readConfigDiagnostics, readPid, resolveEnvValue } from "./config";
-import { readCodexTokens } from "./codex-auth-collision";
-import { resolveCodexHomeDir as resolveCodexHomeDirImpl } from "./codex-home";
-export { resolveCodexHomeDir } from "./codex-home";
+import { getConfigDir, getConfigPath, readConfigDiagnostics, readPid, resolveEnvValue } from "../config";
+import { readCodexTokens } from "../codex/auth-collision";
+import { resolveCodexHomeDir as resolveCodexHomeDirImpl } from "../codex/home";
+import { countPendingOpencodexHistory } from "../codex/history-provider";
+export { resolveCodexHomeDir } from "../codex/home";
 
 const WHAM_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
 const PROBE_TIMEOUT_MS = 8000;
@@ -293,6 +294,19 @@ export async function runDoctor(): Promise<void> {
   console.log(`  ${probe.ok ? "ok " : "-- "} ${WHAM_USAGE_URL}`);
   console.log(`       ${detail}, ${probe.durationMs}ms, ${probe.authenticated ? "authenticated" : "unauthenticated"}`);
 
+  // Design B upgrade visibility: threads still tagged opencodex are invisible to the native
+  // Codex app until the one-time migration lands. Read-only probe (readonly sqlite, 100ms
+  // busy timeout) — reports state, never mutates.
+  console.log("\nCodex history migration");
+  const pending = countPendingOpencodexHistory();
+  if (pending.failed) {
+    console.log("  --     state DB locked or unreadable (Codex app open?) — migration state unknown");
+  } else if (pending.pendingRows === 0 && pending.backupEntries === 0) {
+    console.log("  ok     no legacy opencodex-tagged threads pending");
+  } else {
+    console.log(`  --     ${pending.pendingRows} thread(s) still tagged opencodex, ${pending.backupEntries} backup manifest entr${pending.backupEntries === 1 ? "y" : "ies"}`);
+  }
+
   // Hints, not fixes.
   const hints: string[] = [];
   const anyDrvfs = paths.some(p => detectFsType(p.path, mounts).isDrvfs || detectFsType(p.path, mounts).isMntDrive);
@@ -308,6 +322,9 @@ export async function runDoctor(): Promise<void> {
       }
     }
   }
+  if (pending.failed || pending.pendingRows > 0 || pending.backupEntries > 0) {
+    hints.push("Legacy chat threads are still tagged opencodex (or the DB was locked). The running proxy retries the migration automatically; to force it now, close the Codex app and run 'ocx sync'.");
+  }
   if (hints.length > 0) {
     console.log("\nHints");
     for (const h of hints) console.log(`  - ${h}`);

package/src/{cli-help.ts → cli/help.ts}

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const repoRoot = dirname(fileURLToPath(new URL("../package.json", import.meta.url)));
+const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
 
 type HelpEntry = {
   usage: string;