codex-adaptive-effort 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codex Adaptive Effort contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,5 @@
+# Codex Adaptive Effort
+
+The English documentation now lives in the main [README](README.md).
+
+[Documentation index](docs/README.md) · [简体中文](README.zh-CN.md)

package/README.md

@@ -0,0 +1,115 @@
+# Codex Adaptive Effort
+
+[![CI](https://github.com/ppxu/codex-adaptive-effort/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ppxu/codex-adaptive-effort/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js 22.16+](https://img.shields.io/badge/Node.js-%3E%3D22.16-339933.svg)](package.json)
+
+**Keep your Codex model. Adapt its reasoning effort.**
+
+Codex Adaptive Effort (CAE) is an experimental local HTTP/SSE proxy that can change `reasoning.effort` for a fixed, user-selected model. It supports the Codex CLI and an isolated instance of the validated Codex desktop application. An optional TypeSafe Jev evaluator recommends effort levels from the model's actual capabilities.
+
+[简体中文](README.zh-CN.md) · [Documentation](docs/README.md) · [Acceptance evidence](docs/LOCAL_ACCEPTANCE.md) · [Changelog](CHANGELOG.md)
+
+> **Alpha: `0.1.0-alpha.1`.** This is an independent project, not an official OpenAI or TypeSafe plugin. Desktop support is limited to the exact macOS/app/CLI combination documented below. Task quality, cost savings and production reliability are not established.
+
+## What it does
+
+| Feature | Behavior |
+| --- | --- |
+| Fixed execution model | Keeps the selected model, provider, auth route and service tier; other models bypass adaptation |
+| `off` | Forwards requests without evaluation or effort changes |
+| `shadow` (default) | Records recommendations while forwarding the original request |
+| `auto` | Applies a validated effort to eligible requests; preserves all other request fields |
+| Optional Jev evaluation | Sends a bounded text projection to TypeSafe; uses separate credentials and a call limit |
+| Safe fallback | Retains incoming effort on evaluator failure; unsupported histories bypass adaptation |
+| Local controls | Authenticated loopback controls, manual locks, cancellation and bounded decision reuse |
+| Evidence | Metadata-only decisions, actual send events and response completion; no invented savings |
+
+The default evaluator is **baseline-only**, a transport test fixture rather than a complexity classifier. Live Jev processing must be explicitly enabled. CAE never rewrites global Codex configuration or reads native login files. Native Codex handles its own login.
+
+## Install and run
+
+Requires Node.js **22.16+**, npm and an existing Codex installation for native integration. There are no third-party runtime dependencies or install hooks. The npm package is prepared but **not yet published to the registry**. Until its first release, install a reviewed Git commit with npm (requires Git):
+
+```bash
+# Replace REVIEWED_COMMIT with the full tested Git commit SHA.
+npm install --global --ignore-scripts github:ppxu/codex-adaptive-effort#REVIEWED_COMMIT
+cae --version
+cae --help
+```
+
+After the first alpha registry publication, installation will be `npm install --global --ignore-scripts codex-adaptive-effort@alpha`. See the [npm guide](docs/NPM.md) for local archives, upgrades, uninstalling and configuration locations. Global installation provides the command; configuration stays in your chosen working directory.
+
+For source development:
+
+```bash
+git clone https://github.com/ppxu/codex-adaptive-effort.git
+cd codex-adaptive-effort
+npm ci --ignore-scripts
+npm run verify
+npm link --ignore-scripts
+cae --help
+```
+
+Verification uses synthetic data and local test servers; it does not call real model providers. CI runs on Linux, macOS and Windows with Node 22 and 24. Passing CI does not imply native integration on all these platforms.
+
+## Quick start: inspect capabilities
+
+```bash
+mkdir cae-trial
+cd cae-trial
+cae doctor
+cae probe > capabilities.local.json
+```
+
+These commands inspect the native CLI and query `model/list`; they do not generate model output. If Codex is not on `PATH`, pass `--codex /path/to/trusted/codex`. Select a real model ID and its supported effort values from the capture; do not assume every model supports every effort. Keep captures local and out of version control; this source repository includes ignore rules, but another working directory may not.
+
+Continue with the [CLI validation guide](docs/LOCAL_VALIDATION.md) or the [desktop launcher guide](docs/DESKTOP_LAUNCHER.md).
+
+## Desktop trial
+
+Validated on **macOS 27.0 arm64**, **ChatGPT/Codex desktop 26.924.22138 (build 11645)** and its bundled **codex-cli 0.158.0-alpha.2.1**. The launcher checks the official application signature, exact version, current capabilities and effective provider. Other combinations are rejected pending validation; it does not install or replace native binaries.
+
+```bash
+# Replace MODEL_ID with an ID returned by your native probe.
+cae desktop start --model "$MODEL_ID" --auth chatgpt --enable-upstream
+# In another terminal, from the same working directory:
+cae desktop status
+cae desktop stop
+```
+
+Use a **new local Codex chat** in the experimental window and a directory containing only non-sensitive test material. Existing chats retain their providers. The instance has separate Electron data but shares native Codex home and login. Ordinary ChatGPT conversations and cloud tasks are outside this integration.
+
+Starting the launcher does not submit a task. Sending a task uses the normal model allowance. The default is shadow + baseline. For real Jev evaluation, provide your own `TYPESAFE_API_KEY` through your normal environment setup and add `--enable-jev`:
+
+- `--enable-jev`: process-only Jev shadow; `auto` and manual locks remain disabled.
+- Add `--allow-jev-auto`: permits an explicit `control auto` after startup; it does not switch modes automatically.
+- Optional `--jev-timeout-ms 2000`: replaces the timeout for this process only. The default ceiling remains 1500 ms.
+
+Desktop Jev trials allow at most eight evaluations per process. A timeout or cancellation may still incur provider usage. Read the [complete controls and recovery procedure](docs/DESKTOP_LAUNCHER.md) before enabling auto.
+
+## Validation status
+
+Real tests on the documented installation covered CLI transport, desktop off, manual low/high locks, cancellation/recovery, Jev shadow, automatic `medium → high`, automatic `medium → low`, and timeout fallback. The latest downshift took 665 ms with a 2000 ms limit; **this does not show that increasing the limit improves reliability**. Some earlier evaluations timed out, and their root cause remains unresolved.
+
+See [versioned acceptance evidence](docs/LOCAL_ACCEPTANCE.md) and [known limitations](docs/LIMITATIONS.md). WebSockets, packaged desktop plugins, `configuration_update`, automatic model routing and full cache optimization are not implemented. Structured tool-result, compacted, incremental or multimodal histories can bypass adaptation, including manual locks.
+
+## Stop and restore
+
+```bash
+cae control off --config .cae/desktop/config.json
+cae desktop stop
+```
+
+`off` still uses the proxy. Stop the experimental instance and return to ordinary Codex to leave the proxy path. No global configuration or login files need restoring. A proxy crash does not automatically switch to a direct connection.
+
+## Contribute and get help
+
+- Read [Contributing](CONTRIBUTING.md) before opening a pull request.
+- Use [Issues](https://github.com/ppxu/codex-adaptive-effort/issues) for bugs, questions and feature proposals with synthetic reproductions.
+- Follow [Security](SECURITY.md) for vulnerabilities; never attach credentials, raw logs or private task histories.
+- Follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License and provenance
+
+[MIT](LICENSE) for this project's original code. Design inspiration and fixed source references are recorded in [Third-party notices](THIRD_PARTY_NOTICES.md). No Codex, Astra-Ares or Jev Codex Router source or binaries are bundled. External services retain their own terms; no model-quality or billing guarantees are made.

package/README.zh-CN.md

@@ -0,0 +1,133 @@
+# Codex Adaptive Effort（CAE）
+
+**固定执行模型，动态调整思考强度。** 这是面向本地 Codex 的实验性开源控制器，设计借鉴 Astra-Ares 的固定模型/决策生命周期，以及 Jev Codex Router 的本地代理/有限判断摘要。
+
+**当前版本：`0.1.0-alpha.1`。** 实验性 Node.js 实现，不是官方 Codex 桌面插件。已在一台 macOS arm64 机器上验收 ChatGPT 路线的原生 CLI，以及独立桌面实例的 HTTP/SSE、off、纯文本手动锁档及取消恢复；具体版本、能力和边界见 [本机验收记录](docs/LOCAL_ACCEPTANCE.md) 和 [桌面验收记录](docs/DESKTOP_ACCEPTANCE.md)。另有 8 次真实 Jev 合成样例判断通过协议检查，见 [Jev shadow 记录](docs/JEV_SHADOW_ACCEPTANCE.md)；桌面 Jev 自动升档、降档与超时回退均已有真实通过样例，见 [auto 记录](docs/LOCAL_ACCEPTANCE.md)；正式安装和其他环境仍未验收。没有节省费用、保持质量或生产可用性的保证。
+
+[English](README.md) · [本地验收](docs/LOCAL_VALIDATION.md) · [架构](docs/ARCHITECTURE.md) · [验证记录](docs/VALIDATION.md) · [限制](docs/LIMITATIONS.md)
+
+## 已实现
+
+| 能力 | 本版行为 |
+|---|---|
+| 固定模型 | 只改已配置模型的 `reasoning.effort`，不自动切模型、服务商、速度档或计费渠道；用户选其他模型时透明旁路 |
+| 三种模式 | 默认 `shadow`：评估但不改请求；`auto`：应用已校验档位；`off`：不评估、不改档 |
+| Jev 判断 | TypeSafe System One 两个 Choice：思考强度、1–4 次生成的决策有效期；支持独立超时和调用次数上限 |
+| 状态控制 | 同会话单活动请求；只有成功完成的请求可建立有效期；新输入、错误、历史改写、手动控制或超时会使旧决策失效 |
+| 手动接管 | 本地认证控制接口，可锁档和取消锁档；只有 `auto` 模式实际改档，锁档不越过不兼容形态保护 |
+| 文本摘要 | Jev 只收到有界文本证据，不接收执行模型认证、加密思考或系统指令；执行模型的完整请求历史不被删减 |
+| 传输 | 只监听 `127.0.0.1`；本地随机令牌；Host/浏览器来源检查；HTTP/SSE 字节透传；不重试、不跟随重定向 |
+| 可观察性 | 建议、准备、发送、响应结果分开记录；Jev 调用和已知用量单独记录；缺失值为未知，不造节省比例 |
+| Codex 辅助 | `doctor`、原生 `model/list` 能力探针、一次性 CLI 启动参数；不修改日常 `config.toml` 或读取登录文件 |
+
+**不实现：** WebSocket 代理、原生 Codex 补丁、自动桌面安装、`configuration_update` 注入、多模型路由、配额耗尽换渠道、完整缓存优化。含图片、未知增量上下文、未知历史条目或内容类型、非字符串工具结果、压缩历史或已有配置更新的请求会原样旁路，不调用判断器；手动锁档也不越过此边界。
+
+## 用 npm 安装
+
+需要 Node.js **22.16+**。npm 包已准备好，**尚未发布到 npm registry**。现在可以通过 npm 安装经过验证的 Git 提交（需要 Git），之后直接使用 `cae` 命令，不必保留源码目录：
+
+```bash
+# 把 REVIEWED_COMMIT 替换为经过验证的完整提交 SHA。
+npm install --global --ignore-scripts github:ppxu/codex-adaptive-effort#REVIEWED_COMMIT
+cae --version
+cae --help
+```
+
+首次发布到 npm 后，安装命令可简化为 `npm install --global --ignore-scripts codex-adaptive-effort@alpha`。完整的安装、升级、卸载和桌面启动步骤见 [npm 使用说明](docs/NPM.md)。配置仍保存在你选择的工作目录；在同一目录执行 `cae desktop start/status/stop`，或者始终传入同一个 `--config`。后文的 `node bin/cae.mjs` 都可以替换成 `cae`。
+
+## 从源码离线运行（不需要任何模型密钥）
+
+Node.js **22.16+**。运行代码没有第三方 npm 依赖，也没有安装脚本。
+
+```bash
+npm ci --ignore-scripts
+npm run verify
+```
+
+`verify` 会做语法检查、自动化测试、五阶段 HTTP/SSE 演示。演示启动的判断器和模型后端都是本地模拟；它证明接线与状态控制，不证明 Jev 判断准确度或真实节省。
+
+```bash
+node bin/cae.mjs --help
+node bin/cae.mjs doctor
+```
+
+## 本地 Codex 接入顺序
+
+已验收版本的 macOS arm64 桌面可直接使用实验启动器：
+
+```bash
+node bin/cae.mjs desktop start --model gpt-6-astra --auth chatgpt --enable-upstream
+# 在另一终端检查或退出：
+node bin/cae.mjs desktop status
+node bin/cae.mjs desktop stop
+```
+
+首次自动创建独立 CAE 配置，每次查询实际模型能力并校验生效的 provider；默认 shadow + baseline，不启用 Jev。`--enable-jev` 显式启用进程级 Jev shadow，最多 8 次判断，禁止 auto/锁档；另外添加 `--allow-jev-auto` 才允许随后通过 `control auto` 开始实验性自动改档。第二组三条桌面 shadow 请求均成功；后续 auto 实测完成 medium → high，另一次 Jev 超时后保持 medium。后续 2000 ms 实验以 665 ms 完成 medium → low；降档通过，放宽超时的改善效果与日常稳定性仍未证实。可显式添加 `--jev-timeout-ms 2000` 进行仅本进程生效的超时实验，默认仍为 1500 ms。请在新实例中新建 Codex 本地任务，旧会话不会自动迁移。版本限制、实例辨认和控制命令见 [桌面启动器说明](docs/DESKTOP_LAUNCHER.md)。
+
+先读 [LOCAL_VALIDATION.md](docs/LOCAL_VALIDATION.md)，按「原版 → off → 手动 auto → Jev shadow → Jev auto」逐级验证。**这不是默认启用的桌面兼容承诺。** 首版提供可撤销的 CLI 路径验证代理；本机独立桌面实例已通过启动、纯文本 off/手动锁档及取消恢复，见 [桌面检查记录](docs/DESKTOP_ACCEPTANCE.md)。
+
+仅查询本机 Codex 公布的模型/档位，不发起生成：
+
+```bash
+node bin/cae.mjs probe > capabilities.local.json
+```
+
+选取探针实际返回的模型 ID，保留原有认证方式。使用 ChatGPT 订阅时：
+
+```bash
+# MODEL_ID 必须替换为 probe 返回的真实 model 字段。
+node bin/cae.mjs init --auth chatgpt --model "$MODEL_ID" --capabilities capabilities.local.json
+```
+
+`.cae/` 是新建的隔离控制器目录；已存在时拒绝覆盖。它不是新的 Codex 登录目录。CAE 不打开 `auth.json`；原生 Codex 仍自行处理其正常登录。
+
+在明确同意发起真实模型请求后，开两个终端：
+
+```bash
+# 终端 1：默认仍是 shadow + baseline-only，未接入 Jev。
+node bin/cae.mjs serve --enable-upstream
+
+# 终端 2：仅该子进程使用代理，不改日常 Codex 配置。
+node bin/cae.mjs codex --auth chatgpt --
+```
+
+ChatGPT 路线已完成上述限定版本的 CLI 与独立桌面实例验收，不能外推到所有客户端版本或普通 ChatGPT 聊天。结构化工具结果的历史仍安全旁路，手动锁档也不越过该保护。出现认证/协议错误时停止接入、保留原版 Codex；不能通过导出 Cookie、拷贝网页凭证或改用 API 付费来假装修复。
+
+API 使用者须从初始化起明确选择 `--auth api`，再在自己的终端提供 `OPENAI_API_KEY`。两种路线不能混用，代码会检查。API 请求可能按量计费；此工具不把订阅额度转换成 API 额度。
+
+## 启用 Jev
+
+建议先执行 [固定合成样例 shadow 验收](docs/JEV_SHADOW_ACCEPTANCE.md)：默认只预览，授权后最多 8 次 Jev 请求，不发起 Codex 生成。它用于验证真实判断器；桌面请使用 [Jev shadow 开关](docs/DESKTOP_LAUNCHER.md)，下面的磁盘配置步骤用于独立 serve 服务。
+
+默认 `judge.kind=baseline` **不是复杂度判断器**，只是接线验收用的固定基准。要接入 Jev：停止服务，在 `.cae/config.json` 将 `judge.kind` 改为 `typesafe`，通过你自己的密钥管理方式设置 `TYPESAFE_API_KEY`，然后显式执行：
+
+```bash
+node bin/cae.mjs serve --enable-upstream --enable-jev
+```
+
+此时仍从 `shadow` 开始。只有明确切换到 `auto` 才改档：
+
+```bash
+node bin/cae.mjs status
+node bin/cae.mjs control auto
+node bin/cae.mjs lock high
+node bin/cae.mjs unlock
+node bin/cae.mjs control off
+node bin/cae.mjs report
+```
+
+以上 `high` 必须在你的模型支持集合内。控制是**此 CAE 服务实例级**的，影响其下一次尚未发送的合格请求，不修改正在生成的响应。
+
+Jev 调用把有限任务文本发给 TypeSafe，不是本地离线推理；脱敏是尽力处理，不保证消除业务机密。不得把公司代码或敏感任务送入未批准的第三方服务。默认最多 100 次评估/服务进程，重启重置；这是调用次数上限，不是美元预算。取消或超时仍可能已产生服务端费用。
+
+## 退出与恢复
+
+`control off` 只关闭自动判断，**仍经过代理**。完全恢复：结束这次实验 Codex 进程，停止 CAE 服务，再正常运行原版 `codex` / 官方桌面应用。因为没有写日常配置，不需要回写登录信息。代理进程崩溃不等于自动直连；不承诺不中断地恢复。
+
+## 贡献与仓库维护
+
+本项目已发布，当前仓库应通过普通 Git 和 Pull Request 继续维护，不要再次运行首次建仓脚本。默认文档语言为英文；请参阅 [文档索引](docs/README.md)、[贡献指南](CONTRIBUTING.md)、[安全说明](SECURITY.md) 和 [发布说明](docs/PUBLISHING.md)。原始中文验收记录保留在文档索引的历史证据部分。
+
+## 协议来源与开源边界
+
+这是独立实现，没有打包两个上游项目源码或 Codex 二进制；设计来源和固定参考提交见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。本项目代码为 MIT。模型、Jev API、Codex 和账户服务分别受其自身许可与使用条款约束；CAE 不是 OpenAI / TypeSafe 官方产品。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Provenance and third-party notices
+
+This release contains new project code and no vendored Codex, Astra-Ares or Jev Codex Router source or binaries. It does not modify their copyright notices, claim to be an official fork, or relicense external services. No third-party npm dependencies are installed. Node.js and development tooling have their own licenses.
+
+Design references inspected on 2026-09-24:
+
+| Source | Fixed reference | Design used as inspiration |
+|---|---|---|
+| [miuuyy/Astra-Ares](https://github.com/miuuyy/Astra-Ares) | `b2011446d88202329dcdc5163500ca818aba9dbb` | fixed executor identity, bounded generation lease, decision/commit separation, stale-state rejection |
+| [0xNatoshi/jev-codex-router](https://github.com/0xNatoshi/jev-codex-router) | `8701ef788aa8cb0948f299538747fb01029d32b8` | local adapter, small decision projection vs full executor replay, operational bypass, observed-usage reporting |
+
+The inspected repositories' top-level licenses are MIT. Astra-Ares also identifies patched OpenAI Codex components as Apache-2.0. Future source imports must preserve the exact applicable licenses/NOTICE and record provenance; these references alone do not grant rights to third-party account services or model weights.
+
+Primary protocol references (mutable web documentation, accessed 2026-09-24):
+
+- [Codex configuration reference](https://developers.openai.com/codex/config-reference/): custom provider, Responses wire API, environment headers, native auth and WebSocket configuration.
+- [Codex App Server](https://developers.openai.com/codex/app-server): initialize / initialized / model/list; returned effort capabilities.
+- [OpenAI reasoning guide](https://developers.openai.com/api/docs/guides/reasoning): request effort vs mid-conversation configuration updates and their restrictions. This release **does not implement configuration_update**.
+- [TypeSafe API](https://docs.typesafe.ai/api): System One `state` + typed Choice questions, `/v1/systemone`.
+- [TypeSafe language support](https://docs.typesafe.ai): Jev is text-based; real Chinese follow-up performance requires evaluation.
+- [GitHub CLI repository creation](https://cli.github.com/manual/gh_repo_create): explicit public creation from a local source directory.
+
+The ChatGPT backend path is an experimental compatibility route, not a promise that third-party proxying is officially supported. Native authentication/transport requirements may make a given client version incompatible. Never repair that by scraping or exporting credentials.

package/bin/cae-desktop-bridge.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { loadConfig, readLocalToken } from '../src/config.mjs';
+import { codexArgs } from '../src/codex.mjs';
+import { verifyDesktopProvider, desktopControl } from '../src/desktop.mjs';
+import { CaeError } from '../src/util.mjs';
+
+async function main() {
+  const [configPath, binary, ...input] = process.argv.slice(2);
+  if (!configPath || !binary) throw new CaeError('desktop_bridge_arguments');
+  const config = loadConfig(configPath);
+  let index = 0;
+  while (index < input.length) {
+    if (['-c', '--config'].includes(input[index]) && index + 1 < input.length) index += 2;
+    else if (input[index].startsWith('--config=')) ++index;
+    else break;
+  }
+  const isVersion = input.length === 1 && ['--version', '-V'].includes(input[0]);
+  if (!isVersion && input[index] !== 'app-server') throw new CaeError('desktop_bridge_command_unsupported');
+  const args = isVersion ? input : codexArgs(config, 'chatgpt', input);
+  const env = { ...process.env }; delete env.CODEX_CLI_PATH; delete env.TYPESAFE_API_KEY; delete env.CAE_LOCAL_TOKEN;
+  if (!isVersion) {
+    await verifyDesktopProvider(binary, args, config);
+    const health = await fetch(`http://127.0.0.1:${config.port}/health`, { redirect: 'error',
+      signal: AbortSignal.timeout(3000), headers: { 'x-cae-token': readLocalToken(config.tokenFile) } });
+    const state = health.ok ? await health.json() : null;
+    if (!state?.ok || !state.auditHealthy || state.model !== config.model) throw new CaeError('proxy_health_mismatch');
+    await desktopControl(configPath, 'bridge-ready');
+    env.CAE_LOCAL_TOKEN = readLocalToken(config.tokenFile);
+  }
+  const child = spawn(binary, args, { env, stdio: 'inherit' });
+  let timer;
+  const stop = () => { child.kill('SIGTERM'); timer ??= setTimeout(() => child.kill('SIGKILL'), 1000); timer.unref(); };
+  process.once('SIGTERM', stop); process.once('SIGINT', stop);
+  child.once('error', () => { console.error('CAE: codex_not_available'); process.exitCode = 1; });
+  child.once('exit', code => { clearTimeout(timer); process.off('SIGTERM', stop); process.off('SIGINT', stop); process.exitCode = code ?? 1; });
+}
+main().catch(error => {
+  console.error(`CAE: ${error instanceof CaeError ? error.code : 'desktop_bridge_failed'}`);
+  process.exitCode = 1;
+});

package/bin/cae.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { defaultConfig, loadConfig, readLocalToken } from '../src/config.mjs';
+import { CaeError } from '../src/util.mjs';
+import { BaselineJudge, TypeSafeJudge } from '../src/judge.mjs';
+import { Audit, report } from '../src/audit.mjs';
+import { startProxy } from '../src/proxy.mjs';
+import { doctor, probeModels, codexArgs } from '../src/codex.mjs';
+import { VERSION } from '../src/version.mjs';
+
+const HELP = `Codex Adaptive Effort ${VERSION} (Node >=22.16; no dependencies)
+
+  cae --version / -V                       Print installed package version
+  cae doctor [--codex PATH]                 No credentials or network read by CAE
+  cae probe [--codex PATH]                  Native initialize + model/list only
+  cae init --model ID --auth chatgpt|api --capabilities FILE [--baseline EFFORT]
+  cae init --model ID --auth chatgpt|api --efforts low,medium,high --baseline high
+  cae serve --enable-upstream [--enable-jev] Start local proxy (foreground)
+  cae status                               Authenticated local state
+  cae control off|shadow|auto               Change next unsent request policy
+  cae lock high / cae unlock               Explicit instance-wide lock
+  cae codex --auth chatgpt|api -- [ARGS]     One-off launch, no config.toml writes
+  cae launch-args --auth chatgpt|api         Print non-secret argv for inspection
+  cae desktop start --auth chatgpt --enable-upstream [--model ID] [--enable-jev [--allow-jev-auto]]
+  cae desktop status / desktop stop        Isolated macOS desktop instance
+  cae report                              Observed usage, not savings claims
+
+Shared: --config .cae/config.json; init: --dir .cae
+serve Jev requires config judge.kind=typesafe, TYPESAFE_API_KEY and --enable-jev.
+Desktop --enable-jev is process-only, shadow/off only, at most 8 evaluations.
+Add --allow-jev-auto to permit control auto; startup still requires shadow/off.
+Desktop --jev-timeout-ms 1500|2000 overrides only this process's Jev timeout.
+An external upstream requires --enable-upstream and normal Codex auth.
+Default is SHADOW with a baseline-only evaluator, not a complexity classifier.
+`;
+function print(value) { console.log(typeof value === 'string' ? value : JSON.stringify(value, null, 2)); }
+async function localCall(c, path, body) {
+  const response = await fetch(`http://127.0.0.1:${c.port}${path}`, {
+    method: body ? 'POST' : 'GET', redirect: 'error', signal: AbortSignal.timeout(3000),
+    headers: { 'x-cae-token': readLocalToken(c.tokenFile), 'content-type': 'application/json' },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  if (!response.ok) throw new CaeError(`local_http_${response.status}`);
+  return response.json();
+}
+async function main() {
+  const input = process.argv.slice(2), dash = input.indexOf('--');
+  const passthrough = dash < 0 ? [] : input.slice(dash + 1);
+  const { values: v, positionals: p } = parseArgs({ args: dash < 0 ? input : input.slice(0, dash),
+    allowPositionals: true, strict: true, options: {
+      help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'V' }, config: { type: 'string', default: '.cae/config.json' },
+      dir: { type: 'string', default: '.cae' }, model: { type: 'string' }, efforts: { type: 'string' },
+      baseline: { type: 'string' }, auth: { type: 'string' }, capabilities: { type: 'string' },
+      codex: { type: 'string', default: 'codex' }, 'enable-upstream': { type: 'boolean' }, 'enable-jev': { type: 'boolean' },
+      app: { type: 'string' },
+      'allow-jev-auto': { type: 'boolean' },
+      'jev-timeout-ms': { type: 'string' },
+    } });
+  const command = p[0];
+  if (v.version) { print(VERSION); return; }
+  if (!command || v.help) { print(HELP); return; }
+  if (v['allow-jev-auto'] && (command !== 'desktop' || p[1] !== 'start')) throw new CaeError('desktop_auto_start_only');
+  if (v['jev-timeout-ms'] !== undefined && (command !== 'desktop' || p[1] !== 'start')) throw new CaeError('desktop_timeout_start_only');
+  if (v['jev-timeout-ms'] !== undefined && !['1500', '2000'].includes(v['jev-timeout-ms'])) throw new CaeError('desktop_invalid_jev_timeout');
+  if (command === 'desktop') {
+    if (p.length !== 2 || passthrough.length) throw new CaeError('desktop_invalid_arguments');
+    if (input.some(x => x === '--codex' || x.startsWith('--codex='))) throw new CaeError('desktop_uses_verified_bundled_cli');
+    const { startDesktop, desktopControl } = await import('../src/desktop.mjs');
+    const explicitConfig = input.some(x => x === '--config' || x.startsWith('--config='));
+    const configPath = explicitConfig ? v.config : '.cae/desktop/config.json';
+    if (p[1] === 'start') {
+      const desktop = await startDesktop({ configPath, model: v.model, baseline: v.baseline, auth: v.auth,
+        enableUpstream: v['enable-upstream'], enableJev: v['enable-jev'], allowJevAuto: v['allow-jev-auto'],
+        jevTimeoutMs: v['jev-timeout-ms'] === undefined ? undefined : Number(v['jev-timeout-ms']),
+        appPath: v.app, onState: print });
+      print(await desktop.done); return;
+    }
+    if (!['status', 'stop'].includes(p[1])) throw new CaeError('desktop_unknown_action');
+    print(await desktopControl(configPath, p[1], { timeoutMs: p[1] === 'stop' ? 15000 : 5000 })); return;
+  }
+  if (command === 'doctor') { print(doctor(v.codex)); return; }
+  if (command === 'probe') { print(await probeModels(v.codex)); return; }
+  if (command === 'init') {
+    if (!v.model || !['api', 'chatgpt'].includes(v.auth)) throw new CaeError('init_requires_model_and_auth');
+    let efforts = v.efforts?.split(','), baseline = v.baseline, capabilitySource;
+    if (v.capabilities) {
+      const data = JSON.parse(readFileSync(v.capabilities, 'utf8'));
+      const entry = data.models?.find(m => m.model === v.model);
+      if (!entry) throw new CaeError('model_missing_from_capabilities');
+      efforts = entry.supportedEfforts; baseline ??= entry.baseline;
+      capabilitySource = `${data.source ?? 'provided capture'} at ${data.observedAt ?? 'unknown time'}; refresh after client upgrades`;
+    }
+    if (!efforts || !baseline) throw new CaeError('init_requires_capabilities_or_efforts_and_baseline');
+    const config = defaultConfig(v.model, efforts, baseline); config.upstream.kind = v.auth;
+    if (capabilitySource) config.capabilitySource = capabilitySource;
+    const dir = resolve(v.dir);
+    mkdirSync(dir, { mode: 0o700 }); // EEXIST intentionally refuses to overwrite.
+    writeFileSync(resolve(dir, 'local.key'), randomBytes(32).toString('hex') + '\n', { mode: 0o600, flag: 'wx' });
+    writeFileSync(resolve(dir, 'config.json'), JSON.stringify(config, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+    print('Created isolated CAE configuration. No Codex configuration or login files were touched.'); return;
+  }
+  const c = loadConfig(v.config);
+  if (command === 'serve') {
+    let judge;
+    if (c.judge.kind === 'typesafe') {
+      if (!v['enable-jev']) throw new CaeError('jev_external_processing_not_enabled');
+      judge = new TypeSafeJudge({ apiKey: process.env.TYPESAFE_API_KEY, model: c.judge.model });
+    } else judge = new BaselineJudge();
+    const audit = new Audit(c.logFile);
+    let proxy;
+    try { proxy = await startProxy(c, { token: readLocalToken(c.tokenFile), judge,
+      emit: record => audit.emit(record), auditHealthy: () => !audit.failed, allowUpstream: v['enable-upstream'] === true }); }
+    catch (e) { audit.close(); throw e; }
+    print({ listening: `127.0.0.1:${proxy.port}`, mode: c.mode, judge: c.judge.kind,
+      upstream: c.upstream.kind, credentialsLogged: false, note: 'Foreground service. Stop and relaunch normal Codex to bypass it.' });
+    let stopping = false;
+    const stop = async () => { if (stopping) return; stopping = true; await proxy.close(); audit.close(); };
+    process.once('SIGINT', stop); process.once('SIGTERM', stop); return;
+  }
+  if (command === 'status') { print(await localCall(c, '/health')); return; }
+  if (command === 'control') { print(await localCall(c, '/control', { mode: p[1] })); return; }
+  if (command === 'lock') { print(await localCall(c, '/control', { lockedEffort: p[1] })); return; }
+  if (command === 'unlock') { print(await localCall(c, '/control', { lockedEffort: null })); return; }
+  if (command === 'report') {
+    let text; try { text = readFileSync(c.logFile, 'utf8'); } catch { throw new CaeError('cannot_read_log'); }
+    const records = []; let malformedLines = 0;
+    for (const line of text.split('\n').filter(Boolean)) { try { records.push(JSON.parse(line)); } catch { ++malformedLines; } }
+    print({ ...report(records), malformedLines }); return;
+  }
+  if (['codex', 'launch-args'].includes(command)) {
+    const args = codexArgs(c, v.auth, passthrough);
+    if (command === 'launch-args') { print({ command: v.codex, args, requiredEnvironmentNames: ['CAE_LOCAL_TOKEN', ...(v.auth === 'api' ? ['OPENAI_API_KEY'] : [])] }); return; }
+    const health = await localCall(c, '/health');
+    if (!health.ok || health.model !== c.model) throw new CaeError('proxy_health_mismatch');
+    if (v.auth === 'api' && !process.env.OPENAI_API_KEY) throw new CaeError('missing_openai_api_key');
+    const env = { ...process.env, CAE_LOCAL_TOKEN: readLocalToken(c.tokenFile) };
+    delete env.TYPESAFE_API_KEY;
+    const child = spawn(v.codex, args, { env, stdio: 'inherit', shell: false });
+    child.once('error', () => { console.error('CAE: codex_not_available'); process.exitCode = 1; });
+    child.once('exit', code => { process.exitCode = code ?? 1; }); return;
+  }
+  throw new CaeError('unknown_command');
+}
+main().catch(error => {
+  // Do not echo upstream bodies, environment, argument values or native stderr.
+  console.error(`CAE: ${error instanceof CaeError ? error.code : 'command_failed_check_arguments_and_local_paths'}`);
+  process.exitCode = 1;
+});

package/docs/DESKTOP_LAUNCHER.md

@@ -0,0 +1,122 @@
+# Experimental desktop launcher
+
+The launcher starts an independent instance of the installed Codex desktop application. It is not a packaged plugin, does not control ordinary ChatGPT conversations and does not migrate existing chats.
+
+## Requirements and scope
+
+The current allowlist is **macOS arm64**, **ChatGPT/Codex desktop 26.924.22138 / build 11645**, and its bundled **codex-cli 0.158.0-alpha.2.1**. Local acceptance used macOS 27.0 and Node v24.16.0. The launcher verifies the official application signature and exact version, queries native capabilities, and checks the effective provider with `initialize` + `config/read`. An application update requires revalidation; CAE does not upgrade, downgrade or replace native binaries.
+
+The experimental instance uses its own Electron data directory but shares native Codex home and login. It may show existing projects and chats. **Create a new local Codex chat** in a directory containing only non-sensitive test material. Old chats retain their previous providers; cloud tasks and ordinary ChatGPT chats are not covered.
+
+## Start with baseline shadow
+
+After [npm installation](NPM.md), replace `node bin/cae.mjs` in this guide with `cae` and use your chosen working directory in every terminal. When running from source, use the repository root. Select a model ID returned by the [native probe](LOCAL_VALIDATION.md):
+
+```bash
+node bin/cae.mjs desktop start --model "$MODEL_ID" --auth chatgpt --enable-upstream
+```
+
+Keep this terminal running. First launch creates `.cae/desktop/config.json`; later launches reuse it and reject an unexpected model/baseline change. The default is shadow + baseline-only, which does not classify task complexity or call Jev. Starting does not submit a task; sending a task consumes the normal model allowance.
+
+In another terminal:
+
+```bash
+node bin/cae.mjs desktop status
+```
+
+Wait for `phase=running`, `effectiveProvider=cae`, `connected=true` and at least one successful bridge check. The output includes the experimental desktop PID and configuration path. The provider display name is `CAE experimental local effort controller`; CAE does not patch the native window title. Automated visual identification was not accepted independently.
+
+Custom locations are supported with `--config PATH` and `--app PATH`. Use the same `--config` for start/status/stop. The configuration directory must be private. The default proxy port is 4319; a conflict fails startup without killing another process. Arbitrary CLI replacement via `--codex` is rejected for desktop startup.
+
+## Manual controls without Jev
+
+For a baseline instance, select only efforts from the actual capability set:
+
+```bash
+node bin/cae.mjs control off --config .cae/desktop/config.json
+node bin/cae.mjs lock low --config .cae/desktop/config.json
+node bin/cae.mjs control auto --config .cae/desktop/config.json
+# Send an eligible synthetic text task in the experimental window.
+node bin/cae.mjs control off --config .cae/desktop/config.json
+node bin/cae.mjs unlock --config .cae/desktop/config.json
+```
+
+Controls apply to this CAE instance, not a single chat. Locks affect only eligible auto requests; unsupported history still bypasses adaptation. Controls affect the next unsent request, not a response already being generated.
+
+## Enable Jev shadow
+
+Stop the old experimental instance first. Supply `TYPESAFE_API_KEY` through your normal environment setup, without putting its value in command arguments or public logs:
+
+```bash
+node bin/cae.mjs desktop start --model "$MODEL_ID" --auth chatgpt \
+  --enable-upstream --enable-jev
+```
+
+This changes the evaluator to TypeSafe only for the current process. It does not persist the evaluator or key. Startup still requires a shadow/off configuration. With this flag alone, `shadowOnly=true`: auto and non-null manual locks are rejected with `shadow_only_control`. Off/shadow switching does not renew the budget.
+
+The native CLI, probe and desktop child processes do not inherit the Jev key. Jev receives a bounded text projection; redaction is not a guarantee that business secrets are removed. Use only tasks approved for external processing.
+
+Every desktop Jev process permits at most eight evaluations, or a smaller configured call limit. By default, the timeout is the smaller of the configured timeout and 1500 ms. A timeout or cancellation may still incur provider usage. Exhausting the limit records `judge_call_budget` and falls back without retrying or switching providers. Restarting begins a new budget; this is not a spending guarantee.
+
+<a id="jev-auto受控实验"></a>
+## Enable a controlled auto trial
+
+With explicit authorization to change real request effort, add the separate auto permission:
+
+```bash
+node bin/cae.mjs desktop start --model "$MODEL_ID" --auth chatgpt \
+  --enable-upstream --enable-jev --allow-jev-auto
+```
+
+Startup still uses shadow/off. Once running, check `judgeKind=typesafe`, `shadowOnly=false`, `lockedEffort=null`, `judgeCalls=0` and `activeRequests=0`, then switch:
+
+```bash
+node bin/cae.mjs control auto --config .cae/desktop/config.json
+```
+
+Invalid decisions, timeouts and exhausted budgets retain the incoming effort; when effort is absent, the configured baseline is used. Other models and unsupported shapes bypass adaptation. The desktop effort selector may continue showing the user's chosen baseline: CAE modifies the outbound request, not that selector.
+
+For the recorded installation, `gpt-6-astra` supports medium, low and high. In a new local chat, keep the desktop selection at medium and submit these non-sensitive fixtures one at a time, waiting for completion:
+
+1. `Do not use tools. Correct Helo to Hello. Reply only with the corrected string.`
+2. `Do not use tools. Analyze a fictional scheduler: A is cancelled, B starts, and a late callback from A overwrites B's state. Describe the faulty sequence, ownership invariant, and smallest fix.`
+
+These English examples are reproduction instructions, not a claim that the original Chinese fixtures were rerun in English. Jev need not recommend low/high. A timeout or unchanged recommendation must be recorded honestly, without automatic retries to obtain a preferred outcome.
+
+<a id="可选-2000-ms-实验"></a>
+## Optional 2000 ms timeout experiment
+
+```bash
+node bin/cae.mjs desktop start --model "$MODEL_ID" --auth chatgpt \
+  --enable-upstream --enable-jev --allow-jev-auto --jev-timeout-ms 2000
+```
+
+`--jev-timeout-ms` accepts only 1500 or 2000 and requires `desktop start --enable-jev`. It explicitly replaces the disk timeout for this process, including a smaller disk value. It never writes the configuration. Check `judgeTimeoutMs` in status before switching to auto.
+
+The default remains 1500 ms. Restart without the parameter to restore the original disk value subject to that ceiling. The successful real downshift took 665 ms, below either deadline; it does not establish a benefit from increasing the limit. The worst-case timeout wait increases by roughly 500 ms.
+
+## Inspect results
+
+```bash
+node bin/cae.mjs desktop status
+node bin/cae.mjs report --config .cae/desktop/config.json
+```
+
+Reports aggregate an append-only event file and can include earlier instances. For a trial, filter by its time window and correlate local request IDs across `decision`, `request_prepared`, `request_sent` and `upstream_outcome`. A recommendation alone is not an applied change. An applied request setting plus completion is not proof of actual model reasoning allocation or task quality.
+
+Jev timings separate observed request creation, send start, body sent, response headers, body completion and validation. They do not independently resolve DNS/TCP/TLS or pure server inference time. Missing fields remain unknown. Do not upload raw event files; publish only reviewed, sanitized summaries.
+
+## Stop and recover
+
+```bash
+node bin/cae.mjs control off --config .cae/desktop/config.json
+node bin/cae.mjs desktop stop
+```
+
+The stop command closes this instance, its tracked children and proxy; success returns `stopped`. Ctrl+C in the startup terminal uses the same cleanup path. Stop interrupts active experimental tasks, so wait for completion when possible. Ordinary desktop instances are not cleanup targets.
+
+`off` still uses the proxy. After stop, use the normal official application; no global configuration or login restoration is needed. Forced supervisor death (for example SIGKILL) can leave stale resources and requires manual inspection. CAE does not guess ownership from an old PID, run `killall` or promise automatic direct-routing failover.
+
+## Evidence
+
+[Current local acceptance](LOCAL_ACCEPTANCE.md) covers the real auto upshift/downshift and fallback. [Initial desktop acceptance](DESKTOP_ACCEPTANCE.md) covers manual controls and cancellation. The [original Chinese launcher record](DESKTOP_LAUNCHER.zh-CN.md) preserves dated startup tests and source hashes; its intermediate pending steps are historical.