codex-adaptive-effort 0.1.0-alpha.1

package/docs/LIMITATIONS.md

@@ -0,0 +1,34 @@
+# Known limitations and acceptance boundaries
+
+The dated [local acceptance record](LOCAL_ACCEPTANCE.md) describes the tested macOS CLI subset; [desktop acceptance](DESKTOP_ACCEPTANCE.md) covers an independent desktop instance on that installation. Neither establishes packaged desktop integration or general production readiness.
+
+| Area | What is true now | What is not established |
+|---|---|---|
+| Code delivery | Runnable original Node ESM source, tests, offline demo | No claim of maintained production service |
+| Proxy | Synthetic HTTP/SSE tests plus real CLI and isolated desktop ChatGPT-route acceptance | No WebSocket acceptance |
+| Codex | Native model/list, isolated CLI, desktop plain-text off/locks/cancellation/recovery; CLI tools in off tested on one installation | Other client versions, packaged desktop installation, ordinary ChatGPT chats |
+| ChatGPT auth | Native authentication worked for the recorded CLI run; CAE does not read login files | Other accounts, environments, attestation and client versions |
+| API auth | Explicit separate api route; normal API key remains caller-owned | A subscription is not API credit; no live API request was made |
+| Jev | Eight evaluator-only fixture calls and a second three-case desktop shadow run succeeded; two earlier desktop timeouts remain unexplained. Desktop Jev defaults to enforced off/shadow; a separate process-only auto opt-in retains the 8-call cap and default 1500 ms ceiling; an explicit process-only timeout parameter allows a 2000 ms experiment. Real desktop medium-to-high, medium-to-low and timeout fallback requests completed successfully; the timeout last observed request creation before any send-start event. See [shadow](JEV_SHADOW_ACCEPTANCE.md) and [auto](LOCAL_ACCEPTANCE.md) records | Benefit of the 2000 ms experiment (the successful downshift took only 665 ms), cause of pre-send timeout, reliable completion within the 1500 ms budget, representative Chinese classification quality, reliable uncertainty handling and task outcome quality |
+| Model efforts | Supplied by actual capability probe or operator | No hardcoded assurance that any model supports all known effort names |
+| Cache | Cache controls/history preserved; request-level effort only | No configuration_update insertion, cached-prefix preservation or measured savings |
+| Context | Limited Unicode character excerpts and omission counts | Not token-exact, not all long-history requirements, no image/audio understanding |
+| Errors | Explicit structured tool failure fields recognized | A plain text log can hide failure; content classification remains Jev's job |
+| Bypass | Unsupported requests retain original bytes; structured tool-result history bypass was observed in a real session and is an accepted current boundary | Not every native history shape is tested; manual locks do not override the bypass |
+| Sessions | Explicit header plus auth partition; otherwise no cross-call lease | Cannot infer a reliable session from cache keys or message similarity |
+| Completion | Recognized SSE/JSON terminal metadata | A setting in a response does not prove actual reasoning allocation |
+| Usage | Known counters and unknowns separated; evaluator attempts recorded | Dollar savings, account quota debits, quality equivalence and full-task costs |
+| Other costs | Generation endpoint observed | Compaction costs, invisible retries, incomplete usage and external provider debits may be missing |
+| Security | Local auth/Host/origin checks, bounded state, metadata logs, no redirects | Not resistant to a malicious same-user process; redaction is not total confidentiality |
+| Recovery | No global config writes; normal Codex relaunch restores ordinary path | Proxy crash is not automatic failover |
+| Publication | Existing public repository; baseline CI success verified | Every new commit needs its own CI result; never reuse an older commit's result |
+
+Manual lock is instance-wide and only changes eligible `auto` requests. `off` and `shadow` never change effort, even with a lock set. To retain original execution without Jev cost use `off`; to remove the entire proxy from the path restart ordinary Codex.
+
+History eligibility is conservative: recognized text messages, opaque reasoning/call records and string tool outputs are supported. Unknown item/content types, malformed text and non-string tool outputs bypass unchanged with no evaluator call; a manual lock does not override this boundary. See the [code review](CODE_REVIEW_2026-09-28.md).
+
+The [desktop launcher](DESKTOP_LAUNCHER.md) is limited to the validated macOS arm64 app/CLI combination. It shares the native Codex home, does not migrate old threads, and requires a new local thread to use the configured provider. Normal stop and terminal interruption are tested; forced supervisor death and stale socket recovery require manual inspection. No native UI title patch or packaged plugin is provided.
+
+A server process lifetime cap is not a spending guarantee. Services may bill requests that time out or are cancelled. No trial uses a real key unless the operator explicitly enables it.
+
+Release blockers for any stable claim: independent security review; real native CLI acceptance for both intended auth paths; packaged desktop integration and upgrade compatibility; long-session/compaction acceptance; low/normal/hard task comparisons including Chinese short follow-ups; actual quality, cache, latency and cost observations. Until then, treat this as a protocol-level alpha.

