dsh-codex-connect 0.1.0-alpha.4.5 → 0.1.0-alpha.4.51

package/INSTALL.md

@@ -1,7 +1,11 @@
 # Installation Runbook for CLI Agents
 
+Published Alpha 4.50 is verified with either exact DSH `0.1.7-rc.1` or `0.1.7-rc.2` and pi-ai `0.85.1`, using a consistent host package set. Earlier DSH pairings retain their separately published plugin versions below.
+
 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-26: npm `alpha` points to `0.1.0-alpha.4.50`; `latest` remains `0.1.0-alpha.4.47`. Use the exact-version command for the installed DSH version; moving npm tags are not compatibility guarantees.
+
 ## Safety requirements
 
 - Never read, print, copy, move, or modify `~/.codex/auth.json`.
@@ -12,28 +16,127 @@ 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.41` |
+| `0.1.2-alpha.5` | `0.1.0-alpha.4.25` |
+| `0.1.5-alpha.1` | `0.1.0-alpha.4.41` |
+| `0.1.5-rc.1` | `0.1.0-alpha.4.41` |
+| `0.1.5-rc.2` | `0.1.0-alpha.4.41` |
+| `0.1.7-rc.1` | `0.1.0-alpha.4.50` |
+| `0.1.7-rc.2` | `0.1.0-alpha.4.50` |
+
+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.50 requires one consistent DSH `0.1.7-rc.1` or `0.1.7-rc.2` plugin API and pi-ai `0.85.1`; its direct runtime imports include `@deepseek-ai/schemastery` `3.18.4` and `@earendil-works/pi-ai` `0.85.1` so an isolated profile need not already provide them. Node.js remains `^22.19.0 || >=24.0.0`. It does not support the older DSH rows. Alpha 4.41 remains the choice for DSH `0.1.2-rc.1` with pi-ai `^0.84.2`, or `0.1.5-alpha.1`, `0.1.5-rc.1`, and `0.1.5-rc.2` with pi-ai `0.85.1`. 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 for DSH `0.1.2-alpha.2`, Alpha 4.21 for DSH `0.1.1-rc.2`, and Alpha 4.14 for DSH `0.1.0-rc.7`. 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.50 recommendation follows [PR #275](https://github.com/franksong2702/dsh-codex-connect/pull/275), [exact-release main CI](https://github.com/franksong2702/dsh-codex-connect/actions/runs/36222707376) and a successful [protected publication run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/36222974006) at `6baa422b7b9cd513340948f659b51b0b9d76a724`. The same candidate passed unmodified rc.1 and rc.2 isolated installations without exemptions; Chromium passed 73 tests on each host. The rc.1 frozen full check passed 1,452 tests; rc.2 source types and focused image/auth/transport/compaction suites passed. An independent source reviewer found a mandatory UI-peer consistency gap; five red/green controls covered the correction before the final source review passed. See [the exact scope and evidence](docs/experiments/dsh-017rc2-compatibility.md).
+
+Independent post-publication verification returned `already-complete`, matching the npm archive byte-for-byte to the original verified release artifact (SHA-256 `e974ef71d77b3153c8a41fa454d6e53de41227cf1ee96cee99db42f73a43b58d`). The version, `alpha`, Git tag and [prerelease](https://github.com/franksong2702/dsh-codex-connect/releases/tag/v0.1.0-alpha.4.50) agree. This release's publication workflow succeeded; no recovery mutation or duplicate publication was needed. `latest` remains 4.47. This is not new live-account/image/Reserve or physical Windows/mobile acceptance. All mandatory host peers, including UI peers, are checked by the full capability/strict compatibility checks; the compact doctor report alone is not a full peer audit. Optional commands-service behavior is not certified by the mandatory-peer check. Task controls remain paused and defaults are unchanged.
+
+Historical Alpha 4.49 evidence:
+
+The Alpha 4.49 recommendation follows [exact-release main CI](https://github.com/franksong2702/dsh-codex-connect/actions/runs/36212638824) on Node 22/24, browser and keyless Windows checks, plus the stock DSH `0.1.7-rc.1` same-artifact installation matrix. It fixes both independently reproduced Alpha 4.48 image-editing defects: reuploaded copies could select historical originals, and safe actionable input errors were hidden. The three original reproduction tests pass; a separate ephemeral GPT-6 Astra process reviewed the correction's source without implementation history and found no blockers in that scope.
+
+The [original 4.49 publish run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/36212860716) successfully published npm but failed its bounded public-readback step. It was not rerun. The [recovery-only run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/36213209903) verified npm metadata and exact archive bytes against the original verified artifact, then created the [matching tag and prerelease](https://github.com/franksong2702/dsh-codex-connect/releases/tag/v0.1.0-alpha.4.49). npm exact version and `alpha` were independently read back as 4.49; `latest` remains 4.47. These checks do not claim new real-account image/selection acceptance, physical Windows/mobile behavior or pixel-perfect edits. Stock rc.1 keeps Task controls paused. The 4.48 package and tag remain unchanged and affected; select 4.49 for the corrected behavior.
+
+Historical Alpha 4.47 evidence:
+
+The Alpha 4.47 recommendation follows [exact-release main CI](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35994106350) on Node 22/24, browser and keyless Windows checks, plus the stock DSH `0.1.7-rc.1` same-artifact installation matrix. The [original publish run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35994578156) uploaded the verified package but failed during npm public readback; do not rerun publication. Recovery-only local verification matched the public npm archive byte-for-byte to the original artifact and created the [Git tag and prerelease](https://github.com/franksong2702/dsh-codex-connect/releases/tag/v0.1.0-alpha.4.47) without republishing. npm `alpha` and `latest` were independently read back as 4.47. These checks are not fresh real Chrome OAuth, live model/tool/image requests, or Windows application acceptance. Stock rc.1 keeps Task controls paused; migration of old Task grants across a Harness upgrade remains unverified.
+
+Historical Alpha 4.46 evidence:
+
+The Alpha 4.46 recommendation follows [exact-release main CI](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35982530538) on Node 22/24, browser and keyless Windows checks, plus the stock DSH `0.1.7-rc.1` same-artifact installation matrix. The [original publish run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35983101557) uploaded the verified package but timed out waiting for npm's public readback; it must not be rerun. After the exact version and `alpha` tag appeared, the [recovery-only run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35984180679) matched the public npm archive byte-for-byte to the original artifact and created the Git tag and prerelease without republishing. The fix's real Chrome OAuth and quota refresh on the original Windows PC remain unverified; these checks did not promote npm `latest` or establish real-account acceptance. Stock rc.1 keeps Task controls paused; migration of old Task grants across a Harness upgrade remains unverified.
+
+The historical Alpha 4.43 recommendation followed [exact-release main CI](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35887810404) on Node 22/24, Chromium and Windows checks, plus the stock DSH `0.1.7-rc.1` same-artifact installation matrix. The [original publish run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35888766215) uploaded the verified npm package but timed out waiting for public registry readback; do not rerun publication. Once npm exposed the exact version and `alpha` tag, the [recovery-only run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35889959811) verified the archive against that original artifact and created the matching Git tag and prerelease without republishing. These checks used synthetic providers, not a real ChatGPT account. Stock rc.1 keeps Task controls paused; migration of old Task grants across a Harness upgrade remains unverified.
+
+The Alpha 4.41 recommendation follows successful [exact-release main CI](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35817909046) on Node 22 and 24 (1,282 unit tests each), 52 Chromium tests, and a four-host same-artifact installation matrix. After npm processing completed, the [recovery verification](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35819017165) matched the public npm archive byte-for-byte to the original verified release artifact, then created the matching Git tag and GitHub prerelease. The [original release run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/35818489220) remains failed because npm's public readback was not available within its bounded retry period; do not rerun publication. These are synthetic-provider installation/lifecycle checks, not new real-account acceptance or a newly exercised published-package upgrade. Task-level model control remains opt-in; a new grant preselects only GPT-5.6 Sol / Medium and displays its scope and request limit before Start. Existing grants are not silently narrowed. 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@alpha
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.14
    ```
 
