codex-copilot-dx 0.7.5 → 0.7.7

package/README.md

@@ -1,6 +1,6 @@
 # codex-copilot-dx
 
-Use Codex App with GPT models provided by your **GitHub Copilot** subscription.
+Use Codex App with GPT models available to your **GitHub Copilot** account.
 
 CCDX is a local compatibility adapter for Codex App. It configures Codex to use an OpenAI Responses API on loopback while GitHub authentication, model discovery, and inference stay backed by GitHub Copilot.
 
@@ -14,7 +14,7 @@ One in-process adapter listens on `127.0.0.1:2026` by default and exposes:
 
 Responses-only models and compaction use Copilot's Responses transport directly. For GPT models that advertise only Chat Completions, CCDX converts the supported text, image, and function-tool subset and rejects incompatible request shapes explicitly. Both streaming SSE and non-streaming responses are supported.
 
-The adapter preserves Codex App behavior around response history, encrypted reasoning state, function/custom tools, images, compaction, cancellation, retries, and usage metadata. Model routing follows the live Copilot catalog instead of a hard-coded GPT model list.
+The adapter handles response history, encrypted reasoning state, function/custom tools, images, compaction, cancellation, retries, and usage metadata within the compatibility boundaries below. Routing prefers endpoint metadata from Copilot's live or cached catalog; when metadata is unavailable, a small built-in set identifies known Responses-only GPT models.
 
 ### Fast and Standard modes
 
@@ -24,13 +24,13 @@ Codex Auto-review uses the hidden `codex-auto-review` model ID. CCDX maps it to
 
 ### GPT-6 model catalog
 
-Codex App requests a versioned, capability-rich model catalog that is different from Copilot's raw model list. CCDX reads the complete catalog bundled with the installed Codex App and preserves every other model entry and capability. It makes `gpt-6-astra` visible only when the live Copilot catalog advertises that exact model as enabled, selectable, OpenAI-owned, and Responses-capable.
+Codex App requests a versioned, capability-rich model catalog that is different from Copilot's raw model list. CCDX reads the complete catalog bundled with the installed Codex App and preserves every other model entry and capability. It exposes the bundled `gpt-6-astra` entry only when Copilot's available catalog advertises that exact model as enabled, selectable, OpenAI-owned, and Responses-capable.
 
-CCDX 0.7.2 exposes only the verified GPT-6 Standard path and removes its unverified speed-tier metadata. Codex Ultra remains available because the client maps it to the model's supported multi-agent reasoning effort. GPT-5.6 Sol Fast remains unchanged. The bundled catalog is matched to the Codex client version, cached by application binary identity, and reloaded automatically after an App update.
+CCDX exposes the GPT-6 Standard path and removes its unverified speed-tier metadata. It leaves the bundled reasoning-effort options unchanged, including Ultra when supplied by the installed catalog. GPT-5.6 Sol Fast follows the separate rule above. Versioned model discovery matches the bundled catalog to the client's `client_version`, caches it by application binary identity, and reloads it after an App update. If a matching usable catalog cannot be loaded, the versioned models request returns `503`; an unversioned request returns the Copilot-style list.
 
 ## Prerequisites
 
-- GitHub Copilot subscription (Individual, Business, or Enterprise)
+- A GitHub account with Copilot access to the desired models
 - Node.js 22.15 or newer, for built-in Zstandard request decompression
 - Codex App on macOS
 