package/docs/LOCAL_VALIDATION.md

@@ -0,0 +1,83 @@
+# CLI and native validation guide
+
+Validate in a separate process and a directory containing only synthetic, non-sensitive tasks. Keep an ordinary Codex session available. Never read/copy native login files or change global `~/.codex/config.toml`, approval policies or sandbox settings. For the validated desktop version, use the [desktop guide](DESKTOP_LAUNCHER.md).
+
+## 1. Offline checks and native metadata
+
+```bash
+npm ci --ignore-scripts
+npm run verify
+node bin/cae.mjs doctor
+node bin/cae.mjs probe > capabilities.local.json
+```
+
+The tests and demo do not use real providers. `doctor` queries the native version; `probe` initializes app-server and queries `model/list` without generating output. Native Codex may consult online model metadata. If the CLI is absent from `PATH`, pass `--codex /path/to/trusted/codex` to doctor/probe and subsequent CLI launches. Do not replace or upgrade the desktop binary to make a check pass.
+
+Record the source commit, time, OS/architecture, Node version, trusted CLI path/version, exit codes and actual model/effort set. Keep the raw capture local. A failed probe is not permission to substitute synthetic models or scrape credentials.
+
+## 2. Initialize an isolated configuration
+
+Choose a real model from the capture. `$MODEL_ID` below means the exact value you selected:
+
+```bash
+node bin/cae.mjs init --model "$MODEL_ID" --auth chatgpt --capabilities capabilities.local.json
+node bin/cae.mjs launch-args --auth chatgpt
+```
+
+Initialization refuses to overwrite `.cae`. For another experiment use `--dir PATH` and pass `--config PATH/config.json` to later commands. CAE's directory is not a replacement Codex home. Native Codex continues to handle login.
+
+Preserve the existing auth route. ChatGPT subscription use requires `--auth chatgpt`. API use requires an explicitly selected `--auth api` configuration and the caller's normal `OPENAI_API_KEY`; it may be billed separately. Never silently fall back from subscription to API.
+
+Review the printed non-secret arguments: fixed model, local Responses URL, auth route and environment variable names, with no approval/sandbox overrides. Model IDs and effort values are environment-specific.
+
+## 3. Off transport trial
+
+Real requests need explicit authorization. Set `mode` to `off` in the isolated CAE configuration before starting. Leave normal Codex settings unchanged.
+
+```bash
+# Terminal A: foreground proxy
+node bin/cae.mjs serve --enable-upstream
+# Terminal B: experimental CLI, retaining native authentication
+node bin/cae.mjs codex --auth chatgpt --
+```
+
+Submit a minimal synthetic text task, then test a read-only tool in the synthetic directory, a follow-up, cancellation and recovery. Off disables evaluation/changes, not model usage or network forwarding. Record errors such as 401/403 or protocol failures; do not export cookies, change billing routes or hide retries.
+
+## 4. Manual effort trial without Jev
+
+Use efforts confirmed by the probe. The following values are examples, not universal capabilities:
+
+```bash
+node bin/cae.mjs lock low
+node bin/cae.mjs control auto
+# Send an eligible synthetic text task and wait for completion.
+node bin/cae.mjs lock high
+# Send another eligible task and wait for completion.
+node bin/cae.mjs control off
+node bin/cae.mjs unlock
+node bin/cae.mjs report
+```
+
+Correlate prepared/sent/completed events. Unsupported shapes, including structured tool-result history, can bypass even a manual lock. Do not remove history to force eligibility. A request sent with a value does not prove the model's actual reasoning allocation.
+
+## 5. Jev shadow, then auto
+
+Jev sends bounded task text to TypeSafe and may incur usage. Enable it only with explicit authorization for that external processing and the normal independent key.
+
+For a standalone serve process: stop the proxy, set `judge.kind` to `typesafe` and `mode` to `shadow` in the isolated configuration, supply `TYPESAFE_API_KEY` through your normal environment setup, then run:
+
+```bash
+node bin/cae.mjs serve --enable-upstream --enable-jev
+```
+
+Use a small configured `judge.maxCalls` budget. First verify shadow recommendations and fallback. With separate authorization to change effort, use `control auto`. The [desktop launcher](DESKTOP_LAUNCHER.md) has its own process-only flags, eight-call cap and timeout experiment; do not assume standalone serve uses those desktop caps.
+
+The evaluator-only [fixture runner](JEV_SHADOW_ACCEPTANCE.md) provides a separate bounded protocol check without executor generation. Neither fixtures nor a few successful requests establish representative accuracy or savings.
+
+## 6. Record evidence and recover
+
+Use the [acceptance template](acceptance-template.md). Separate local tests, CI, native metadata, actual sends, completion, UI observations and task quality. Record unknown usage as unknown. For comparative evaluation, control task content, starting state, context, model, mode, versions and timing; a single later success is not an A/B result.
+
+End the experimental CLI, stop the foreground proxy, then relaunch normal Codex. Desktop trials use `desktop stop`. `control off` alone does not remove the proxy. Do not rewrite login files as a recovery step.
+
+Never commit `.cae`, captures, raw logs, credentials or private task histories. Public evidence must be a reviewed, sanitized summary.