-   To pin this release exactly, use `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.5`. If npm is unavailable, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.5'`.
+   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
+   ```
 
-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:
+   For DSH `0.1.2-alpha.2`, use Alpha 4.23:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.23
+   ```
+
+   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.41:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.41
+   ```
+
+   For either exact DSH `0.1.7-rc.1` or `0.1.7-rc.2` pairing, use Alpha 4.50:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.50
+   ```
+
+   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, `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.41'` only for the DSH `0.1.2-rc.1`, `0.1.5-alpha.1`, `0.1.5-rc.1`, and `0.1.5-rc.2` combinations, or `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.46'` only for DSH `0.1.7-rc.1`.
+
+   For the current DSH `0.1.7-rc.1` or `0.1.7-rc.2` pairing, 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.50'`.
+
+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 +144,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 +164,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

@@ -1,5 +1,45 @@
 # Migrating from `dsh-codex`
 
+## Alpha 4.43 candidate: upgrade the Harness together
+
+This candidate targets DeepSeek Harness `0.1.7-rc.1` only. Upgrade the Harness
+and its profile runtime first, then install the matching Codex Connect release;
+this candidate is not compatible with the previously declared `0.1.2-rc.1` or
+`0.1.5` hosts. Keep the existing `llm-openai-codex` row and OAuth store. The DSH
+settings lifecycle, message-source types, and native-compaction integration have
+changed, but the migration does not require signing in again or editing
+credentials. This candidate is not published; do not use a public install
+command until its exact package/host pair is verified and released.
+DSH `0.1.7-rc.1` also changes the Session log format. Migration of an active
+task from the previously supported Harness versions to this target has not
+passed acceptance; do not treat same-host task recovery below as proof of a
+cross-Harness upgrade. Finish or safely stop active delegated tasks before
+changing the Harness until that migration is verified.
+
+## Next release candidate: public task orchestration paused
+
+Task-level automatic model selection and read-only delegation are being withheld
+until maintainer acceptance. This change does not retroactively disable npm 4.41
+or already-running installations. It takes effect only after the new package is
+published, installed, and loaded.
+
+A new ordinary conversation has no collaboration activation options. Cached
+clients cannot start, resume, upgrade or authorize delegation through the closed
+server route. On a supported same-version host, existing tasks keep authenticated
+readback, Stop and manual takeover;
+grants, original history and spent request counts are not deleted or reset.
+Manual model selection (including GPT-6/Astra), accounts, existing optional tools
+and native compaction settings are unchanged. Internal orchestration source and
+tests remain, but there is no public setting or environment-variable escape hatch.
+Reopening requires a separately reviewed source change and new build after
+acceptance; per-task user authorization will still be required.
+
+Before downgrading an existing delegated task, use the authenticated safety exits
+and let the runtime verify cleanup and delivery. Do not delete the task ledger or
+edit its counters to force recovery. Cross-device/new-cookie task ownership limits
+remain unchanged.
+
+
 `dsh-codex-connect` uses the same provider id (`openai-codex`), OAuth filename (`.openai-codex-auth.json`), Cordis row id (`llm-openai-codex`), and browser auth routes for compatibility. The packages cannot be active together because Harness forbids duplicate provider adapters.
 
 1. Record the effective default model, search route, and `llm-openai-codex` config without reading any OAuth file.