@@ -41,7 +41,7 @@ npm install -g codex-copilot-dx@latest
 ccdx
 ```
 
-`ccdx` is the primary launcher. The old `codex-copilot-dx` executable remains temporarily as a compatibility shim: it prints a deprecation warning at most once every seven days in interactive terminals, runs `ccdx`, and remains silent in scripts. It will be removed in a future breaking release.
+`ccdx` is the primary launcher. The old `codex-copilot-dx` executable remains temporarily as a compatibility shim: it prints a deprecation warning at most once every seven days in interactive terminals, runs `ccdx`, and remains silent in scripts. The warning timestamp is stored under `XDG_CACHE_HOME` or `~/.cache`; `doctor config` bypasses that warning cache to remain read-only. The alias will be removed in a future breaking release.
 
 For a one-off run without a global install:
 
@@ -53,15 +53,29 @@ 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. Refreshes Copilot model metadata and listens on the configured loopback address.
-4. Updates `~/.codex/config.toml` to use the local `/v1` endpoint while preserving unrelated Codex settings.
+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.
 5. Attempts to open Codex App on macOS unless `CCDX_AUTO_LAUNCH` disables it.
 
-The `OPENAI_API_KEY=dummy` value written into 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.
+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.
 
-On startup, CCDX also adds `context_management = true` under `[features]` when the key is missing, creating the section if needed. Existing values, including `false`, are preserved. Existing inline or dotted `features` declarations and nested context-management settings are left intact to avoid conflicting TOML definitions. This enables Codex's development-stage context-management feature by default for users who have not configured it. A configuration that already matches is not rewritten.
+On startup, CCDX also adds `context_management = true` under `[features]` when the key is missing, creating the section if needed. Existing values, including `false`, are preserved. Existing inline or dotted `features` declarations and nested context-management settings are left intact to avoid conflicting TOML definitions. This opts unconfigured users into Codex context management; support and behavior depend on the installed Codex version. A configuration that already matches is not rewritten.
 
-If a compatible adapter is already running, a later launch reuses it and refreshes the local Codex configuration. After updating the package, stop the old adapter before starting the new version; the CLI refuses to silently reuse an incompatible protocol version.
+If a compatible adapter is already running, a later launch reuses it and checks the local Codex configuration. Reuse requires the same package version, protocol version, and required capabilities. After updating the package, stop the old adapter before starting the new version. Installing or updating the package alone does not restart the adapter or update Codex configuration.
+
+### 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.
+
+| Setting | Existing file | New file |
+| --- | --- | --- |
+| Top-level `openai_base_url` | Add or update to the adapter's `/v1` address | Set to the adapter address |
+| `model_context_window` | Add `1000000` only when missing | `1000000` |
+| `model_auto_compact_token_limit` | Add `900000` only when missing | `900000` |
+| `[shell_environment_policy.set]` OpenAI URL/key | Update `OPENAI_BASE_URL` and set `OPENAI_API_KEY="dummy"` when this section is recognized; leave an absent section absent | Create the section and set both keys; set `shell_environment_policy.inherit="core"` |
+| `[features]` `context_management` | Add `true` when missing; preserve explicit values and alternative declarations as described above | `true` |
+
+The two token limits are fixed defaults, not detected model capabilities. Existing custom values are retained. Writes target the listed keys with line-based edits and atomic replacement; this is not a general TOML formatter. The shell environment updater recognizes the literal `[shell_environment_policy.set]` header. Use `ccdx doctor config` to inspect parsed values and preview what this writer would do with the current file. No actual change means no file rewrite.
 
 ## Version 0.7.0 migration
 
@@ -91,7 +105,7 @@ Interactive terminals use aligned tables for `models`, `auth status`, and `usage
 ccdx auto-review-model
 ```
 
-The selector first queries the running adapter, including its last-known-good model list when live refresh is unavailable, then falls back to the non-expired local model cache. It offers only enabled models that advertise a Responses endpoint.
+The selector first queries the running adapter, including its last-known-good model list when live refresh is unavailable, then falls back to a local model cache no older than seven days. It offers model IDs that advertise a Responses endpoint and are not explicitly hidden from the model picker. This selection does not itself verify policy or inference access.
 
 The selection is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set. Choosing `gpt-5.5` clears the override and restores the package default. A running adapter reads the setting on the next Auto-review request.
 
@@ -111,10 +125,14 @@ The selector is ordered numerically:
 4. Chase
 5. Mirror
 6. Pulse
-7. Braille
+7. Stack — short light trails arrive, accumulate, then leave as one bundle
+8. Relay — fixed nodes receive and pass a short light trail
+9. Split — one incoming light trail divides into two outgoing trails
 
 Enter the corresponding number to select an animation. The Comet row includes a static preview, and after a selection CCDX plays one cycle of the chosen animation as confirmation when terminal animation is enabled. The setting is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set.
 
+All nine animations use the same 20-column colon track and cyan/blue palette. They indicate activity, not completion percentage. Braille was removed in 0.7.7. A saved `terminal_animation: "braille"` falls back to Comet without rewriting the settings file; choosing another animation replaces it, and explicitly choosing Comet clears it. Other settings remain intact.
+
 The selected theme is loaded once when a new adapter starts, so changing it does not restart or alter an adapter that is already running. Stop and start CCDX to apply the new theme. `CCDX_TERMINAL_ANIMATION=0` (also `false`, `no`, or `off`) remains the boolean gate that disables terminal animation regardless of the selected theme.
 
 ### Update
@@ -138,13 +156,25 @@ If a configured npm mirror has not synchronized the current release yet, use the
 
 ## Diagnostics
 
-Run a read-only local configuration check:
+Inspect only the local Codex configuration:
+
+```bash
+ccdx doctor config
+```
+
+This command reads `~/.codex/config.toml` and checks UTF-8/TOML syntax, correctly scoped CCDX-managed URL/environment settings, positive integer context limits, their relative ordering, and `features.context_management`. Explicit `false` is valid. A missing optional shell environment section is valid for an existing file. Structured context-management settings are retained and reported as unverified for the installed Codex version.
+
+It also runs the existing startup writer in memory and lists the managed keys that would change. A missing file produces a creation preview. A preview that yields invalid TOML or changes unowned settings is reported as an error rather than applied. No files are written, including debug logs; it does not read credentials, contact the adapter or upstream, start Device Flow, or open Codex App. It uses `ADAPTER_HOST` and `ADAPTER_PORT` for the expected URL. Unrelated startup/probe timeout settings do not affect this config-only command.
+
+The syntax check uses a TOML 1.1 parser and validates only the listed managed fields, not the full installed Codex schema. It does not merge project files, profiles, environment overrides, or command-line overrides into an effective Codex configuration. Syntax errors report line/column without source snippets; configured URL and key values are not printed. The command accepts no `--online`, `--compat`, or write/fix options.
+
+For the broader credential/configuration/adapter diagnostic:
 
 ```bash
 ccdx doctor
 ```
 
-The doctor checks the saved GitHub credential, Codex configuration, and adapter availability without starting the adapter or changing files. It exits with status `1` for an invalid configuration and `0` when results contain only OK or warning rows.
+The ordinary doctor reuses the same configuration checks, inspects the saved GitHub credential, and probes the local adapter. It does not start the adapter or modify credentials or Codex configuration; when `CCDX_LOG_PATH` is set, this broader command can write its diagnostics to that log. Both doctor modes exit `1` when any check is an error, and `0` for OK/warning-only results, including missing configuration or an explicit feature opt-out. Unsupported arguments or invalid relevant CLI options exit `2`.
 
 To verify the saved GitHub token, Copilot entitlement, and live models endpoint without starting Device Flow or changing the credential:
 
@@ -188,19 +218,21 @@ When the saved token is missing, `ccdx` looks for compatible local Copilot GitHu
 
 After an account is selected, automatic `401`/`403` recovery and in-process token rotation accept only that same GitHub account. Concurrent callers share token refresh work without sharing cancellation, and a still-valid Copilot token may be used briefly after a transient refresh failure. Explicit token variables remain the intentional way to select another account.
 
-If refresh still fails with `401` or `403`, the saved GitHub OAuth credential may be expired, revoked, or missing Copilot access. Remove that exact saved token and start again to trigger Device Flow:
+If refresh still fails with `401` or `403`, the saved GitHub OAuth credential may be expired, revoked, or missing Copilot access. After stopping the adapter, remove that exact saved token and start again to rerun authentication recovery:
 
 ```bash
 rm ~/.local/share/copilot-api/github_token
 ccdx
 ```
 
+Recovery first tries compatible local credentials and starts Device Flow only when none can be imported. Set `CCDX_DISABLE_TOKEN_DISCOVERY=1` for that launch if a fresh Device Flow is intended after removing the saved token.
+
 ## Security
 
 - CCDX binds to loopback by default. Non-loopback hosts are rejected unless `CCDX_ALLOW_LAN=1` is set explicitly.
 - Enabling LAN binding exposes a Copilot-backed API to other reachable machines. Provide your own host firewall and network isolation; do not expose the listener to an untrusted network.
 - The GitHub OAuth credential is stored locally at `~/.local/share/copilot-api/github_token`. Short-lived Copilot service tokens remain in process memory and are refreshed as needed.
-- Runtime status, usage, and debug logs exclude authorization headers, prompts, completions, tool arguments, and image content.
+- Runtime status and usage records retain metadata rather than request/response content. Diagnostic logging records status and error messages; it is not a general redaction layer for arbitrary error text. See Debug logging before sharing logs.
 - Request and response bodies are bounded. Queues, history, image work, SSE parsing, retries, and shutdown all have explicit resource or time limits.
 
 ## Configuration
@@ -232,9 +264,9 @@ ccdx
 | `CCDX_TERMINAL_ANIMATION` | auto | Show the selected transient animation while an interactive terminal has active requests and no output for 800 ms; set to `0`, `false`, `no`, or `off` to disable |
 | `CCDX_IMG_MAX_DIM` | `2048` | Maximum long edge in pixels for image downscaling |
 | `CCDX_IMG_QUALITY` | `82` | Initial WebP quality for image re-encoding |
-| `CCDX_IMG_MIN_BYTES` | `100000` | In-bounds images smaller than this remain unchanged; oversized images are still downscaled |
+| `CCDX_IMG_MIN_BYTES` | `100000` | In-bounds images smaller than this skip re-encoding; oversized dimensions still trigger an optimization attempt |
 | `CCDX_IMG_CONCURRENCY` | `2` | Global concurrent image-optimization tasks; values above `12` are capped |
-| `CCDX_IMG_MAX_INPUT_PIXELS` | `40000000` | Maximum decoded pixels accepted for one image |
+| `CCDX_IMG_MAX_INPUT_PIXELS` | `40000000` | Sharp's per-image decode limit; an optimization failure retains the original image, subject to the overall forwarded-body limit |
 | `CCDX_IMG_CACHE_MAX_BYTES` | `67108864` | Process-local byte ceiling for cached image transforms; set to `0` to disable the cache |
 | `CCDX_DISABLE_IMG_OPT` | unset | Set to `1` to disable image optimization |
 | `CCDX_AUTO_LAUNCH` | enabled | Set to `0`, `false`, `no`, or `off` to start without opening Codex App |
@@ -244,10 +276,10 @@ ccdx
 | `CCDX_GITHUB_LOGIN` | saved account | Require automatic discovery and recovery to use this GitHub login |
 | `CCDX_DISABLE_TOKEN_DISCOVERY` | unset | Set to `1` to skip local token discovery and use the saved token or Device Flow |
 | `CCDX_TOKEN_LOCK_TIMEOUT_MS` | `600000` | Maximum time to wait for another process to finish GitHub token login or import |
-| `CCDX_TOKEN_LOCK_STALE_MS` | `900000` | Age after which a stale GitHub-token lock can be removed |
+| `CCDX_TOKEN_LOCK_STALE_MS` | `900000` | Minimum age for stale-lock recovery; a lock with a live owner is not removed |
 | `CCDX_EXISTING_ADAPTER_TIMEOUT_MS` | `500` | Timeout for detecting an already-running local adapter during startup |
 | `CCDX_MODEL_REFRESH_TIMEOUT_MS` | `5000` | Timeout for Copilot model refresh or live Auto-review model lookup |
-| `CCDX_MODEL_REFRESH_INTERVAL_MS` | `7200000` | Model refresh interval; successful lists are cached as last-known-good data |
+| `CCDX_MODEL_REFRESH_INTERVAL_MS` | `7200000` | Periodic model refresh interval; `0` disables periodic refresh, while startup cache/refresh behavior still applies |
 | `CCDX_RESPONSE_HISTORY_MAX_BYTES` | `67108864` | Total in-memory byte budget for locally expanded Responses history |
 | `CCDX_RESPONSE_HISTORY_MAX_ENTRIES` | `4096` | Maximum stored incremental Responses history nodes |
 | `CCDX_USAGE_PATH` | `~/.local/share/codex-copilot-dx/usage.jsonl` | Local JSONL token-usage log |
@@ -267,27 +299,31 @@ The summary covers the current log and its single rotated backup, not an unbound
 
 ## Debug logging
 
-Set `CCDX_LOG_PATH=1` to mirror terminal logs to `~/.local/share/codex-copilot-dx/debug.log`, or provide a custom path. Add `CCDX_LOG_LEVEL=debug` for upstream attempts, retry causes, status codes, and timings. Debug logs do not include prompts, completions, request bodies, or authorization tokens.
+Set `CCDX_LOG_PATH=1` to mirror terminal logs to `~/.local/share/codex-copilot-dx/debug.log`, or provide a custom path. Add `CCDX_LOG_LEVEL=debug` for upstream attempts, retry causes, status codes, and timings. The adapter does not deliberately dump request/response bodies or authorization headers. The log mirror writes console text verbatim, including diagnostic/error messages that can originate in external components, so review logs before sharing them. `ccdx doctor config` bypasses file logging entirely.
 
 ## Large histories and images
 
 Long computer-use sessions can accumulate screenshots that are sent again on later turns. This can increase local preparation time, upstream handshake latency, and the chance of a `413 Payload Too Large` response.
 
-CCDX automatically downsamples embedded screenshots to model-appropriate pixel bounds, with a conservative 2048 px fallback, and initially encodes them as WebP quality 82. It never replaces an image with a larger encoding and uses one global concurrency limit across direct images and function/custom-tool outputs.
+The response-history cache is process-local and byte/entry bounded. Restarting the adapter discards it; a `previous_response_id` stored only in that process becomes unavailable. CCDX does not persist conversation history to disk. Clients can still submit explicit history in the request body, subject to the same limits.
+
+CCDX attempts to downsample inline base64 images to model-appropriate pixel bounds, with a 2048 px long-edge fallback, and initially encodes them as WebP quality 82. It never replaces an image with a larger encoding and uses one global concurrency limit across direct images and function/custom-tool outputs. GIFs and non-inline references are not re-encoded. An encoding/decode failure keeps the original image; the final request-byte limit still applies.
 
 The final serialized UTF-8 body is measured before forwarding. Above the configured limit, unique source images are processed largest-first from their originals at quality 75 / 1600 px and then quality 65 / 1280 px, stopping when the body fits. If necessary, the forwarded view omits older duplicate images, historical tool images, other historical images, and finally old tool outputs while preserving current input and tool-call skeletons. Requests that still do not fit receive a structured local `413`.
 
 Completed image transforms are reused from a byte-bounded process-local LRU cache, and concurrent requests for the same transform share one encode. Failures are not cached and request cancellation remains isolated.
 
-Ordinary visual history stays byte-for-byte unchanged while it has at most 24 historical images and the expanded body is at most 18 MiB. Above either threshold, the temporary upstream view keeps every current-turn image and up to 16 recent historical images, targeting 16 MiB. After a preparation, handshake, upstream timeout, or HTTP `408`, the next retry uses an 8-image, 10 MiB recovery window for ten minutes. Two successful requests or a successful compaction clear recovery mode. CCDX never transparently repeats an ambiguous timed-out POST, and it does not delete local history.
+The visual-history pressure pass does not omit images while there are at most 24 historical images and the expanded body is at most 18 MiB; normal image encoding and other limits still apply. Above either threshold, this pass preserves current-turn images and keeps up to 16 recent historical images, targeting 16 MiB. The separate 50-image and total-body limits remain in force. After an eligible large-visual-history preparation, handshake, upstream timeout, or HTTP `408`, the next retry uses an 8-image, 10 MiB recovery window for ten minutes. Two successful requests or a successful compaction clear recovery mode. CCDX never transparently repeats an ambiguous timed-out POST, and it does not delete local history.
 
 When expanded history exceeds Copilot's 50-image request limit, CCDX removes older duplicate occurrences first and then keeps the 50 most recent images. This affects only the forwarded request; local history remains complete and current images are preferred.
 
 For `/v1/responses/compact`, CCDX sends one terminal `compaction_trigger`, validates completed compaction state, and preserves the complete returned window as the canonical next context. Only a validated window becomes a new local history root. Existing older branches remain available until normal history eviction.
 
-Successful streaming responses are accepted only when the upstream body is SSE and reaches its protocol terminal event. Unexpected EOF becomes a protocol-native stream error, and repeated blank tool-argument deltas are stopped per tool call. Safe quota, retry, model, trace, and upstream request-ID metadata are forwarded; cookies, authorization, body-length, and encoding headers are not.
+Changing the model or transport of a continuation can require removing incompatible encrypted history from the forwarded request. A specific upstream encrypted-state verification failure can also trigger one sanitized retry. CCDX does not decrypt that state locally.
 
-CCDX 0.7.3 keeps each native Responses message on its first upstream ID when Copilot changes that ID during streaming. Message deltas, completion events, and cached history stay consistent, preventing duplicate live messages in Codex App. Tool identities, reasoning/encrypted content, message phases, and speed-tier routing are unchanged. Stable events retain their original SSE bytes; changed events are rewritten with bounded, backpressured streaming.
+Successful streaming responses are accepted only when the upstream body is SSE and reaches its protocol terminal event. Unexpected EOF becomes a protocol-native stream error, and repeated blank tool-argument deltas are stopped per tool call. Allowlisted rate-limit, retry, model, trace, and upstream request-ID metadata are forwarded; cookies, authorization, body-length, and encoding headers are not.
+
+CCDX keeps each native Responses message on its first upstream ID when Copilot changes that ID during streaming. Message deltas, completion events, and cached history stay consistent, addressing this cause of duplicate live messages in Codex App. Tool identities, reasoning/encrypted content, message phases, and speed-tier routing are unchanged by this ID normalization. Stable events retain their original SSE bytes; changed events are rewritten with bounded, backpressured streaming.
 
 Newer Codex App builds can advertise an `image_gen` namespace that already exists upstream. CCDX removes that exact conflicting client tool before forwarding and retries once only when Copilot explicitly reports an image namespace collision. Image input and screenshot optimization remain enabled.
 
@@ -301,7 +337,9 @@ npm run bench:payload
 
 `bench:check` covers both SSE parsers, including native Responses identity rewriting, 1/4/8 MiB fragmented events, write batching, and slow-client backpressure. It also repeats four concurrent image preparations across six rounds using a desktop-sized synthetic screenshot and a public-domain photograph. Checks enforce content preservation, single-pass JSON parsing, bounded copying, cache reuse, settled work, and bounded retained heap/ArrayBuffers after warm-up and GC. Sampled RSS and absolute timings remain report-only because allocators, runtimes, and machines differ; the fixtures do not establish production latency or visual model accuracy.
 
-`npm test` runs unit and handler-level tests. `npm run test:smoke` starts a real local adapter with fully injected offline upstreams. `npm run bench:check` enforces linear SSE scanning, image/tool processing, and request-admission resource limits. `npm run pack:check` verifies npm tarball contents without publishing. `npm run bench:payload` is a report-only isolated-process benchmark for 5–60 MiB image payloads and does not contact Copilot. CI runs verification on the supported Node.js release lines.
+`npm test` runs unit, handler, CLI, and documentation-contract tests. `npm run test:smoke` starts a real local adapter with fully injected offline upstreams. `npm run bench:check` enforces linear SSE scanning, image/tool processing, and request-admission resource limits. `npm run pack:check` verifies npm tarball contents without publishing. `npm run bench:payload` is a report-only isolated-process benchmark for 5–60 MiB synthetic padded-image payloads and does not contact Copilot. CI runs the complete `verify` gate on Node 22.15.0 and 24.x.
+
+The [documentation index](https://github.com/DaleXiao/codex-copilot-dx/blob/main/docs/README.md) distinguishes current guidance from historical release evidence. Release reports retain the measurements and limits of their specific versions; they do not establish current live-provider compatibility.
 
 From a source checkout, `node scripts/codex-message-id-replay.mjs --codex /absolute/path/to/codex` checks message identity against an installed Codex runtime using only synthetic SSE, a local mock server, and automatically cleaned temporary Codex directories. It does not use the real client configuration or call Copilot.
 

package/bin/cli.mjs

@@ -12,7 +12,7 @@ import { runDoctor } from "../src/doctor.mjs";
 import { adapterBaseUrl, checkRunningAdapter } from "../src/running-adapter.mjs";
 import { assertSafeAdapterHost, isLoopbackHost } from "../src/security.mjs";
 import { runInBackground } from "../src/startup.mjs";
-import { cliCommandName, cliHelp, parseAdapterProbeOptions, parseCliArgs, parseRuntimeOptions } from "../src/cli-options.mjs";
+import { cliCommandName, cliHelp, parseAdapterAddressOptions, parseAdapterProbeOptions, parseCliArgs, parseRuntimeOptions } from "../src/cli-options.mjs";
 import { formatAdapterStatus, readAdapterStatus } from "../src/cli-status.mjs";
 import { closeHttpServer } from "../src/shutdown.mjs";
 import { runAutoReviewModelCommand } from "../src/auto-review-model.mjs";
@@ -143,6 +143,23 @@ if (CLI.command === "update") {
     process.exit(1);
   }
 }
+if (CLI.command === "doctor" && CLI.configOnly) {
+  let probe;
+  try {
+    probe = parseAdapterAddressOptions(process.env);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+  }
+  const checks = await runDoctor({
+    commandName: CLI_NAME,
+    configOnly: true,
+    host: probe.adapterHost,
+    port: probe.adapterPort,
+  });
+  process.exit(checks.some((check) => check.kind === "err") ? 1 : 0);
+}
+
 let RUNTIME;
 try {
   RUNTIME = parseRuntimeOptions(process.env);

package/bin/codex-copilot-dx.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-if (process.stderr.isTTY === true) {
+const configDoctor = ["doctor", "--doctor"].includes(process.argv[2]) && process.argv[3] === "config";
+if (process.stderr.isTTY === true && !configDoctor) {
   const {
     LEGACY_COMMAND_WARNING,
     shouldShowLegacyCommandWarning,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Use Codex App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",
@@ -48,6 +48,7 @@
     "prepublishOnly": "npm run verify"
   },
   "dependencies": {
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.3",
+    "smol-toml": "1.8.0"
   }
 }

package/src/cli-options.mjs

@@ -16,6 +16,7 @@ const HELP_TOPICS = new Set([
   "auth",
   "auth status",
   "doctor",
+  "doctor config",
   "status",
   "models",
   "usage",
@@ -126,11 +127,16 @@ export function parseCliArgs(args = []) {
     || (command === "start" && rest.some((option) => RETIRED_CLAUDE_OPTIONS.has(option)))
     || (command === "auth" && rest[0] === "login" && rest[1] === "claude")
     || (command === "models" && requestedProfile === "claude")
-    || (command === "doctor" && ["claude", "all"].includes(requestedProfile));
+    || (command === "doctor" && rest[0] !== "config" && ["claude", "all"].includes(requestedProfile));
   if (PM_COMMANDS.has(command)) return baseCommand("retired", { integration: "PM Studio" });
   if (retiredClaudeInvocation) {
     return baseCommand("retired", { integration: "Claude App and Claude Code" });
   }
+  if ((command === "doctor" || command === "--doctor") && rest[0] === "config") {
+    if (rest.length === 2 && HELP_COMMANDS.has(rest[1])) return helpCommand(["doctor", "config"]);
+    if (rest.length > 1) unexpectedArgs(rest.slice(1));
+    return baseCommand("doctor", { configOnly: true });
+  }
   const requestedHelp = nestedHelp(command, rest);
   if (requestedHelp) return requestedHelp;
   if (VERSION_COMMANDS.has(command)) {
@@ -245,10 +251,16 @@ function integerEnv(env, name, fallback, { min, max = Number.MAX_SAFE_INTEGER })
   return value;
 }
 
-export function parseRuntimeOptions(env = process.env) {
+export function parseAdapterAddressOptions(env = process.env) {
   return {
     adapterPort: integerEnv(env, "ADAPTER_PORT", 2026, { min: 1, max: 65535 }),
     adapterHost: String(env.ADAPTER_HOST || "127.0.0.1").trim() || "127.0.0.1",
+  };
+}
+
+export function parseRuntimeOptions(env = process.env) {
+  return {
+    ...parseAdapterAddressOptions(env),
     modelRefreshTimeoutMs: integerEnv(env, "CCDX_MODEL_REFRESH_TIMEOUT_MS", 5000, { min: 1, max: MAX_TIMER_DELAY_MS }),
     existingAdapterTimeoutMs: integerEnv(env, "CCDX_EXISTING_ADAPTER_TIMEOUT_MS", 500, { min: 1, max: MAX_TIMER_DELAY_MS }),
     modelRefreshIntervalMs: integerEnv(env, "CCDX_MODEL_REFRESH_INTERVAL_MS", 2 * 60 * 60 * 1000, { min: 0, max: MAX_TIMER_DELAY_MS }),
@@ -261,8 +273,7 @@ export function parseRuntimeOptions(env = process.env) {
 
 export function parseAdapterProbeOptions(env = process.env) {
   return {
-    adapterPort: integerEnv(env, "ADAPTER_PORT", 2026, { min: 1, max: 65535 }),
-    adapterHost: String(env.ADAPTER_HOST || "127.0.0.1").trim() || "127.0.0.1",
+    ...parseAdapterAddressOptions(env),
     existingAdapterTimeoutMs: integerEnv(env, "CCDX_EXISTING_ADAPTER_TIMEOUT_MS", 500, { min: 1, max: MAX_TIMER_DELAY_MS }),
   };
 }
@@ -276,12 +287,13 @@ function topicHelp(name, topic) {
     start: `Usage:\n  ${name} [start] [--show-request-id]\n\nStarts or reuses the local adapter, updates Codex configuration, and attempts to open Codex App when auto-launch is enabled and supported.`,
     auth: `Usage:\n  ${name} auth status [--online] [--format table|plain]\n\nShows the saved GitHub Copilot account without exposing credentials. --online also verifies its entitlement and model catalog.`,
     "auth status": `Usage:\n  ${name} auth status [--online] [--format table|plain]\n\nShows the saved GitHub Copilot account without exposing credentials. --online also verifies its entitlement and model catalog. Interactive terminals use a table by default.`,
-    doctor: `Usage:\n  ${name} doctor [--online] [--compat]\n\nChecks the local credential, Codex configuration, and adapter. --online validates account entitlement; --compat sends minimal inference requests and consumes a small amount of Copilot usage.`,
+    doctor: `Usage:\n  ${name} doctor [--online] [--compat]\n  ${name} doctor config\n\nChecks the local credential, Codex configuration, and adapter. --online validates account entitlement; --compat sends minimal inference requests and consumes a small amount of Copilot usage. The config subcommand checks only the local file and previews startup changes, without network, authentication, or file writes.`,
+    "doctor config": `Usage:\n  ${name} doctor config\n\nReads ~/.codex/config.toml, checks TOML syntax and CCDX-managed settings, and previews the existing startup writer's changes. Does not merge Codex profiles or validate the complete installed Codex schema. No authentication, network requests, file writes, or adapter/GUI startup. Existing context_management=false is valid. Exit 1 for errors, 0 for OK/warnings; unsupported arguments exit 2.`,
     status: `Usage:\n  ${name} status\n\nShows bounded runtime, routing, performance, queue, and cache metrics from a running adapter.`,
     models: `Usage:\n  ${name} models [--format table|plain]\n\nPerforms a fresh, read-only Copilot model-directory lookup for the saved account. Interactive terminals use a table by default.`,
     usage: `Usage:\n  ${name} usage [--format table|plain]\n\nSummarizes local token usage metadata without reading prompt or completion content. Interactive terminals use a table by default.`,
     animation: `Usage:\n  ${name} animation\n\nInteractively selects the terminal activity animation used the next time the adapter starts.`,