package/docs/NPM.md

@@ -0,0 +1,73 @@
+# Install and run the npm package
+
+Requires Node.js **22.16+** and npm. Native integration also requires your existing Codex installation and normal login. The package contains original CAE runtime code and selected guides, with no runtime dependencies, install hooks or bundled native binaries.
+
+## Package availability
+
+This revision prepares `codex-adaptive-effort@0.1.0-alpha.1` for npm distribution. **It has not been published to the npm registry by this change.** Do not infer registry availability from a source version or a successful package test.
+
+Until the first registry 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 a maintainer publishes the alpha release to npm, the shorter installation command will be:
+
+```bash
+npm install --global --ignore-scripts codex-adaptive-effort@alpha
+```
+
+No administrator privileges should be necessary with a user-owned Node installation. If `cae` is not found, add npm's global executable directory to your `PATH` (`npm prefix --global`: the `bin` subdirectory on macOS/Linux, or the prefix itself on Windows). Do not put credentials in command arguments.
+
+## Use a dedicated working directory
+
+Global installation makes the command available from any directory; configuration remains local to the directory you choose. It does not create or modify `~/.codex/config.toml`. Keep the same working directory in each terminal, or pass the same explicit `--config PATH`.
+
+```bash
+mkdir cae-trial
+cd cae-trial
+cae doctor
+cae probe > capabilities.local.json
+```
+
+If the native CLI is not on `PATH`, use `--codex /path/to/trusted/codex` for doctor/probe. Select `MODEL_ID` from the actual capability capture. Do not use a model ID copied from a fixture.
+
+For the [validated desktop version](DESKTOP_LAUNCHER.md):
+
+```bash
+cae desktop start --model "$MODEL_ID" --auth chatgpt --enable-upstream
+# In a second terminal, from the same cae-trial directory:
+cae desktop status
+cae desktop stop
+```
+
+The first launch creates `.cae/desktop/config.json`. Later starts can omit `--model` and reuse that configuration. Startup is foreground and still enforces native signature/version/capability/provider checks. Use a new local chat in the experimental window. Default mode is shadow with the baseline evaluator; Jev remains separately opt-in. Starting the launcher does not submit a task. Sending a task uses the normal model allowance.
+
+For CLI integration, follow [local validation](LOCAL_VALIDATION.md), replacing `node bin/cae.mjs` with `cae`. The [desktop guide](DESKTOP_LAUNCHER.md) uses the same substitution for manual controls, Jev opt-in and recovery. No repository checkout is needed after installation.
+
+## Upgrade, remove or install a local archive
+
+Stop the experimental instance before replacing the package: generated desktop launchers reference the installed package path. After an authorized registry release, upgrade with the same `npm install --global ...@alpha` command. A CAE upgrade does not widen native desktop compatibility or change stored configuration.
+
+```bash
+cae desktop stop
+npm uninstall --global codex-adaptive-effort
+```
+
+Removal leaves your project-local `.cae` directory intact. Stop the experiment and return to ordinary Codex to restore the normal route. Never remove native login files.
+
+From a source checkout, a local archive can be built and installed without any registry publication:
+
+```bash
+npm ci --ignore-scripts
+npm run verify
+npm pack --ignore-scripts
+npm install --global --ignore-scripts ./codex-adaptive-effort-0.1.0-alpha.1.tgz
+cae --version
+```
+
+The explicit `package.json` file list excludes `.cae`, captures, dotenv, credentials, logs, source manifests, tests and maintenance scripts. Archives are ignored by Git. The automated package test builds and installs an archive into a temporary prefix offline, checks the actual command shim, version/help, synthetic initialization and launch arguments, and verifies that desktop startup still refuses missing authorization before native inspection. It never installs globally into the user's prefix or starts a real model.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "codex-adaptive-effort",
+  "version": "0.1.0-alpha.1",
+  "description": "A fixed-model, opt-in reasoning-effort controller for local Codex Responses traffic.",
+  "type": "module",
+  "publishConfig": {"access": "public", "registry": "https://registry.npmjs.org/", "tag": "alpha"},
+  "files": [
+    "bin/cae.mjs",
+    "bin/cae-desktop-bridge.mjs",
+    "src/audit.mjs",
+    "src/codex.mjs",
+    "src/config.mjs",
+    "src/context.mjs",
+    "src/controller.mjs",
+    "src/desktop.mjs",
+    "src/judge-timing.mjs",
+    "src/judge.mjs",
+    "src/proxy.mjs",
+    "src/stream.mjs",
+    "src/util.mjs",
+    "src/version.mjs",
+    "README.en.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "docs/NPM.md",
+    "docs/DESKTOP_LAUNCHER.md",
+    "docs/LOCAL_VALIDATION.md",
+    "docs/LIMITATIONS.md"
+  ],
+  "engines": {"node": ">=22.16.0"},
+  "bin": {"cae": "./bin/cae.mjs"},
+  "scripts": {
+    "check": "node scripts/check.mjs",
+    "test": "node --test test/*.test.mjs",
+    "coverage": "node --experimental-test-coverage --test test/*.test.mjs",
+    "demo": "node scripts/demo.mjs",
+    "verify": "npm run check && npm test && npm run demo"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ppxu/codex-adaptive-effort.git"
+  },
+  "homepage": "https://github.com/ppxu/codex-adaptive-effort#readme",
+  "bugs": {
+    "url": "https://github.com/ppxu/codex-adaptive-effort/issues"
+  },
+  "keywords": [
+    "codex",
+    "reasoning-effort",
+    "local-proxy",
+    "jev",
+    "nodejs"
+  ]
+}

