dsh-codex-connect 0.1.0-alpha.4.4 → 0.1.0-alpha.4.40

package/INSTALL.md

@@ -1,7 +1,11 @@
 # Installation Runbook for CLI Agents
 
+Published Alpha 4.39 is verified with DSH `0.1.2-rc.1` and pi-ai `0.84.4` within `^0.84.2`, and with each exact DSH `0.1.5-alpha.1`, `0.1.5-rc.1`, and `0.1.5-rc.2` model-runtime pairing using pi-ai `0.85.1`.
+
 Install `dsh-codex-connect` into one requested DeepSeek Harness profile without changing its current default model, search route, global configuration, or OAuth state.
 
+Channel snapshot on 2026-09-21: npm `alpha` points to `0.1.0-alpha.4.39`; `latest` intentionally remains on `0.1.0-alpha.4.34`. Use the exact-version commands below for 4.39. Publishing an Alpha and promoting the default installation channel are separate actions.
+
 ## Safety requirements
 
 - Never read, print, copy, move, or modify `~/.codex/auth.json`.
@@ -12,28 +16,97 @@ Install `dsh-codex-connect` into one requested DeepSeek Harness profile without
 
 ## Install and validate
 
-1. Check `dsh --version` or `dsh --help`. From a Harness checkout use `pnpm dsh`.
-2. Install the package:
+### Select an exact version before installation
+
+Check `dsh --version` before changing the requested profile. Use `dsh --help` to locate the CLI if needed; from a Harness checkout use `pnpm dsh --version`. The CLI string alone does not identify every installed model-runtime package: a CLI reporting `0.1.5-rc.1` can resolve `0.1.5-rc.2` packages. When the plugin is already installed, also run `dsh plugin --profile web exec dsh-codex-connect doctor --json` and inspect the installed `@deepseek-ai/dsh-llm`, `@deepseek-ai/dsh-llm-pi-ai`, and pi-ai versions. Substitute the requested profile. Select an exact pair from [verified-compatibility.json](verified-compatibility.json):
+
+| Installed DSH version | Codex Connect version to pin |
+| --- | --- |
+| `0.1.0-rc.7` | `0.1.0-alpha.4.14` |
+| `0.1.1-rc.2` | `0.1.0-alpha.4.21` |
+| `0.1.2-alpha.2` | `0.1.0-alpha.4.23` |
+| `0.1.2-rc.1` | `0.1.0-alpha.4.39` |
+| `0.1.2-alpha.5` | `0.1.0-alpha.4.25` |
+| `0.1.5-alpha.1` | `0.1.0-alpha.4.39` |
+| `0.1.5-rc.1` | `0.1.0-alpha.4.39` |
+| `0.1.5-rc.2` | `0.1.0-alpha.4.39` |
+
+If your exact DSH version is unknown or not listed, preserve the installed host, report that the combination is unverified, and verify it before making installation changes. A missing record does not prove incompatibility, and the catalog's latest verified DSH version is not the latest upstream release. Do not recommend upgrading or downgrading DSH merely to match a row. Investigate any specific failure and seek verification of the installed combination. Do not blindly install `dsh-codex-connect@alpha`: `alpha` is a moving tag, not a compatibility guarantee. Do not infer support for newer DSH versions from these rows.
+
+Alpha 4.39 requires one consistent DSH plugin API version: `0.1.2-rc.1` with `@earendil-works/pi-ai` `^0.84.2`, or one of `0.1.5-alpha.1`, `0.1.5-rc.1`, and `0.1.5-rc.2` with pi-ai `0.85.1`; Node.js remains `^22.19.0 || >=24.0.0`. Mixed host versions and other DSH/pi-ai combinations remain unverified. Alpha 4.25 remains the verified choice for DSH `0.1.2-alpha.5`, Alpha 4.23 remains the verified choice for DSH `0.1.2-alpha.2`, Alpha 4.21 remains the verified choice for DSH `0.1.1-rc.2`, and staying on DSH `0.1.0-rc.7` means selecting Alpha 4.14. Changing DSH is a separate operation requiring the user's explicit request; a plugin update request does not authorize it. The repository's `pnpm --silent run check:compatibility` remains a strict development/release dependency gate, not a recommendation to change a user's host.
+
+The Alpha 4.39 recommendation follows successful exact-release main CI, 1,037 local tests, 32 Chromium tests, and a four-host same-artifact installation matrix with 40 fresh native-compaction lifecycle processes. Independent post-publication download verified that npm's archive is byte-identical to the tested artifact; the Git tag and GitHub prerelease resolve to the exact release commit. These are synthetic-provider installation/lifecycle checks, not new real-account acceptance or a newly exercised published-package upgrade. See [.github/ALPHA_439_PUBLICATION.md](.github/ALPHA_439_PUBLICATION.md). Native context management remains opt-in. Stock DSH 0.1.6-alpha.1 and alpha.2 remain undeclared; their separate compatibility trackers are not broadened by this release.
+
+Historical Alpha 4.35 evidence (not relabeled as 4.37):
+
+The Alpha 4.35 rows reflect successful release-commit CI on Node 22.19.0 and 24.20.0 (840 tests each), 28 Chromium tests, Windows canary contracts, and the four-host installation/Reserve matrix. Independent post-publication checks installed the exact npm version on all four hosts, matched all 63 installed plugin files to the verified published archive, and exercised a 4.34-to-4.35 upgrade on rc.2. All eight advertised models resolved and prepared, defaults were unchanged, all optional capabilities remained disabled, and provider disposal and synthetic Reserve transitions passed. These checks are not fresh real OAuth, live Reserve/model/tool/image, or full Windows application acceptance. See [.github/ALPHA_435_RELEASE_READINESS.md](.github/ALPHA_435_RELEASE_READINESS.md) for publication, installation evidence, and limitations. Historical rows remain the repository's existing verification record. This guidance does not change upstream DSH behavior or resolve [Issue #64](https://github.com/franksong2702/dsh-codex-connect/issues/64).
+
+Alpha 4.33 omits the `modelErrors` profile field required by RC model packages, producing `Cannot read properties of undefined (reading 'get')`. Alpha 4.34 contains the fix, retained in 4.35. Reauthorization or repeated model-list retries do not add a missing profile field. Pin the corrected plugin version for a verified host combination; do not delete credentials or change DSH merely to work around this failure. DSH `0.1.5-alpha.2` remains unverified.
+
+### Install the selected version and validate
+
+1. Complete the version selection above. The commands below use `web`; substitute only the requested profile.
+2. Install the selected exact version. For DSH `0.1.0-rc.7`:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.14
+   ```
+
+   For DSH `0.1.1-rc.2`, use Alpha 4.21:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.21
+   ```
+
+   For DSH `0.1.2-alpha.2`, use Alpha 4.23:
 
    ```sh
-   dsh plugin --profile web add dsh-codex-connect@alpha
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.23
    ```
 