-    "auto-review-model": `Usage:\n  ${name} auto-review-model\n\nInteractively selects an enabled Responses model for Codex Auto-review.`,
+    "auto-review-model": `Usage:\n  ${name} auto-review-model\n\nInteractively selects an advertised Responses model for Codex Auto-review.`,
     update: `Usage:\n  ${name} update [npm|github]\n\nUpdates the global package from the configured npm registry or GitHub main. With no source, an interactive terminal prompts for one.`,
     version: `Usage:\n  ${name} --version`,
   };
@@ -296,6 +308,7 @@ export function cliHelp(commandName = "ccdx", topic = "") {
   ${name} [start] [--show-request-id]
   ${name} auth status [--online] [--format table|plain]
   ${name} doctor [--online] [--compat]
+  ${name} doctor config
   ${name} status
   ${name} models [--format table|plain]
   ${name} usage [--format table|plain]

package/src/codex-config-doctor.mjs

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { parse } from "smol-toml";
+import { computeUpdatedCodexConfig, initialCodexConfig } from "./config.mjs";
+import { adapterBaseUrl } from "./running-adapter.mjs";
+
+const MANAGED_KEYS = [
+  "openai_base_url",
+  "model_context_window",
+  "model_auto_compact_token_limit",
+  "shell_environment_policy.inherit",
+  "shell_environment_policy.set.OPENAI_BASE_URL",
+  "shell_environment_policy.set.OPENAI_API_KEY",
+  "features.context_management",
+];
+
+function field(config, key) {
+  return key.split(".").reduce((value, part) => (
+    value && Object.hasOwn(value, part) ? value[part] : undefined
+  ), config);
+}
+
+function table(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
+}
+
+function parseConfig(text) {
+  // Keep integer and floating-point TOML values distinct, including large ints.
+  return parse(text, { integersAsBigInt: true });
+}
+
+function unmanagedSettings(config) {
+  const remaining = structuredClone(config);
+  for (const key of MANAGED_KEYS) {
+    const parts = key.split(".");
+    const leaf = parts.pop();
+    const parent = parts.length ? field(remaining, parts.join(".")) : remaining;
+    if (table(parent)) delete parent[leaf];
+  }
+  for (const key of ["shell_environment_policy.set", "shell_environment_policy", "features"]) {
+    const value = field(remaining, key);
+    if (!table(value) || Object.keys(value).length) continue;
+    const parts = key.split(".");
+    const leaf = parts.pop();
+    const parent = parts.length ? field(remaining, parts.join(".")) : remaining;
+    delete parent[leaf];
+  }
+  return remaining;
+}
+
+function startupPreview(content, config, host, port) {
+  const updated = content === null
+    ? { content: initialCodexConfig(port, host), changed: true }
+    : computeUpdatedCodexConfig(content, port, host);
+  if (!updated.changed) return { kind: "ok", message: "No startup configuration changes required" };
+  let next;
+  try {
+    next = parseConfig(updated.content);
+  } catch {
+    return { kind: "err", message: "Startup configuration preview is not valid TOML; review the file before starting ccdx" };
+  }
+  if (!isDeepStrictEqual(unmanagedSettings(config), unmanagedSettings(next))) {
+    return { kind: "err", message: "Startup preview would change settings outside CCDX's managed keys; review the file before starting ccdx" };
+  }
+  const changed = MANAGED_KEYS.filter((key) => !isDeepStrictEqual(field(config, key), field(next, key)));
+  return {
+    kind: "warn",
+    message: changed.length
+      ? `Next startup would ${content === null ? "create the file and set" : "set"}: ${changed.join(", ")}`
+      : "Next startup would rewrite the file; managed key values are unchanged",
+  };
+}
+
+function checkUrl(value, expected, label) {
+  if (value === undefined) return { kind: "warn", message: `${label} is missing` };
+  if (typeof value !== "string") return { kind: "err", message: `${label} must be a string` };
+  // Do not echo configured URLs: userinfo and query strings can contain secrets.
+  return value === expected
+    ? { kind: "ok", message: `${label} points to ${expected}` }
+    : { 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");
+  let content;
+  try {
+    content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(filePath));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return [
+        { kind: "warn", message: `Codex config not found at ${filePath}` },
+        startupPreview(null, {}, host, port),
+      ];
+    }
+    return [{ kind: "err", message: `Cannot read UTF-8 Codex config at ${filePath}` }];
+  }
+
+  let config;
+  try {
+    config = parseConfig(content);
+  } catch (error) {
+    const location = Number.isInteger(error?.line) && Number.isInteger(error?.column)
+      ? ` at line ${error.line}, column ${error.column}`
+      : "";
+    // Parser messages include source snippets. Report only numeric locations.
+    return [{ kind: "err", message: `Invalid TOML in ${filePath}${location}` }];
+  }
+
+  const expectedBaseUrl = `${adapterBaseUrl(host, port)}/v1`;
+  const checks = [
+    { kind: "ok", message: `Codex config is readable TOML: ${filePath}` },
+    checkUrl(config.openai_base_url, expectedBaseUrl, "Codex base URL"),
+  ];
+  for (const key of ["model_context_window", "model_auto_compact_token_limit"]) {
+    const value = field(config, key);
+    checks.push(value === undefined
+      ? { kind: "warn", message: `${key} is missing` }
+      : typeof value === "bigint" && value > 0n
+        ? { kind: "ok", message: `${key} = ${value} (existing value retained)` }
+        : { kind: "err", message: `${key} must be a positive TOML integer` });
+  }
+  if (typeof config.model_context_window === "bigint" && config.model_context_window > 0n
+    && typeof config.model_auto_compact_token_limit === "bigint" && config.model_auto_compact_token_limit > 0n
+    && config.model_auto_compact_token_limit >= config.model_context_window) {
+    checks.push({ kind: "warn", message: "model_auto_compact_token_limit is not below model_context_window; review the custom limits" });
+  }
+
+  const policy = field(config, "shell_environment_policy");
+  const env = field(config, "shell_environment_policy.set");
+  if ((policy !== undefined && !table(policy)) || (env !== undefined && !table(env))) {
+    checks.push({ kind: "err", message: "shell_environment_policy and its set value must be TOML tables" });
+  } else if (env === undefined) {
+    checks.push({ kind: "ok", message: "Optional shell_environment_policy.set table is absent; existing files do not require it" });
+  } else {
+    checks.push(checkUrl(env.OPENAI_BASE_URL, expectedBaseUrl, "Codex shell OPENAI_BASE_URL"));
+    checks.push(env.OPENAI_API_KEY === undefined
+      ? { kind: "warn", message: "Codex shell OPENAI_API_KEY placeholder is missing" }
+      : typeof env.OPENAI_API_KEY !== "string"
+        ? { kind: "err", message: "Codex shell OPENAI_API_KEY must be a string (value hidden)" }
+        : env.OPENAI_API_KEY === "dummy"
+          ? { kind: "ok", message: "Codex shell OPENAI_API_KEY uses the dummy placeholder" }
+          : { kind: "warn", message: "Codex shell OPENAI_API_KEY differs from the dummy placeholder (value hidden)" });
+  }
+
+  const features = field(config, "features");
+  const management = field(config, "features.context_management");
+  if (features !== undefined && !table(features)) {
+    checks.push({ kind: "err", message: "features must be a TOML table" });
+  } else if (management === undefined) {
+    checks.push({ kind: "warn", message: "features.context_management is missing; see the startup preview for whether it will be added" });
+  } else if (typeof management === "boolean") {
+    checks.push({ kind: "ok", message: `features.context_management = ${management} (${management ? "enabled" : "explicitly disabled"}; retained)` });
+  } else if (table(management)) {
+    checks.push({ kind: "warn", message: "Structured context-management settings are retained; installed Codex support is not verified" });
+  } else {
+    checks.push({ kind: "err", message: "features.context_management must be a boolean for the basic feature flag" });
+  }
+  checks.push(startupPreview(content, config, host, port));
+  return checks;
+}