package/src/audit.mjs

@@ -0,0 +1,71 @@
+import { openSync, writeSync, closeSync, constants, fchmodSync } from 'node:fs';
+import { CaeError, knownNumber, isObject } from './util.mjs';
+
+const FIELDS = new Set(['event', 'requestId', 'model', 'mode', 'effort', 'source', 'reason', 'revision',
+  'proposedEffort', 'incomingEffort', 'changed', 'lease', 'confidence', 'judgeMs', 'judgeInputTokens',
+  'judgeKind', 'stateChars', 'httpStatus', 'terminal', 'inputTokens', 'cachedInputTokens', 'outputTokens',
+  'reasoningTokens', 'durationMs', 'completed']);
+const TIMING_FIELDS = ['judgeRequestCreatedMs', 'judgeSendStartMs', 'judgeRequestSentMs',
+  'judgeResponseHeadersMs', 'judgeResponseBodyMs', 'judgeValidatedMs', 'judgeObservedMs'];
+const TIMING_STAGES = new Set(['started', 'created', 'sending', 'waiting_headers', 'reading_body', 'validating', 'completed']);
+export class Audit {
+  constructor(path) {
+    this.failed = false;
+    try {
+      this.fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | (constants.O_NOFOLLOW ?? 0), 0o600);
+      if (process.platform !== 'win32') fchmodSync(this.fd, 0o600);
+    } catch { throw new CaeError('cannot_open_audit_log'); }
+  }
+  emit(record) {
+    const clean = { schema: 1, time: new Date().toISOString() };
+    for (const [key, value] of Object.entries(record)) {
+      if (TIMING_FIELDS.includes(key)) { clean[key] = knownNumber(value); continue; }
+      if (key === 'judgeStage') { if (TIMING_STAGES.has(value)) clean[key] = value; continue; }
+      if (!FIELDS.has(key)) continue;
+      if (value === null || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value))) clean[key] = value;
+      else if (typeof value === 'string' && value.length < 200) clean[key] = value;
+    }
+    try { writeSync(this.fd, JSON.stringify(clean) + '\n'); }
+    catch { this.failed = true; } // Do not interrupt a model stream for a logging failure.
+  }
+  close() { if (this.fd !== undefined) { closeSync(this.fd); this.fd = undefined; } }
+}
+export function usageOf(response) {
+  const u = response?.usage;
+  return { inputTokens: knownNumber(u?.input_tokens), cachedInputTokens: knownNumber(u?.input_tokens_details?.cached_tokens),
+    outputTokens: knownNumber(u?.output_tokens), reasoningTokens: knownNumber(u?.output_tokens_details?.reasoning_tokens) };
+}
+export function report(records) {
+  records = records.filter(isObject);
+  const outcomes = records.filter(r => r.event === 'upstream_outcome');
+  const decisions = records.filter(r => r.event === 'decision');
+  const summary = {
+    decisions: decisions.length, requests: outcomes.length,
+    completed: outcomes.filter(r => r.completed).length,
+    changedRequests: records.filter(r => r.event === 'request_sent' && r.changed).length,
+    sources: {}, tokenObservations: {}, measuredSavings: null,
+    note: 'Observed usage only. Reasoning tokens are a subset of output tokens; do not add them again. Missing is not zero. Shadow traffic still uses the original effort. No counterfactual or quality equivalence is established.',
+  };
+  for (const r of decisions) summary.sources[r.source] = (summary.sources[r.source] ?? 0) + 1;
+  for (const key of ['inputTokens', 'cachedInputTokens', 'outputTokens', 'reasoningTokens']) {
+    const values = outcomes.map(r => knownNumber(r[key])).filter(v => v !== null);
+    summary.tokenObservations[key] = { observedSum: values.length ? values.reduce((a, b) => a + b, 0) : null,
+      knownRequests: values.length, unknownRequests: outcomes.length - values.length };
+  }
+  const judgeOutcomes = records.filter(r => r.event === 'judge_finished');
+  const knownJudgeUsage = judgeOutcomes.map(r => knownNumber(r.judgeInputTokens)).filter(v => v !== null);
+  summary.evaluator = {
+    attempts: records.filter(r => r.event === 'judge_started').length,
+    externalAttempts: records.filter(r => r.event === 'judge_started' && r.judgeKind === 'typesafe').length,
+    observedInputTokens: knownJudgeUsage.length ? knownJudgeUsage.reduce((a, b) => a + b, 0) : null,
+    unknownInputUsage: judgeOutcomes.length - knownJudgeUsage.length,
+    observedDurationMs: judgeOutcomes.reduce((n, r) => n + (knownNumber(r.judgeMs) ?? 0), 0),
+    note: 'Cancelled/timed-out evaluator calls may be billable even when usage is unknown. No dollar estimate.'
+  };
+  summary.evaluator.timeoutStages = {};
+  for (const row of judgeOutcomes.filter(r => r.reason === 'judge_timeout')) {
+    const stage = TIMING_STAGES.has(row.judgeStage) ? row.judgeStage : 'unknown';
+    summary.evaluator.timeoutStages[stage] = (summary.evaluator.timeoutStages[stage] ?? 0) + 1;
+  }
+  return summary;
+}

