ocx restore / stop / uninstall refuse to restore config.toml on paginated Codex history, leaving the CLI pointed at a dead proxy port

[practical-tools-lab]

Client or integration

Codex CLI

Area

Service lifecycle

Summary

When any Codex thread in ~/.codex/state_*.sqlite is tagged model_provider='opencodex' on a paginated-history store — the schema every current Codex build uses — ocx restore, ocx stop, and ocx uninstall all refuse to touch ~/.codex/config.toml. The proxy can then be stopped and uninstalled while config.toml still contains model_provider = "opencodex" + [model_providers.opencodex] base_url = "http://127.0.0.1:10100/v1" (or the root openai_base_url override). Every subsequent codex invocation fails with a connection error on the dead port until the user hand-edits TOML.

There is no --force, no fallback strip, and no escape hatch in the CLI. The refusal message ("Native writer coordination is required") does not tell the user how to recover.

Expected instead:

One of:

• a documented --force / "strip routing anyway" mode for restore/uninstall, accepting that opencodex-tagged threads will not resume;
• or, on refusal, a degraded-but-working end state: e.g. remove the root model_provider/openai_base_url while keeping the [model_providers.opencodex] table on disk (so tagged threads still resolve by id and native requests fall back to the built-in openai provider);
• or at minimum, an actionable error telling the user the exact config.toml lines to delete.

Notably, the apply path already implements the middle option: when the relabel unit stands down, injection deliberately keeps an existing opencodex table so tagged threads keep resolving (src/codex/inject.ts:497-502). The remove path has no equivalent.

Reproduction

1. Loopback install, codexDesktopAuthless: true, run ocx sync → config.toml gets model_provider = "opencodex" + the provider table.
2. Start one Codex Desktop/CLI conversation → the thread row is written with model_provider='opencodex' and history_mode='paginated' (current Codex schema).
3. ocx uninstall (or ocx stop, or ocx restore).
4. Observe: the Codex-config step reports Codex configuration preserved: history_paginated_requires_native_writer; uninstall finishes with a failed step; config.toml still routes to 127.0.0.1:10100.
5. codex / the desktop app → connection refused until manual TOML edit.

Version

2.56.0

Operating system

macOS 26 (arm64)

Checks

• I searched existing issues and documentation.
• I removed secrets, tokens, account details, request credentials, and personal data.

---

Why it happens

preflightCodexHistoryInjection is a read-only guard that returns "history_paginated_requires_native_writer" if the threads table has a history_mode column AND either the restore manifest is non-empty or any queried thread is paginated:

src/codex/history-provider.ts:404-421

    if (!existsSync(resolvedPath)) {
      return restoreEntries.length > 0 ? "history_state_database_missing" : null;
    }
    db = new Database(resolvedPath, { readonly: true });
    const columns = db.query<{ name: string }, []>("PRAGMA table_info(threads)").all();
    const paginatedColumn = columns.some(column => column.name === "history_mode");
    if (paginatedColumn && restoreEntries.length > 0) return "history_paginated_requires_native_writer";
    ...
      WHERE ${providerTableMode ? resumeHistory ? "model_provider IN ('openai', 'opencodex')" : "0"
        : "model_provider = 'opencodex'"}
    `).all();
    for (const row of rows) {
      if (paginatedColumn || row.history_mode === "paginated") return "history_paginated_requires_native_writer";

Both restore entry points refuse on that result, in order:

src/codex/inject/restore.ts:233-234 — config restore refuses before touching the journal:

    const historyError = preflightCodexHistoryInjection(false, false);
    if (historyError) return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${historyError}.` };

src/codex/inject/remove.ts:145-146 — the strip path refuses identically:

  const historyError = preflightCodexHistoryInjection(false, false);
  if (historyError) return { success: false, message: `Codex configuration preserved: ${historyError}. Native writer coordination is required.` };

Every user-facing command funnels into restoreNativeCodexAsync → restoreCodexConfigInlineImpl → that preflight: ocx restore (src/cli/dispatch.ts:196), ocx stop (src/server/stop-teardown.ts:60, src/cli/index.ts:793), ocx uninstall (src/cli/index.ts:1315), and the service paths (src/service/cli.ts:293,337).

ocx uninstall then completes the trap: the failed restore is recorded in failures (src/cli/index.ts:1364-1367 exits 1 and keeps config/backups "so the failed restore step can be retried"), but the proxy service/shim is still removed — so the state it preserves is precisely a config.toml pointing at a now-unroutable port.

Impact

• Self-inflicted deadlock: the guard exists to keep opencodex-tagged threads resolvable, but after uninstall the endpoint is gone, so the protected threads fail at request time anyway — while all native use is also broken. The protection protects nothing once the proxy is uninstalled.
• ocx status already knows this state is fatal ("Not running — Codex/Claude requests will fail with connection errors", src/cli/index.ts:1422-1423), yet restore/stop/uninstall can all produce it with no supported recovery path.
• Any authless / client-compaction / admission-token user on a current Codex build who has started ≥1 conversation is in the refusal class.

Suggested fix

Add a degraded mode to the restore preflight: when refusal is due only to history_paginated_requires_native_writer, allow stripping the root routing keys (model_provider, openai_base_url, experimental_realtime_ws_base_url) while leaving the marker-owned [model_providers.opencodex] table on disk, and print exactly what was kept and why. Offer ocx restore --force-remove-provider (or similar) for full removal including the table.

