codex-copilot-dx 0.9.23 → 0.9.25

package/README.md

@@ -5,6 +5,7 @@ Use Codex App with GitHub Copilot through a local adapter.
 CCDX targets Codex App. It discovers Copilot models, adapts the client's model
 catalog, and preserves Responses streaming, tool calls and conversation history.
 Default Auto-review: **GPT-6.1 Sol / low**. Image generation is **off by default**.
+Native predictions are also **off by default**.
 
 ## Install and run
 
@@ -29,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 |
@@ -38,14 +39,13 @@ The dashboard does not poll in the background; refresh when needed.
 | `ccdx models` | Fresh upstream model list |
 | `ccdx usage` | Recorded tokens and upstream prompt-cache hit rate |
 | `ccdx auto-review-model` | Select model, then reasoning effort; `0` follows client |
-| `ccdx suggestion on` / `ccdx suggestion off` | Enable or disable the optional next-message panel |
-| `ccdx suggestion model` / `ccdx suggestion status` | Choose its model by number, or check settings |
 | `ccdx animation` | Preview and select terminal animation |
 | `ccdx cache --limit 128` | Set the history-cache budget in MiB |
 | `ccdx cache --clean` | Clear the rebuildable image-transform cache |
 | `ccdx limits --decoded 256` | Set the decoded request-body budget; restart to apply |
 | `ccdx enable-image` | Opt in to image generation/editing with your own API |
 | `ccdx image-status` / `ccdx disable-image` | Check or disable optional images |
+| `ccdx prediction on` / `off` / `status` | Opt in to native next-message predictions (macOS) |
 | `ccdx update` | Update the global package |
 
 ## Compatibility and safety
@@ -64,20 +64,17 @@ The dashboard does not poll in the background; refresh when needed.
   break continuations. Generated images and Codex transcripts are not deleted.
 - Optional image setup/maintenance never blocks the primary service. Disabled
   users get no CCDX image skill or MCP installation.
-- Next-message suggestions are **off by default**. Opt in with `ccdx suggestion on`,
-  then open **Next message / 下一句** in a local conversation panel or ask Codex for
-  a next-message suggestion. **Add to draft / 加入草稿** appends ordinary text; it
-  never sends, replaces your draft, or patches the client. Default model:
-  `gpt-6-luna`, with `low` reasoning when advertised. Requires a running local
-  adapter and a recent Codex with paginated thread reads and MCP draft support.
-- Suggestions read only a bounded page from the host-identified current thread.
-  Images, reasoning items and tool outputs are excluded. On supported runtimes,
-  `suggestion on` configures an async Stop hook; review it in Codex before it runs.
-  CCDX never grants trust. The panel reads saved suggestions; adding drafts is manual.
-  The dashboard shows settings and generation status. Model selection alone stays off.
-  Existing user-managed MCP/profile configuration is preserved. Native prediction
-  settings are untouched; account/remote defaults in all future clients cannot be
-  reliably detected. Use `ccdx suggestion off` when preferring an official feature.
+- The manual prediction MCP, background hook and dashboard panel are retired.
+  Startup removes only unchanged CCDX registrations and disables saved prediction
+  settings. The optional image MCP remains unchanged. Modified old registrations
+  can use inert compatibility entrypoints; they no longer generate suggestions.
+- Native predictions are a separate, opt-in compatibility feature. Quit Codex,
+  run `ccdx prediction on`, then restart CCDX. This adds App-profile certificate
+  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. 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.
@@ -87,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();
@@ -77,8 +74,24 @@ if (CLI.command === "image") {
 }
 if (CLI.command === "suggestion") {
   try {
-    const { runSuggestionCommand } = await import("../src/cli-suggestion.mjs");
-    await runSuggestionCommand({ action: CLI.action, model: CLI.model, commandName: CLI_NAME });
+    const { retirePredictionIntegration } = await import("../src/prediction-retirement.mjs");
+    const result = retirePredictionIntegration({ dryRun: CLI.action === "status" });
+    console.log("The CCDX prediction panel has been retired and cannot be enabled.");
+    if (CLI.action === "status" && result.changed) console.log(`Legacy settings remain; run ${CLI_NAME} suggestion off to clean them up.`);
+    if (result.preserved) console.warn("Modified prediction settings were preserved.");
+    process.exit(0);
+  } catch (error) {
+    console.error(status("err", error.message));
+    process.exit(1);
+  }
+}
+if (CLI.command === "prediction") {
+  try {
+    const { runPredictionCommand } = await import("../src/native-prediction.mjs");
+    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));
@@ -251,6 +264,17 @@ const LOGGING = configureLogging();
 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}`));
@@ -272,7 +296,18 @@ async function reuseRunningAdapterIfAvailable() {
   console.log(status("ok", `Using existing adapter at ${running.baseUrl}`));
   const { compressionSetup } = await configureCodexClient();
 
-  await openCodex();
+  let predictionPacUrl = null;
+  let predictionApp = null;
+  try {
+    const { readPredictionSettings } = await import("../src/native-prediction-profile.mjs");
+    const preference = readPredictionSettings();
+    if (preference.enabled) {
+      predictionPacUrl = running.data?.native_prediction_pac || null;
+      predictionApp = preference.app?.app;
+      if (!predictionPacUrl) console.warn(status("warn", "Restart ccdx to activate the newly enabled prediction bridge"));
+    }
+  } catch (error) { console.warn(status("warn", error.message)); }
+  await openCodex({ predictionPacUrl, predictionApp });
   console.log(`
   ${status("ok", "Ready, using the existing ccdx adapter")}
 