-   To pin this release exactly, use `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.4`. If npm is unavailable, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.4'`.
+   For DSH `0.1.2-rc.1`, `0.1.5-alpha.1`, `0.1.5-rc.1`, or `0.1.5-rc.2`, use Alpha 4.39:
 
-3. Run `dsh --profile web --dump-config` and require exactly one `llm-openai-codex` row loading `dsh-codex-connect`.
-4. Confirm the effective `agent-default-model` and `web.searchProvider` values are unchanged from before installation.
-5. Run secret-free diagnostics:
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.39
+   ```
+
+   For DSH `0.1.2-alpha.5`, use Alpha 4.25:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.25
+   ```
+
+   If npm is unavailable after the matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.21'` only for the DSH `0.1.1-rc.2` combination, `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.23'` only for the DSH `0.1.2-alpha.2` combination, `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.25'` only for the DSH `0.1.2-alpha.5` combination, or `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.39'` only for the DSH `0.1.2-rc.1`, `0.1.5-alpha.1`, `0.1.5-rc.1`, or `0.1.5-rc.2` combinations.
+
+3. Run `dsh web --help` once to compose the installed profile without starting the server. DSH `0.1.2-rc.1` prepares profile plugin dependency fallback during this step.
+4. Run `dsh --profile web --dump-config` and require exactly one `llm-openai-codex` row loading `dsh-codex-connect`.
+5. Confirm the effective `agent-default-model` and `web.searchProvider` values are unchanged from before installation.
+6. Run secret-free diagnostics:
 
    ```sh
    dsh plugin --profile web exec dsh-codex-connect doctor
    ```
 
-6. If the user explicitly requests login, open **Settings → Plugins → Plugin configuration → Codex Connect**, or check `status` and then use `login` or `login --device-code`. OAuth approval belongs to the user.
+7. If the user explicitly requests login, open **Settings → Plugins → Plugin configuration → Codex Connect**, or check `status` and then use `login` or `login --device-code`. OAuth approval belongs to the user.
+
+   Alpha 4.25 offers the same account actions in **Settings → Models → Openai-Codex**, plus a shared **More settings** dialog for model visibility, proxy, search, image, context-budget, and Auto-review controls. The original Plugin settings entry remains available; neither entry automatically starts login or changes model/search defaults.
+
+   When signed out, select **Authorize**. When signed in, use **Sign out** or **View quota**; use **More settings** for plugin options. If authorization is abandoned, use **Reopen authorization** or **Cancel sign-in** and retry; cancellation does not delete an existing account. Pending authorization expires after 10 minutes by default (`oauthTimeoutMs` in plugin configuration, applied on load).
+
+### Remote browser access
+
+The default Web OAuth boundary is loopback-only. When DSH runs on one device and you open it from another device on a trusted network through an IP address or domain, run the following on the device that runs DSH with the exact origin from the browser address bar:
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect trust-origin http://192.168.1.20:3080
+dsh plugin --profile web exec dsh-codex-connect trusted-origins
+```
+
+The value is a full `http://` or `https://` origin including its port, not a bare device IP and not a path/query/fragment. Use `untrust-origin <origin>` to remove it. Restrict this to a trusted network and never expose the route publicly; use an SSH tunnel when that is safer. The Web client does not edit this list.
 
 ## Optional configuration
 