package/src/codex.mjs

@@ -0,0 +1,101 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { CaeError, isObject } from './util.mjs';
+import { EFFORT_NAMES } from './config.mjs';
+import { VERSION } from './version.mjs';
+
+export function nativeEnvironment(source = process.env) {
+  const env = { ...source }; delete env.TYPESAFE_API_KEY; return env;
+}
+export function doctor(binary = 'codex') {
+  const check = spawnSync(binary, ['--version'], { encoding: 'utf8', timeout: 5000, windowsHide: true, env: nativeEnvironment() });
+  return { node: process.version, platform: process.platform, architecture: process.arch,
+    codexFound: !check.error && check.status === 0,
+    codexVersion: /codex[^\r\n]{0,50}\d[^\r\n]{0,50}/i.exec(check.stdout ?? '')?.[0] ?? null,
+    credentialsReadByCAE: false, paidCallsMade: false,
+    desktopCompatibility: 'pending local acceptance', websocketAdapter: 'not implemented' };
+}
+export function normalizeModel(m) {
+  if (typeof m?.model !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,159}$/.test(m.model)) return null;
+  if (!Array.isArray(m.supportedReasoningEfforts)) return null;
+  const efforts = m.supportedReasoningEfforts.map(e => e?.reasoningEffort);
+  if (!Array.isArray(efforts) || !efforts.length || efforts.some(e => !EFFORT_NAMES.includes(e)) ||
+      !efforts.includes(m.defaultReasoningEffort)) return null;
+  return { model: m.model, supportedEfforts: [...new Set(efforts)], baseline: m.defaultReasoningEffort };
+}
+/** Only initialize + model/list. No turns, tool calls, credentials API or file API. */
+export async function probeModels(binary = 'codex', { args = ['app-server'], timeoutMs = 15000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true, env: nativeEnvironment() });
+    const rl = createInterface({ input: child.stdout });
+    let settled = false, nextId = 2, expected = 1, pages = 0, outputBytes = 0;
+    const models = []; const cursors = new Set();
+    const timer = setTimeout(() => finish(new CaeError('codex_probe_timeout')), timeoutMs);
+    function finish(error) {
+      if (settled) return; settled = true; clearTimeout(timer); rl.close(); child.stdin.end(); child.kill();
+      const killTimer = setTimeout(() => { if (child.exitCode === null) child.kill('SIGKILL'); }, 1000);
+      killTimer.unref(); child.once('exit', () => clearTimeout(killTimer));
+      if (error) reject(error);
+      else resolve({ schema: 1, observedAt: new Date().toISOString(), source: 'codex app-server model/list', models,
+        skippedUnsupportedEntries: skipped, paidGenerations: 0 });
+    }
+    let skipped = 0;
+    function send(msg) { if (!settled) child.stdin.write(JSON.stringify(msg) + '\n'); }
+    function list(cursor) {
+      if (++pages > 20) { finish(new CaeError('codex_probe_page_limit')); return; }
+      expected = nextId++;
+      send({ id: expected, method: 'model/list', params: { limit: 100, includeHidden: false, ...(cursor ? { cursor } : {}) } });
+    }
+    child.stdout.on('data', b => { outputBytes += b.length; if (outputBytes > 4 * 1024 * 1024) finish(new CaeError('codex_probe_output_limit')); });
+    child.once('error', () => finish(new CaeError('codex_not_available')));
+    child.stdin.on('error', () => finish(new CaeError('codex_probe_pipe_error')));
+    child.once('exit', () => { if (!settled) finish(new CaeError('codex_probe_exited')); });
+    rl.on('line', line => {
+      if (settled) return;
+      let msg; try { msg = JSON.parse(line); } catch { finish(new CaeError('codex_probe_invalid_json')); return; }
+      if (!isObject(msg)) { finish(new CaeError('codex_probe_invalid_message')); return; }
+      if (msg.id !== expected) return;
+      if (msg.error) { finish(new CaeError('codex_probe_rpc_error')); return; }
+      if (expected === 1) { send({ method: 'initialized', params: {} }); list(); return; }
+      if (!Array.isArray(msg.result?.data)) { finish(new CaeError('codex_probe_invalid_models')); return; }
+      for (const entry of msg.result.data) { const m = normalizeModel(entry); if (m) models.push(m); else ++skipped; }
+      const cursor = msg.result.nextCursor;
+      if (cursor === null || cursor === undefined) { finish(); return; }
+      if (typeof cursor !== 'string' || cursors.has(cursor)) { finish(new CaeError('codex_probe_cursor_loop')); return; }
+      cursors.add(cursor); list(cursor);
+    });
+    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'codex_adaptive_effort', version: VERSION } } });
+  });
+}
+export function codexArgs(config, auth, passthrough = []) {
+  if (!['api', 'chatgpt'].includes(auth) || config.upstream.kind !== auth) throw new CaeError('auth_route_mismatch');
+  if (!config.port) throw new CaeError('fixed_port_required_for_codex');
+  const pairs = {
+    model: config.model,
+    model_reasoning_effort: config.baseline,
+    model_provider: 'cae',
+    'model_providers.cae.name': 'CAE experimental local effort controller',
+    'model_providers.cae.base_url': `http://127.0.0.1:${config.port}/v1`,
+    'model_providers.cae.wire_api': 'responses',
+    'model_providers.cae.supports_websockets': false,
+    'model_providers.cae.request_max_retries': 0,
+    'model_providers.cae.stream_max_retries': 0,
+    'model_providers.cae.env_http_headers': null,
+  };
+  if (auth === 'chatgpt') pairs['model_providers.cae.requires_openai_auth'] = true;
+  else { pairs['model_providers.cae.requires_openai_auth'] = false; pairs['model_providers.cae.env_key'] = 'OPENAI_API_KEY'; }
+  const overrides = Object.entries(pairs).flatMap(([key, value]) => ['-c', `${key}=${value === null ? '{"x-cae-token"="CAE_LOCAL_TOKEN"}' : JSON.stringify(value)}`]);
+  // Desktop supplies root -c flags and app-server-local -c flags. Native CLI
+  // discards the root config collection when the subcommand has its own.
+  // Recognize the desktop prefix without mistaking an exec prompt or a config
+  // value for a subcommand; other launch shapes keep their existing ordering.
+  let command = 0;
+  while (command < passthrough.length) {
+    if (['-c', '--config'].includes(passthrough[command]) && command + 1 < passthrough.length) command += 2;
+    else if (passthrough[command].startsWith('--config=')) ++command;
+    else break;
+  }
+  if (passthrough[command] === 'app-server')
+    return [...passthrough.slice(0, command + 1), ...overrides, ...passthrough.slice(command + 1)];
+  return [...overrides, ...passthrough];
+}