@@ -10,3 +50,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,14 @@ 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.
+
+The standalone CLI bundles selected code from host and provider dependencies so
+it can run from an isolated DSH plugin-exec process without copying host peers.
+The bundled third-party package attributions and license texts are in
+docs/licenses/standalone-cli.txt. Runtime plugin imports continue to use the
+host's packages rather than these standalone CLI copies.

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: 27439ded00edd30a248acf6cc7af53d0ef93ef1b
-docs/README.zh.md: 49e5e00191ff055ab23109e1237d9e75f84f3b46
+README.md: 042cbc25138136fb6086b74b9174e560c7dcdd26
+docs/README.zh.md: 394fa85a66eccbdee1adbfe2b859dd51b73ab785

package/README.md

@@ -1,136 +1,149 @@
 # 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 and editing, user-controlled defaults, Harness-native approvals, diagnostics, and reliable session recovery.
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/hero.jpg" alt="Codex Connect — ChatGPT OAuth for DeepSeek Harness" width="100%">
-</p>
+Community Alpha — not affiliated with or endorsed by OpenAI, ChatGPT, Codex, DeepSeek, or DeepSeek Harness.
 
-`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.
+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.
 
-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.
+## Quick start
 
-## See it in Harness
+This guide describes the published pairing below. Check `dsh --version` first and use `doctor --json` for local diagnostics; the CLI version alone does not prove which model-runtime packages are installed, and missing metadata is reported as unknown. For other versions, use [Installation and upgrades](INSTALL.md). A moving npm tag such as `alpha` is not a compatibility guarantee.
 
-Sign in and manage the plugin from **Settings → Plugins → Plugin configuration → Codex Connect**.
+| Requirement | Verified pairing |
+|---|---|
+| Codex Connect | `0.1.0-alpha.4.50` |
+| DeepSeek Harness | `0.1.7-rc.1` or `0.1.7-rc.2` (consistent package set) |
+| Node.js | `^22.19.0 \|\| >=24.0.0` |
+| Account | ChatGPT OAuth with access to the requested Codex model; availability is decided by OpenAI |
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/oauth-status.jpg" alt="Codex Connect ChatGPT OAuth status inside Harness plugin configuration" width="720">
-</p>
+As of 2026-09-26, npm `alpha` points to 4.50 while `latest` remains 4.47; publishing this release did not promote `latest`. Use the exact version below for this DSH pairing; a moving npm tag is not a compatibility guarantee for other hosts.
+
+On stock DSH `0.1.7-rc.1` and `0.1.7-rc.2`, the package is installation/runtime-regression verified; Task controls remain paused: activation is rejected and fresh Sessions do not show them. Migration of earlier Task grants across a Harness upgrade is not verified. Older supported pairings and their task behavior are documented in [Installation and upgrades](INSTALL.md).
+
+### 1. Install
+
+```sh
+dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.50
+dsh web
+```
+
+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).
+
+### 3. Check the installation
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect status --json
+dsh plugin --profile web exec dsh-codex-connect doctor --json
+```
 