Related issues

• Paginated Codex history stops projecting after provider metadata relabeling #4311, readyz permanently failed when Codex history is paginated (history_paginated_requires_native_writer counted as sync warning) #4665 (closed not planned), [Bug][Windows]: ocx update aborts on pending shared teardown when paginated-history restore is refused #4716 (closed not planned) — the same history_paginated_requires_native_writer guard, reported as a readyz classification problem and as an ocx update teardown abort.

This report is filed separately because it is not about how the refusal is classified or surfaced. It is about the end state after ocx uninstall has already completed: the guard preserves a config.toml pointing at a port that no longer exists, so the opencodex-tagged threads it protects fail at request time anyway, while all native Codex use breaks too. That recovery gap remains regardless of whether the warning is counted as fatal or advisory.

Investigated by reading the installed @bitkyc08/opencodex@2.56.0 package (npm -g; 2.56.0 is the current published version at time of filing). Every quoted snippet is byte-exact from that tree. Corroborating host state: loopback bind, codexDesktopAuthless: true, codexClientCompaction unset, no codexAccountNamespaces, 15-model injected catalog with no reserve row.

[github-actions]

Issue reopened

The report now contains the information required by the automated check. Thanks for updating it.

[lidge-jun]

리뷰 · 우선순위 74 / 80

이 이슈는 Codex가 이미 paginated history(history_mode='paginated')를 쓰는 상태에서 ocx restore / stop / uninstall 이 ~/.codex/config.toml 라우팅을 되돌리지 못해, 프록시는 죽었는데 model_provider = "opencodex" 와 dead loopback URL만 남는 실제 발 묶임 버그입니다. 보고 버전은 2.56.0이지만, 지금 dev(HEAD d210c46da, tip #4814, package 2.57.0)에도 같은 거절 경로가 그대로 있습니다.

코드로 보면 src/codex/history-provider.ts 가 paginated 컬럼·payload를 보면 history_paginated_requires_native_writer 를 던지고, src/codex/inject/remove.ts removeCodexConfig 는 preflight 실패 시 “Codex configuration preserved: …. Native writer coordination is required.” 만 돌려준 채 TOML을 건드리지 않습니다. 사용자는 --force도, strip 안내도, 최소 복구 문구도 없이 수동으로 TOML을 고칠 때까지 codex 연결 거절을 봅니다. 반면 apply/stand-down 쪽(src/codex/inject.ts 근처 Design B)은 opencodex provider table을 남겨 태그된 스레드 id 해석을 지키는 중간 상태를 이미 구현해 두었습니다. remove 경로만 대칭이 없습니다.

심각도는 높습니다. uninstall/stop이 “성공한 것처럼” 끝나도 클라이언트는 죽은 포트로 고정되고, 에러 문구는 복구 방법을 알려 주지 않습니다. 최근 dev 방향(잘못된 신호·숨은 전제 제거)과도 맞고, types/config 분리와는 무관합니다. 프리뷰 배포도 해당 없습니다.

라인 / 경로 수준의 메모입니다.

src/codex/inject/remove.ts removeCodexConfig - paginated preflight 실패 시 즉시 return. force/strip/부분 복구 분기 없음.

src/codex/history-provider.ts - history_paginated_requires_native_writer 거절은 레거시 relabel 안전을 위한 것이라 맞지만, remove와 inject의 사용자 메시지가 동일 톤이라 “설치 해제인데 설정을 보존한다”는 결과가 직관에 반합니다.

src/codex/inject.ts stand-down 유지 경로 - apply는 provider table을 남겨 태그 스레드를 지키는데 remove는 대등한 degraded 상태가 없습니다. 이슈가 제안한 “root model_provider만 제거하고 table은 유지”가 여기와 가장 잘 맞습니다.

CLI UX - 거절 메시지에 지울 줄( model_provider / openai_base_url / section marker )을 적어 주지 않아 비전공 사용자 복구 비용이 큽니다.

재현 전제 - codexDesktopAuthless + 한 번이라도 opencodex 태그 스레드가 있으면 현재 Codex 스키마에서 쉽게 걸립니다. macOS 보고지만 경로는 OS 비의존입니다.

메인테이너의 판단이 필요한 지점

• remove에 --force / strip-anyway를 열지, 아니면 apply와 같은 degraded 유지(table 유지·root 라우팅만 해제)를 기본으로 할지
• paginated 거절을 유지한 채 에러 문구만 actionable하게 바꿀지(최소 패치)
• stop과 uninstall의 기대 UX를 다르게 할지(stop은 보존, uninstall은 반드시 라우팅 해제)
• native writer 조정이 올 때까지 upstream-tracking으로 둘지, 프록시 쪽 탈출구를 먼저 줄지

너의 추천
높은 우선순위로 받아 주세요. 최소로는 uninstall/restore 거절 메시지에 지울 TOML 줄을 명시하고, 가능하면 remove 경로에 apply와 대칭인 degraded strip(root 라우팅 해제 + provider table 유지) 또는 문서화된 --force 를 추가하세요. 관련 열린 중복은 이 배치(#4809–#4812) 안에서 주제가 갈라져 있어 close 대상 중복은 아닙니다. types/config 분리에 무효화되지 않습니다.

이 댓글은 grok-bot이 작성했습니다