package/src/config.mjs

@@ -0,0 +1,74 @@
+import { readFileSync, lstatSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { CaeError, isObject } from './util.mjs';
+
+export const EFFORT_NAMES = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
+export const UPSTREAMS = Object.freeze({
+  api: 'https://api.openai.com/v1',
+  chatgpt: 'https://chatgpt.com/backend-api/codex',
+});
+export function validateConfig(c) {
+  if (!isObject(c) || c.version !== 1) throw new CaeError('config_version');
+  const allowed = ['version', 'model', 'supportedEfforts', 'baseline', 'mode', 'port', 'upstream',
+    'tokenFile', 'logFile', 'judge', 'lease', 'maxBodyBytes', 'upstreamTimeoutMs', 'capabilitySource'];
+  if (Object.keys(c).some(k => !allowed.includes(k))) throw new CaeError('unknown_config_field');
+  if (typeof c.model !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,159}$/.test(c.model)) throw new CaeError('config_model');
+  if (!Array.isArray(c.supportedEfforts) || c.supportedEfforts.length < 1 || c.supportedEfforts.length > EFFORT_NAMES.length ||
+      new Set(c.supportedEfforts).size !== c.supportedEfforts.length ||
+      c.supportedEfforts.some(v => !EFFORT_NAMES.includes(v))) throw new CaeError('config_efforts');
+  if (!c.supportedEfforts.includes(c.baseline)) throw new CaeError('config_baseline');
+  if (!['off', 'shadow', 'auto'].includes(c.mode)) throw new CaeError('config_mode');
+  if (!Number.isInteger(c.port) || c.port < 0 || c.port > 65535) throw new CaeError('config_port');
+  if (!isObject(c.upstream)) throw new CaeError('config_upstream');
+  if (c.upstream.kind === 'mock') {
+    let url;
+    try { url = new URL(c.upstream.baseUrl); } catch { throw new CaeError('config_mock_url'); }
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port || url.username || url.password || url.search || url.hash || !['', '/', '/v1'].includes(url.pathname))
+      throw new CaeError('config_mock_url');
+  } else if (typeof c.upstream.kind !== 'string' || !Object.hasOwn(UPSTREAMS, c.upstream.kind) || c.upstream.baseUrl !== undefined) throw new CaeError('config_upstream');
+  if (typeof c.tokenFile !== 'string' || !c.tokenFile || typeof c.logFile !== 'string' || !c.logFile) throw new CaeError('config_paths');
+  if (!isObject(c.judge) || !['baseline', 'typesafe'].includes(c.judge.kind)) throw new CaeError('config_judge');
+  if (typeof c.judge.model !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,159}$/.test(c.judge.model)) throw new CaeError('config_judge_model');
+  for (const [v, lo, hi, code] of [
+    [c.judge.timeoutMs, 50, 30000, 'config_judge_timeout'],
+    [c.judge.maxCalls, 0, 100000, 'config_judge_budget'],
+    [c.lease?.maxGenerations, 1, 4, 'config_lease'],
+    [c.lease?.ttlMs, 100, 300000, 'config_lease_ttl'],
+    [c.maxBodyBytes, 1024, 32 * 1024 * 1024, 'config_body_limit'],
+    [c.upstreamTimeoutMs, 100, 3600000, 'config_upstream_timeout'],
+  ]) if (!Number.isInteger(v) || v < lo || v > hi) throw new CaeError(code);
+  return structuredClone(c);
+}
+export function defaultConfig(model, supportedEfforts, baseline) {
+  return validateConfig({
+    version: 1, model, supportedEfforts, baseline, mode: 'shadow', port: 4318,
+    upstream: { kind: 'api' }, tokenFile: 'local.key', logFile: 'events.jsonl',
+    judge: { kind: 'baseline', model: 'jev-latest', timeoutMs: 1500, maxCalls: 100 },
+    lease: { maxGenerations: 4, ttlMs: 30000 }, maxBodyBytes: 8 * 1024 * 1024,
+    upstreamTimeoutMs: 300000, capabilitySource: 'operator-supplied; not live-verified',
+  });
+}
+export function loadConfig(path) {
+  const absolute = resolve(path);
+  let value;
+  try { value = JSON.parse(readFileSync(absolute, 'utf8')); }
+  catch { throw new CaeError('cannot_read_config'); }
+  const config = validateConfig(value);
+  config.tokenFile = resolve(dirname(absolute), config.tokenFile);
+  config.logFile = resolve(dirname(absolute), config.logFile);
+  if (config.tokenFile === config.logFile) throw new CaeError('config_path_collision');
+  return config;
+}
+export function readLocalToken(path) {
+  try {
+    const st = lstatSync(path);
+    if (!st.isFile() || st.isSymbolicLink()) throw new Error();
+    if (process.platform !== 'win32' && (st.mode & 0o077) !== 0) throw new Error();
+    const token = readFileSync(path, 'utf8').trim();
+    if (!/^[a-f0-9]{64}$/.test(token)) throw new Error();
+    return token;
+  } catch { throw new CaeError('invalid_or_insecure_local_token'); }
+}
+export function upstreamBase(c) {
+  return c.upstream.kind === 'mock' ? c.upstream.baseUrl.replace(/\/$/, '') : UPSTREAMS[c.upstream.kind];
+}