-Use **Settings → Plugins → Plugin configuration → Codex Connect** for live, staged Save/Discard edits. The package row accepts the same `enableSearch` and `enableImageTool` fields as its composition base, both defaulting to `false`. Enabling search registers a provider but does not select it; selecting `web.searchProvider: openai-codex` is a second explicit profile change. Setting `agent-default-model` to `openai-codex` is also a separate explicit change.
+Use **Settings → Plugins → Plugin configuration → Codex Connect** for live, staged Save/Discard edits organized under Account & quota, Models, Network, and Capabilities. Switching modules preserves the draft. The same settings control `enableSearch`, `enableReserveFallback`, `enableImageTool`, `enableImageGeneration`, and `enableAutoReview`; all five default to `false`. Luna Reserve is a published experiment in Alpha 4.35: enable it only when explicitly requested, never as an automatic installation step. Real-account Reserve entry and recovery remain unverified; authorization must come from the identity-matched backend response, not a generic `429` or quota percentage. Enabling Auto-review permits bounded approval context, tool arguments, working directory, and the planned action to be sent to `chatgpt.com`; failures return to human approval. Enabling image generation uses the image generation capability included with the current GPT subscription and saves results as DSH attachments. Enabling search registers the provider and selects it while the capability remains enabled; disabling restores the previous provider before unregistering Codex Search. Setting `agent-default-model` to `openai-codex` remains a separate explicit change.
 
 Apply only requested choices and preserve unrelated keys:
 
@@ -41,20 +114,19 @@ Apply only requested choices and preserve unrelated keys:
 - id: llm-openai-codex
   config:
     enableSearch: true
+    enableReserveFallback: false
     enableImageTool: false
+    enableImageGeneration: false
+    enableAutoReview: false
     searchMode: live
 
-- id: web
-  config:
-    searchProvider: openai-codex
-
 - id: agent-default-model
   config:
     provider: openai-codex
     model: gpt-5.6-sol
 ```
 
-Do not add the last two rows unless the user separately requested those routing changes.
+Do not add a separate `web` row for this UI action. Do not add the `agent-default-model` row unless the user separately requested that default.
 
 ## Conflict handling
 
@@ -62,6 +134,10 @@ Do not add the last two rows unless the user separately requested those routing
 
 ## Update and removal
 
+The update card checks Codex Connect releases only. It does not assess the installed host or recommend a DSH upgrade or downgrade. Run `doctor --json` explicitly for local dependency diagnostics; an `unverified` result (and its nonzero exit code) means the installed combination is outside the declared support set, not that it is known to fail. See the [diagnostic statuses](docs/reference.md#local-installation-diagnostics).
+
+Before updating, repeat the exact-version selection above. Use `@alpha` only after verifying that the version it currently resolves to is compatible with the installed DSH; otherwise pin the selected version in the update command.
+
 ```sh
 dsh plugin --profile web update dsh-codex-connect@alpha
 dsh plugin --profile web remove dsh-codex-connect

package/MIGRATION.md

@@ -10,3 +10,34 @@
 6. Run `--dump-config`, then `dsh-codex-connect doctor`. Do not run OAuth again when `status` already reports signed in.
 
 Rollback is the inverse package swap. Do not delete or copy the separate OAuth file during either direction. If Harness reports a duplicate `openai-codex` adapter, the old bundle or a manual provider row is still active; resolve that one row instead of changing credentials.
+
+## Astra reasoning selections
+
+The plugin's Astra fallback definition offers `low`, `medium`, `high`, `xhigh`, and `max`. An omitted `reasoningEffort` preserves the provider default; it does not select Low or disable reasoning. The native dependency definition still takes precedence when present.
+
+Before using Astra with a saved `minimal` or `off` selection, update the selected conversation and, if applicable, the default model setting:
+
+| Saved value | Selection preserving its effective request behavior |
+| --- | --- |
+| `minimal` | Select `Low` (`reasoningEffort: low`); both send `low`. |
+| `off` | Select `Default` (provider default), omitting `reasoningEffort`; both omit wire `reasoning`. This never guaranteed disabled reasoning. |
+
+Other valid explicit efforts remain unchanged. A saved `minimal`, `off`, or unsupported `none` request is rejected with `UNSUPPORTED_REASONING_EFFORT` before authentication or model traffic; the plugin does not silently change it. `none` has no supported prior behavior to preserve: choose a valid effort or `Default` explicitly. The plugin does not rewrite settings or historical Session events. Use the conversation model selector for an existing Session; changing only the default model does not replace that Session's explicit selection. OAuth credentials do not need migration.
+
+## Repairing search history written by Alpha 4.10
+
+Alpha 4.10 briefly wrote `web/openai-codex-search-llm-request` as a required private Session event. Because an external plugin cannot extend the Host persistence vocabulary across independent module instances, a newer Harness can refuse to read those histories after the event writer is removed.
+
+Upgrade Codex Connect, then inspect the default `$DSH_HOME/sessions` root without changing it:
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect migrate-history --json
+```
+
+If the dry run reports affected events, stop every DSH process that can write this Session root and apply the migration. `--confirm-stopped` is required together with `--apply`:
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect migrate-history --apply --confirm-stopped --json
+```
+
+The migration changes only that retired event's envelope by adding `"ignorable": true`. It preserves event data, sequence, time, and the concatenated Zstandard frame layout, and creates `session.jsonl.zstd.pre-codex-search-history-migration` beside every changed artifact before replacing it. Keep that backup until you have reopened and verified the repaired Session. Re-running the command is safe. For a non-default JSONL persistence root, pass `--root /absolute/path/to/sessions`. SQLite and uncompressed JSONL stores are not modified by this command. Applying fails closed when the filesystem cannot create the required same-directory hard-link backup. Applying is also fail-closed on Windows; Windows users can run the dry-run only.