package/src/config.mjs

@@ -135,7 +135,7 @@ export function computeUpdatedCodexConfig(content, adapterPort = 2026, adapterHo
   return { content: lines.join("\n") + (hadTrailingNewline ? "\n" : ""), changed };
 }
 
-function initialCodexConfig(adapterPort, adapterHost) {
+export function initialCodexConfig(adapterPort, adapterHost) {
   const baseUrl = `${adapterBaseUrl(adapterHost, adapterPort)}/v1`;
   return `openai_base_url = "${baseUrl}"
 model_context_window = ${MODEL_CONTEXT_WINDOW}

package/src/doctor.mjs

@@ -11,6 +11,9 @@ import { status } from "./status.mjs";
 import { buildHeaders, FALLBACK_VSCODE_VERSION, parseApiBase } from "./copilot.mjs";
 import { adapterBaseUrl, checkRunningAdapter } from "./running-adapter.mjs";
 import { CODEX_AUTO_REVIEW_MODEL } from "./models.mjs";
+import { inspectCodexConfig } from "./codex-config-doctor.mjs";
+
+export { inspectCodexConfig };
 
 function localGatewayBaseUrl(host, port) {
   const safeHost = String(host || "127.0.0.1");
@@ -26,22 +29,12 @@ function readText(filePath) {
   }
 }
 
-function tomlString(content, key) {
-  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const match = new RegExp(`^\\s*${escaped}\\s*=\\s*"([^"]*)"`, "m").exec(content);
-  return match?.[1] || "";
-}
-
 function displayPath(home, filePath) {
   const rel = path.relative(home, filePath);
   if (!rel.startsWith("..") && !path.isAbsolute(rel)) return `~/${rel}`;
   return filePath;
 }
 