-Optional Codex search and `view_image` capabilities remain explicit, profile-scoped choices:
+`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.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/plugin-configuration.jpg" alt="Codex Connect optional capability settings in DeepSeek Harness" width="720">
+  <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>
 
-Codex models then appear in Harness's normal model picker alongside the existing providers:
+## Core capabilities
+
+- **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. Optional, separate profile settings can enable it for newly started top-level or subagent conversations without changing existing conversations. 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.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/model-selector.jpg" alt="OpenAI Codex models in the DeepSeek Harness model picker" width="320">
+  <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>
 
-## Install
+## Optional capabilities
 
-```sh
-dsh plugin --profile web add dsh-codex-connect@alpha
-dsh web
-```
+**Earlier Alpha 4.40/4.41 pairings:** task-level model control is off by default. After explicit task authorization, GPT-5.6 Sol/Medium starts the task, and the active model may continue, change effort, or hand off the main task within the granted scope. The task shares one request ledger and budget; stopping, manual takeover, and restart recovery retain the grant boundary. Phase 2 read-only delegation requires separate consent and does not grant workers write access. Stock DSH `0.1.7-rc.1` with Alpha 4.43 keeps these Task controls paused; do not infer they are available from an older pairing. See [Phase 1](docs/experiments/adaptive-task-phase1.md) and [Phase 2 consent](docs/experiments/adaptive-task-phase2-consent.md).
 
-To pin this release exactly, use `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.5`. If npm is unavailable, use the GitHub tag fallback: `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.5'`. From a DeepSeek Harness source checkout, prefix commands with `pnpm`. For a local checkout, install `link:/absolute/path/to/dsh-codex-connect`.
+Alpha 4.40 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. A catalog entry is not proof of account access. See [compatibility scope and validation](docs/experiments/gpt6-sol-luna-compatibility.md).
 
-Sign in from **Settings → Plugins → Plugin configuration → Codex Connect → Sign in with ChatGPT**, or use the CLI:
+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.
 
-```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
-```
+| Capability | Enable with | Important behavior |
+|---|---|---|
+| Proxy | `enableProxy` | Credential-free HTTP(S), scoped to this plugin's traffic, including compressed OAuth and quota responses. Unrelated Fetch calls retain the host's original transport. 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 and editing | `enableImageGeneration` | Generate from a prompt or edit selected conversation images with ordered references. 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. |
 
-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.
+**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.
 
-## Explicit configuration
+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.
 
-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.
+Use the image generation capability included with your current GPT subscription. Successful images appear below the conversation answer without opening its processing details; the original tool card remains available there. 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.
 
-The installed bundle row remains the composition base and is intentionally inert beyond model-provider registration:
+Alpha 4.49 fixes the re-uploaded-copy/original confusion and hidden safe failure reasons found in 4.48. Ambiguous inputs require an explicit selection rather than silently changing the target. The original package remains unchanged; Alpha 4.50 retains both repairs and adds exact DSH rc.2 compatibility while preserving rc.1. Do not mix rc.1 and rc.2 packages or bypass the plugin manager's version checks.
 
-```yaml
-- id: llm-openai-codex
-  config:
-    enableSearch: false
-    enableImageTool: false
-```
+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 make a Codex model the default for new agents, add or update the separate Harness row yourself:
+## FAQ and important limits
 
-```yaml
-- id: agent-default-model
-  config:
-    provider: openai-codex
-    model: gpt-5.6-sol
-```
+### Where are my credentials stored?
 
-The card can enable Codex standalone search. Selecting it as the profile's global search provider remains a separate explicit choice:
+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.
 
-```yaml
-- id: llm-openai-codex
-  config:
-    enableSearch: true
-    searchMode: live
-    searchContextSize: medium
+### Does uninstalling sign me out?
 
-- id: web
-  config:
-    searchProvider: openai-codex
-```
+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.
+
+### Can I switch accounts for different conversations?
+
+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).
+
+### Why does a listed model fail?
 
-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.
+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.
 
-| 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 |
+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.
 
-## Credentials, diagnostics, and conflicts
+### Does changing client headers prevent persistent authorization failures?
 
-- 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.
+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.
 
-## Compatibility and security boundary
+### Can I keep the original `dsh-codex` plugin installed?
 
-- 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.
+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.
 
-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.
+### What do diagnostics prove?
 
-## Development
+`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).