@@ -285,17 +320,7 @@ async function reuseRunningAdapterIfAvailable() {
 }
 
 async function configureCodexClient() {
-  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") {
@@ -369,13 +394,18 @@ try {
     streamHandshakeTimeoutMs: RUNTIME.streamHandshakeTimeoutMs,
     streamIdleTimeoutMs: RUNTIME.streamIdleTimeoutMs,
     terminalAnimationTheme,
+    nativePredictionPac: () => nativePrediction?.pacUrl || null,
+    clientIntegrationSnapshot: () => clientIntegration?.snapshot() || null,
   });
 
   // Point Codex App at the adapter.
   const { compressionSetup } = await configureCodexClient();
 
-  // Launch Codex when available.
-  await openCodex();
+  // Optional native prediction setup must never prevent the core adapter from running.
+  nativePrediction = await (await clientIntegrations()).start();
+
+  // Launch Codex when available. A running App is never forcibly restarted.
+  await openCodex({ predictionPacUrl: nativePrediction?.pacUrl, predictionApp: nativePrediction?.app });
 
   // Periodically refresh the model list + endpoint cache so a long-running
   // adapter picks up newly released models without a restart.
@@ -404,6 +434,7 @@ try {
     let exitCode = 0;
     try {
       if (modelRefreshTimer) clearInterval(modelRefreshTimer);
+      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();
@@ -420,6 +451,7 @@ try {
   await compressionSetup;
 } catch (e) {
   console.error(status("err", e.message));
+  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

@@ -6,78 +6,124 @@ CCDX is a local compatibility adapter for Codex App. It configures Codex to use
 
 ## How it works
 
-### Optional next-message suggestions
-
-Suggestions are disabled by default. No suggestion MCP or skill is installed at
-startup, and the primary adapter does not start a predictor.
+### Retired prediction integration
+
+The manual prediction MCP, automatic Stop hook and dashboard panel are removed.
+CCDX does not install a prediction skill or replacement predictor. Startup disables
+the old `suggestion.json` preference and removes only unchanged CCDX declarations
+from the active `CODEX_HOME/config.toml` (or `~/.codex/config.toml`).
+`CCDX_SUGGESTION_CONFIG` still identifies the legacy settings path for cleanup.
+For an immediate cleanup without starting the adapter, run `ccdx suggestion off`.
+The old `suggestion on` and `suggestion model` commands cannot re-enable it.
+
+Modified, inline and profile-specific declarations are preserved. Cleanup failures
+do not block the core adapter. Saved model preferences and old candidate files are
+not deleted; they are inactive. Native Codex preference settings, hook trust records,
+other hooks and the optional image MCP are untouched. Two inert compatibility
+entrypoints prevent user-modified registrations from invoking a removed module:
+the old Hook exits with an empty result, and the old MCP exposes no tools or panel.
+
+### Optional native predictions
+
+Native next-message predictions are **off by default** and use no MCP, Hook, skill,
+panel, renderer injection, or client-program modification. This macOS-only
+compatibility feature uses the App's existing composer UI and the conversation's
+selected model through CCDX. Suggestions are not sent automatically. Native
+eligibility rules still apply; availability is not promised for every thread type.
 
 ```bash
-ccdx suggestion on
-ccdx suggestion off
-ccdx suggestion model
-ccdx suggestion model gpt-6.1-sol
-ccdx suggestion status
+# Fully quit Codex App first.
+ccdx prediction on
+# Restart the running CCDX process, then launch Codex through ccdx.
+ccdx
+ccdx prediction status
+
+# To remove the optional setup, fully quit Codex first:
+ccdx prediction off
 ```
 
-Start CCDX, enable suggestions, then open **Next message / 下一句** from a local
-conversation panel, or ask Codex for a next-message suggestion. **Add to draft /
-加入草稿** appends ordinary text and never sends. The user still presses Send.
-If the MCP has not appeared in an open App, restart the App once. There is no
-client patch, grey ghost text, automatic draft insertion, or auto-approval.
-Model selection alone keeps the feature disabled. The initial model is
-`gpt-6-luna`; `low` reasoning is used when advertised. No service tier is forced.
-
-Settings are stored in `suggestion.json` beside CCDX's `config.json`.
-`CCDX_SUGGESTION_CONFIG` overrides this file path; the managed MCP sets it to
-the exact saved file, so normal users do not need to set it. The managed
-MCP is `mcp_servers.ccdx_suggestion` in the active `CODEX_HOME/config.toml` (or
-`~/.codex/config.toml`). Existing user-managed, inline or profile-specific entries
-are preserved rather than overwritten; identical enabled setup is a no-op.
-Native prediction settings are never changed. Official account/remote defaults
-currently have no reliable generic local signal, so CCDX does not promise to
-detect every future client default. Use `suggestion off` when preferring native
-predictions. An unavailable capability reports a local error, not a fallback
-that edits the client or sends a chat message.
-
-The MCP uses the host-supplied thread ID and the installed Codex's paginated
-`thread/items/list` API. It reads at most 24 recent items, retaining up to eight
-user/assistant text excerpts and 16,000 characters. Images, reasoning items and
-tool outputs are excluded; there is no transcript scan, fork or resumed turn.
-Recent text is sent through the local CCDX adapter to the selected Copilot model
-when requested manually, or after a reply through the separately reviewed optional
-hook described below. Provider data policies still apply.
-Context lookup is capped at 5 seconds/2 MiB, the operation at 30 seconds, output
-at 64 KiB/300 characters, concurrent work at two, and in-memory candidates at 16.
-Candidates expire for adoption after 10 minutes and are bound to their thread
-and selected model. Failure/HTTP 200 incomplete responses never become drafts.
-No additional retry is added by the suggestion feature. Existing adapter policies
-remain unchanged. App support requires MCP draft insertion; the executable can
-be selected explicitly with `CCDX_CODEX_BINARY` when automatic discovery fails.
-
-On supported macOS/Linux Codex runtimes, `suggestion on` also registers an
-asynchronous `Stop` hook. It generates after a finished reply only after the user
-reviews and trusts that exact `suggestion-auto.mjs` command through Codex's normal
-hook review screen (`/hooks` in Codex CLI). CCDX never writes hook trust or bypasses
-review. Existing handlers and native prediction settings are preserved. Windows,
-unsupported hook runtimes and conflicting hook declarations keep the manual panel.
-Existing 0.9.22 users can run `ccdx suggestion on` once to configure the hook.
-
-Automatic work has one local slot, a 30-second deadline, no added retries and one
-attempt per observed turn. It checks the latest turn before and after inference;
-newer turns or changed settings discard the result. The hook does not start a new
-turn, send a message, edit a draft or wait on the foreground reply. Enabled users
-incur additional selected-model usage after replies. `suggestion off` removes only
-the unchanged CCDX hook and disables both automatic and manual requests.
-
-Only the candidate and generation metadata are saved locally in `suggestion-state`
-beside settings, with at most 32 entries. Candidates expire for adoption after ten
-minutes; stale files are pruned on the next automatic operation. No context excerpts
-are saved there. The loopback dashboard reads settings and safe recent status only;
-it does not invoke a model or confirm hook trust. Refresh it after changing settings.
-Opening Next message reads a current cached candidate without a second model call.
-The user must still choose **Add to draft**, then Send. Closed panels cannot access
-the composer, and the host exposes no atomic empty-draft insertion; automatic
-draft filling is therefore intentionally unavailable.
+Enabling explicitly adds a private certificate trust record to the selected App
+profile and a process-scoped PAC route for `chatgpt.com` and `ab.chatgpt.com` only.
+HTTPS traffic for **all paths on those two hosts** is decrypted and forwarded
+locally; PAC cannot select HTTPS paths before TLS. Only the bootstrap prediction
+flag, prediction configuration, and corresponding Statsig refresh values are
+overlaid. Other paths preserve upstream status, cookies, streaming and WebSocket
+traffic. Upstream TLS verification stays enabled; no OS trust, global proxy, login,
+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.
+
+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
+check. Updating the App invalidates that check: quit it and run `prediction on`
+again. Unknown client/store/configuration formats are not forcibly rewritten.
+These are checked compatibility boundaries, not a promise for every future App.
+
+The bridge changes only its own prediction fields and preserves already-enabled
+official prediction configuration. A missing prediction-config route can receive
+CCDX's own short JSON-suggestion prompt using low reasoning effort. Authentication,
+permission, rate-limit and server errors are returned unchanged. Full and live
+refresh schemas are supported; delta requests ask for complete values to avoid
+merging upstream checksums with locally changed fields. Configuration bodies are
+bounded at 16 MiB; larger or unknown bodies pass through without an overlay.
+No extra inference or bridge exists for users who leave the feature disabled.
+When enabled, prediction requests consume Copilot usage; the setting does not
+provide a separate prediction-model picker.
+
+`prediction off` immediately disables new local overlays. Quit/reopen Codex to
+clear its cached predictions and temporary route. If the App is still running,
+trust removal is deferred; quit it and run `prediction off` again. Only the exact
+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 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 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
 
@@ -133,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.
@@ -148,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 |
 | --- | --- | --- |
@@ -310,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.23",
+  "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

@@ -64,7 +64,7 @@ export {
 
 const ADAPTER_RUNTIME_CONFIG = loadRuntimeConfig();
 const DASHBOARD_PATHS = new Set(["/", "/ui.css", "/theme.js", "/language.js", "/ui.js"]);
-const DASHBOARD_API_PATHS = new Set(["/_ccdx/ui/animation", "/_ccdx/ui/models/live", "/_ccdx/ui/usage", "/_ccdx/ui/auth", "/_ccdx/ui/suggestion"]);
+const DASHBOARD_API_PATHS = new Set(["/_ccdx/ui/animation", "/_ccdx/ui/models/live", "/_ccdx/ui/usage", "/_ccdx/ui/auth"]);
 
 export function requestPath(reqUrl) {
   return new URL(reqUrl || "/", "http://localhost").pathname;
@@ -236,13 +236,16 @@ export function createAdapterHandler(options = {}) {
         codexClient,
         codexModelRegistry,
         codexModelCatalog,
+        clientIntegrations: options.clientIntegrationSnapshot?.(),
       })));
       return;
     }
 
     if (req.method === "GET" && pathname === ADAPTER_HEALTH_PATH) {
       res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify(adapterHealthPayload()));
+      const predictionPac = isLoopbackAddress(req.socket?.remoteAddress) && isLoopbackHostHeader(req.headers?.host)
+        ? options.nativePredictionPac?.() : null;
+      res.end(JSON.stringify({ ...adapterHealthPayload(), ...(predictionPac ? { native_prediction_pac: predictionPac } : {}) }));
       return;
     }