codex-copilot-dx 0.9.24 → 0.9.25

package/README.md

@@ -30,7 +30,7 @@ The dashboard does not poll in the background; refresh when needed.
 | Command | Purpose |
 | --- | --- |
 | `ccdx help` | Command help; use `ccdx help <command>` for details |
-| `ccdx start` | Start without launching the App |
+| `ccdx start` | Start or reuse the adapter and open Codex when auto-launch is enabled |
 | `ccdx status` | Runtime, limits and bounded request diagnostics |
 | `ccdx doctor` | Configuration, adapter and read-only App/catalog diagnostics |
 | `ccdx doctor config` | Read-only configuration check |
@@ -73,8 +73,8 @@ The dashboard does not poll in the background; refresh when needed.
   trust and an App-only route for `chatgpt.com` and `ab.chatgpt.com`; HTTPS on those
   hosts is decrypted locally, but only prediction configuration is changed.
   Other domains and the CCDX model endpoint stay on their existing routes.
-  No program files or OS trust are changed. Existing proxies are not replaced.
-  See the reference for restart, rollback and client-version boundaries.
+  No program files or OS trust are changed. Static HTTP/HTTPS/SOCKS5 proxies and bypass rules are retained.
+  Dynamic PAC/WPAD routes are reported as unsupported; see the reference for routing, rollback and client-version limits.
 - CCDX adds experimental local history compression only when installed App
   runtimes support it and report it off. Existing choices are preserved; an
   already-enabled default, unavailable runtime or failed check is skipped.
@@ -84,11 +84,14 @@ The dashboard does not poll in the background; refresh when needed.
   expose it to the public internet. The dashboard is not an authentication wall
   for the API. Diagnostic errors may contain sensitive upstream text.
 
