codex-copilot-dx 0.9.22 → 0.9.24

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
 
@@ -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,18 +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. There is no background
-  prediction or startup hook; selecting a model alone does not enable the feature.
-  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. Existing proxies are not replaced.
+  See the reference for restart, rollback and client-version boundaries.
 - 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.

package/bin/cli.mjs

@@ -77,8 +77,21 @@ 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 });
     process.exit(0);
   } catch (error) {
     console.error(status("err", error.message));
@@ -251,6 +264,7 @@ const LOGGING = configureLogging();
 let activeServer = null;
 let modelRefreshTimer = null;
 let shuttingDown = false;
+let nativePrediction = null;
 
 if (LOGGING.filePath) {
   console.log(status("info", `Debug log: ${LOGGING.filePath}`));
@@ -272,7 +286,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,6 +310,14 @@ 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) {
@@ -369,13 +402,20 @@ try {
     streamHandshakeTimeoutMs: RUNTIME.streamHandshakeTimeoutMs,
     streamIdleTimeoutMs: RUNTIME.streamIdleTimeoutMs,
     terminalAnimationTheme,
+    nativePredictionPac: () => nativePrediction?.pacUrl || 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.
+  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.`)); }
+
+  // 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 +444,7 @@ try {
     let exitCode = 0;
     try {
       if (modelRefreshTimer) clearInterval(modelRefreshTimer);
+      await nativePrediction?.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 +461,7 @@ try {
   await compressionSetup;
 } catch (e) {
   console.error(status("err", e.message));
+  await nativePrediction?.close().catch(() => {});
   await closeHttpServer(activeServer, { timeoutMs: RUNTIME.shutdownTimeoutMs }).catch(() => {});
   await flushUsageWrites();
   await LOGGING.cleanup();

package/docs/REFERENCE.md

@@ -6,52 +6,86 @@ 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 import or 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 background prediction, 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
-only when the user requests a suggestion. 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.
+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.
+
+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
+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 direct routing; 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
+`~/.config/codex-copilot-dx/native-prediction/` (or under `XDG_CONFIG_HOME`).
 
 ### Core adapter
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.9.22",
+  "version": "0.9.24",
   "description": "Use Codex App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/src/adapter.mjs

@@ -242,7 +242,9 @@ export function createAdapterHandler(options = {}) {
 
     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;
     }
 

package/src/cli-options.mjs

@@ -28,6 +28,7 @@ const HELP_TOPICS = new Set([
   "image-status",
   "auto-review-model",
   "suggestion",
+  "prediction",
   "update",
   "version",
 ]);
@@ -252,11 +253,18 @@ export function parseCliArgs(args = []) {
     if (rest.length) unexpectedArgs(rest);
     return baseCommand("animation");
   }
+  if (command === "prediction") {
+    const [action = "status", ...extra] = rest;
+    if (!["on", "off", "status"].includes(action)) throw new Error("Prediction action must be on, off, or status");
+    if (extra.length) unexpectedArgs(extra);
+    return baseCommand("prediction", { action });
+  }
   if (command === "suggestion") {
     const [action = "status", model, ...extra] = rest;
     if (!["on", "off", "model", "status"].includes(action)) throw new Error("Suggestion action must be on, off, model, or status");
     if (extra.length || (model !== undefined && action !== "model")) unexpectedArgs(rest.slice(1));
-    return baseCommand("suggestion", { action, ...(model !== undefined ? { model } : {}) });
+    if (["on", "model"].includes(action)) throw new Error("The CCDX prediction panel has been retired; use ccdx prediction for the separate optional native feature");
+    return baseCommand("suggestion", { action });
   }
   if (command === "enable-image" || command === "disable-image" || command === "image-status") {
     if (rest.length) unexpectedArgs(rest);
@@ -363,7 +371,8 @@ function topicHelp(name, topic) {
     "disable-image": `Usage:\n  ${name} disable-image\n\nDisables the local CCDX image tool and removes its stored API credential and unmodified CCDX image guidance.`,
     "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": `Usage:\n  ${name} suggestion on\n  ${name} suggestion off\n  ${name} suggestion model [MODEL_ID]\n  ${name} suggestion status\n\nOptional next-message panel; disabled by default. Open it in a local Codex conversation to generate a suggestion, then choose Add to draft. Ordinary text only: no client patch, background prediction, automatic insertion or sending. Model selection alone does not enable the feature. Requires a running local adapter and recent Codex. Existing user-owned MCP configuration is preserved; native prediction settings are never modified. Future account/remote defaults cannot be universally detected.`,
+    "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.`,
     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`,
   };
@@ -389,7 +398,7 @@ export function cliHelp(commandName = "ccdx", topic = "") {
   ${name} disable-image
   ${name} image-status
   ${name} auto-review-model
-  ${name} suggestion on|off|model|status
+  ${name} prediction [status|on|off]
   ${name} update [npm|github]
   ${name} --version
   ${name} --help
@@ -408,7 +417,7 @@ Commands:
   disable-image      Disable the image provider and remove its credential
   image-status       Show the optional image provider status
   auto-review-model  Select the Codex Auto-review model and reasoning effort
-  suggestion         Optional next-message suggestions (off by default)
+  prediction         Toggle optional native next-message predictions
   update             Update the global package from npm or GitHub
 
 Run ${name} <command> --help for command details.`;

package/src/launcher.mjs

@@ -36,7 +36,7 @@ export function launchAttempts() {
   return [["-b", CODEX_BUNDLE_ID], ...APP_PATH_CANDIDATES.map((path) => [path])];
 }
 
-export async function openCodex({ env = process.env, spawnImpl = spawn, platform = process.platform } = {}) {
+export async function openCodex({ env = process.env, spawnImpl = spawn, platform = process.platform, predictionPacUrl = null, predictionApp = null } = {}) {
   if (platform !== "darwin") {
     console.log(status("warn", "Auto-launch is only supported on macOS"));
     console.log(status("info", "Open Codex App manually; it will connect to the adapter."));
@@ -48,7 +48,12 @@ export async function openCodex({ env = process.env, spawnImpl = spawn, platform
     return false;
   }
 
-  for (const args of launchAttempts()) {
+  const extraArgs = typeof predictionPacUrl === "string" && /^http:\/\/127\.0\.0\.1:\d{1,5}\/proxy\.pac$/.test(predictionPacUrl)
+    && APP_PATH_CANDIDATES.includes(predictionApp)
+    ? ["--args", `--proxy-pac-url=${predictionPacUrl}`] : [];
+  const attempts = extraArgs.length ? [[predictionApp]] : launchAttempts();
+  for (const attempt of attempts) {
+    const args = [...attempt, ...extraArgs];
     if (await tryOpen(args, { spawnImpl })) {
       console.log(status("ok", "Codex app launched"));
       return true;

package/src/native-prediction-overlay.mjs

@@ -0,0 +1,92 @@
+export const NATIVE_PREDICTION_GATE = "4290031608";
+
+const LOCAL_PREDICTION_CONFIG = Object.freeze({
+  is_enabled: true,
+  prompt: 'Predict one useful next message the user may send, based on the conversation. Write from the user\'s perspective and use the user\'s language. Do not answer the message, call tools, or invent new requests, consent, or permission. Prefer a short, natural follow-up. If no useful follow-up is apparent, use an empty string. Return only a JSON object with exactly one key: {"suggestion":"the predicted user message"}.',
+  prompt_version: "ccdx-native-prediction-v1",
+  prediction_reasoning_effort: "low",
+});
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseBody(body) {
+  if (typeof body !== "string" && !Buffer.isBuffer(body)) return null;
+  try { return JSON.parse(body.toString()); } catch { return null; }
+}
+
+function encodeBody(value, original) {
+  const text = JSON.stringify(value);
+  return Buffer.isBuffer(original) ? Buffer.from(text) : text;
+}
+
+export function classifyNativePredictionPath({ hostname, pathname } = {}) {
+  const host = typeof hostname === "string" ? hostname.toLowerCase() : "";
+  if (host === "chatgpt.com") {
+    if (pathname === "/backend-api/wham/statsig/bootstrap") return "bootstrap";
+    if (pathname === "/backend-api/wham/predictions/config") return "config";
+  }
+  if (host === "ab.chatgpt.com" && pathname === "/v1/initialize") return "refresh";
+  return null;
+}
+
+function enablePredictionGate(payload) {
+  if (!isObject(payload) || (payload.response_mode === "live_overlay" ? payload.has_updates === false : payload.has_updates !== true) ||
+      (payload.is_delta !== undefined && payload.is_delta !== false) ||
+      (payload.response_mode !== undefined && !["full", "live_overlay"].includes(payload.response_mode)) ||
+      !isObject(payload.feature_gates)) return false;
+  // Statsig V1 first resolves the literal name, then its djb2 lookup key.
+  let hash = 0;
+  for (const char of NATIVE_PREDICTION_GATE) hash = ((hash << 5) - hash + char.charCodeAt(0)) | 0;
+  const hashedKey = String(hash >>> 0);
+  const key = Object.hasOwn(payload.feature_gates, NATIVE_PREDICTION_GATE) ? NATIVE_PREDICTION_GATE
+    : Object.hasOwn(payload.feature_gates, hashedKey) ? hashedKey : NATIVE_PREDICTION_GATE;
+  const gate = payload.feature_gates[key];
+  if (gate !== undefined && (!isObject(gate) || typeof gate.value !== "boolean" || gate.value === true)) return false;
+  if (payload.response_mode === "live_overlay" && !Array.isArray(payload.live_entity_names?.feature_gates)) return false;
+  if (gate) gate.value = true;
+  else payload.feature_gates[key] = { name: key, value: true, rule_id: "ccdx-local-compatibility", secondary_exposures: [] };
+  if (payload.response_mode === "live_overlay" && !payload.live_entity_names.feature_gates.includes(key)) {
+    payload.live_entity_names.feature_gates.push(key);
+  }
+  return true;
+}
+
+// No-op results retain the original bytes; callers own HTTP headers and decoding.
+export function applyNativePredictionOverlay({ hostname, pathname, statusCode, body, enabled = false } = {}) {
+  const kind = classifyNativePredictionPath({ hostname, pathname });
+  const result = { body, statusCode, changed: false, official: false, kind };
+  if (!enabled || !kind) return result;
+  if (kind === "config" && statusCode === 404) {
+    return { ...result, statusCode: 200, body: encodeBody(LOCAL_PREDICTION_CONFIG, body), changed: true };
+  }
+  if (statusCode !== 200) return result;
+  const parsed = parseBody(body);
+  if (!isObject(parsed)) return result;
+  if (kind === "config") {
+    if (parsed.is_enabled === true) return { ...result, official: true };
+    if (parsed.is_enabled !== false || typeof parsed.prompt !== "string" || !parsed.prompt.trim()) return result;
+    parsed.is_enabled = true;
+  } else if (kind === "bootstrap") {
+    const stringPayload = typeof parsed.statsigPayload === "string";
+    const payload = stringPayload ? parseBody(parsed.statsigPayload) : parsed.statsigPayload;
+    if (!enablePredictionGate(payload)) return result;
+    if (stringPayload) parsed.statsigPayload = JSON.stringify(payload);
+  } else if (!enablePredictionGate(parsed)) return result;
+  return { ...result, body: encodeBody(parsed, body), changed: true };
+}
+
+// Overlaying a delta would invalidate its checksum. Ask for a full response instead.
+export function normalizeStatsigRequest({ hostname, pathname, body, enabled = false } = {}) {
+  const result = { body, changed: false };
+  if (!enabled || classifyNativePredictionPath({ hostname, pathname }) !== "refresh") return result;
+  const parsed = parseBody(body);
+  if (!isObject(parsed) || !isObject(parsed.user) ||
+      (parsed.responseMode !== undefined && !["full", "live_overlay"].includes(parsed.responseMode))) return result;
+  if (parsed.deltasResponseRequested === false && parsed.full_checksum === null && parsed.sinceTime === 0) return result;
+  parsed.deltasResponseRequested = false;
+  parsed.full_checksum = null;
+  parsed.sinceTime = 0;
+  return { body: encodeBody(parsed, body), changed: true };
+}