codex-adaptive-effort 0.1.0-alpha.1 → 0.1.0-beta.1

package/AGENTS.md

@@ -0,0 +1,21 @@
+# Agent work contract
+
+Project: Codex Adaptive Effort, experimental independent Node ESM implementation. Read README.md, docs/LIMITATIONS.md and docs/VALIDATION.md first. The initial planning-only package has been superseded by this code, not all long-term goals are implemented.
+
+## Invariants
+
+- Fixed user-selected model, provider, auth route and service tier. No account/quota workarounds.
+- Never read, copy, print, upload or patch native login files, cookies, keychains, secrets, or `.cae/local.key`. Read local CAE token only in the application paths designed for it. Never put it in shell arguments.
+- No global Codex configuration edits, no approval/sandbox bypass flags and no native binary replacement.
+- Baseline + shadow by default. Live GPT or Jev calls need explicit user permission and existing normal credentials; absence of credentials is not permission to retrieve them elsewhere.
+- User has requested open-source publication. Publishing original source to the named user-owned repository is allowed; `.cae`, capabilities captures, logs, dotenv, and private task histories are not publishable.
+- Check actual remote/commit/CI state before claiming success. A connector without repo-creation capability cannot be represented as having created a repo.
+- An executor body may change only `reasoning.effort` for eligible auto requests. Unsupported shapes bypass without deleting history. All upstream response bytes remain unchanged.
+- Per-session transaction ownership, cancellation, stale revision rejection and completed-response lease commit must remain tested.
+- No invented quality, success probabilities, cache savings or cost savings. `configuration_update`, WebSocket and a packaged desktop plugin are not implemented. The experimental desktop launcher is limited to its validated app/CLI version and new local threads; preserve its preflight and owned-process cleanup checks.
+
+## Development
+
+Run `npm run verify`. No dependency install hooks, network or paid provider calls in tests. Use synthetic fixtures. Actual model IDs and effort sets must come from a freshly captured native model/list or an explicitly supplied operator capability set. The test model `synthetic-model` must never be substituted into a live request.
+
+Prefer small changes. Do not combine a native patch and proxy as two simultaneous controllers. Add a regression test for every confirmed defect. Update acceptance status honestly and preserve provenance.

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+User-visible changes are recorded here. Unreleased entries describe the current main branch; they are not a promise of a tagged release or production support.
+
+## Unreleased
+
+No pending changes.
+
+## 0.1.0-beta.1 — 2026-09-29
+
+First beta, using the opt-in `beta` npm channel. Native desktop compatibility remains limited to the documented macOS/app/CLI combination; this is not a stable or production-readiness claim.
+
+### Fixed and improved
+
+- Keep authenticated health/off controls available when all 64 forwarding slots are occupied; controls have a separate eight-request limit.
+- Observe BOM and CR/LF/CRLF SSE across chunk boundaries without changing response bytes, and restrict JSON terminal metadata to known statuses.
+- Verify effective desktop retry settings, and forward wrapper termination to the owned native process with bounded cleanup.
+- Reject unknown commands and surplus/missing operands before config reads; provide sanitized local recovery hints.
+- Stream audit reports line by line and retain unknown usage for evaluator attempts interrupted before their finish record.
+- Include complete linked public documentation in the npm archive, add an offline link/anchor check and troubleshooting guide, and exercise Node 22.16.0 in CI with pinned Actions.
+- Advance the package version and default publish tag to `0.1.0-beta.1` / `beta`, with matching English and Chinese installation instructions. The published alpha archive remains unchanged.
+
+### Validation
+
+- 236 offline tests, including 22 new regression cases; archive installation and linked documentation are checked without model calls.
+- Native signature/version, capability metadata and effective provider retry preflight passed on the existing validated installation. No real model/Jev generation was rerun for this iteration.
+- See the [review and validation scope](docs/CODE_REVIEW_2026-09-29.md) and [release receipt](https://github.com/ppxu/codex-adaptive-effort/releases/tag/v0.1.0-beta.1) for the exact released commit, CI and registry checks. Known Jev timeout and general compatibility limits remain.
+
+## 0.1.0-alpha.1 — 2026-09-24
+
+Initial source version: fixed-model effort controller, TypeSafe Jev Choice evaluator, bounded decision reuse, shadow/off/auto modes, manual controls, circuit/call limits, authenticated HTTP/SSE proxy, bounded audit metadata, capability probe, CLI launcher, offline tests and publication helper.
+
+The initial source date precedes the first npm publication on 2026-09-29. The additions and fixes below accumulated before that publication. At the initial source stage, native acceptance, repository publication and CI execution were not established; later acceptance is recorded separately. This heading does not assert a GitHub Release on the initial source date.
+
+### Added
+
+- Installable npm CLI package with an explicit runtime/docs file list, `cae --version`, offline archive/install tests and installation/upgrade instructions. The first npm alpha was published on 2026-09-29; see [release evidence](docs/VALIDATION.md#npm-registry-publication--2026-09-29).
+- Guarded macOS arm64 desktop launcher with version/signature checks, native capability/provider preflight and owned-process cleanup.
+- Explicit desktop Jev shadow and auto trial controls, an eight-evaluation process cap and optional process-only 2000 ms timeout; the default ceiling remains 1500 ms.
+- Metadata-only Jev fetch stage timings and actual timeout values in status.
+- Bounded evaluator-only synthetic fixture runner for explicitly authorized real Jev checks.
+- English-first documentation, Chinese entry point and preserved original acceptance records; issue and pull request templates.
+
+### Fixed
+
+- Reject non-object native metadata/control frames and safely ignore non-object SSE data without changing response bytes.
+- Bypass unknown or malformed history before evaluation; require response identity before committing a JSON completion lease.
+- Validate upstream kinds against own string allowlist entries and keep offline syntax checks within public source boundaries.
+- Preserve desktop provider overrides when native app-server uses subcommand-scoped configuration arguments.
+- Recognize native `ultra` capabilities without widening individual models' supported effort sets.
+- Handle headerless SSE for explicitly streaming requests and retain validated completion when a client closes after the terminal event.
+
+### Validation
+
+- The 2026-09-28 [code review](docs/CODE_REVIEW_2026-09-28.md) added 12 regressions: 212 offline tests passed locally; new-commit CI and native acceptance remain separate evidence.
+- Real tests on one documented macOS/app/CLI combination covered CLI transport, desktop off/manual locks/cancellation/recovery, Jev shadow, automatic upshift/downshift and timeout fallback.
+- The runtime baseline passed 199 offline tests. Check the current commit's CI separately after documentation or tooling changes.
+- Jev timeouts remain unresolved. A 665 ms successful downshift under a 2000 ms deadline does not establish a benefit from the larger deadline. No quality, cost or general compatibility claims were added.

package/CODEX_START.md

@@ -0,0 +1,14 @@
+# Maintainer handoff
+
+This repository is already implemented and published at [ppxu/codex-adaptive-effort](https://github.com/ppxu/codex-adaptive-effort). Continue maintaining the existing code. Do not rerun repository creation, rebuild the architecture, install upstream routers or treat historical plans as current tasks.
+
+1. Read `AGENTS.md`, `README.md`, `docs/LIMITATIONS.md`, `docs/LOCAL_ACCEPTANCE.md` and `docs/VALIDATION.md`.
+2. Inspect the branch, source commit, worktree changes and origin. Preserve all existing changes; do not reset, clean or force-push. Check CI for the actual commit.
+3. Run `npm ci --ignore-scripts` and `npm run verify` when relevant; report the observed result. Reuse complete results only when the tested source is unchanged and their time/commit are identified.
+4. For native compatibility work, use `doctor` and the native `model/list` probe. Query metadata only unless real generation is explicitly authorized. Use actual model IDs and capabilities.
+5. Make the smallest relevant change, add regression coverage for defects and update English documentation. Keep historical evidence dated and distinguish synthetic tests from real acceptance.
+6. Review staged files for private data. Publish only original source, synthetic tests and sanitized documentation through ordinary Git/PR workflows. Check the new commit's CI after pushing.
+
+Never read native login files, cookies, keychains or secrets; never change global Codex configuration, approval/sandbox settings or account/billing routes. The native client retains responsibility for login. `.cae`, capability captures, raw logs, credentials and real task histories remain local.
+
+See [Publishing](docs/PUBLISHING.md) for existing-repository maintenance and [Local validation](docs/LOCAL_VALIDATION.md) for explicitly authorized experiments. A change in one installed desktop version is not a compatibility promise for all versions.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of Conduct
+
+We want participation in this project to be respectful, constructive and welcoming, regardless of background, identity or level of experience.
+
+## Expectations
+
+- Discuss ideas and code in good faith; give specific, actionable feedback.
+- Respect other contributors' time, privacy and boundaries.
+- Do not harass, threaten, discriminate, disclose private information or post personal attacks.
+- Do not share credentials, private task histories or confidential code.
+
+These expectations apply to repository issues, pull requests and other project-managed spaces. Maintainers may edit or remove inappropriate contributions, close discussions or restrict participation. Responses should reflect the severity and context of the behavior.
+
+For a conduct concern, contact the repository owner through an available private contact channel on their [GitHub profile](https://github.com/ppxu). If no private channel is available, request a contact method without publishing identifying or sensitive details. Security vulnerabilities should use the separate [security reporting process](SECURITY.md).

package/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+CAE is an experimental independent implementation. Focus contributions on small, reviewable improvements within the [documented scope](docs/LIMITATIONS.md). Use English for new public documentation, issues and pull requests where possible; keep the Chinese entry point consistent when user-facing behavior changes.
+
+## Development setup
+
+```bash
+git clone https://github.com/ppxu/codex-adaptive-effort.git
+cd codex-adaptive-effort
+npm ci --ignore-scripts
+npm run verify
+```
+
+Use Node.js 22.16 or later. Runtime code is Node ESM with no third-party runtime dependencies. `verify` checks syntax, JSON and public Markdown links/anchors, runs tests and executes the offline demo. Tests use synthetic inputs and local servers: no real credentials, model generation or paid provider requests. CI covers Node 22/24 on Linux, macOS and Windows, plus the minimum Node 22.16.0 on Linux. Keep Actions pinned to reviewed commits when updating CI.
+
+## Report a problem
+
+Search existing issues, then use the bug report template. Include the source commit, OS/architecture, Node and native app/CLI versions, mode, auth route name and sanitized error codes. Reproduce with synthetic text. A UI response alone does not prove that traffic traversed CAE; distinguish decisions, sends and completed outcomes.
+
+Never attach `.cae`, capability captures, dotenv files, raw native logs, auth files, keys, private paths or task histories. Follow [Security](SECURITY.md) for vulnerabilities instead of a public issue.
+
+## Submit a change
+
+1. Fork the repository or create a topic branch if you have write access.
+2. Keep each change focused; preserve existing user work and avoid unrelated refactors.
+3. Add a regression test for a confirmed defect. Keep provider calls mocked or on local test servers.
+4. Run `npm run verify` and review `git diff --check` and the files being staged.
+5. Update affected guides and the Unreleased changelog when behavior changes.
+6. Open a pull request describing the problem, resulting behavior, validation and remaining limits.
+
+There is no required commit-message convention. Prefer a short imperative summary. Passing CI is necessary evidence, not proof of native compatibility. Cite the exact commit and environment for any real acceptance claim; mark untested behavior explicitly.
+
+## Behavioral contract
+
+- Preserve the user-selected model, provider, auth route, service tier, approval policy and sandbox.
+- Only eligible auto requests may change `reasoning.effort`; preserve executor history and upstream response bytes.
+- Keep cancellation, per-session ownership, stale revision rejection and completed-response lease commits tested.
+- Default to shadow + baseline. Real Jev/model calls require explicit authorization and normal credentials.
+- Do not read native login files, retrieve secrets elsewhere, replace binaries, add implicit billing fallbacks or alter global Codex configuration.
+- Record known usage and unknowns separately. Do not infer quality equivalence or savings from effort changes.
+
+Read [AGENTS.md](AGENTS.md), [Architecture](docs/ARCHITECTURE.md), [Limitations](docs/LIMITATIONS.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before substantial work. Proposed third-party source imports must retain applicable licenses and provenance.

package/README.md

@@ -8,9 +8,11 @@
 
 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)
+[简体中文](README.zh-CN.md) · [Documentation](docs/README.md) · [Troubleshooting](docs/TROUBLESHOOTING.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.
+> **Beta: `0.1.0-beta.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.
+
+This beta includes the [runtime, reporting and installation fixes](docs/CODE_REVIEW_2026-09-29.md). It is an opt-in prerelease with the same native compatibility boundaries. See the [release notes and publication receipt](https://github.com/ppxu/codex-adaptive-effort/releases/tag/v0.1.0-beta.1).
 
 ## What it does
 
@@ -29,16 +31,15 @@ The default evaluator is **baseline-only**, a transport test fixture rather than
 
 ## 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):
+Requires Node.js **22.16+**, npm and an existing Codex installation for native integration. There are no third-party runtime dependencies or install hooks. Install the [npm beta](https://www.npmjs.com/package/codex-adaptive-effort):
 
 ```bash
-# Replace REVIEWED_COMMIT with the full tested Git commit SHA.
-npm install --global --ignore-scripts github:ppxu/codex-adaptive-effort#REVIEWED_COMMIT
+npm install --global --ignore-scripts codex-adaptive-effort@beta
 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.
+To pin this release, use `codex-adaptive-effort@0.1.0-beta.1`. Use the explicit `beta` tag; publishing a beta does not promote `latest`. See the [npm guide](docs/NPM.md) for Git commits, local archives, upgrades, uninstalling and configuration locations. Global installation provides the command; configuration stays in your chosen working directory.
 
 For source development:
 
@@ -51,7 +52,7 @@ 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.
+Verification checks public documentation links and 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, plus Linux on the minimum Node 22.16.0. Passing CI does not imply native integration on all these platforms.
 
 ## Quick start: inspect capabilities
 

package/README.zh-CN.md

@@ -2,9 +2,11 @@
 
 **固定执行模型，动态调整思考强度。** 这是面向本地 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)；正式安装和其他环境仍未验收。没有节省费用、保持质量或生产可用性的保证。
+**当前版本：`0.1.0-beta.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)
+[English](README.md) · [本地验收](docs/LOCAL_VALIDATION.md) · [排错指南](docs/TROUBLESHOOTING.md) · [架构](docs/ARCHITECTURE.md) · [验证记录](docs/VALIDATION.md) · [限制](docs/LIMITATIONS.md)
+
+本 beta 包含[本轮运行时、报告与安装修复](docs/CODE_REVIEW_2026-09-29.md)，保持现有原生兼容范围和默认 shadow 行为，适合主动选择的实验验证。确切发布提交、CI 与 npm 校验见[发布记录](https://github.com/ppxu/codex-adaptive-effort/releases/tag/v0.1.0-beta.1)。
 
 ## 已实现
 
@@ -24,16 +26,15 @@
 
 ## 用 npm 安装
 
-需要 Node.js **22.16+**。npm 包已准备好，**尚未发布到 npm registry**。现在可以通过 npm 安装经过验证的 Git 提交（需要 Git），之后直接使用 `cae` 命令，不必保留源码目录：
+需要 Node.js **22.16+**。[npm 包](https://www.npmjs.com/package/codex-adaptive-effort)的 beta 版本为 `0.1.0-beta.1`。安装后直接使用 `cae` 命令，不必保留源码目录：
 
 ```bash
-# 把 REVIEWED_COMMIT 替换为经过验证的完整提交 SHA。
-npm install --global --ignore-scripts github:ppxu/codex-adaptive-effort#REVIEWED_COMMIT
+npm install --global --ignore-scripts codex-adaptive-effort@beta
 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`。
+请显式使用 `@beta`，或固定 `@0.1.0-beta.1`；本次 beta 发布不提升 `latest` 标签。完整的安装、升级、卸载和桌面启动步骤见 [npm 使用说明](docs/NPM.md)。配置仍保存在你选择的工作目录；在同一目录执行 `cae desktop start/status/stop`，或者始终传入同一个 `--config`。后文的 `node bin/cae.mjs` 都可以替换成 `cae`。
 
 ## 从源码离线运行（不需要任何模型密钥）
 
@@ -44,7 +45,7 @@ npm ci --ignore-scripts
 npm run verify
 ```
 
-`verify` 会做语法检查、自动化测试、五阶段 HTTP/SSE 演示。演示启动的判断器和模型后端都是本地模拟；它证明接线与状态控制，不证明 Jev 判断准确度或真实节省。
+`verify` 会做语法与公共文档链接检查、自动化测试、五阶段 HTTP/SSE 演示。CI 覆盖三种系统的 Node 22/24，以及 Linux 上的最低 Node 22.16.0。演示启动的判断器和模型后端都是本地模拟；它证明接线与状态控制，不证明 Jev 判断准确度或真实节省。
 
 ```bash
 node bin/cae.mjs --help
@@ -56,7 +57,8 @@ node bin/cae.mjs doctor
 已验收版本的 macOS arm64 桌面可直接使用实验启动器：
 
 ```bash
-node bin/cae.mjs desktop start --model gpt-6-astra --auth chatgpt --enable-upstream
+# MODEL_ID 必须来自本机真实能力探针。
+node bin/cae.mjs desktop start --model "$MODEL_ID" --auth chatgpt --enable-upstream
 # 在另一终端检查或退出：
 node bin/cae.mjs desktop status
 node bin/cae.mjs desktop stop

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security and data boundaries
+
+This is beta software, not a sandbox or a security certification. Do not use confidential or production workloads before an independent review and provider approval.
+
+## Trust model
+
+The local user, configuration file, native Codex binary and OS account are trusted. The local random token is a defense against unrelated processes/browser traffic, not against a malicious same-user process that can read your files. Only `127.0.0.1` is bound. Authenticated control is instance-wide, not per-chat. Browser Origin/site/destination metadata is refused and Host is checked; a valid 256-bit local token is still required. No browser UI is provided.
+
+OpenAI authentication is relayed in memory only to a fixed API or ChatGPT origin. The token used to authenticate to CAE is stripped from outgoing traffic. TypeSafe receives its own dedicated key and limited redacted text, not OpenAI authentication, cookies, encrypted reasoning, system/developer text or tool definitions. CAE does not open Codex `auth.json`, cookie stores, browser profiles or keychains. Native Codex still manages its ordinary authentication.
+
+Task text and tool output can contain business secrets not recognized by redaction. **Enable Jev only for workloads allowed to leave your environment.** CAE has no offline Jev implementation. Prompt-injection resistance of the external classifier is not proven: schema validation limits values, not semantic judgment quality. A mistaken low-effort decision can harm task quality even though the protocol is valid.
+
+## Operational protections and limits
+
+No automatic upstream retries or redirect following. Generated launcher configuration disables Codex provider retries, but other clients may retry themselves. Requests have body/time limits; concurrent requests in one recognized session receive 409. Separate sessions can run concurrently. Cancellation propagates to the network where possible; it does not prove the remote service stopped billing.
+
+Metadata-only audit files are 0600 on POSIX. Only explicitly allowlisted fields are written; request bodies and provider error bodies are not logged. `status` includes `auditHealthy`; a logging failure does not break the model stream. There is no log rotation in this beta. Windows ACL and cross-user confidentiality require local validation; POSIX modes are not Windows ACL guarantees.
+
+Forwarding saturation does not consume the separate authenticated health/control slots. Audit reports process logs incrementally; malformed lines are counted, and evaluator attempts without a finish record retain unknown usage. These controls and reporting fixes are included in `0.1.0-beta.1`.
+
+Some unsupported histories bypass adaptation but still go to the original executor. `off` is not network isolation and still uses the proxy. If the proxy crashes, end the experimental session and relaunch ordinary Codex; there is no background config rewrite or automatic direct-routing promise.
+
+## Supported versions
+
+Security fixes are considered for the current main branch and latest beta. There is no long-term support commitment for older snapshots. Include the exact source commit and native client version when reporting a problem.
+
+## Reporting a vulnerability
+
+Use [GitHub private vulnerability reporting](https://github.com/ppxu/codex-adaptive-effort/security/advisories/new) for this repository. Do not open a public issue with exploit details or sensitive data. Include a synthetic reproduction, affected versions, impact and any suggested mitigation. If the private channel is unavailable, request a private contact method without disclosing the vulnerability publicly. No response-time guarantee is offered.
+
+Do not post keys, auth files, raw private requests or real session histories. For a credential exposure, rotate the affected key through its provider and remove the exposure through the relevant hosting service. Never put a live credential into a test fixture or security report.

package/bin/cae-desktop-bridge.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { loadConfig, readLocalToken } from '../src/config.mjs';
-import { codexArgs } from '../src/codex.mjs';
+import { codexArgs, waitForNative } from '../src/codex.mjs';
 import { verifyDesktopProvider, desktopControl } from '../src/desktop.mjs';
 import { CaeError } from '../src/util.mjs';
 
@@ -29,11 +29,7 @@ async function main() {
     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; });
+  process.exitCode = await waitForNative(child);
 }
 main().catch(error => {
   console.error(`CAE: ${error instanceof CaeError ? error.code : 'desktop_bridge_failed'}`);

package/bin/cae.mjs

@@ -7,9 +7,9 @@ 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 { Audit, reportFile } from '../src/audit.mjs';
 import { startProxy } from '../src/proxy.mjs';
-import { doctor, probeModels, codexArgs } from '../src/codex.mjs';
+import { doctor, probeModels, codexArgs, waitForNative } from '../src/codex.mjs';
 import { VERSION } from '../src/version.mjs';
 
 const HELP = `Codex Adaptive Effort ${VERSION} (Node >=22.16; no dependencies)
@@ -39,12 +39,18 @@ 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}`, {
+  const token = readLocalToken(c.tokenFile);
+  let response;
+  try { 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' },
+    headers: { 'x-cae-token': token, 'content-type': 'application/json' },
     ...(body ? { body: JSON.stringify(body) } : {}),
-  });
-  if (!response.ok) throw new CaeError(`local_http_${response.status}`);
+  }); } catch { throw new CaeError('local_proxy_unreachable'); }
+  if (!response.ok) {
+    const code = (await response.json().catch(() => null))?.error?.code;
+    const known = ['shadow_only_control', 'unsupported_lock', 'invalid_mode', 'invalid_control', 'too_many_requests'];
+    throw new CaeError(known.includes(code) ? code : `local_http_${response.status}`);
+  }
   return response.json();
 }
 async function main() {
@@ -63,6 +69,13 @@ async function main() {
   const command = p[0];
   if (v.version) { print(VERSION); return; }
   if (!command || v.help) { print(HELP); return; }
+  const commands = ['doctor', 'probe', 'init', 'serve', 'status', 'control', 'lock', 'unlock', 'report', 'codex', 'launch-args', 'desktop'];
+  if (!commands.includes(command)) throw new CaeError('unknown_command');
+  if (command !== 'desktop') {
+    if (p.length !== (['control', 'lock'].includes(command) ? 2 : 1) ||
+        (dash >= 0 && !['codex', 'launch-args'].includes(command))) throw new CaeError('invalid_arguments');
+    if (command === 'control' && !['off', 'shadow', 'auto'].includes(p[1])) throw new CaeError('invalid_mode');
+  }
   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');
@@ -114,7 +127,7 @@ async function main() {
     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; }
+    catch (e) { audit.close(); throw e.code === 'EADDRINUSE' ? new CaeError('proxy_port_in_use') : 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;
@@ -126,10 +139,7 @@ async function main() {
   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;
+    print(await reportFile(c.logFile)); return;
   }
   if (['codex', 'launch-args'].includes(command)) {
     const args = codexArgs(c, v.auth, passthrough);
@@ -140,13 +150,24 @@ async function main() {
     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;
+    process.exitCode = await waitForNative(child); 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'}`);
+  const code = error instanceof CaeError ? error.code : error.code?.startsWith('ERR_PARSE_ARGS_') ? 'invalid_arguments' : 'command_failed_check_arguments_and_local_paths';
+  console.error(`CAE: ${code}`);
+  const hint = {
+    unknown_command: 'Run cae --help to see available commands.',
+    invalid_arguments: 'Run cae --help. Native CLI arguments belong after -- with cae codex or cae launch-args.',
+    cannot_read_config: 'Run cae init first, use the same working directory, or pass --config PATH. Desktop controls use --config .cae/desktop/config.json.',
+    cannot_read_log: 'No readable audit log yet. Start the proxy using this configuration before requesting a report.',
+    local_proxy_unreachable: 'Start the foreground proxy and use its matching --config PATH; desktop status uses cae desktop status.',
+    proxy_port_in_use: 'This proxy port is occupied. Stop your existing experiment or choose a free port in the isolated CAE configuration.',
+    shadow_only_control: 'This desktop process allows off/shadow only. Auto needs a new explicitly opted-in --enable-jev --allow-jev-auto start.',
+    unsupported_lock: 'Choose an effort from cae status supportedEfforts for this model.',
+  }[code];
+  if (hint) console.error(`Hint: ${hint}`);
   process.exitCode = 1;
 });

package/docs/ARCHITECTURE.md

@@ -0,0 +1,48 @@
+# Architecture
+
+```text
+Native Codex CLI or guarded desktop bridge (native auth)
+       |
+       | HTTP Responses; optional SSE; native session header when present
+       v
+127.0.0.1 CAE proxy -- local token + Host + origin checks
+       |
+       +--> bounded text projection --> TypeSafe Jev --> effort + lease
+       |       (or baseline fixture for transport verification)
+       |
+       +--> controller: validated decision + revision + single session owner
+       |       | off / unsupported: original bytes
+       |       | shadow: original bytes, proposed effort only in audit
+       |       | auto: full body with reasoning.effort changed only
+       v
+Fixed OpenAI API OR experimental ChatGPT Codex backend
+       |
+       +--> response bytes streamed unchanged --> Codex
+       +--> bounded terminal metadata observer --> usage + completion audit
+```
+
+## Ownership and commit
+
+`Controller.prepare` reserves one owner per recognized session and computes local integrity fingerprints. A new user input, changed model/instructions/tools/reasoning setting, non-append-only history or newly observed explicit tool error breaks reuse. A retained decision applies for at most 1–4 generations, with a fixed deadline that does not extend on every reuse. A repeated identical request is not counted as a continuation.
+
+A decision is not proof of application. `beforeSend` checks the latest control revision. `request_prepared` marks request construction; `request_sent` is emitted only when the Node HTTP request finishes writing. Even that is **not** evidence that the model obeyed the setting. `upstream_outcome` records the actual terminal event/status/usage, if observable. A lease is committed only after successful stream completion and only for the same control revision. Unknown or truncated completion never establishes a lease.
+
+The native `session_id` or explicit trusted `x-cae-session` is HMAC'd together with the auth partition using a per-process salt. These identifiers are not written to logs or sent to Jev. `prompt_cache_key` is preserved but never treated as session identity. Without a session header, every eligible call is assessed independently and lease=1. Sessions are capped at 128 retained entries; forwarding has 64 in-flight slots and authenticated local controls have eight separate slots. Memory state is not durable across restart.
+
+## Context and scope
+
+The executor retains every input item, encrypted reasoning item, instruction, tool definition, result, service tier and cache key. The evaluator gets a bounded character projection: recent user context, latest user request, up to two public notes and three tool-result excerpts, plus omission metadata. The projection does not run another language model or token-costly summarizer. It is intentionally limited; long-history requirements may be omitted. Chinese task understanding must be evaluated with real tasks.
+
+Media, existing configuration updates, standalone/in-history compaction and unknown server-side continuations bypass classification/adaptation. This is conservative gating, not support for every such native workflow. Standalone `/responses/compact` is forwarded but is not included in the generation usage report in this release.
+
+The adapter only supports HTTP/SSE, not WebSocket. Its explicit 426 prevents accidental claims of WebSocket compatibility. Generated settings request Responses and disable WebSockets/retries. The guarded desktop launcher verifies these effective settings for the documented app/CLI combination; other versions and transports remain unvalidated. See [desktop setup](DESKTOP_LAUNCHER.md).
+
+## Failure behavior
+
+Jev timeout/provider errors/malformed choices preserve the request's incoming effort; configured baseline is used only when that value is absent. Expired low leases are never used as an error fallback. A 3-failure circuit opens for 30 seconds; maxCalls is a process-lifetime attempt limit. These are availability safeguards, not proof the retained effort is adequate for the task.
+
+The proxy does not retry OpenAI requests or follow redirects. It forwards a provider error once. A caller may choose to retry; such identical requests are re-evaluated instead of consuming a prior lease. Client disconnect aborts local judge/upstream networking but cannot guarantee remote billing stopped. Logging failure is exposed in health without corrupting the stream.
+
+## Future adapter boundary
+
+An Ares-style native checkpoint adapter can use the same decision lifecycle, but is not built here. A future adapter must prove which actual step settings were captured and obey native compaction/configuration-update rules. There must never be two controllers modifying the same request. No native source fork is required for the current proxy MVP.

package/docs/CODE_REVIEW_2026-09-28.md

@@ -0,0 +1,33 @@
+# Code quality review — 2026-09-28
+
+## Scope and provenance
+
+Reviewed all runtime modules, CLI and desktop entry points, maintenance scripts, offline tests and CI configuration. Focus areas were request mutation boundaries, transaction ownership, cancellation, completion, malformed protocol messages, subprocess cleanup and private-data handling. This was a source review with synthetic regressions, not an independent security audit or new native acceptance run.
+
+Baseline: `1f3b4e205da4603c7aac1d066fa1c82b691cbd4d`. Its [matching CI run](https://github.com/ppxu/codex-adaptive-effort/actions/runs/36391209920) succeeded. The changes accompanying this record require their own CI result; the baseline result does not validate them.
+
+Local environment: macOS 27.0, arm64, Node v24.16.0. Validation took place on 2026-09-28 UTC. The pre-existing untracked source manifest was preserved and excluded from this change. No native configuration, credentials, local captures or private task histories were read for this review.
+
+## Confirmed findings and fixes
+
+| Priority | Finding | Fix and regression evidence |
+| --- | --- | --- |
+| P1 | `null` is valid JSON but caused uncaught property-access exceptions in SSE observation, native model metadata, desktop provider preflight and the desktop management socket. | Check object shape before accessing fields. Ignore non-object SSE events while preserving response bytes; fail native metadata checks with sanitized codes; close malformed management frames without stopping the supervisor. Unit, synthetic subprocess, socket and HTTP regressions cover these paths. |
+| P1 | Unknown or malformed history entries could be silently omitted from evaluator evidence while the request remained eligible for effort changes. | Bypass unsupported history with `unsupported_history_item`, retaining original request bytes and making no evaluator call, even under a manual lock. Known text messages, opaque reasoning/call records and string tool outputs remain eligible and unchanged. |
+| P2 | A JSON body with `status: completed` but no valid response ID could establish a reusable decision lease. | Require a nonempty string ID as well as completed status, consistent with SSE completion checks. Preserve observable usage and response bytes; do not commit a lease for malformed completion. |
+| P2 | Upstream validation accepted inherited object properties such as `constructor`, and coerced array keys. | Require a string that is an own entry in the upstream allowlist. Invalid configuration fails before a proxy starts. |
+| P2 | The syntax checker recursively parsed arbitrary repository-local JSON, including ignored captures and possible credential files. | Reuse the existing public-source selection and safety checks. Root captures, credential files and local manifests are excluded. Private files or symlinks inside public source roots are rejected before their contents are read. A synthetic fixture proves private root JSON is not parsed and malformed public JavaScript still fails. |
+
+Eight focused regression tests were run against the unchanged implementation and failed as expected: four protocol crash paths, completion identity, history eligibility, upstream kind validation and private-file scanning. They passed after the fixes. Additional HTTP tests verify byte preservation, evaluator bypass and lease behavior, and a positive history test protects the accepted text/tool subset.
+
+## Validation result
+
+`npm run verify` passed with **212 tests**, zero failures, cancellations or skips, plus syntax/JSON checks and the offline HTTP/SSE demo. All provider responses and native metadata in this review were synthetic; HTTP tests used loopback servers. The check now also applies the existing public-source scanner.
+
+Existing regression coverage for session ownership, stale control revisions, cancellation, late judge results, timeout fallback, call budgets, response byte preservation, desktop opt-in and process cleanup remains passing. No dependencies, external services, real generation, model capability capture or desktop application launch were needed.
+
+## Behavior changes and remaining limits
+
+Unsupported history now bypasses more conservatively. New native item/content types, refusal parts and structured tool outputs need explicit compatibility work before automatic or manual effort changes apply. Original upstream requests continue intact; this can reduce the number of requests CAE adjusts.
+
+The known native compatibility window, Jev latency uncertainty, forced-supervisor-death recovery, lack of WebSocket support and unmeasured task quality/cost remain as documented in [limitations](LIMITATIONS.md). This review does not establish a new native version, improve the 2000 ms timeout evidence or justify production-readiness claims. If a later native version emits new history shapes, first capture sanitized metadata and add synthetic compatibility fixtures, then perform separately authorized transport acceptance.

package/docs/CODE_REVIEW_2026-09-29.md

@@ -0,0 +1,29 @@
+# Code quality and usability review — 2026-09-29
+
+## Scope and baseline
+
+Reviewed runtime and CLI/desktop entry points, protocol boundaries, cancellation and child ownership, audit/reporting, package contents, public documentation and repository CI. Baseline: `3726e3178bdc218da794ee20c493db7826fedf5d`; its [six-job CI](https://github.com/ppxu/codex-adaptive-effort/actions/runs/36514188536) passed. This source revision needs its own CI result.
+
+The baseline passed `npm ci --ignore-scripts` and `npm run verify`: 214 tests on macOS arm64 / Node 24.16.0. Baseline coverage was also inspected to identify unexercised branches; its aggregate percentage is not a measure of native compatibility or complete product quality. Existing local files were preserved.
+
+## Findings and changes
+
+| Area | Finding and resulting behavior | Verification |
+| --- | --- | --- |
+| Availability | 64 active forwarding requests also blocked health and off controls. Eight separate authenticated control slots now remain available while the 64-request forwarding cap still applies. | Real loopback saturation, 429 for excess forwarding, successful health and off control. |
+| Streaming | The metadata observer missed valid CR-only SSE, leading BOM and case-insensitive SSE media types. It now handles CR/LF/CRLF across byte boundaries without changing relayed bytes. An incomplete final event still cannot commit a lease. | Byte-fragmented Unicode, each line-ending form, truncation and HTTP byte-preservation regressions. Parsing follows the [SSE format](https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream). |
+| Privacy | Arbitrary JSON `status` strings from provider bodies could become audit terminal metadata. Only known status values are now recorded. | Synthetic private status remains absent from metadata. |
+| Desktop preflight | Effective provider checks omitted retry settings. Both native request and stream retry counts must now equal zero. Preflight uses the installed package version. | Synthetic native config/read rejects either nonzero retry setting. |
+| Process ownership | The CLI wrapper did not forward termination to its native child. CLI and desktop bridge now share owned-child signal forwarding, a one-second termination deadline and handler cleanup. | Real synthetic subprocesses: normal exit, SIGINT, SIGTERM, missing executable and POSIX escalation. |
+| CLI usability | Unknown commands could report missing config, and surplus operands could be silently ignored. Commands/operands are validated before config access; common local failures have sanitized recovery hints. | Actual CLI subprocess failures and existing lifecycle integration. |
+| Reporting | Reports retained the complete log plus parsed records and omitted unknown usage for interrupted evaluator attempts without a finish record. Reports now fold one line at a time and keep incomplete attempts unknown. | Streamed/in-memory totals, zero versus unknown counters, malformed/truncated records and missing logs. Memory scales with the largest line and stream buffering instead of the full log; log rotation remains unimplemented. |
+| npm documentation | The archive omitted targets linked from its README and bundled guides. Its explicit allowlist now includes the complete linked public documentation and original synthetic evidence. | Real offline archive/install plus installed-document link checks; synthetic private sentinels remain excluded. |
+| Maintenance | Relative links and section anchors were not continuously checked, and CI did not exercise the advertised minimum Node version. Verification now checks public document links offline. CI adds Linux/Node 22.16.0, pins existing v4 actions to verified commit SHAs and cancels superseded branch runs. | Public-source boundary tests, link/anchor fixtures, package checks and the exact new commit's CI. |
+
+Eight protocol/control/CLI regression cases failed before repair. A separate interrupted-attempt regression and the installed-document check also failed before their fixes. No failing test was removed or relaxed.
+
+## Validation and release boundary
+
+The revised source passed 236 offline tests locally, including 22 new cases. The real installed native metadata probe and stricter provider preflight also passed without generation. Detailed environment, model capabilities, runtime fingerprint and a synthetic reporting memory comparison are recorded in [Validation](VALIDATION.md#comprehensive-review--2026-09-29). This review does not establish a new native desktop version, real model/Jev generation, task-quality or cost improvement, a stable release, or an npm publication. At review time these changes were unreleased; they are included in `0.1.0-beta.1`, whose [publication receipt](https://github.com/ppxu/codex-adaptive-effort/releases/tag/v0.1.0-beta.1) is separate evidence. The published `0.1.0-alpha.1` archive remains immutable.
+
+Native desktop guards, fixed model/provider/auth/service tier, conservative history bypass, manual-lock scope and completed-response lease ownership remain in force. Independent security review, general native compatibility, crash recovery after forced supervisor death and representative task-quality/latency/cost evidence remain outstanding.

package/docs/DESKTOP_ACCEPTANCE.md

@@ -0,0 +1,42 @@
+# Initial desktop acceptance
+
+**Recorded 2026-09-28, UTC+08:00.** One isolated desktop instance passed off transport, plain-text low/high manual locks, cancellation and same-chat recovery. Later Jev auto results are in [current local acceptance](LOCAL_ACCEPTANCE.md).
+
+The [original Chinese record](DESKTOP_ACCEPTANCE.zh-CN.md) preserves the full sequence, initial failure, exact source hashes and dated intermediate states. This page is a summary, not a new test run.
+
+## Environment and provenance
+
+- macOS 27.0 arm64, Node v24.16.0.
+- ChatGPT/Codex desktop 26.924.22138, build 11645; bundled codex-cli 0.158.0-alpha.2.1.
+- Source baseline `3c13aac2dcad333fae689b1273d3d4657bf90b8d` plus the argument-scope repair described below. The patch was uncommitted during initial capture; the original record identifies its file hashes.
+- Baseline [CI 36371612189](https://github.com/ppxu/codex-adaptive-effort/actions/runs/36371612189) succeeded for that baseline only. It must not be represented as CI coverage of the then-uncommitted patch.
+- Native ChatGPT authentication; independent Electron data and CAE configuration, shared native Codex home. No credential copying or global configuration edits.
+
+## Failure found and fixed
+
+The first UI response succeeded, but CAE recorded no proxy events. Native thread metadata showed the original provider, so this was a failed proxy acceptance result rather than a success.
+
+The launcher placed provider overrides before `app-server`. When the desktop also supplied subcommand-scoped `-c` options, this CLI version discarded the earlier override set. A command line containing `model_provider=cae` did not prove it was effective.
+
+The repair puts CAE overrides in the app-server subcommand scope, while preserving ordinary exec arguments. Native `initialize` + `config/read` confirmed the effective provider afterward, without generation. Two synthetic regressions covered desktop composition and avoiding false matches in prompts/config values. The repaired source passed 155 offline tests.
+
+## Real post-fix outcomes
+
+| Time | Check | Observed result |
+| --- | --- | --- |
+| 11:55–11:56 | Off | Main gpt-6-astra/medium request traversed CAE unchanged and completed |
+| 11:57–11:58 | Manual low | Incoming medium, source=manual, actual low send, HTTP 200 + completed |
+| 12:19–12:20 | Manual high | Incoming medium, source=manual, actual high send, HTTP 200 + completed |
+| 12:21 | Cancel | Native turn interrupt succeeded; proxy recorded cancelled, completed=false |
+| 12:21 | Same-chat recovery | Subsequent medium request completed unchanged |
+| 12:23 | Cleanup | Tracked experimental processes exited, port 4319 was free, native CLI version check succeeded |
+
+The post-fix batch had six upstream sends: five user test turns and one native auxiliary title request. Five completed and one was cancelled. Only the two manual-lock requests changed effort; Jev was not enabled. The initial request that bypassed CAE is outside these counts.
+
+UI interaction was performed by the user. The automation tool refused to control its own application, and no alternate UI-control mechanism was used to bypass that restriction. Metadata/transport completion should not be described as an independent visual inspection.
+
+## Limits
+
+This validates the installed app's local Codex programming surface, not ordinary ChatGPT chats, cloud tasks, a packaged plugin or arbitrary versions. Structured tool-result histories still bypass adaptation. Application upgrades, long-context behavior, task quality and cost savings were not accepted by these tests.
+
+Use the guarded [desktop launcher](DESKTOP_LAUNCHER.md) for current instructions. Do not replay historical process-management steps or use old PIDs from the archived record.