-Startup checks GitHub Releases, not npm, and suggests `ccdx update github` when a newer stable version is available. GitHub updates install the exact release tag; dependency downloads still use npm's configured registry.
+Startup checks GitHub's latest-release web redirect, not npm or the anonymous REST quota, and suggests `ccdx update github`.
+Updates install the exact stable tag; dependencies still use npm's configured registry. Lookup errors identify HTTP refusal, timeout, network failure or invalid redirects.
+
+The dashboard and CLI separate prediction preference, bridge state and observed config traffic; candidate visibility stays unknown.
+Inference, client integration, optional images and management have separate ownership. See [architecture boundaries](docs/ARCHITECTURE.md).
 
 See the [complete command/configuration reference](https://github.com/DaleXiao/codex-copilot-dx/blob/main/docs/REFERENCE.md)
-for authentication recovery, configuration-write boundaries, advanced limits,
-logging, image setup and client compatibility details.
+for authentication recovery, configuration safety, limits, logging, images and client compatibility.
 The same reference is included as `docs/REFERENCE.md` in the installed npm package.
 
 ## Development

package/bin/cli.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 import { ensureAuth, openCodex } from "../src/launcher.mjs";
-import { ensureCodexConfig } from "../src/config.mjs";
 import { startAdapter } from "../src/adapter.mjs";
 import { defaultCopilotClient, refreshVSCodeVersion } from "../src/copilot.mjs";
 import { status } from "../src/status.mjs";
@@ -22,9 +21,7 @@ import { runAuthCommand } from "../src/cli-auth.mjs";
 import { createProfileRuntime } from "../src/profile-runtime.mjs";
 import { createProfileModelRuntime } from "../src/profile-model-runtime.mjs";
 import { createCodexModelCatalog } from "../src/codex-model-catalog.mjs";
-import { readImageProviderConfig } from "../src/image-provider-config.mjs";
 import { setResponseHistoryMaxBytes } from "../src/response-history.mjs";
-import { ensureCodexThreadCompression } from "../src/codex-thread-compression.mjs";
 
 const LOCAL_VERSION = localPackageVersion();
 const CLI_NAME = cliCommandName();
@@ -91,7 +88,10 @@ if (CLI.command === "suggestion") {
 if (CLI.command === "prediction") {
   try {
     const { runPredictionCommand } = await import("../src/native-prediction.mjs");
-    await runPredictionCommand({ action: CLI.action });
+    await runPredictionCommand({ action: CLI.action, runtimeSnapshot: () => {
+      const probe = parseAdapterProbeOptions(process.env);
+      return readAdapterStatus({ host: probe.adapterHost, port: probe.adapterPort, timeoutMs: probe.existingAdapterTimeoutMs }).then(({ data }) => data);
+    } });
     process.exit(0);
   } catch (error) {
     console.error(status("err", error.message));
@@ -265,6 +265,16 @@ let activeServer = null;
 let modelRefreshTimer = null;
 let shuttingDown = false;
 let nativePrediction = null;
+let clientIntegration = null;
+
+async function clientIntegrations() {
+  if (!clientIntegration) {
+    const { createClientIntegration } = await import("../src/client-integration.mjs");
+    clientIntegration = createClientIntegration({ port: ADAPTER_PORT, host: ADAPTER_HOST,
+      info: (message) => console.log(status("info", message)), warning: (message) => console.warn(status("warn", message)) });
+  }
+  return clientIntegration;
+}
 
 if (LOGGING.filePath) {
   console.log(status("info", `Debug log: ${LOGGING.filePath}`));
@@ -310,25 +320,7 @@ async function reuseRunningAdapterIfAvailable() {
 }
 
 async function configureCodexClient() {
-  try {
-    const { retirePredictionIntegration } = await import("../src/prediction-retirement.mjs");
-    const result = retirePredictionIntegration();
-    if (result.changed) console.log(status("info", "Removed the retired CCDX prediction integration"));
-    if (result.preserved) console.warn(status("warn", "Modified prediction settings were preserved"));
-  } catch (error) {
-    console.warn(status("warn", `${error.message}. Core startup will continue.`));
-  }
-  const imageProviderEnabled = Boolean(readImageProviderConfig());
-  const { imageMcpSkipped } = ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST, imageProviderEnabled });
-  if (imageProviderEnabled && !imageMcpSkipped) {
-    try {
-      const { syncEnabledImageSkill } = await import("../src/cli-image.mjs");
-      syncEnabledImageSkill({ adapterPort: ADAPTER_PORT, adapterHost: ADAPTER_HOST });
-    } catch (error) {
-      console.warn(status("warn", `Image guidance could not be updated: ${error.message}`));
-    }
-  }
-  return { compressionSetup: runInBackground(ensureCodexThreadCompression) };
+  return (await clientIntegrations()).configure();
 }
 
 if (CLI.command === "doctor") {
@@ -403,16 +395,14 @@ try {
     streamIdleTimeoutMs: RUNTIME.streamIdleTimeoutMs,
     terminalAnimationTheme,
     nativePredictionPac: () => nativePrediction?.pacUrl || null,
+    clientIntegrationSnapshot: () => clientIntegration?.snapshot() || null,
   });
 
   // Point Codex App at the adapter.
   const { compressionSetup } = await configureCodexClient();
 
   // Optional native prediction setup must never prevent the core adapter from running.
-  try {
-    const { startNativePrediction } = await import("../src/native-prediction.mjs");
-    nativePrediction = await startNativePrediction({ warning: (message) => console.log(status("info", message)) });
-  } catch (error) { console.warn(status("warn", `${error.message}. Core startup will continue.`)); }
+  nativePrediction = await (await clientIntegrations()).start();
 
   // Launch Codex when available. A running App is never forcibly restarted.
   await openCodex({ predictionPacUrl: nativePrediction?.pacUrl, predictionApp: nativePrediction?.app });
@@ -444,7 +434,7 @@ try {
     let exitCode = 0;
     try {
       if (modelRefreshTimer) clearInterval(modelRefreshTimer);
-      await nativePrediction?.close();
+      await clientIntegration?.close();
       const result = await closeHttpServer(activeServer, { timeoutMs: RUNTIME.shutdownTimeoutMs });
       if (result.forced) console.warn(status("warn", "Forced remaining adapter connections closed"));
       await flushUsageWrites();
@@ -461,7 +451,7 @@ try {
   await compressionSetup;
 } catch (e) {
   console.error(status("err", e.message));
-  await nativePrediction?.close().catch(() => {});
+  await clientIntegration?.close().catch(() => {});
   await closeHttpServer(activeServer, { timeoutMs: RUNTIME.shutdownTimeoutMs }).catch(() => {});
   await flushUsageWrites();
   await LOGGING.cleanup();

package/docs/ARCHITECTURE.md

@@ -0,0 +1,50 @@
+# Architecture boundaries
+
+CCDX is one local Node service for Codex App. Client integration, image tools and
+the dashboard are optional parts of that service, not a general plugin framework.
+
+| Responsibility | Ownership | Boundary |
+| --- | --- | --- |
+| Core inference | `adapter.mjs`, Responses modules, model catalog, history | Copilot requests, streaming and recovery |
+| Client integration | `client-integration.mjs`, Codex config, native prediction | Client setup, optional start/stop, diagnostic snapshots |
+| Optional images | Image provider, CLI setup, image MCP and skill | Opt-in API access and image delivery; failures do not block core startup |
+| Management | CLI, dashboard, observability, package updates | Bounded metadata and explicit user actions |
+| Shared foundations | Codex paths, file locks, atomic files, network routes | No dependency on inference or dashboard rendering |
+
+## Composition and lifecycle
+
+The CLI composes the service. Client integration owns its `configure`, `start`,
+`snapshot` and `close` operations. It does not forward inference requests or
+render the dashboard. The adapter exposes integration snapshots and keeps
+management/MCP routes separate from the Responses path.
+
+Native prediction has a separate loopback transport and an isolated HTTPS agent.
+Only its two selected hosts use the App-specific route. Non-configuration requests
+on those hosts are forwarded unchanged. The bridge does not replace Copilot or
+image-provider networking, modify client program files, or install system trust.
+Static upstream proxy routes and bypass rules are preserved. Dynamic PAC/WPAD
+and CIDR bypass rules are reported as unsupported, not silently discarded.
+
+## Configuration ownership
+
+`CODEX_HOME` selects Codex configuration. App profile/trust paths have their own
+selection and are not inferred from that directory. CCDX writers use a shared
+per-file lock, reread current contents and preserve unrelated values. Locks do
+not coordinate editors or other applications that ignore them. Read-only status
+and doctor commands do not write configuration.
+
+Legacy public module exports remain available. This change adds a concrete
+composition boundary; it does not relocate every file or add speculative APIs.
+
+## Evidence and verification
+
+Prediction preference, bridge readiness and observed configuration responses are
+different states. None proves that a candidate appeared in the App. The dashboard
+keeps that result unknown. Integration diagnostics retain bounded, redacted
+metadata, not conversation or image contents.
+
+Tests cover module dependency direction, default-off behavior, concurrent writers,
+proxy handshakes, TLS validation, streaming, history isolation and release lookup.
+Performance measurements distinguish request preparation from model latency.
+Release reports describe a specific environment, not an SLA or a guarantee of
+compatibility with every future client or corporate network policy.

package/docs/README.md

@@ -4,6 +4,8 @@ The [root README](../README.md) is the quick start; the [command/configuration
 reference](REFERENCE.md) preserves complete current behavior and limits. `ccdx --help` and
 `ccdx <command> --help` describe the installed package's CLI. Code and tests
 resolve any discrepancy; CLI version and running-adapter version can differ.
+The [architecture boundaries](ARCHITECTURE.md) explain module ownership,
+optional integration lifecycle and configuration safety.
 
 `ccdx doctor config` performs local, read-only configuration diagnostics and
 previews the current startup writer. It does not claim to resolve the complete
@@ -15,6 +17,8 @@ These reports record a specific release and test environment. Their version,
 test counts, timings, live-provider observations, and limitations remain
 historical facts rather than current guarantees.
 
+- [0.9.25: static proxy compatibility, integration boundaries and release diagnostics](RELEASE_0.9.25.md)
+
 - [0.9.19: GitHub startup checks and stable-release updates](RELEASE_0.9.19.md)
 - [0.9.21: compatibility-gated local history compression](RELEASE_0.9.21.md)
 - [0.9.20: timing evidence, real-client checks and bounded analytics reuse](RELEASE_0.9.20.md)

package/docs/REFERENCE.md

@@ -53,8 +53,25 @@ account identity or account-permission value is rewritten. Credentials are not
 logged or persisted by the bridge. The local private key has owner-only permissions;
 its signing key is discarded after certificate creation.
 
-Existing App proxy/PAC/environment routes cause setup to skip with an explanation.
-This initial version does not compose enterprise proxies. The default App profile
+Static proxy settings are composed with the local bridge. For HTTPS targets,
+`https_proxy` takes precedence over `HTTPS_PROXY`, then `all_proxy`/`ALL_PROXY`,
+then the macOS HTTPS proxy or SOCKS proxy. HTTP targets follow their corresponding
+HTTP setting. An HTTP-only environment proxy is not used for HTTPS. HTTP CONNECT,
+TLS to an HTTPS proxy, SOCKS5 (including username/password), `NO_PROXY`/`no_proxy`,
+system exceptions and simple-host exclusions are supported. Proxy credentials
+remain in memory, are never included in PAC responses or diagnostics, and are
+sent only to the proxy. TLS verification remains enabled for both proxy and target.
+Other App domains keep the resolved original route; if a bridge fails, its PAC
+fallback uses that route rather than adding an unrequested direct connection.
+Route selection is a startup snapshot; restart CCDX and Codex after changing it.
+Bypass lists support host/domain patterns and optional ports. Unsupported CIDR
+notation is reported explicitly rather than silently changing the route.
+
+Dynamic PAC/WPAD is not executed or overwritten. Setup identifies the exact
+system setting and preserves its rules. A non-default `CODEX_API_BASE_URL` is
+also preserved and reported as a custom-route conflict; setting it to the normal
+`https://chatgpt.com/backend-api` does not cause a conflict. No automatic direct
+fallback after upstream-proxy rejection is added. The default App profile
 is `~/Library/Application Support/Codex`; an explicit
 `CODEX_ELECTRON_USER_DATA_PATH` is respected. Quit the App before trust changes;
 CCDX never kills it. The launcher uses the exact App that passed the compatibility
@@ -79,14 +96,35 @@ trust removal is deferred; quit it and run `prediction off` again. Only the exac
 owned certificate record is removed, never the whole store. Failed activation
 rolls back newly added trust; certificate replacement keeps old trust until the
 new preference is committed. If the bridge stops, new connections can fall back
-to direct routing; already-interrupted requests are not replayed. Run `ccdx`
+to the original route; already-interrupted requests are not replayed. Run `ccdx`
 after quitting Codex to attach a newly started bridge. `CCDX_AUTO_LAUNCH=0` keeps
 automatic launch disabled and does not attach the route to a manually opened App.
 Optional prediction failures never prevent the core adapter or image service from
-starting. `prediction status` reports the saved preference, not proof of live UI
-availability. Prediction settings are stored separately in
+starting. `prediction status` reports the saved preference and, when a compatible
+running adapter responds, its bridge state, configuration-response observations
+and bounded TLS/upstream errors. The dashboard uses the same snapshot and manual
+refresh. Configuration traffic is evidence of a request reaching the bridge, not
+proof of a generated/displayed candidate. Candidate visibility remains unknown;
+no prompt matching, UI injection, transcript scanning or extra inference is used
+to invent that status. Prediction settings are stored separately in
 `~/.config/codex-copilot-dx/native-prediction/` (or under `XDG_CONFIG_HOME`).
 
+### Configuration ownership
+
+Core setup, image setup/guidance, config doctor, optional history compression and
+legacy prediction cleanup resolve the same `CODEX_HOME/config.toml`; absent
+`CODEX_HOME`, they use `~/.codex/config.toml`. An explicit function-level file path
+still takes precedence for embedders. App-profile trust is a separate location
+selected by `CODEX_ELECTRON_USER_DATA_PATH`, not by `CODEX_HOME`.
+
+CCDX-owned config mutations share an owner-recorded cross-process lock, reread
+under the lock, and retain existing atomic replacement/rollback checks. User
+settings updates use a separate lock for their shared JSON file; prediction
+on/off uses its own settings lock. Readers take no lock and write no lock file.
+Contention fails with a retry message instead of stealing a live lock. Other
+applications do not participate in these locks, so snapshot conflict checks still
+apply; the locks do not claim a global filesystem transaction.
+
 ### Core adapter
 
 One in-process adapter listens on `127.0.0.1:2026` by default and exposes:
@@ -141,7 +179,7 @@ On a normal launch, CCDX:
 1. Prints the installed package version and checks for a newer npm release in the background.
 2. Reuses a compatible running adapter when available; otherwise it reuses a compatible local Copilot credential or starts GitHub Device Flow when authentication is required.
 3. Loads a usable model cache or attempts a live refresh, then starts listening. A cache older than two hours refreshes in the background; a fresh cache can be used immediately. A failed refresh retains the last-known-good list when one is available.
-4. Checks the startup-managed settings in `~/.codex/config.toml`, including the local `/v1` endpoint.
+4. Checks the startup-managed settings in `CODEX_HOME/config.toml` (default `~/.codex/config.toml`), including the local `/v1` endpoint.
 5. Attempts to open Codex App on macOS unless `CCDX_AUTO_LAUNCH` disables it.
 
 The `OPENAI_API_KEY=dummy` value used in the Codex shell environment is only a client-side placeholder. It is not a GitHub credential. CCDX exchanges the saved GitHub OAuth credential for short-lived Copilot service tokens internally.
@@ -156,7 +194,7 @@ If a compatible adapter is already running, a later launch reuses it and checks
 
 ### Codex configuration writes
 
-Normal startup and reuse of an existing adapter check `~/.codex/config.toml` once, after startup prerequisites succeed. There is no file watcher or periodic configuration rewrite. The path is based on the OS home directory; CCDX does not redirect it through `CODEX_HOME` or edit project-level Codex files.
+Normal startup and reuse of an existing adapter check `CODEX_HOME/config.toml` (default `~/.codex/config.toml`) once, after startup prerequisites succeed. There is no file watcher or periodic configuration rewrite. Startup, image setup, config doctor, compression and legacy prediction cleanup share this path. CCDX does not edit project-level Codex files.
 
 | Setting | Existing file | New file |
 | --- | --- | --- |
@@ -318,7 +356,14 @@ ccdx update npm
 ccdx update github
 ```
 
-Normal startup checks the latest stable GitHub Release once in the background, without accessing the npm registry. The anonymous check requires no PAT or Copilot credentials, has a two-second deadline and a bounded response body, and silently skips network errors, rate limits and invalid metadata. It never falls back to npm, retries, polls, installs an update or restarts the service. When a newer release is found, it prints the versions and `ccdx update github`. On adapter reuse, Ready is displayed before waiting for any remaining check budget so the short-lived command does not lose its notification.
+Normal startup checks the official GitHub `releases/latest` web endpoint once in
+the background, without accessing the npm registry or REST API. The anonymous
+check requires no PAT or Copilot credentials, has a two-second deadline, validates
+only the redirect header, cancels the response body without reading HTML, and
+silently skips errors. Redirects must use HTTPS, the exact GitHub repository and
+a stable version tag with no credentials, query or fragment. It never follows
+the redirect, retries, polls, installs or restarts. On adapter reuse, Ready is
+displayed before waiting for any remaining check budget.
 
 `ccdx update gh` is accepted as shorthand for the GitHub source. The npm source installs `codex-copilot-dx@latest` through the registry already configured for npm, including a company mirror. The GitHub source queries the latest stable published Release (ten-second deadline), validates its version tag, and installs that exact tag from `DaleXiao/codex-copilot-dx`, not `main`. Lookup failure stops before installation, without an npm fallback. It opts in to Git fetching only for that command and does not change npm's persistent `allow-git` setting.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.9.24",
+  "version": "0.9.25",
   "description": "Use Codex App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",
@@ -15,7 +15,8 @@
     "scripts/benchmark-probes.mjs",
     "scripts/fixtures/",
     "README.md",
-    "docs/REFERENCE.md"
+    "docs/REFERENCE.md",
+    "docs/ARCHITECTURE.md"
   ],
   "keywords": [
     "codex",

package/src/adapter.mjs

@@ -236,6 +236,7 @@ export function createAdapterHandler(options = {}) {
         codexClient,
         codexModelRegistry,
         codexModelCatalog,
+        clientIntegrations: options.clientIntegrationSnapshot?.(),
       })));
       return;
     }

package/src/cli-image.mjs

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import os from "node:os";
-import path from "node:path";
 import readline from "node:readline";
 import { createInterface } from "node:readline/promises";
+import { codexPaths } from "./codex-paths.mjs";
+import { withFileLockSync } from "./lock.mjs";
 import { atomicWriteFileIfChangedSync, atomicWriteFilePairSync } from "./atomic-file.mjs";
 import { terminalCell } from "./cli-table.mjs";
 import { computeImageMcpCodexConfig } from "./config.mjs";
@@ -15,11 +16,6 @@ import {
   readImageProviderConfig,
   validateImageProviderConfig,
 } from "./image-provider-config.mjs";
-
-function defaultCodexConfigPath(home) {
-  return path.join(home, ".codex", "config.toml");
-}
-
 async function visibleQuestion(input, output, question) {
   const prompt = createInterface({ input, output });
   try { return await prompt.question(question); }
@@ -102,7 +98,10 @@ function configSummary(config) {
   };
 }
 
-function enableImageProvider({ providerConfig, providerPath, codexPath, codexContent, adapterPort, adapterHost }) {
+function enableImageProvider(options) {
+  return withFileLockSync(`${options.codexPath}.ccdx.lock`, () => enableImageProviderUnlocked(options));
+}
+function enableImageProviderUnlocked({ providerConfig, providerPath, codexPath, codexContent, adapterPort, adapterHost }) {
   const codex = computeImageMcpCodexConfig(codexContent, {
     enabled: true,
     adapterPort,
@@ -128,7 +127,11 @@ function enableImageProvider({ providerConfig, providerPath, codexPath, codexCon
   return { codexChanged: codex.changed, config: normalized };
 }
 
-function disableImageProvider({ providerPath, codexPath, codexContent, adapterPort, adapterHost }) {
+function disableImageProvider(options) {
+  if (!fs.existsSync(options.codexPath)) return disableImageProviderUnlocked(options);
+  return withFileLockSync(`${options.codexPath}.ccdx.lock`, () => disableImageProviderUnlocked(options));
+}
+function disableImageProviderUnlocked({ providerPath, codexPath, codexContent, adapterPort, adapterHost }) {
   const codex = computeImageMcpCodexConfig(codexContent, {
     enabled: false,
     adapterPort,
@@ -154,7 +157,7 @@ function disableImageProvider({ providerPath, codexPath, codexContent, adapterPo
   return { changed: providerExists || codex.changed || skill.changed, preservedGuidance: Boolean(skill.preserved) };
 }
 
-export function syncEnabledImageSkill({ home = os.homedir(), codexPath = defaultCodexConfigPath(home), ...options } = {}) {
+export function syncEnabledImageSkill({ home = os.homedir(), env = process.env, codexPath = codexPaths({ env, home }).config, ...options } = {}) {
   return updateImageSkill({ ...options, enabled: true, codexPath });
 }
 
@@ -179,7 +182,7 @@ export async function runImageCommand({
   probeFetchImpl = fetch,
   adapterPort = 2026,
   adapterHost = "127.0.0.1",
-  codexPath = defaultCodexConfigPath(home),
+  codexPath = codexPaths({ env, home }).config,
 } = {}) {
   const providerPath = imageProviderConfigPath({ env, home });
   if (action === "status") {

package/src/cli-options.mjs

@@ -372,7 +372,7 @@ function topicHelp(name, topic) {
     "image-status": `Usage:\n  ${name} image-status\n\nShows provider configuration and locally advertised generation/editing tools without generating an image or exposing its API key.`,
     "auto-review-model": `Usage:\n  ${name} auto-review-model\n\nSelect a Responses model, then an advertised reasoning effort. Enter keeps the default/current choice; q cancels both steps without saving. Effort 0 follows the client (low when omitted). Settings apply only to Auto-review on the next request; no client patch or restart is required for adapters running 0.9.13 or newer.`,
     "suggestion": `The CCDX prediction panel has been retired. Run ${name} suggestion off to safely remove unchanged CCDX registrations. This cleanup does not change native predictions; see ${name} prediction --help for that separate opt-in feature.`,
-    prediction: `Usage:\n  ${name} prediction [status|on|off]\n\nOptional native next-message predictions; off by default. macOS only. Quit Codex before on/off, then restart ccdx. On adds private App-profile certificate trust and an App-only route for chatgpt.com and ab.chatgpt.com. HTTPS on those hosts is decrypted locally; only prediction configuration is changed. No client program files, OS trust, account permissions, MCP or Hooks are changed. Existing proxies are not replaced. Official prediction configuration is preserved; the conversation's model is used. App updates require another compatibility check.`,
+    prediction: `Usage:\n  ${name} prediction [status|on|off]\n\nOptional native next-message predictions; off by default. macOS only. Quit Codex before on/off, then restart ccdx. On adds private App-profile certificate trust and an App-only route for chatgpt.com and ab.chatgpt.com. HTTPS on those hosts is decrypted locally; only prediction configuration is changed. No client program files, OS trust, account permissions, MCP or Hooks are changed. Static HTTP/HTTPS/SOCKS5 proxies and bypass rules are preserved; dynamic PAC/WPAD and CIDR bypass rules are reported as unsupported. Official prediction configuration is preserved; the conversation's model is used. App updates require another compatibility check. Status distinguishes saved preference and observed config traffic from unverified candidate visibility.`,
     update: `Usage:\n  ${name} update [npm|github]\n\nUpdates the global package from the configured npm registry or the latest stable GitHub release. With no source, an interactive terminal prompts for one.`,
     version: `Usage:\n  ${name} --version`,
   };

package/src/cli-status.mjs

@@ -188,6 +188,11 @@ export function formatAdapterStatus({ baseUrl, data }, { commandName = "ccdx", c
     }
   }
   lines.push(status("info", `Models: ${count(models.models)} total; Copilot token ${copilot.token_cached ? `cached (${duration(copilot.token_expires_in_ms)} remaining)` : "not cached"}`));
+  const prediction = data.client_integrations?.prediction;
+  if (prediction) {
+    lines.push(status("info", `Native predictions: ${prediction.configured ? "on" : "off"}; bridge ${prediction.bridge}; client route ${prediction.client_route}; visible candidate unknown`));
+    if (prediction.reason) lines.push(status("warn", terminalCell(prediction.reason).slice(0, 400)));
+  }
   if (data.profiles?.codex) {
     lines.push(status("info", `Profile: ${profileSummary("Codex", data.profiles.codex)}`));
   }

package/src/client-integration.mjs

@@ -0,0 +1,41 @@
+import { ensureCodexConfig } from "./config.mjs";
+import { readImageProviderConfig } from "./image-provider-config.mjs";
+import { ensureCodexThreadCompression } from "./codex-thread-compression.mjs";
+import { runInBackground } from "./startup.mjs";
+import { createPredictionState } from "./native-prediction-state.mjs";
+
+// The CLI composes the services; this module owns optional client integration
+// lifecycle. It never forwards model requests or depends on dashboard rendering.
+export function createClientIntegration({ port, host, info = () => {}, warning = () => {} } = {}) {
+  const prediction = createPredictionState();
+  let native = null;
+  return {
+    async configure() {
+      try {
+        const { retirePredictionIntegration } = await import("./prediction-retirement.mjs");
+        const result = retirePredictionIntegration();
+        if (result.changed) info("Removed the retired CCDX prediction integration");
+        if (result.preserved) warning("Modified prediction settings were preserved");
+      } catch (error) { warning(`${error.message}. Core startup will continue.`); }
+      const enabled = Boolean(readImageProviderConfig());
+      const { imageMcpSkipped } = ensureCodexConfig(port, { host, imageProviderEnabled: enabled });
+      if (enabled && !imageMcpSkipped) {
+        try {
+          const { syncEnabledImageSkill } = await import("./cli-image.mjs");
+          syncEnabledImageSkill({ adapterPort: port, adapterHost: host });
+        } catch (error) { warning(`Image guidance could not be updated: ${error.message}`); }
+      }
+      return { compressionSetup: runInBackground(ensureCodexThreadCompression) };
+    },
+    async start() {
+      try {
+        const { startNativePrediction } = await import("./native-prediction.mjs");
+        native = await startNativePrediction({ state: prediction, warning: info });
+      } catch (error) { prediction.unavailable(error); warning(`${error.message}. Core startup will continue.`); }
+      return native;
+    },
+    pacUrl() { return native?.pacUrl || null; },
+    snapshot() { return { prediction: prediction.snapshot() }; },
+    async close() { await native?.close(); native = null; },
+  };
+}

package/src/codex-config-doctor.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import os from "node:os";
-import path from "node:path";
+import { codexPaths } from "./codex-paths.mjs";
 import { isDeepStrictEqual } from "node:util";
 import { parse } from "smol-toml";
 import { computeUpdatedCodexConfig, initialCodexConfig } from "./config.mjs";
@@ -87,8 +87,8 @@ function checkUrl(value, expected, label) {
     : { kind: "warn", message: `${label} differs from the CCDX address ${expected}` };
 }
 
-export function inspectCodexConfig({ home = os.homedir(), host = "127.0.0.1", port = 2026 } = {}) {
-  const filePath = path.join(home, ".codex", "config.toml");
+export function inspectCodexConfig({ home = os.homedir(), env: processEnv = process.env, host = "127.0.0.1", port = 2026 } = {}) {
+  const filePath = codexPaths({ env: processEnv, home }).config;
   let content;
   try {
     content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(filePath));

package/src/codex-paths.mjs

@@ -0,0 +1,10 @@
+import os from "node:os";
+import path from "node:path";
+
+export function codexPaths({ env = process.env, home = os.homedir() } = {}) {
+  const directory = path.resolve(String(env.CODEX_HOME || "").trim() || path.join(home, ".codex"));
+  const profile = path.resolve(String(env.CODEX_ELECTRON_USER_DATA_PATH || "").trim()
+    || path.join(home, "Library", "Application Support", "Codex"));
+  return { directory, config: path.join(directory, "config.toml"), profile,
+    certificateStore: path.join(profile, "Default", "ServerCertificate") };
+}

package/src/codex-thread-compression.mjs

@@ -6,6 +6,8 @@ import { promisify } from "node:util";
 import { CODEX_APP_BINARY_PATHS } from "./codex-model-catalog.mjs";
 import { parseCodexToml, codexTomlStatements, validateManagedConfigEdit } from "./config-toml.mjs";
 import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
+import { codexPaths } from "./codex-paths.mjs";
+import { withFileLockSync } from "./lock.mjs";
 import { status } from "./status.mjs";
 
 const FEATURE = "local_thread_store_compression";
@@ -70,7 +72,8 @@ export async function codexNeedsThreadCompressionDefault({
 }
 
 export async function ensureCodexThreadCompression({
-  filePath = path.join(os.homedir(), ".codex", "config.toml"),
+  env = process.env, home = os.homedir(),
+  filePath = codexPaths({ env, home }).config,
   probe = codexNeedsThreadCompressionDefault,
 } = {}) {
   try {
@@ -79,11 +82,13 @@ export async function ensureCodexThreadCompression({
     if (!await probe()) return;
     // The client/user may edit the shared file while the asynchronous probe runs.
     // Recompute against its current bytes; explicit opt-outs always win.
-    const updated = computeThreadCompressionDefault(read());
-    if (updated.changed) {
-      atomicWriteFileIfChangedSync(filePath, updated.content);
-      console.log(status("ok", "Enabled Codex local history compression (experimental)"));
-    }
+    withFileLockSync(`${filePath}.ccdx.lock`, () => {
+      const updated = computeThreadCompressionDefault(read());
+      if (updated.changed) {
+        atomicWriteFileIfChangedSync(filePath, updated.content);
+        console.log(status("ok", "Enabled Codex local history compression (experimental)"));
+      }
+    });
   } catch {
     console.warn(status("warn", "Optional Codex history compression setup was skipped; core proxy remains available"));
   }

package/src/config.mjs

@@ -1,13 +1,12 @@
 import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
 import { status } from "./status.mjs";
 import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
 import { adapterBaseUrl } from "./running-adapter.mjs";
 import { isLoopbackHost } from "./security.mjs";
 import { codexTomlStatements, configValue, parseCodexToml, validateManagedConfigEdit } from "./config-toml.mjs";
+import { codexPaths } from "./codex-paths.mjs";
+import { withFileLockSync } from "./lock.mjs";
 
-const CONFIG_PATH = path.join(os.homedir(), ".codex", "config.toml");
 const MODEL_CONTEXT_WINDOW = 1_000_000;
 const MODEL_AUTO_COMPACT_TOKEN_LIMIT = 900_000;
 const IMAGE_MCP_START = "# ccdx:image-mcp:start";
@@ -278,8 +277,13 @@ export function computeImageMcpCodexConfig(content, options = {}) {
   return computeImageConfig(content, options);
 }
 
-export function ensureCodexConfig(adapterPort = 2026, {
-  filePath = CONFIG_PATH,
+export function ensureCodexConfig(adapterPort = 2026, options = {}) {
+  const filePath = options.filePath || codexPaths(options).config;
+  return withFileLockSync(`${filePath}.ccdx.lock`, () => ensureCodexConfigUnlocked(adapterPort, { ...options, filePath }));
+}
+
+function ensureCodexConfigUnlocked(adapterPort = 2026, {
+  filePath,
   host = "127.0.0.1",
   imageProviderEnabled = false,
 } = {}) {
@@ -303,7 +307,7 @@ export function ensureCodexConfig(adapterPort = 2026, {
     console.log(status("ok", `Codex already points to ${baseUrl}`));
   } else {
     atomicWriteFileIfChangedSync(filePath, core.content);
-    console.log(status("ok", content === undefined ? "Created ~/.codex/config.toml" : `Configured Codex base URL: ${baseUrl}`));
+    console.log(status("ok", content === undefined ? `Created Codex configuration: ${filePath}` : `Configured Codex base URL: ${baseUrl}`));
   }
   // Disabled means no image maintenance, including no implicit removal of old
   // or user-owned entries. Explicit disable-image owns the cleanup operation.

package/src/copilot-responses-policy.mjs

@@ -1,10 +1,12 @@
+import { errorEvidenceText } from "./operation-error.mjs";
+
 function cloneJson(value) {
   return value === undefined ? undefined : structuredClone(value);
 }
 
 export function isEncryptedContentVerificationError(statusCode, text) {
   if (statusCode < 400 || !text) return false;
-  const lower = String(text).toLowerCase();
+  const lower = errorEvidenceText(text).toLowerCase();
   const reasoningFailure = lower.includes("encrypted content")
     && lower.includes("could not be verified")
     && (lower.includes("could not be decrypted") || lower.includes("could not be parsed"));
@@ -17,7 +19,7 @@ export function isEncryptedContentVerificationError(statusCode, text) {
 
 export function isImageNamespaceCollisionError(statusCode, text) {
   if (statusCode < 400 || !text) return false;
-  const lower = String(text).toLowerCase();
+  const lower = errorEvidenceText(text).toLowerCase();
   return lower.includes("namespace")
     && lower.includes("image_gen")
     && lower.includes("collid");

package/src/dashboard/index.html

@@ -57,6 +57,13 @@
           <p class="hint" data-i18n>Recent upstream request metadata, not exact live session occupancy. Missing values are unknown. No prompt or image content is retained.</p>
         </details>
 
+        <section class="panel dashboard-section" aria-label="CLIENT FEATURES" data-i18n-label>
+          <div class="panel-heading"><h2 data-i18n>CLIENT FEATURES</h2><span data-i18n>OBSERVED STATE</span></div>
+          <dl class="stats"><div><dt data-i18n>Native predictions</dt><dd id="prediction-preference">—</dd></div><div><dt data-i18n>Local bridge</dt><dd id="prediction-bridge">—</dd></div><div><dt data-i18n>Client route</dt><dd id="prediction-route">—</dd></div><div><dt data-i18n>Visible candidate</dt><dd id="prediction-candidate">—</dd></div></dl>
+          <p id="prediction-note" class="hint">—</p>
+          <p class="hint" data-i18n>Configured does not mean displayed. Use ccdx prediction status for details.</p>
+        </section>
+
         <section class="panel dashboard-section" aria-label="Live upstream models" data-i18n-label>
           <div class="panel-heading"><h2 data-i18n>UPSTREAM GPT MODELS</h2><div class="heading-actions"><span id="models-state" data-i18n>CHECKING LIVE</span><button id="refresh-models" type="button" data-i18n>Refresh</button></div></div>
           <p id="models-note" class="table-note" data-i18n>Querying GitHub Copilot…</p>