package/NOTICE

@@ -13,3 +13,8 @@ release validation.
 
 The upstream material and the Codex Connect modifications are distributed
 under the Apache License, Version 2.0 included in LICENSE.
+
+This product also includes OAuth login and refresh code from earendil-works/pi
+(@earendil-works/pi-ai 0.84.4), under the MIT license reproduced in
+docs/licenses/pi-ai-oauth.txt. JWT payload decoding, callback connection cleanup
+and structured refresh rejection handling are modified.

package/README.i18n.yaml

@@ -1,6 +1,6 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# Bilingual-pair consistency record: the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   git hash-object README.md docs/README.zh.md
-README.md: 16d921296b08e7b01cb9cf3cf5ade516544acba5
-docs/README.zh.md: 3de5c7920bf27ec7e72cc8d67941578a31b5a00b
+README.md: dd62e2e61bb8541efc785538d1510afb37c4e221
+docs/README.zh.md: 4bf1f92786f86c484343b57a8259dd5a769a2a26

package/README.md

@@ -1,112 +1,143 @@
 # Codex Connect
 
-[![npm version](https://img.shields.io/npm/v/dsh-codex-connect?label=npm&color=cb3837)](https://www.npmjs.com/package/dsh-codex-connect)
+[![npm version](https://img.shields.io/npm/v/dsh-codex-connect/alpha?label=npm%20alpha&color=cb3837)](https://www.npmjs.com/package/dsh-codex-connect)
 
 English | [中文](docs/README.zh.md)
 
-Connect your ChatGPT subscription to DeepSeek Harness with OAuth, user-controlled defaults, Harness-native approvals, diagnostics, and reliable session recovery.
+Connect your ChatGPT subscription to DeepSeek Harness with OAuth, optional GPT Image generation, user-controlled defaults, Harness-native approvals, diagnostics, and reliable session recovery.
 
-`dsh-codex-connect` adds the `openai-codex` model catalog and a separate ChatGPT OAuth login. Models run through Harness's normal LLM service, so streaming, tool calls, reasoning replay, compaction, filesystem controls, permission gates, and approval prompts remain Harness-owned. It does not turn a ChatGPT subscription into an OpenAI Platform API credential.
+Community Alpha — not affiliated with or endorsed by OpenAI, ChatGPT, Codex, DeepSeek, or DeepSeek Harness.
 
-Installation is additive. The bundle does not replace the current default model or search route, and its standalone search provider and `view_image` tool are disabled until explicitly enabled.
+Codex Connect adds the `openai-codex` model provider to the normal Harness agent loop. Harness continues to manage tools, permissions, approvals, attachments, session persistence, compaction, and recovery. Installing the plugin does not change your default model or search route, and it does not turn a ChatGPT subscription into an OpenAI Platform API key.
 
-## Install
+## Quick start
+
+This guide describes the published pairings below. Check `dsh --version` first and use `doctor --json` to inspect the installed model-runtime packages: an rc.1 CLI can resolve rc.2 packages. For other versions, use [Installation and upgrades](INSTALL.md). A moving npm tag such as `alpha` is not a compatibility guarantee.
+
+| Requirement | Verified pairing |
+|---|---|
+| Codex Connect | `0.1.0-alpha.4.39` |
+| DeepSeek Harness | `0.1.2-rc.1`, `0.1.5-alpha.1`, `0.1.5-rc.1`, or `0.1.5-rc.2` |
+| Node.js | `^22.19.0 \|\| >=24.0.0` |
+| Account | ChatGPT OAuth with access to the requested Codex model; availability is decided by OpenAI |
+
+As of 2026-09-21, npm `alpha` points to 4.39 while `latest` intentionally remains on 4.34. Use the exact version below for 4.39; this recommendation does not promote the default installation channel.
+
+### 1. Install
 
 ```sh
-dsh plugin --profile web add dsh-codex-connect@alpha
+dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.39
 dsh web
 ```
 
-To pin this release exactly, use `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.4`. If npm is unavailable, use the GitHub tag fallback: `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.4'`. From a DeepSeek Harness source checkout, prefix commands with `pnpm`. For a local checkout, install `link:/absolute/path/to/dsh-codex-connect`.
+Replace `web` with your existing profile name; use that same profile when starting Harness. From a DSH source checkout, prefix commands with `pnpm`. See [INSTALL.md](INSTALL.md) for other profiles and installation checks.
+
+### 2. Authorize and select a model
+
+Open **Settings → Models → Openai-Codex → Authorize**, then complete approval yourself in the browser. If an embedded window is blocked, select **Open ChatGPT sign-in page**. Choose an `openai-codex` model in the normal Harness model picker.
+
+Never paste an authorization URL, code, token, or account identifier into an issue, log, chat, or configuration file. For a browser on another device, the optional manual callback form can complete the pending login without forwarding the localhost callback port; follow [Remote browser authorization](docs/reference.md#remote-browser-authorization).
 
-Sign in from **Settings → Plugins → Plugin configuration → Codex Connect → Sign in with ChatGPT**, or use the CLI:
+### 3. Check the installation
 
 ```sh
-dsh plugin --profile web exec dsh-codex-connect login
-dsh plugin --profile web exec dsh-codex-connect status
-dsh plugin --profile web exec dsh-codex-connect doctor
+dsh plugin --profile web exec dsh-codex-connect status --json
+dsh plugin --profile web exec dsh-codex-connect doctor --json
 ```
 
-The doctor command reads process and filesystem metadata only. It never opens the OAuth document or prints a token, authorization URL, authorization code, account id, or auth-file content.
+`status --json` exits `0` when signed in and `1` when signed out, without starting OAuth. `doctor --json` reports local installation diagnostics without a network request or raw credentials. A passing diagnostic is not proof of model access; verify that with an actual request.
 
-## Explicit configuration
+<p align="center">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/en/hero.jpg" alt="Codex Connect — ChatGPT OAuth for DeepSeek Harness" width="100%">
+</p>
 
-Open **Settings → Plugins → Plugin configuration → Codex Connect** to manage the ChatGPT account and optional capabilities in one card. Changes use Harness's revision-fenced settings store and apply live. **Save changes** affects only this plugin's capability section; it never selects a default model or global search route.
+## Core capabilities
 
-The installed bundle row remains the composition base and is intentionally inert beyond model-provider registration:
+- **Accounts:** save up to 16 accounts on the DSH host and manually select the active account for subsequent requests. Account selection is not a per-session binding. Requests keep their captured account; the plugin does not rotate accounts or silently fail over.
+- **Models and Astra support:** the currently verified DSH and plugin combination supports `gpt-6-astra`. The plugin supplies its missing model definition with Low, Medium, High, Xhigh, and Max reasoning levels; Default preserves the provider default. Saved Off/Minimal selections require an [explicit update](MIGRATION.md#astra-reasoning-selections). When the installed dependency catalog includes Astra, the plugin preserves its native metadata while retaining these five calibrated reasoning choices. A model appearing in the list does not mean the current account has permission to use it; overall compatibility with new dependency versions still requires separate verification.
+- **Fast Mode:** request priority service for one conversation, off by default. Actual speed and quota consumption depend on the service; no fixed speed multiplier is guaranteed.
+- **Quota:** show the server-returned `5h` and `7d` windows and reset times, normally refreshed every 60 seconds while signed in and the tab is visible; failures back off. Missing windows are not invented; Spark uses its separate quota bucket.
+- **Plugin updates:** check for newer Codex Connect releases without installing anything or recommending changes to DSH. Host compatibility is available through explicit local diagnostics.
 
-```yaml
-- id: llm-openai-codex
-  config:
-    enableSearch: false
-    enableImageTool: false
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/composer-capabilities.jpg" alt="Fast Mode and quota controls in the DeepSeek Harness Composer" width="820">
+</p>
 
-To make a Codex model the default for new agents, add or update the separate Harness row yourself:
+## Optional capabilities
 
-```yaml
-- id: agent-default-model
-  config:
-    provider: openai-codex
-    model: gpt-5.6-sol
-```
+**Unreleased model compatibility:** the development branch also supplies `gpt-6-sol` and `gpt-6-luna` when older provider catalogs omit them, retaining native metadata when present. Both expose Low through Max (including Xhigh); Default omits an explicit effort. Codex Sol's Ultra orchestration mode is not implemented. New task grants can explicitly include these models, but existing grants, GPT-5.6 Sol/Medium startup and Luna Reserve remain unchanged. This is not included in the published 4.39 package or proof of account access. See [compatibility scope and validation](docs/experiments/gpt6-sol-luna-compatibility.md).
 
-The card can enable Codex standalone search. Selecting it as the profile's global search provider remains a separate explicit choice:
+All options below are off on a fresh installation. Edit them in **Settings → Plugins → Plugin configuration → Codex Connect** or **Settings → Models → Openai-Codex → More settings**, then select **Save changes**. A conflict or failed save preserves your draft.
 
-```yaml
-- id: llm-openai-codex
-  config:
-    enableSearch: true
-    searchMode: live
-    searchContextSize: medium
+| Capability | Enable with | Important behavior |
+|---|---|---|
+| Proxy | `enableProxy` | Credential-free HTTP(S), scoped to this plugin's traffic. A failed proxy request does not silently retry directly. |
+| Codex Search | `enableSearch` | Selects Codex for the entire profile's search route; disabling restores the previously active route. |
+| Luna Reserve | `enableReserveFallback` | Uses the hidden Reserve route only when the backend explicitly authorizes it for the captured account; never changes global defaults or retries a generic `429`. |
+| Image viewing | `enableImageTool` | Adds `view_image` to vision-capable models for local files and validated public HTTP(S) images. |
+| GPT Image generation | `enableImageGeneration` | Prompt-only generation; availability, dimensions, and quota remain account- and service-controlled. |
+| Auto-review | `enableAutoReview` | Sends bounded approval context, tool arguments, working directory, and the planned action to `chatgpt.com`, with confirmation on first enablement. Failures return to human approval. |
 
-- id: web
-  config:
-    searchProvider: openai-codex
-```
+**Published experiment:** Alpha 4.35 includes Luna Reserve fallback, disabled by default. Real-account Reserve entry and recovery remain unverified; Alpha 4.34 does not include this feature.
+
+With `enableReserveFallback: true`, the account UI and agent routing share one identity-bound quota state. Background refresh follows the returned quota windows while recently in use; fresh state is reused across agent steps. Ordinary quota reads also share the cache, even with Reserve disabled. The plugin enters `gpt-reserve` only with complete, non-FedRAMP account/user identity and backend Luna Reserve authorization, then restores the session's previous model and reasoning effort after confirmed ordinary-usage recovery. Reserve has its own allowance, is hidden from the model picker, and is not unlimited. The backend decides eligibility; reset times alone do not authorize a switch. This version supports known `gpt-5.6-luna` metadata only. See [Luna Reserve fallback](docs/reference.md#luna-reserve-fallback) for refresh, identity, and verification limits.
+
+Use the image generation capability included with your current GPT subscription. Generated originals are stored separately from attachment previews; disabling the capability or uninstalling the plugin does not delete them. See [Configuration and recovery](docs/reference.md#search-and-image-tools) for storage and access rules.
+
+Auto-review operates after Harness policy requires approval; it does not bypass that policy. See [Auto-review behavior](docs/auto-review.md) before enabling it.
 
-To add the image-loading tool, set `enableImageTool: true` on `llm-openai-codex`. Browser paste/drop remains a Harness attachment feature and does not depend on this tool.
+## FAQ and important limits
 
-| Field | Default | Values |
-|---|---:|---|
-| `enableSearch` | `false` | boolean |
-| `enableImageTool` | `false` | boolean |
-| `searchModel` | `gpt-5.6-sol` | Codex model id |
-| `searchMode` | `cached` | `cached`, `indexed`, `live` |
-| `searchContextSize` | `medium` | `low`, `medium`, `high` |
-| `searchMaxOutputTokens` | `10000` | positive integer |
+### Where are my credentials stored?
 
-## Credentials, diagnostics, and conflicts
+OAuth credentials are stored on the host running DSH and used there to authenticate and send requests to OpenAI. Normal browser account responses return account summaries, not raw tokens. A remote browser device is not necessarily the DSH host.
 
-- OAuth is stored separately at `$DSH_HOME/.openai-codex-auth.json` (`~/.dsh` by default); `~/.codex/auth.json` is never copied or modified.
-- The parent directory and file are created with owner-only permissions where supported. Writes are atomic, and refresh writes use a cross-process file lock.
-- Status and diagnostics return only non-sensitive state. OAuth flow output is confined to an explicit `login` operation.
-- Browser OAuth routes accept only loopback clients and loopback Host/Origin values; sign-in fails closed when no valid HTTPS authorization URL arrives within 30 seconds.
-- A second adapter cannot own `openai-codex`. Startup fails with a focused hint when the legacy `dsh-codex` bundle or a manual provider row conflicts.
-- Removing the package does not delete OAuth state. Run `logout` only when credential removal is intended.
+### Does uninstalling sign me out?
 
-## Compatibility and security boundary
+No. OAuth state is stored separately at `$DSH_HOME/.openai-codex-auth.json` (`~/.dsh` by default). The plugin does not copy or modify `~/.codex/auth.json`. Use **Sign out all accounts**, or `logout` before uninstalling, only when deleting credentials is intentional.
 
-- Alpha compatibility targets the current Harness `0.1.0-rc.5` main-line composition and compatible `0.1.0-rc.6` plugin APIs, Node.js `^22.19.0 || >=24.0.0`, and the pinned `@earendil-works/pi-ai` Codex provider.
-- ChatGPT plan eligibility, model access, quotas, and backend behavior are controlled by OpenAI and may change.
-- The Codex endpoint does not enforce the ordinary Responses `max_output_tokens` field. Harness compaction still works, but that summary cap cannot be imposed server-side on this route.
-- Shell, filesystem, skills, MCP, subagents, approvals, permissions, attachments, session persistence, compaction, and recovery continue to come from the active Harness profile.
-- Remote `view_image` URLs are limited to public HTTP(S) destinations. Every DNS result and redirect is checked, and the connection is pinned to the validated address so localhost, private networks, link-local services, and cloud metadata endpoints remain unreachable.
-- No real OAuth operation is required for installation, build, tests, doctor, or package validation.
+### Can I switch accounts for different conversations?
 
-See [INSTALL.md](INSTALL.md) for the idempotent agent runbook, [RELEASING.md](RELEASING.md) for the Alpha release checklist, [MIGRATION.md](MIGRATION.md) for migration from `dsh-codex`, and [docs/design.md](docs/design.md) for architecture details.
+Subsequent Codex requests use the selected active account; conversations do not bind their own accounts. Fast Mode is conversation-scoped. Cancelling a new authorization preserves existing accounts; an explicit revoked-refresh response asks for reauthorization, while temporary failures preserve the account for retry. See [Account behavior](docs/reference.md#accounts-models-and-quota).
 
-## Development
+### Why does a listed model fail?
+
+Model HTTP/SSE failures include bounded, request-local diagnostic metadata after the existing error message. An `overloaded` message alone does not establish an account block. See [persistent-error diagnostics](docs/experiments/issue-219-diagnostics.md) for scope and reproduction.
+
+Account permissions, plugin/host compatibility, and network conditions all affect availability. Access on another client does not guarantee this integration will work. OpenAI controls model access, quota, context capacity, and service behavior; catalog entries are not proof of entitlement.
+
+### Does changing client headers prevent persistent authorization failures?
+
+No such guarantee is established. Codex Connect is a third-party integration; it does not impersonate Codex Desktop or fabricate installation/attestation headers. The pi-ai model/OAuth route and auxiliary routes currently identify themselves differently. OpenAI's [App Server documentation](https://developers.openai.com/codex/app-server/) asks integrations to identify their own client with `clientInfo`; it does not establish acceptance rules for this plugin's direct backend calls. An `overloaded` message is not proof of a block. Capture the bounded error metadata and compare successful and failed windows before attributing the cause; share request IDs privately, never tokens or full session archives.
+
+### Can I keep the original `dsh-codex` plugin installed?
+
+Not in the same effective configuration: both register `openai-codex`. Follow [MIGRATION.md](MIGRATION.md); remove only the confirmed conflicting entry, not credentials or unrelated providers.
+
+### What do diagnostics prove?
+
+`doctor` is local. Capability and reviewer probes may make network requests and consume quota when their preconditions are met. `auto-review-probe` checks only the reviewer route and structured response, not the full Harness approval integration or execution of the reviewed action. Commands, limits, and exit codes are in the [diagnostics reference](docs/reference.md#capability-probes).
+
+A missing entry in [verified-compatibility.json](verified-compatibility.json) means a DSH/plugin combination is unverified, not known to be broken. Do not infer support for newer hosts from an older pairing.
+
+## Documentation and development
+
+- [Installation and upgrades](INSTALL.md)
+- [Configuration, diagnostics, and recovery](docs/reference.md)
+- [Migration from `dsh-codex`](MIGRATION.md)
+- [Architecture and security details](docs/design.md)
+- [Auto-review behavior](docs/auto-review.md)
+- [Release runbook](RELEASING.md), [Contributing](CONTRIBUTING.md), and [Security policy](SECURITY.md)
 
 ```sh
 pnpm install --frozen-lockfile
 pnpm run check
+pnpm run test:browser
+pnpm run check:dsh-install
 ```
 
-## Legal / Acknowledgements
-
-Copyright 2026 Frank Song for the modifications and additional work in Codex Connect. This project includes software derived from [Yan-Zero/dsh-codex](https://github.com/Yan-Zero/dsh-codex); Copyright 2026 Yan-Zero is retained for the upstream material. Both are distributed under Apache-2.0, with details in [NOTICE](NOTICE). This project is not affiliated with or endorsed by OpenAI, ChatGPT, Codex, DeepSeek, or DeepSeek Harness.
+`check` covers static checks, unit tests, build, compatibility, and packaging. `lint:metadata` checks package and release rules; `lint:source` checks host and browser TypeScript for unhandled or misused promises, invalid awaits, duplicate cases, and unreachable code. Browser regression and isolated DSH installation are separate commands. These checks use no real OAuth authorization and do not replace real-account acceptance.
 
-## License
+## License and acknowledgements
 
-Apache-2.0
+Copyright 2026 Frank Song for Codex Connect modifications and additional work. This project contains software derived from [Yan-Zero/dsh-codex](https://github.com/Yan-Zero/dsh-codex); Copyright 2026 Yan-Zero is retained for upstream material. Both are distributed under Apache-2.0; see [NOTICE](NOTICE).

package/VERSIONING.md

@@ -0,0 +1,65 @@
+# Versioning policy
+
+English | [中文](docs/VERSIONING.zh.md)
+
+Codex Connect versions identify plugin releases independently of DeepSeek Harness. Show the plugin version and its verified DSH pairing together; do not infer one from the other.
+
+## Release identity and phase
+
+The current release series is `0.1.0-alpha.4.x`. Increment the final counter for another release in this series; a DSH update does not reset it. This policy does not rename any existing release or select a new version.
+
+The publishing workflow accepts `MAJOR.MINOR.PATCH-alpha.NUMBER[.NUMBER…]`, with nonnegative integer components and no leading zeroes. Build metadata is not a release counter: SemVer ignores `+build.n` when comparing versions, and the pinned npm publishing implementation removes it. Use a distinct, higher-precedence version for every new package. Never overwrite a published package or move its release tag to different content.
+
+The plugin's public behavior includes configuration, tools, commands, and stored data. In the `0.y.z` development period, incompatible changes require explicit release notes and migration guidance; intentionally starting a new incompatible release line increments the plugin minor version. Routine iterations within the current Alpha line increment its prerelease counter. Copying a host's version is not a substitute for deciding the plugin's change scope.
+
+Alpha, Beta, RC, and a non-prerelease version describe the plugin's readiness, not DSH's. Phase promotion is a separate maintainer decision backed by recorded verification, including real-account and upgrade acceptance where relevant. A stable DSH release does not make the plugin stable. The current workflow remains Alpha-only; Beta, RC, and stable publishing need a separately reviewed workflow/channel change.
+
+## Compatibility evidence
+
+| Information | Maintained in | Meaning |
+|---|---|---|
+| Plugin build version | `package.json.version` | Identity embedded in the build and CLI |
+| Host dependency requirements | `compatibility.json` and dependency declarations | Intended supported runtime constraints, checked for consistency |
+| Verified exact combinations | `verified-compatibility.json` | Evidence from checks of each explicit DSH/plugin pair |
+| User-visible changes | GitHub Release notes and `update-highlights.json` | What changed between plugin releases |
+
+Keep the compatibility catalog's `schemaVersion: 1`, `checkedAt`, `latestDshVersion`, and `pluginVersions[].{version,verifiedDshVersions}` fields at the existing URL. Preserve historical entries. An unlisted pair is unverified, not necessarily incompatible. Neither a target dependency nor a green test on a different pairing proves compatibility.
+
+Record a new exact pair only after verification. A candidate's verification record does not prove npm publication. Before recommending it publicly, confirm both that the version exists on npm with its matching release tag and that the pair is recorded. The offline lint check verifies the recorded pair and bilingual agreement; it does not contact npm or certify publication.
+
+Do not replace V1 in place with a version-keyed object or infer a range from a single successful version. Any future incompatible format needs a versioned endpoint and continued output for installed V1 clients.
+
+## Channels and recommendations
+
+- `alpha` is the moving channel written by the current release workflow.
+- `latest` is promoted separately and intentionally. Before the first stable release it may point to a verified Alpha; afterward it must point only to stable releases. Publishing an Alpha does not authorize or perform this promotion.
+- Exact installation commands identify a plugin release; dist-tags do not guarantee compatibility.
+- Keep the public README recommendation on a confirmed published pair while preparing a newer candidate. The recommendation may therefore differ from `package.json.version`.
+
+The project newest version and the newest verified plugin for a user's existing DSH are different questions. More precise host-specific recommendations and generated installation sections are follow-up work; this policy does not claim the current update UI computes that choice from every historical record.
+
+## Update highlights
+
+Keep V1 highlight entries in increasing SemVer order, with unique versions and known capability kinds. Preserve the existing history. New documentation-only or maintenance releases may be omitted; existing empty `highlights` arrays remain valid. Release notes still describe fixes. Do not invent capabilities or require a contiguous counter sequence just to validate the catalog.
+
+## A future numbering cleanup
+
+A shorter independent series, such as `0.2.0-alpha.1`, is a possible later migration, not the next version selected by this change. Do not reset to `0.1.0-alpha.1`: it sorts below the current `0.1.0-alpha.4.x` releases.
+
+Before a migration, verify that installed clients recognize the new version as an update, preserve compatibility and highlight history, and check package, workflow, tag, and channel agreement. For a phase change, also update the Alpha-only gates and publication/readback path. Keep host upgrades, schema changes, and numbering migration separately reviewable.
+
+## Release checks
+
+Follow [RELEASING.md](RELEASING.md) for the complete procedure. Run the frozen install and existing checks separately:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check
+pnpm run test:browser
+pnpm run check:dsh-matrix
+npm pack --dry-run
+```
+
+`check` does not include the browser suite or isolated DSH installation. Regenerate the lockfile only when dependency changes require it; do not refresh the dependency tree for a documentation or localization release. Automated checks do not replace real OAuth acceptance. Merge, publish, and `latest` promotion remain distinct operations.
+
+Normative references: [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) and the pinned [npm 11.6.4 publishing implementation](https://github.com/npm/cli/blob/v11.6.4/workspaces/libnpmpublish/lib/publish.js).

package/compatibility.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 1,
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dshPluginApi": {
+    "version": "0.1.2-rc.1",
+    "versions": ["0.1.2-rc.1", "0.1.5-alpha.1", "0.1.5-rc.1", "0.1.5-rc.2"],
+    "packages": [
+      "@deepseek-ai/dsh-agent",
+      "@deepseek-ai/dsh-atomic-write",
+      "@deepseek-ai/dsh-attachment",
+      "@deepseek-ai/dsh-home-paths",
+      "@deepseek-ai/dsh-host-webserver",
+      "@deepseek-ai/dsh-invariants",
+      "@deepseek-ai/dsh-llm",
+      "@deepseek-ai/dsh-llm-pi-ai",
+      "@deepseek-ai/dsh-fs",
+      "@deepseek-ai/dsh-session",
+      "@deepseek-ai/dsh-settings",
+      "@deepseek-ai/dsh-tools",
+      "@deepseek-ai/dsh-util-values",
+      "@deepseek-ai/dsh-web"
+    ]
+  },
+  "piAi": {
+    "package": "@earendil-works/pi-ai",
+    "version": "^0.84.2 || 0.85.1"
+  }
+}

package/cordis.patch.yml

@@ -4,5 +4,10 @@
     - id: llm-openai-codex
       name: dsh-codex-connect
       config:
+        enableProxy: false
         enableSearch: false
+        enableReserveFallback: false
+        enableNativeCompaction: false
         enableImageTool: false
+        enableImageGeneration: false
+        enableAutoReview: false