package/src/context.mjs

@@ -0,0 +1,87 @@
+import { digest, isObject, shortText, stable } from './util.mjs';
+
+/** Best-effort redaction; never a promise that an excerpt is safe to disclose. */
+export function redact(text) {
+  return String(text)
+    .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/g, '[REDACTED PRIVATE KEY]')
+    .replace(/\b(?:sk-|ghp_|github_pat_)[A-Za-z0-9_-]{12,}\b/g, '[REDACTED TOKEN]')
+    .replace(/\bBearer\s+[A-Za-z0-9._~+\/-]+=*/gi, 'Bearer [REDACTED]')
+    .replace(/((?:api[_-]?key|access[_-]?token|password|secret)\s*["']?\s*[:=]\s*["']?)[^\s,"'}]+/gi, '$1[REDACTED]')
+    .replace(/\/(?:Users|home)\/[^/\s]+/g, '/[HOME]');
+}
+function textOf(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.filter(p => isObject(p) && ['input_text', 'output_text', 'text'].includes(p.type))
+    .map(p => typeof p.text === 'string' ? p.text : '').join('\n');
+}
+function hasMedia(content) {
+  return Array.isArray(content) && content.some(p => isObject(p) && /image|audio|video|file/.test(p.type ?? ''));
+}
+function supportedItem(item) {
+  if (!isObject(item)) return false;
+  if (item.type === undefined || item.type === 'message') {
+    return ['user', 'assistant', 'system', 'developer'].includes(item.role) &&
+      (typeof item.content === 'string' || (Array.isArray(item.content) && item.content.every(p =>
+        isObject(p) && ['input_text', 'output_text', 'text'].includes(p.type) && typeof p.text === 'string')));
+  }
+  if (['function_call_output', 'custom_tool_call_output'].includes(item.type)) return typeof item.output === 'string';
+  // Retain opaque reasoning and call records for history integrity, never evaluator text.
+  return ['reasoning', 'function_call', 'custom_tool_call'].includes(item.type);
+}
+function failed(item) {
+  if (item.is_error === true || item.success === false) return true;
+  let out = item.output;
+  if (typeof out === 'string') { try { out = JSON.parse(out); } catch { return false; } }
+  return isObject(out) && (out.is_error === true || out.success === false ||
+    (typeof out.exit_code === 'number' && out.exit_code !== 0) ||
+    (typeof out.exitCode === 'number' && out.exitCode !== 0));
+}
+export function inspectRequest(body) {
+  const items = typeof body.input === 'string' ? [{ role: 'user', content: body.input }] : body.input;
+  if (!Array.isArray(items)) return { eligible: false, reason: 'unsupported_input' };
+  if (items.length > 4096) return { eligible: false, reason: 'history_item_limit' };
+  if (body.previous_response_id || body.conversation) return { eligible: false, reason: 'delta_history' };
+  if (body.background === true) return { eligible: false, reason: 'background_response' };
+  if (items.some(i => isObject(i) && i.type === 'configuration_update')) return { eligible: false, reason: 'existing_configuration_update' };
+  if (items.some(i => isObject(i) && /compaction/.test(i.type ?? '')) || body.context_management)
+    return { eligible: false, reason: 'compaction_boundary' };
+  if (body.truncation && body.truncation !== 'disabled') return { eligible: false, reason: 'automatic_truncation' };
+  if (items.some(i => isObject(i) && (hasMedia(i.content) || (typeof i.output === 'object' && i.output !== null))))
+    return { eligible: false, reason: 'media_or_structured_tool_evidence' };
+  if (!items.every(supportedItem)) return { eligible: false, reason: 'unsupported_history_item' };
+  const users = items.filter(i => isObject(i) && i.role === 'user');
+  const latest = users.at(-1);
+  if (!latest || !textOf(latest.content).trim()) return { eligible: false, reason: 'missing_user_goal' };
+  const publicNotes = items.filter(i => isObject(i) && i.role === 'assistant').slice(-2);
+  const tools = items.filter(i => isObject(i) && ['function_call_output', 'custom_tool_call_output'].includes(i.type));
+  const errors = tools.filter(failed).map(i => digest(i));
+  const clean = (text, max) => shortText(redact(text), max);
+  const state = {
+    task: clean(textOf(users.length > 1 ? users.at(-2).content : latest.content), 1800),
+    latestUser: clean(textOf(latest.content), 2200),
+    publicNotes: publicNotes.map(i => clean(textOf(i.content), 600)),
+    recentTools: tools.slice(-3).map(i => ({
+      result: clean(typeof i.output === 'string' ? i.output : '', 600), failed: failed(i),
+    })),
+    omittedToolCalls: Math.max(0, tools.length - 3),
+    evidenceLimits: 'Bounded character excerpts; missing text remains unknown. No image understanding.',
+  };
+  // All integrity fingerprints are local only. No auth, session ids, encrypted reasoning,
+  // tool definitions or system/developer instructions enter evaluator state.
+  return {
+    eligible: true, state, itemCount: items.length,
+    itemHashes: items.map(digest),
+    taskKey: digest(users.map(i => textOf(i.content))),
+    constraintsKey: digest({ model: body.model, instructions: body.instructions ?? null, tools: body.tools ?? null }),
+    errorsKey: digest(errors),
+    reasoningKey: digest(body.reasoning ?? null),
+    stateChars: Array.from(stable(state)).length,
+  };
+}
+export function canContinue(previous, next) {
+  return previous && next.eligible && previous.taskKey === next.taskKey &&
+    previous.constraintsKey === next.constraintsKey && previous.errorsKey === next.errorsKey &&
+    previous.reasoningKey === next.reasoningKey && next.itemCount > previous.itemCount &&
+    previous.itemHashes.every((h, i) => next.itemHashes[i] === h);
+}