-function valueLabel(value) {
-  return value ? `"${value}"` : "missing";
-}
-
 function copilotModelData(models) {
   const data = Array.isArray(models) ? models : models?.data;
   return Array.isArray(data) ? data : [];
@@ -282,29 +275,6 @@ export async function inspectAuthProfilesOnline(options = {}) {
   return inspectGitHubTokenOnline(options);
 }
 
-export function inspectCodexConfig({ home = os.homedir(), host = "127.0.0.1", port = 2026 } = {}) {
-  const filePath = path.join(home, ".codex", "config.toml");
-  const expectedBaseUrl = `${adapterBaseUrl(host, port)}/v1`;
-  const config = readText(filePath);
-  if (!config.ok) {
-    return [{ kind: "warn", message: `Codex config not found at ${displayPath(home, filePath)}` }];
-  }
-
-  const checks = [];
-  const baseUrl = tomlString(config.text, "openai_base_url");
-  checks.push(baseUrl === expectedBaseUrl
-    ? { kind: "ok", message: `Codex base URL points to ${expectedBaseUrl}` }
-    : { kind: "warn", message: `Codex base URL is ${valueLabel(baseUrl)}; expected "${expectedBaseUrl}"` });
-
-  const missing = [];
-  if (tomlString(config.text, "OPENAI_BASE_URL") !== expectedBaseUrl) missing.push("OPENAI_BASE_URL");
-  if (tomlString(config.text, "OPENAI_API_KEY") !== "dummy") missing.push("OPENAI_API_KEY");
-  checks.push(missing.length === 0
-    ? { kind: "ok", message: "Codex shell env local API keys are configured" }
-    : { kind: "warn", message: `Codex shell env local API keys need update: ${missing.join(", ")}` });
-  return checks;
-}
-
 function connectHost(host) {
   const normalized = String(host || "127.0.0.1").replace(/^\[(.*)\]$/, "$1");
   if (normalized === "0.0.0.0") return "127.0.0.1";
@@ -332,6 +302,7 @@ export async function collectDoctorChecks({
   host = "127.0.0.1",
   port = 2026,
   checkAdapter = true,
+  configOnly = false,
   checkAdapterListeningFn = checkAdapterListening,
   checkRunningAdapterFn = checkRunningAdapter,
   online = false,
@@ -342,6 +313,7 @@ export async function collectDoctorChecks({
   compatTimeoutMs = 120000,
   inspectAdapterCompatibilityFn = inspectAdapterCompatibility,
 } = {}) {
+  if (configOnly) return inspectCodexConfig({ home, host, port });
   checkedDoctorProfile(profile);
   const checks = [
     ...inspectAuthProfiles({ home }),
@@ -406,7 +378,7 @@ export async function runDoctor(options = {}) {
     options.online ? "--online" : "",
     options.compat ? "--compat" : "",
   ].filter(Boolean);
-  log(`${options.commandName || "ccdx"} doctor${flags.length ? ` ${flags.join(" ")}` : ""}`);
+  log(`${options.commandName || "ccdx"} doctor${options.configOnly ? " config" : flags.length ? ` ${flags.join(" ")}` : ""}`);
   const checks = await collectDoctorChecks(options);
   for (const check of checks) log(status(check.kind, check.message));
   const totals = { ok: 0, warn: 0, err: 0 };

package/src/terminal-animation.mjs

@@ -5,7 +5,7 @@ export const DEFAULT_TERMINAL_ANIMATION_THEME = "comet";
 
 const TAIL_LENGTH = 7;
 const TAIL_COLORS = Object.freeze([159, 123, 87, 51, 45, 39, 33]);
-const BRAILLE_GLYPHS = Object.freeze(["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]);
+const RELAY_ROUTE = Object.freeze([2, 9, 16, 9, 2]);
 
 function colorCell(glyph, color) {
   return `${ESC}[${color}m${glyph}${ESC}[0m`;
@@ -39,6 +39,25 @@ function pingPongState(index) {
     : { position: period - offset, direction: -1 };
 }
 
+function setGlowCell(cells, index, level) {
+  const color = level === 0 ? "97" : `38;5;${TAIL_COLORS[Math.min(level - 1, TAIL_LENGTH - 1)]}`;
+  setCell(cells, index, ":", color);
+}
+
+function stackState(index) {
+  // Three incoming packets each leave three cells parked on the left.
+  for (let parked = 0; parked < 9; parked += 3) {
+    const travelFrames = TERMINAL_ANIMATION_TRACK_WIDTH - parked;
+    if (index < travelFrames) {
+      return { parked, head: TERMINAL_ANIMATION_TRACK_WIDTH - 1 - index, delayMs: 55 };
+    }
+    if (index === travelFrames) return { parked: parked + 3, delayMs: 180 };
+    index -= travelFrames + 1;
+  }
+  // Release the accumulated bundle, then leave a blank frame before restarting.
+  return { shift: index, delayMs: index === 0 ? 130 : index === 21 ? 180 : 50 };
+}
+
 const THEME_DEFINITIONS = Object.freeze([
   Object.freeze({
     id: "comet",
@@ -137,15 +156,84 @@ const THEME_DEFINITIONS = Object.freeze([
     },
   }),
   Object.freeze({
-    id: "braille",
-    label: "Braille",
-    frameCount: BRAILLE_GLYPHS.length,
-    frameDelayMs: 80,
+    id: "stack",
+    label: "Stack",
+    frameCount: 76,
+    frameDelayMs: 55,
+    loopPauseMs: 0,
+    startFrame: 0,
+    frameDelay(index) {
+      return stackState(index).delayMs;
+    },
+    render(index) {
+      const cells = blankTrack();
+      const state = stackState(index);
+      if (state.shift !== undefined) {
+        for (let column = 0; column < 9; column += 1) {
+          setGlowCell(cells, state.shift + column, 8 - column);
+        }
+      } else {
+        for (let column = 0; column < state.parked; column += 1) setGlowCell(cells, column, 5);
+        if (state.head !== undefined) drawComet(cells, state.head, -1, 2);
+      }
+      return wrapTrack(cells);
+    },
+  }),
+  Object.freeze({
+    id: "relay",
+    label: "Relay",
+    frameCount: 40,
+    frameDelayMs: 85,
     loopPauseMs: 0,
     startFrame: 0,
+    frameDelay(index) {
+      const phase = index % 10;
+      return phase === 0 ? 220 : phase < 7 ? 85 : 70;
+    },
     render(index) {
       const cells = blankTrack();
-      setCell(cells, Math.floor(TERMINAL_ANIMATION_TRACK_WIDTH / 2), BRAILLE_GLYPHS[index], `38;5;${TAIL_COLORS[2]}`);
+      const leg = Math.floor(index / 10);
+      const from = RELAY_ROUTE[leg];
+      const to = RELAY_ROUTE[leg + 1];
+      const phase = index % 10;
+      const active = phase === 0 ? from : phase >= 7 ? to : -1;
+      const level = phase >= 7 ? [0, 1, 3][phase - 7] : 0;
+      for (let center = 2; center <= 16; center += 7) {
+        for (let offset = -1; offset <= 1; offset += 1) {
+          setGlowCell(cells, center + offset, center === active ? level + Math.abs(offset) * 2 : 7);
+        }
+      }
+      if (phase > 0 && phase < 7) {
+        const direction = Math.sign(to - from);
+        drawComet(cells, from + direction * phase, direction, 2);
+      }
+      return wrapTrack(cells);
+    },
+  }),
+  Object.freeze({
+    id: "split",
+    label: "Split",
+    frameCount: 29,
+    frameDelayMs: 65,
+    loopPauseMs: 0,
+    startFrame: 0,
+    frameDelay(index) {
+      return index < 10 ? 70 : index < 13 ? 80 : index < 28 ? 65 : 220;
+    },
+    render(index) {
+      const cells = blankTrack();
+      if (index < 10) {
+        drawComet(cells, index, 1, 4);
+      } else if (index < 13) {
+        const level = [2, 0, 1][index - 10];
+        for (let offset = -2; offset <= 2; offset += 1) {
+          setGlowCell(cells, 9 + offset, level + Math.abs(offset));
+        }
+      } else if (index < 28) {
+        const distance = index - 13;
+        drawComet(cells, 9 - distance, -1, 4);
+        drawComet(cells, 10 + distance, 1, 4);
+      }
       return wrapTrack(cells);
     },
   }),

package/src/user-settings.mjs

@@ -37,7 +37,8 @@ export function readUserSettings({ env = process.env, home = os.homedir(), stric
     }
     if (Object.hasOwn(parsed, TERMINAL_ANIMATION_KEY)) {
       const value = parsed[TERMINAL_ANIMATION_KEY];
-      if (!isTerminalAnimationTheme(value)) {
+      // Accept the retired value on read so upgrades can fall back and select a replacement.
+      if (value !== "braille" && !isTerminalAnimationTheme(value)) {
         const choices = TERMINAL_ANIMATION_THEMES.map(({ id }) => id).join(", ");
         if (strict) {
           throw invalidSettings(filePath, `${TERMINAL_ANIMATION_KEY} must be one of: ${choices}`);