Add files using upload-large-folder tool

.gitattributes

@@ -1,3 +1,6 @@
 codex-rs/app-server-protocol/schema/** linguist-generated
 codex-rs/hooks/schema/generated/** linguist-generated
 third_party/voice/sources.json text eol=lf
+.github/codex-cli-splash.png filter=lfs diff=lfs merge=lfs -text
+codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst filter=lfs diff=lfs merge=lfs -text
+codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst filter=lfs diff=lfs merge=lfs -text

codex-cli/bin/codex.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+// Unified entry point for the Codex CLI.
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "fs";
+import { createRequire } from "node:module";
+import path from "path";
+import { fileURLToPath } from "url";
+
+// __dirname equivalent in ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+const codexPackageRoot = realpathSync(path.join(__dirname, ".."));
+
+const PLATFORM_PACKAGE_BY_TARGET = {
+  "x86_64-unknown-linux-musl": "@openai/codex-linux-x64",
+  "aarch64-unknown-linux-musl": "@openai/codex-linux-arm64",
+  "x86_64-apple-darwin": "@openai/codex-darwin-x64",
+  "aarch64-apple-darwin": "@openai/codex-darwin-arm64",
+  "x86_64-pc-windows-msvc": "@openai/codex-win32-x64",
+  "aarch64-pc-windows-msvc": "@openai/codex-win32-arm64",
+};
+
+const { platform, arch } = process;
+
+let targetTriple = null;
+switch (platform) {
+  case "linux":
+  case "android":
+    switch (arch) {
+      case "x64":
+        targetTriple = "x86_64-unknown-linux-musl";
+        break;
+      case "arm64":
+        targetTriple = "aarch64-unknown-linux-musl";
+        break;
+      default:
+        break;
+    }
+    break;
+  case "darwin":
+    switch (arch) {
+      case "x64":
+        targetTriple = "x86_64-apple-darwin";
+        break;
+      case "arm64":
+        targetTriple = "aarch64-apple-darwin";
+        break;
+      default:
+        break;
+    }
+    break;
+  case "win32":
+    switch (arch) {
+      case "x64":
+        targetTriple = "x86_64-pc-windows-msvc";
+        break;
+      case "arm64":
+        targetTriple = "aarch64-pc-windows-msvc";
+        break;
+      default:
+        break;
+    }
+    break;
+  default:
+    break;
+}
+
+if (!targetTriple) {
+  throw new Error(`Unsupported platform: ${platform} (${arch})`);
+}
+
+const platformPackage = PLATFORM_PACKAGE_BY_TARGET[targetTriple];
+if (!platformPackage) {
+  throw new Error(`Unsupported target triple: ${targetTriple}`);
+}
+
+function findCodexExecutable() {
+  let vendorRoot;
+  try {
+    const packageJsonPath = require.resolve(`${platformPackage}/package.json`);
+    vendorRoot = path.join(path.dirname(packageJsonPath), "vendor");
+  } catch {
+    vendorRoot = path.join(__dirname, "..", "vendor");
+  }
+
+  const codexExecutable = path.join(
+    vendorRoot,
+    targetTriple,
+    "bin",
+    process.platform === "win32" ? "codex.exe" : "codex",
+  );
+  if (existsSync(codexExecutable)) {
+    return codexExecutable;
+  }
+
+  const packageManager = detectPackageManager();
+  const updateCommand =
+    packageManager === "bun"
+      ? "bun install -g @openai/codex@latest"
+      : packageManager === "pnpm"
+        ? "pnpm add -g @openai/codex@latest"
+        : packageManager === "vite-plus"
+          ? "vp install -g @openai/codex@latest"
+          : "npm install -g @openai/codex@latest";
+  throw new Error(
+    `Missing optional dependency ${platformPackage}. Reinstall Codex: ${updateCommand}`,
+  );
+}
+
+const binaryPath = findCodexExecutable();
+
+// Use an asynchronous spawn instead of spawnSync so that Node is able to
+// respond to signals (e.g. Ctrl-C / SIGINT) while the native binary is
+// executing. This allows us to forward those signals to the child process
+// and guarantees that when either the child terminates or the parent
+// receives a fatal signal, both processes exit in a predictable manner.
+
+function isPnpmOwnedCodexInstall(nodeModulesDir) {
+  if (!existsSync(path.join(nodeModulesDir, ".modules.yaml"))) {
+    return false;
+  }
+
+  try {
+    return (
+      realpathSync(path.join(nodeModulesDir, "@openai", "codex")) ===
+      codexPackageRoot
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isVitePlusOwnedCodexInstall(packagesDir) {
+  if (path.basename(packagesDir) !== "packages") {
+    return false;
+  }
+
+  try {
+    const metadata = JSON.parse(
+      readFileSync(path.join(packagesDir, "@openai", "codex.json"), "utf8"),
+    );
+    if (metadata.name !== "@openai/codex") {
+      return false;
+    }
+
+    // Vite+ records the active global installation in packages/@openai/codex.json.
+    // Older installs have no ID or append a #-prefixed ID to the package name;
+    // newer installs put the ID in a subdirectory of the package prefix.
+    const installId = metadata.installId || "";
+    const installDir = installId.startsWith("#")
+      ? path.join(packagesDir, `@openai/codex${installId}`)
+      : path.join(packagesDir, "@openai/codex", installId);
+    for (const nodeModulesDir of [
+      path.join(installDir, "lib", "node_modules"),
+      path.join(installDir, "node_modules"),
+    ]) {
+      const packageRoot = path.join(nodeModulesDir, "@openai", "codex");
+      if (
+        existsSync(packageRoot) &&
+        realpathSync(packageRoot) === codexPackageRoot
+      ) {
+        return true;
+      }
+    }
+  } catch {
+    // Missing or unreadable ownership metadata must not prevent Codex starting.
+  }
+  return false;
+}
+
+/**
+ * Use heuristics to detect the package manager that was used to install Codex
+ * in order to give the user a hint about how to update it.
+ */
+function detectPackageManager() {
+  // Package-manager ownership metadata can be several parents above the package.
+  // Search ancestors of both the canonical package root and lexical entrypoint
+  // because the package manager may link either path.
+  const entrypointDir = path.dirname(path.resolve(process.argv[1]));
+  for (const startDir of new Set([codexPackageRoot, entrypointDir])) {
+    const filesystemRoot = path.parse(startDir).root;
+    for (
+      let currentDir = startDir;
+      currentDir !== filesystemRoot;
+      currentDir = path.dirname(currentDir)
+    ) {
+      if (isVitePlusOwnedCodexInstall(currentDir)) {
+        return "vite-plus";
+      }
+      if (isPnpmOwnedCodexInstall(path.join(currentDir, "node_modules"))) {
+        return "pnpm";
+      }
+    }
+
+    if (isPnpmOwnedCodexInstall(path.join(filesystemRoot, "node_modules"))) {
+      return "pnpm";
+    }
+  }
+
+  const userAgent = process.env.npm_config_user_agent || "";
+  if (/\bbun\//.test(userAgent)) {
+    return "bun";
+  }
+
+  const execPath = process.env.npm_execpath || "";
+  if (execPath.includes("bun")) {
+    return "bun";
+  }
+
+  if (
+    __dirname.includes(".bun/install/global") ||
+    __dirname.includes(".bun\\install\\global")
+  ) {
+    return "bun";
+  }
+
+  return userAgent ? "npm" : null;
+}
+
+const packageManager = detectPackageManager();
+const packageManagerEnvVar =
+  packageManager === "bun"
+    ? "CODEX_MANAGED_BY_BUN"
+    : packageManager === "pnpm"
+      ? "CODEX_MANAGED_BY_PNPM"
+      : packageManager === "vite-plus"
+        ? "CODEX_MANAGED_BY_VITE_PLUS"
+        : "CODEX_MANAGED_BY_NPM";
+const env = {
+  ...process.env,
+  CODEX_MANAGED_PACKAGE_ROOT: codexPackageRoot,
+};
+delete env.CODEX_MANAGED_BY_NPM;
+delete env.CODEX_MANAGED_BY_BUN;
+delete env.CODEX_MANAGED_BY_PNPM;
+delete env.CODEX_MANAGED_BY_VITE_PLUS;
+env[packageManagerEnvVar] = "1";
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  env,
+});
+
+child.on("error", (err) => {
+  // Typically triggered when the binary is missing or not executable.
+  // Re-throwing here will terminate the parent with a non-zero exit code
+  // while still printing a helpful stack trace.
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});
+
+// Forward common termination signals to the child so that it shuts down
+// gracefully. In the handler we temporarily disable the default behavior of
+// exiting immediately; once the child has been signaled we simply wait for
+// its exit event which will in turn terminate the parent (see below).
+const forwardSignal = (signal) => {
+  if (child.killed) {
+    return;
+  }
+  try {
+    child.kill(signal);
+  } catch {
+    /* ignore */
+  }
+};
+
+["SIGINT", "SIGTERM", "SIGHUP"].forEach((sig) => {
+  process.on(sig, () => forwardSignal(sig));
+});
+
+// When the child exits, mirror its termination reason in the parent so that
+// shell scripts and other tooling observe the correct exit status.
+// Wrap the lifetime of the child process in a Promise so that we can await
+// its termination in a structured way. The Promise resolves with an object
+// describing how the child exited: either via exit code or due to a signal.
+const childResult = await new Promise((resolve) => {
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      resolve({ type: "signal", signal });
+    } else {
+      resolve({ type: "code", exitCode: code ?? 1 });
+    }
+  });
+});
+
+if (childResult.type === "signal") {
+  // Re-emit the same signal so that the parent terminates with the expected
+  // semantics (this also sets the correct exit code of 128 + n).
+  process.kill(process.pid, childResult.signal);
+} else {
+  process.exit(childResult.exitCode);
+}

codex-cli/scripts/README.md

@@ -0,0 +1,23 @@
+# npm releases
+
+Use the staging helper in the repo root to generate npm tarballs for a release. For
+example, to stage the CLI, responses proxy, and SDK packages for version `0.6.0`:
+
+```bash
+./scripts/stage_npm_packages.py \
+  --release-version 0.6.0 \
+  --package codex \
+  --package codex-responses-api-proxy \
+  --package codex-sdk
+```
+
+This downloads the required native package archive artifacts, hydrates `vendor/` for
+each package, and writes tarballs to `dist/npm/`.
+
+When `--package codex` is provided, the staging helper builds the lightweight
+`@openai/codex` meta package plus all platform-native `@openai/codex` variants
+that are later published under platform-specific dist-tags.
+
+Direct `build_npm_package.py` invocations are still useful for package-specific
+debugging, but native packages expect `--vendor-src` to point at a prehydrated
+`vendor/` tree. Release packaging should use `scripts/stage_npm_packages.py`

codex-cli/scripts/build_npm_package.py

@@ -0,0 +1,461 @@
+#!/usr/bin/env python3
+"""Stage and optionally package the @openai/codex npm module."""
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+CODEX_CLI_ROOT = SCRIPT_DIR.parent
+REPO_ROOT = CODEX_CLI_ROOT.parent
+RESPONSES_API_PROXY_NPM_ROOT = REPO_ROOT / "codex-rs" / "responses-api-proxy" / "npm"
+CODEX_SDK_ROOT = REPO_ROOT / "sdk" / "typescript"
+CODEX_NPM_NAME = "@openai/codex"
+CODEX_PACKAGE_COMPONENT = "codex-package"
+
+# `npm_name` is the local optional-dependency alias consumed by `bin/codex.js`.
+# The underlying package published to npm is always `@openai/codex`.
+CODEX_PLATFORM_PACKAGES: dict[str, dict[str, str]] = {
+    "codex-linux-x64": {
+        "npm_name": "@openai/codex-linux-x64",
+        "npm_tag": "linux-x64",
+        "target_triple": "x86_64-unknown-linux-musl",
+        "os": "linux",
+        "cpu": "x64",
+    },
+    "codex-linux-arm64": {
+        "npm_name": "@openai/codex-linux-arm64",
+        "npm_tag": "linux-arm64",
+        "target_triple": "aarch64-unknown-linux-musl",
+        "os": "linux",
+        "cpu": "arm64",
+    },
+    "codex-darwin-x64": {
+        "npm_name": "@openai/codex-darwin-x64",
+        "npm_tag": "darwin-x64",
+        "target_triple": "x86_64-apple-darwin",
+        "os": "darwin",
+        "cpu": "x64",
+    },
+    "codex-darwin-arm64": {
+        "npm_name": "@openai/codex-darwin-arm64",
+        "npm_tag": "darwin-arm64",
+        "target_triple": "aarch64-apple-darwin",
+        "os": "darwin",
+        "cpu": "arm64",
+    },
+    "codex-win32-x64": {
+        "npm_name": "@openai/codex-win32-x64",
+        "npm_tag": "win32-x64",
+        "target_triple": "x86_64-pc-windows-msvc",
+        "os": "win32",
+        "cpu": "x64",
+    },
+    "codex-win32-arm64": {
+        "npm_name": "@openai/codex-win32-arm64",
+        "npm_tag": "win32-arm64",
+        "target_triple": "aarch64-pc-windows-msvc",
+        "os": "win32",
+        "cpu": "arm64",
+    },
+}
+
+PACKAGE_EXPANSIONS: dict[str, list[str]] = {
+    "codex": ["codex", *CODEX_PLATFORM_PACKAGES],
+}
+
+PACKAGE_NATIVE_COMPONENTS: dict[str, list[str]] = {
+    "codex": [],
+    "codex-linux-x64": [CODEX_PACKAGE_COMPONENT],
+    "codex-linux-arm64": [CODEX_PACKAGE_COMPONENT],
+    "codex-darwin-x64": [CODEX_PACKAGE_COMPONENT],
+    "codex-darwin-arm64": [CODEX_PACKAGE_COMPONENT],
+    "codex-win32-x64": [CODEX_PACKAGE_COMPONENT],
+    "codex-win32-arm64": [CODEX_PACKAGE_COMPONENT],
+    "codex-responses-api-proxy": ["codex-responses-api-proxy"],
+    "codex-sdk": [],
+}
+
+PACKAGE_TARGET_FILTERS: dict[str, str] = {
+    package_name: package_config["target_triple"]
+    for package_name, package_config in CODEX_PLATFORM_PACKAGES.items()
+}
+
+PACKAGE_CHOICES = tuple(PACKAGE_NATIVE_COMPONENTS)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build or stage the Codex CLI npm package."
+    )
+    parser.add_argument(
+        "--package",
+        choices=PACKAGE_CHOICES,
+        default="codex",
+        help="Which npm package to stage (default: codex).",
+    )
+    parser.add_argument(
+        "--version",
+        help="Version number to write to package.json inside the staged package.",
+    )
+    parser.add_argument(
+        "--release-version",
+        help=("Version to stage for npm release."),
+    )
+    parser.add_argument(
+        "--staging-dir",
+        type=Path,
+        help=(
+            "Directory to stage the package contents. Defaults to a new temporary directory "
+            "if omitted. The directory must be empty when provided."
+        ),
+    )
+    parser.add_argument(
+        "--tmp",
+        dest="staging_dir",
+        type=Path,
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--pack-output",
+        type=Path,
+        help="Path where the generated npm tarball should be written.",
+    )
+    parser.add_argument(
+        "--vendor-src",
+        type=Path,
+        help="Directory containing pre-installed native binaries to bundle (vendor root).",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    package = args.package
+    version = args.version
+    release_version = args.release_version
+    if release_version:
+        if version and version != release_version:
+            raise RuntimeError(
+                "--version and --release-version must match when both are provided."
+            )
+        version = release_version
+
+    if not version:
+        raise RuntimeError("Must specify --version or --release-version.")
+
+    staging_dir, created_temp = prepare_staging_dir(args.staging_dir)
+
+    try:
+        stage_sources(staging_dir, version, package)
+
+        vendor_src = args.vendor_src.resolve() if args.vendor_src else None
+        native_components = PACKAGE_NATIVE_COMPONENTS.get(package, [])
+        target_filter = PACKAGE_TARGET_FILTERS.get(package)
+
+        if native_components:
+            if vendor_src is None:
+                components_str = ", ".join(native_components)
+                raise RuntimeError(
+                    "Native components "
+                    f"({components_str}) required for package '{package}'. Provide --vendor-src "
+                    "pointing to a directory containing pre-installed binaries."
+                )
+
+            copy_native_binaries(
+                vendor_src,
+                staging_dir,
+                native_components,
+                target_filter={target_filter} if target_filter else None,
+            )
+
+        if release_version:
+            staging_dir_str = str(staging_dir)
+            if package == "codex":
+                print(
+                    f"Staged version {version} for release in {staging_dir_str}\n\n"
+                    "Verify the CLI:\n"
+                    f"    node {staging_dir_str}/bin/codex.js --version\n"
+                    f"    node {staging_dir_str}/bin/codex.js --help\n\n"
+                )
+            elif package == "codex-responses-api-proxy":
+                print(
+                    f"Staged version {version} for release in {staging_dir_str}\n\n"
+                    "Verify the responses API proxy:\n"
+                    f"    node {staging_dir_str}/bin/codex-responses-api-proxy.js --help\n\n"
+                )
+            elif package in CODEX_PLATFORM_PACKAGES:
+                print(
+                    f"Staged version {version} for release in {staging_dir_str}\n\n"
+                    "Verify native payload contents:\n"
+                    f"    ls {staging_dir_str}/vendor\n\n"
+                )
+            else:
+                print(
+                    f"Staged version {version} for release in {staging_dir_str}\n\n"
+                    "Verify the SDK contents:\n"
+                    f"    ls {staging_dir_str}/dist\n"
+                    "    node -e \"import('./dist/index.js').then(() => console.log('ok'))\"\n\n"
+                )
+        else:
+            print(f"Staged package in {staging_dir}")
+
+        if args.pack_output is not None:
+            output_path = run_npm_pack(staging_dir, args.pack_output)
+            print(f"npm pack output written to {output_path}")
+    finally:
+        if created_temp:
+            # Preserve the staging directory for further inspection.
+            pass
+
+    return 0
+
+
+def prepare_staging_dir(staging_dir: Path | None) -> tuple[Path, bool]:
+    if staging_dir is not None:
+        staging_dir = staging_dir.resolve()
+        staging_dir.mkdir(parents=True, exist_ok=True)
+        if any(staging_dir.iterdir()):
+            raise RuntimeError(f"Staging directory {staging_dir} is not empty.")
+        return staging_dir, False
+
+    temp_dir = Path(tempfile.mkdtemp(prefix="codex-npm-stage-"))
+    return temp_dir, True
+
+
+def stage_sources(staging_dir: Path, version: str, package: str) -> None:
+    package_json: dict
+    package_json_path: Path | None = None
+
+    if package == "codex":
+        bin_dir = staging_dir / "bin"
+        bin_dir.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(CODEX_CLI_ROOT / "bin" / "codex.js", bin_dir / "codex.js")
+
+        readme_src = REPO_ROOT / "README.md"
+        if readme_src.exists():
+            shutil.copy2(readme_src, staging_dir / "README.md")
+
+        package_json_path = CODEX_CLI_ROOT / "package.json"
+    elif package in CODEX_PLATFORM_PACKAGES:
+        platform_package = CODEX_PLATFORM_PACKAGES[package]
+        platform_npm_tag = platform_package["npm_tag"]
+        platform_version = compute_platform_package_version(version, platform_npm_tag)
+
+        readme_src = REPO_ROOT / "README.md"
+        if readme_src.exists():
+            shutil.copy2(readme_src, staging_dir / "README.md")
+
+        with open(CODEX_CLI_ROOT / "package.json", "r", encoding="utf-8") as fh:
+            codex_package_json = json.load(fh)
+
+        package_json = {
+            "name": CODEX_NPM_NAME,
+            "version": platform_version,
+            "license": codex_package_json.get("license", "Apache-2.0"),
+            "os": [platform_package["os"]],
+            "cpu": [platform_package["cpu"]],
+            "files": ["vendor"],
+            "repository": codex_package_json.get("repository"),
+        }
+
+        engines = codex_package_json.get("engines")
+        if isinstance(engines, dict):
+            package_json["engines"] = engines
+
+        package_manager = codex_package_json.get("packageManager")
+        if isinstance(package_manager, str):
+            package_json["packageManager"] = package_manager
+    elif package == "codex-responses-api-proxy":
+        bin_dir = staging_dir / "bin"
+        bin_dir.mkdir(parents=True, exist_ok=True)
+        launcher_src = (
+            RESPONSES_API_PROXY_NPM_ROOT / "bin" / "codex-responses-api-proxy.js"
+        )
+        shutil.copy2(launcher_src, bin_dir / "codex-responses-api-proxy.js")
+
+        readme_src = RESPONSES_API_PROXY_NPM_ROOT / "README.md"
+        if readme_src.exists():
+            shutil.copy2(readme_src, staging_dir / "README.md")
+
+        package_json_path = RESPONSES_API_PROXY_NPM_ROOT / "package.json"
+    elif package == "codex-sdk":
+        package_json_path = CODEX_SDK_ROOT / "package.json"
+        stage_codex_sdk_sources(staging_dir)
+    else:
+        raise RuntimeError(f"Unknown package '{package}'.")
+
+    if package_json_path is not None:
+        with open(package_json_path, "r", encoding="utf-8") as fh:
+            package_json = json.load(fh)
+        package_json["version"] = version
+
+    if package == "codex":
+        package_json["files"] = ["bin/codex.js"]
+        package_json["optionalDependencies"] = {
+            CODEX_PLATFORM_PACKAGES[platform_package]["npm_name"]: (
+                f"npm:{CODEX_NPM_NAME}@"
+                f"{compute_platform_package_version(version, CODEX_PLATFORM_PACKAGES[platform_package]['npm_tag'])}"
+            )
+            for platform_package in PACKAGE_EXPANSIONS["codex"]
+            if platform_package != "codex"
+        }
+
+    elif package == "codex-sdk":
+        scripts = package_json.get("scripts")
+        if isinstance(scripts, dict):
+            scripts.pop("prepare", None)
+
+        dependencies = package_json.get("dependencies")
+        if not isinstance(dependencies, dict):
+            dependencies = {}
+        dependencies[CODEX_NPM_NAME] = version
+        package_json["dependencies"] = dependencies
+
+    with open(staging_dir / "package.json", "w", encoding="utf-8") as out:
+        json.dump(package_json, out, indent=2)
+        out.write("\n")
+
+
+def compute_platform_package_version(version: str, platform_tag: str) -> str:
+    # npm forbids republishing the same package name/version, so each
+    # platform-specific tarball needs a unique version string.
+    return f"{version}-{platform_tag}"
+
+
+def run_command(cmd: list[str], cwd: Path | None = None) -> None:
+    print("+", " ".join(cmd), flush=True)
+    subprocess.run(cmd, cwd=cwd, check=True)
+
+
+def stage_codex_sdk_sources(staging_dir: Path) -> None:
+    package_root = CODEX_SDK_ROOT
+
+    run_command(["pnpm", "install", "--frozen-lockfile"], cwd=package_root)
+    run_command(["pnpm", "run", "build"], cwd=package_root)
+
+    dist_src = package_root / "dist"
+    if not dist_src.exists():
+        raise RuntimeError("codex-sdk build did not produce a dist directory.")
+
+    shutil.copytree(dist_src, staging_dir / "dist")
+
+    readme_src = package_root / "README.md"
+    if readme_src.exists():
+        shutil.copy2(readme_src, staging_dir / "README.md")
+
+    license_src = REPO_ROOT / "LICENSE"
+    if license_src.exists():
+        shutil.copy2(license_src, staging_dir / "LICENSE")
+
+
+def copy_native_binaries(
+    vendor_src: Path,
+    staging_dir: Path,
+    components: list[str],
+    target_filter: set[str] | None = None,
+) -> None:
+    vendor_src = vendor_src.resolve()
+    if not vendor_src.exists():
+        raise RuntimeError(f"Vendor source directory not found: {vendor_src}")
+
+    components_set = set(components)
+    if not components_set:
+        return
+
+    vendor_dest = staging_dir / "vendor"
+    if vendor_dest.exists():
+        shutil.rmtree(vendor_dest)
+    vendor_dest.mkdir(parents=True, exist_ok=True)
+
+    copied_targets: set[str] = set()
+
+    for target_dir in vendor_src.iterdir():
+        if not target_dir.is_dir():
+            continue
+
+        if target_filter is not None and target_dir.name not in target_filter:
+            continue
+
+        copied_targets.add(target_dir.name)
+
+        dest_target_dir = vendor_dest / target_dir.name
+
+        if CODEX_PACKAGE_COMPONENT in components_set:
+            if dest_target_dir.exists():
+                shutil.rmtree(dest_target_dir)
+            shutil.copytree(target_dir, dest_target_dir)
+        else:
+            dest_target_dir.mkdir(parents=True, exist_ok=True)
+
+        for component in sorted(components_set - {CODEX_PACKAGE_COMPONENT}):
+            src_component_dir = target_dir / component
+            if not src_component_dir.exists():
+                raise RuntimeError(
+                    f"Missing native component '{component}' in vendor source: {src_component_dir}"
+                )
+
+            dest_component_dir = dest_target_dir / component
+            if dest_component_dir.exists():
+                shutil.rmtree(dest_component_dir)
+            shutil.copytree(src_component_dir, dest_component_dir)
+
+    if target_filter is not None:
+        missing_targets = sorted(target_filter - copied_targets)
+        if missing_targets:
+            missing_list = ", ".join(missing_targets)
+            raise RuntimeError(
+                f"Missing target directories in vendor source: {missing_list}"
+            )
+
+
+def run_npm_pack(staging_dir: Path, output_path: Path) -> Path:
+    output_path = output_path.resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.TemporaryDirectory(prefix="codex-npm-pack-") as pack_dir_str:
+        pack_dir = Path(pack_dir_str)
+        npm_cache_dir = pack_dir / "npm-cache"
+        npm_logs_dir = pack_dir / "npm-logs"
+        npm_cache_dir.mkdir()
+        npm_logs_dir.mkdir()
+        env = os.environ.copy()
+        env["NPM_CONFIG_CACHE"] = str(npm_cache_dir)
+        env["NPM_CONFIG_LOGS_DIR"] = str(npm_logs_dir)
+        stdout = subprocess.check_output(
+            ["npm", "pack", "--json", "--pack-destination", str(pack_dir)],
+            cwd=staging_dir,
+            env=env,
+            text=True,
+        )
+        try:
+            pack_output = json.loads(stdout)
+        except json.JSONDecodeError as exc:
+            raise RuntimeError("Failed to parse npm pack output.") from exc
+
+        if not pack_output:
+            raise RuntimeError("npm pack did not produce an output tarball.")
+
+        tarball_name = pack_output[0].get("filename") or pack_output[0].get("name")
+        if not tarball_name:
+            raise RuntimeError("Unable to determine npm pack output filename.")
+
+        tarball_path = pack_dir / tarball_name
+        if not tarball_path.exists():
+            raise RuntimeError(f"Expected npm pack output not found: {tarball_path}")
+
+        shutil.move(str(tarball_path), output_path)
+
+    return output_path
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())

codex-cli/scripts/init_firewall.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+set -euo pipefail  # Exit on error, undefined vars, and pipeline failures
+IFS=$'\n\t'       # Stricter word splitting
+
+# Read allowed domains from file
+ALLOWED_DOMAINS_FILE="/etc/codex/allowed_domains.txt"
+if [ -f "$ALLOWED_DOMAINS_FILE" ]; then
+    ALLOWED_DOMAINS=()
+    while IFS= read -r domain; do
+        ALLOWED_DOMAINS+=("$domain")
+    done < "$ALLOWED_DOMAINS_FILE"
+    echo "Using domains from file: ${ALLOWED_DOMAINS[*]}"
+else
+    # Fallback to default domains
+    ALLOWED_DOMAINS=("api.openai.com")
+    echo "Domains file not found, using default: ${ALLOWED_DOMAINS[*]}"
+fi
+
+# Ensure we have at least one domain
+if [ ${#ALLOWED_DOMAINS[@]} -eq 0 ]; then
+    echo "ERROR: No allowed domains specified"
+    exit 1
+fi
+
+# Flush existing rules and delete existing ipsets
+iptables -F
+iptables -X
+iptables -t nat -F
+iptables -t nat -X
+iptables -t mangle -F
+iptables -t mangle -X
+ipset destroy allowed-domains 2>/dev/null || true
+
+# First allow DNS and localhost before any restrictions
+# Allow outbound DNS
+iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+# Allow inbound DNS responses
+iptables -A INPUT -p udp --sport 53 -j ACCEPT
+# Allow localhost
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# Create ipset with CIDR support
+ipset create allowed-domains hash:net
+
+# Resolve and add other allowed domains
+for domain in "${ALLOWED_DOMAINS[@]}"; do
+    echo "Resolving $domain..."
+    ips=$(dig +short A "$domain")
+    if [ -z "$ips" ]; then
+        echo "ERROR: Failed to resolve $domain"
+        exit 1
+    fi
+
+    while read -r ip; do
+        if [[ ! "$ip" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
+            echo "ERROR: Invalid IP from DNS for $domain: $ip"
+            exit 1
+        fi
+        echo "Adding $ip for $domain"
+        ipset add allowed-domains "$ip"
+    done < <(echo "$ips")
+done
+
+# Get host IP from default route
+HOST_IP=$(ip route | grep default | cut -d" " -f3)
+if [ -z "$HOST_IP" ]; then
+    echo "ERROR: Failed to detect host IP"
+    exit 1
+fi
+
+HOST_NETWORK=$(echo "$HOST_IP" | sed "s/\.[0-9]*$/.0\/24/")
+echo "Host network detected as: $HOST_NETWORK"
+
+# Set up remaining iptables rules
+iptables -A INPUT -s "$HOST_NETWORK" -j ACCEPT
+iptables -A OUTPUT -d "$HOST_NETWORK" -j ACCEPT
+
+# Set default policies to DROP first
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+# First allow established connections for already approved traffic
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# Then allow only specific outbound traffic to allowed domains
+iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT
+
+# Append final REJECT rules for immediate error responses
+# For TCP traffic, send a TCP reset; for UDP, send ICMP port unreachable.
+iptables -A INPUT -p tcp -j REJECT --reject-with tcp-reset
+iptables -A INPUT -p udp -j REJECT --reject-with icmp-port-unreachable
+iptables -A OUTPUT -p tcp -j REJECT --reject-with tcp-reset
+iptables -A OUTPUT -p udp -j REJECT --reject-with icmp-port-unreachable
+iptables -A FORWARD -p tcp -j REJECT --reject-with tcp-reset
+iptables -A FORWARD -p udp -j REJECT --reject-with icmp-port-unreachable
+
+echo "Firewall configuration complete"
+echo "Verifying firewall rules..."
+if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - was able to reach https://example.com"
+    exit 1
+else
+    echo "Firewall verification passed - unable to reach https://example.com as expected"
+fi
+
+# Always verify OpenAI API access is working
+if ! curl --connect-timeout 5 https://api.openai.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - unable to reach https://api.openai.com"
+    exit 1
+else
+    echo "Firewall verification passed - able to reach https://api.openai.com as expected"
+fi

codex-cli/scripts/run_in_container.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+set -e
+
+# Usage:
+#   ./run_in_container.sh [--work_dir directory] "COMMAND"
+#
+#   Examples:
+#     ./run_in_container.sh --work_dir project/code "ls -la"
+#     ./run_in_container.sh "echo Hello, world!"
+
+# Default the work directory to WORKSPACE_ROOT_DIR if not provided.
+WORK_DIR="${WORKSPACE_ROOT_DIR:-$(pwd)}"
+# Default allowed domains - can be overridden with OPENAI_ALLOWED_DOMAINS env var
+OPENAI_ALLOWED_DOMAINS="${OPENAI_ALLOWED_DOMAINS:-api.openai.com}"
+
+# Parse optional flag.
+if [ "$1" = "--work_dir" ]; then
+  if [ -z "$2" ]; then
+    echo "Error: --work_dir flag provided but no directory specified."
+    exit 1
+  fi
+  WORK_DIR="$2"
+  shift 2
+fi
+
+WORK_DIR=$(realpath "$WORK_DIR")
+
+# Generate a unique container name based on the normalized work directory
+CONTAINER_NAME="codex_$(echo "$WORK_DIR" | sed 's/\//_/g' | sed 's/[^a-zA-Z0-9_-]//g')"
+
+# Define cleanup to remove the container on script exit, ensuring no leftover containers
+cleanup() {
+  docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
+}
+# Trap EXIT to invoke cleanup regardless of how the script terminates
+trap cleanup EXIT
+
+# Ensure a command is provided.
+if [ "$#" -eq 0 ]; then
+  echo "Usage: $0 [--work_dir directory] \"COMMAND\""
+  exit 1
+fi
+
+# Check if WORK_DIR is set.
+if [ -z "$WORK_DIR" ]; then
+  echo "Error: No work directory provided and WORKSPACE_ROOT_DIR is not set."
+  exit 1
+fi
+
+# Verify that OPENAI_ALLOWED_DOMAINS is not empty
+if [ -z "$OPENAI_ALLOWED_DOMAINS" ]; then
+  echo "Error: OPENAI_ALLOWED_DOMAINS is empty."
+  exit 1
+fi
+
+# Kill any existing container for the working directory using cleanup(), centralizing removal logic.
+cleanup
+
+# Run the container with the specified directory mounted at the same path inside the container.
+docker run --name "$CONTAINER_NAME" -d \
+  -e OPENAI_API_KEY \
+  --cap-add=NET_ADMIN \
+  --cap-add=NET_RAW \
+  -v "$WORK_DIR:/app$WORK_DIR" \
+  codex \
+  sleep infinity
+
+# Write the allowed domains to a file in the container
+docker exec --user root "$CONTAINER_NAME" bash -c "mkdir -p /etc/codex"
+for domain in $OPENAI_ALLOWED_DOMAINS; do
+  # Validate domain format to prevent injection
+  if [[ ! "$domain" =~ ^[a-zA-Z0-9][a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ ]]; then
+    echo "Error: Invalid domain format: $domain"
+    exit 1
+  fi
+  echo "$domain" | docker exec --user root -i "$CONTAINER_NAME" bash -c "cat >> /etc/codex/allowed_domains.txt"
+done
+
+# Set proper permissions on the domains file
+docker exec --user root "$CONTAINER_NAME" bash -c "chmod 444 /etc/codex/allowed_domains.txt && chown root:root /etc/codex/allowed_domains.txt"
+
+# Initialize the firewall inside the container as root user
+docker exec --user root "$CONTAINER_NAME" bash -c "/usr/local/bin/init_firewall.sh"
+
+# Remove the firewall script after running it
+docker exec --user root "$CONTAINER_NAME" bash -c "rm -f /usr/local/bin/init_firewall.sh"
+
+# Execute the provided command in the container, ensuring it runs in the work directory.
+# We use a parameterized bash command to safely handle the command and directory.
+
+quoted_args=""
+for arg in "$@"; do
+  quoted_args+=" $(printf '%q' "$arg")"
+done
+docker exec -it "$CONTAINER_NAME" bash -c "cd \"/app$WORK_DIR\" && codex --sandbox workspace-write --ask-for-approval on-request ${quoted_args}"

codex-rs/agent-identity/src/lib.rs

@@ -0,0 +1,1000 @@
+use std::collections::BTreeMap;
+use std::error::Error as StdError;
+use std::fmt;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use base64::Engine as _;
+use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use chrono::SecondsFormat;
+use chrono::Utc;
+use codex_http_client::HttpClient;
+use codex_http_client::HttpError;
+use codex_protocol::auth::PlanType as AuthPlanType;
+use codex_protocol::protocol::SessionSource;
+use crypto_box::SecretKey as Curve25519SecretKey;
+use ed25519_dalek::Signer as _;
+use ed25519_dalek::SigningKey;
+use ed25519_dalek::VerifyingKey;
+use ed25519_dalek::pkcs8::DecodePrivateKey;
+use ed25519_dalek::pkcs8::EncodePrivateKey;
+use http::StatusCode;
+use jsonwebtoken::Algorithm;
+use jsonwebtoken::DecodingKey;
+use jsonwebtoken::Validation;
+use jsonwebtoken::decode;
+use jsonwebtoken::decode_header;
+use jsonwebtoken::jwk::JwkSet;
+use rand::TryRngCore;
+use rand::rngs::OsRng;
+use serde::Deserialize;
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+use sha2::Digest as _;
+use sha2::Sha512;
+
+const AGENT_TASK_REGISTRATION_TIMEOUT: Duration = Duration::from_secs(30);
+const AGENT_IDENTITY_JWKS_TIMEOUT: Duration = Duration::from_secs(10);
+const AGENT_IDENTITY_JWT_AUDIENCE: &str = "codex-app-server";
+const AGENT_IDENTITY_JWT_ISSUER: &str = "https://chatgpt.com/codex-backend/agent-identity";
+const AGENT_REGISTRATION_TIMEOUT: Duration = Duration::from_secs(15);
+const PROD_AGENT_IDENTITY_AUTHAPI_BASE_URL: &str = "https://auth.openai.com/api/accounts";
+const STAGING_AGENT_IDENTITY_AUTHAPI_BASE_URL: &str = "https://auth.api.openai.org/api/accounts";
+const AGENT_IDENTITY_KEY_SEED_BYTES: usize = 64;
+const AGENT_IDENTITY_KEY_DERIVATION_CONTEXT: &[u8] = b"codex-agent-identity-ed25519-v1";
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum ChatGptEnvironment {
+    #[default]
+    Production,
+    Staging,
+}
+
+impl ChatGptEnvironment {
+    pub fn from_chatgpt_base_url(chatgpt_base_url: &str) -> Result<Self> {
+        match chatgpt_base_url.trim_end_matches('/') {
+            "https://chatgpt.com"
+            | "https://chatgpt.com/backend-api"
+            | "https://chatgpt.com/codex"
+            | "https://chatgpt.com/backend-api/codex"
+            | "https://chat.openai.com"
+            | "https://chat.openai.com/backend-api"
+            | "https://chat.openai.com/codex"
+            | "https://chat.openai.com/backend-api/codex" => Ok(Self::Production),
+            "https://chatgpt-staging.com"
+            | "https://chatgpt-staging.com/backend-api"
+            | "https://chatgpt-staging.com/codex"
+            | "https://chatgpt-staging.com/backend-api/codex" => Ok(Self::Staging),
+            _ => anyhow::bail!(
+                "Agent Identity only supports production and staging ChatGPT environments"
+            ),
+        }
+    }
+
+    pub fn chatgpt_base_url(self) -> &'static str {
+        match self {
+            Self::Production => "https://chatgpt.com/backend-api",
+            Self::Staging => "https://chatgpt-staging.com/backend-api",
+        }
+    }
+
+    pub fn agent_identity_authapi_base_url(self) -> &'static str {
+        match self {
+            Self::Production => PROD_AGENT_IDENTITY_AUTHAPI_BASE_URL,
+            Self::Staging => STAGING_AGENT_IDENTITY_AUTHAPI_BASE_URL,
+        }
+    }
+}
+
+/// Borrowed durable signing material for a registered agent identity.
+///
+/// This intentionally does not include a task id. Task ids are scoped to a
+/// single Codex run, while the agent runtime id and private key are the
+/// reusable identity material used to register and sign that run task.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct AgentIdentityKey<'a> {
+    pub agent_runtime_id: &'a str,
+    pub private_key_pkcs8_base64: &'a str,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+pub struct AgentBillOfMaterials {
+    pub agent_version: String,
+    pub agent_harness_id: String,
+    pub running_location: String,
+}
+
+pub struct GeneratedAgentKeyMaterial {
+    pub private_key_pkcs8_base64: String,
+    pub public_key_ssh: String,
+}
+
+/// Claims carried by an Agent Identity JWT.
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
+pub struct AgentIdentityJwtClaims {
+    pub iss: String,
+    pub aud: String,
+    pub iat: usize,
+    pub exp: usize,
+    pub agent_runtime_id: String,
+    pub agent_private_key: String,
+    pub account_id: String,
+    pub chatgpt_user_id: String,
+    pub email: Option<String>,
+    pub plan_type: AuthPlanType,
+    pub chatgpt_account_is_fedramp: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+struct AgentAssertionEnvelope {
+    agent_runtime_id: String,
+    task_id: String,
+    timestamp: String,
+    signature: String,
+}
+
+#[derive(Serialize)]
+struct RegisterTaskRequest {
+    timestamp: String,
+    signature: String,
+}
+
+#[derive(Deserialize)]
+struct RegisterTaskResponse {
+    #[serde(default)]
+    task_id: Option<String>,
+    #[serde(default, rename = "taskId")]
+    task_id_camel: Option<String>,
+    #[serde(default)]
+    encrypted_task_id: Option<String>,
+    #[serde(default, rename = "encryptedTaskId")]
+    encrypted_task_id_camel: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+struct RegisterAgentRequest {
+    abom: AgentBillOfMaterials,
+    agent_public_key: String,
+    capabilities: Vec<String>,
+    ttl: Option<u64>,
+}
+
+#[derive(Debug, Deserialize)]
+struct RegisterAgentResponse {
+    agent_runtime_id: String,
+}
+
+/// HTTP status failure returned by Agent Identity registration endpoints.
+#[derive(Debug)]
+pub struct AgentIdentityRegistrationHttpError {
+    operation: &'static str,
+    status: StatusCode,
+    body: String,
+}
+
+impl AgentIdentityRegistrationHttpError {
+    fn new(operation: &'static str, status: StatusCode, body: String) -> Self {
+        Self {
+            operation,
+            status,
+            body,
+        }
+    }
+
+    /// HTTP status returned by the registration endpoint.
+    pub fn status(&self) -> StatusCode {
+        self.status
+    }
+}
+
+impl fmt::Display for AgentIdentityRegistrationHttpError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        if self.body.is_empty() {
+            write!(f, "{} failed with status {}", self.operation, self.status)
+        } else {
+            write!(
+                f,
+                "{} failed with status {}: {}",
+                self.operation, self.status, self.body
+            )
+        }
+    }
+}
+
+impl StdError for AgentIdentityRegistrationHttpError {}
+
+/// Returns whether an Agent Identity registration error is safe to retry.
+pub fn is_retryable_registration_error(error: &anyhow::Error) -> bool {
+    error.chain().any(is_retryable_registration_cause)
+}
+
+fn is_retryable_registration_cause(cause: &(dyn StdError + 'static)) -> bool {
+    if let Some(error) = cause.downcast_ref::<AgentIdentityRegistrationHttpError>() {
+        return is_retryable_registration_status(error.status());
+    }
+
+    if let Some(error) = cause.downcast_ref::<HttpError>() {
+        if let Some(status) = error.status() {
+            return is_retryable_registration_status(status);
+        }
+        return error.is_timeout() || error.is_connect() || error.is_request();
+    }
+
+    false
+}
+
+fn is_retryable_registration_status(status: StatusCode) -> bool {
+    status == StatusCode::TOO_MANY_REQUESTS || status.is_server_error()
+}
+
+pub fn authorization_header_for_agent_task(
+    key: AgentIdentityKey<'_>,
+    task_id: &str,
+) -> Result<String> {
+    let timestamp = Utc::now().to_rfc3339_opts(SecondsFormat::Secs, true);
+    let envelope = AgentAssertionEnvelope {
+        agent_runtime_id: key.agent_runtime_id.to_string(),
+        task_id: task_id.to_string(),
+        timestamp: timestamp.clone(),
+        signature: sign_agent_assertion_payload(key, task_id, &timestamp)?,
+    };
+    let serialized_assertion = serialize_agent_assertion(&envelope)?;
+    Ok(format!("AgentAssertion {serialized_assertion}"))
+}
+
+pub async fn fetch_agent_identity_jwks(
+    client: &HttpClient,
+    agent_identity_jwt_base_url: &str,
+) -> Result<JwkSet> {
+    let response = client
+        .get(agent_identity_jwks_url(agent_identity_jwt_base_url))
+        .timeout(AGENT_IDENTITY_JWKS_TIMEOUT)
+        .send()
+        .await
+        .context("failed to request agent identity JWKS")?
+        .error_for_status()
+        .context("agent identity JWKS endpoint returned an error")?;
+
+    response
+        .json()
+        .await
+        .context("failed to decode agent identity JWKS")
+}
+
+pub fn decode_agent_identity_jwt(
+    jwt: &str,
+    jwks: Option<&JwkSet>,
+) -> Result<AgentIdentityJwtClaims> {
+    let Some(jwks) = jwks else {
+        return decode_agent_identity_jwt_payload(jwt);
+    };
+
+    let header = decode_header(jwt).context("failed to decode agent identity JWT header")?;
+    let kid = header
+        .kid
+        .context("agent identity JWT header does not include a kid")?;
+    let jwk = jwks
+        .find(&kid)
+        .with_context(|| format!("agent identity JWT kid {kid} is not trusted"))?;
+    let decoding_key = DecodingKey::from_jwk(jwk).context("failed to build JWT decoding key")?;
+    let mut validation = Validation::new(Algorithm::RS256);
+    validation.set_audience(&[AGENT_IDENTITY_JWT_AUDIENCE]);
+    validation.set_issuer(&[AGENT_IDENTITY_JWT_ISSUER]);
+    validation.required_spec_claims.insert("iss".to_string());
+    validation.required_spec_claims.insert("aud".to_string());
+    decode::<AgentIdentityJwtClaims>(jwt, &decoding_key, &validation)
+        .map(|data| data.claims)
+        .context("failed to verify agent identity JWT")
+}
+
+fn decode_agent_identity_jwt_payload<T: DeserializeOwned>(jwt: &str) -> Result<T> {
+    let mut parts = jwt.split('.');
+    let (_header_b64, payload_b64, _sig_b64) = match (parts.next(), parts.next(), parts.next()) {
+        (Some(h), Some(p), Some(s)) if !h.is_empty() && !p.is_empty() && !s.is_empty() => (h, p, s),
+        _ => anyhow::bail!("invalid agent identity JWT format"),
+    };
+    anyhow::ensure!(parts.next().is_none(), "invalid agent identity JWT format");
+
+    let payload_bytes = URL_SAFE_NO_PAD
+        .decode(payload_b64)
+        .context("agent identity JWT payload is not valid base64url")?;
+    serde_json::from_slice(&payload_bytes).context("agent identity JWT payload is not valid JSON")
+}
+
+pub fn sign_task_registration_payload(
+    key: AgentIdentityKey<'_>,
+    timestamp: &str,
+) -> Result<String> {
+    let signing_key = signing_key_from_private_key_pkcs8_base64(key.private_key_pkcs8_base64)?;
+    let payload = format!("{}:{timestamp}", key.agent_runtime_id);
+    Ok(BASE64_STANDARD.encode(signing_key.sign(payload.as_bytes()).to_bytes()))
+}
+
+pub async fn register_agent_task(
+    client: &HttpClient,
+    agent_identity_authapi_base_url: &str,
+    key: AgentIdentityKey<'_>,
+) -> Result<String> {
+    let timestamp = Utc::now().to_rfc3339_opts(SecondsFormat::Secs, true);
+    let request = RegisterTaskRequest {
+        signature: sign_task_registration_payload(key, &timestamp)?,
+        timestamp,
+    };
+    let url = agent_task_registration_url(agent_identity_authapi_base_url, key.agent_runtime_id);
+
+    let response = client
+        .post(url)
+        .timeout(AGENT_TASK_REGISTRATION_TIMEOUT)
+        .json(&request)
+        .send()
+        .await
+        .context("failed to register agent task")?;
+    if !response.status().is_success() {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        let body = if body.len() > 512 {
+            format!("{}...", body.chars().take(512).collect::<String>())
+        } else {
+            body
+        };
+        return Err(AgentIdentityRegistrationHttpError::new(
+            "agent task registration",
+            status,
+            body,
+        )
+        .into());
+    }
+
+    let response = response
+        .json()
+        .await
+        .context("failed to decode agent task registration response")?;
+
+    task_id_from_register_task_response(key, response)
+}
+
+pub async fn register_agent_identity(
+    client: &HttpClient,
+    agent_identity_authapi_base_url: &str,
+    access_token: &str,
+    is_fedramp_account: bool,
+    key_material: &GeneratedAgentKeyMaterial,
+    abom: AgentBillOfMaterials,
+    capabilities: Vec<String>,
+) -> Result<String> {
+    let url = agent_registration_url(agent_identity_authapi_base_url);
+    let request = RegisterAgentRequest {
+        abom,
+        agent_public_key: key_material.public_key_ssh.clone(),
+        capabilities,
+        ttl: None,
+    };
+
+    let mut request_builder = client
+        .post(&url)
+        .bearer_auth(access_token)
+        .json(&request)
+        .timeout(AGENT_REGISTRATION_TIMEOUT);
+    if is_fedramp_account {
+        request_builder = request_builder.header("X-OpenAI-Fedramp", "true");
+    }
+
+    let response = request_builder
+        .send()
+        .await
+        .with_context(|| format!("failed to send agent identity registration request to {url}"))?
+        .error_for_status()
+        .with_context(|| format!("agent identity registration failed for {url}"))?
+        .json::<RegisterAgentResponse>()
+        .await
+        .with_context(|| format!("failed to parse agent identity response from {url}"))?;
+
+    Ok(response.agent_runtime_id)
+}
+
+fn task_id_from_register_task_response(
+    key: AgentIdentityKey<'_>,
+    response: RegisterTaskResponse,
+) -> Result<String> {
+    if let Some(task_id) = response.task_id.or(response.task_id_camel) {
+        return Ok(task_id);
+    }
+    let encrypted_task_id = response
+        .encrypted_task_id
+        .or(response.encrypted_task_id_camel)
+        .context("agent task registration response omitted task id")?;
+    decrypt_task_id_response(key, &encrypted_task_id)
+}
+
+pub fn decrypt_task_id_response(
+    key: AgentIdentityKey<'_>,
+    encrypted_task_id: &str,
+) -> Result<String> {
+    let signing_key = signing_key_from_private_key_pkcs8_base64(key.private_key_pkcs8_base64)?;
+    let ciphertext = BASE64_STANDARD
+        .decode(encrypted_task_id)
+        .context("encrypted task id is not valid base64")?;
+    let plaintext = curve25519_secret_key_from_signing_key(&signing_key)
+        .unseal(&ciphertext)
+        .map_err(|_| anyhow::anyhow!("failed to decrypt encrypted task id"))?;
+    String::from_utf8(plaintext).context("decrypted task id is not valid UTF-8")
+}
+
+pub fn generate_agent_key_material() -> Result<GeneratedAgentKeyMaterial> {
+    let mut seed_material = [0u8; AGENT_IDENTITY_KEY_SEED_BYTES];
+    OsRng
+        .try_fill_bytes(&mut seed_material)
+        .context("failed to generate agent identity private key seed material")?;
+    // Ed25519 stores a 32-byte seed, so derive it from all sampled seed material.
+    let mut digest = Sha512::new();
+    digest.update(AGENT_IDENTITY_KEY_DERIVATION_CONTEXT);
+    digest.update(seed_material);
+    let digest = digest.finalize();
+    let mut secret_key_bytes = [0u8; 32];
+    secret_key_bytes.copy_from_slice(&digest[..32]);
+    let signing_key = SigningKey::from_bytes(&secret_key_bytes);
+    let private_key_pkcs8 = signing_key
+        .to_pkcs8_der()
+        .context("failed to encode agent identity private key as PKCS#8")?;
+
+    Ok(GeneratedAgentKeyMaterial {
+        private_key_pkcs8_base64: BASE64_STANDARD.encode(private_key_pkcs8.as_bytes()),
+        public_key_ssh: encode_ssh_ed25519_public_key(&signing_key.verifying_key()),
+    })
+}
+
+pub fn public_key_ssh_from_private_key_pkcs8_base64(
+    private_key_pkcs8_base64: &str,
+) -> Result<String> {
+    let signing_key = signing_key_from_private_key_pkcs8_base64(private_key_pkcs8_base64)?;
+    Ok(encode_ssh_ed25519_public_key(&signing_key.verifying_key()))
+}
+
+pub fn verifying_key_from_private_key_pkcs8_base64(
+    private_key_pkcs8_base64: &str,
+) -> Result<VerifyingKey> {
+    let signing_key = signing_key_from_private_key_pkcs8_base64(private_key_pkcs8_base64)?;
+    Ok(signing_key.verifying_key())
+}
+
+pub fn curve25519_secret_key_from_private_key_pkcs8_base64(
+    private_key_pkcs8_base64: &str,
+) -> Result<Curve25519SecretKey> {
+    let signing_key = signing_key_from_private_key_pkcs8_base64(private_key_pkcs8_base64)?;
+    Ok(curve25519_secret_key_from_signing_key(&signing_key))
+}
+
+pub fn agent_registration_url(agent_identity_authapi_base_url: &str) -> String {
+    agent_identity_authapi_url(agent_identity_authapi_base_url, "/v1/agent/register")
+}
+
+pub fn agent_task_registration_url(
+    agent_identity_authapi_base_url: &str,
+    agent_runtime_id: &str,
+) -> String {
+    agent_identity_authapi_url(
+        agent_identity_authapi_base_url,
+        &format!("/v1/agent/{agent_runtime_id}/task/register"),
+    )
+}
+
+pub fn agent_identity_jwks_url(agent_identity_jwt_base_url: &str) -> String {
+    let trimmed = agent_identity_jwt_base_url.trim_end_matches('/');
+    if trimmed.contains("/backend-api") {
+        format!("{trimmed}/wham/agent-identities/jwks")
+    } else {
+        format!("{trimmed}/agent-identities/jwks")
+    }
+}
+
+fn agent_identity_authapi_url(agent_identity_authapi_base_url: &str, api_path: &str) -> String {
+    let base_url = agent_identity_authapi_base_url.trim_end_matches('/');
+    format!("{base_url}{api_path}")
+}
+
+pub fn build_abom(session_source: SessionSource) -> AgentBillOfMaterials {
+    AgentBillOfMaterials {
+        agent_version: env!("CARGO_PKG_VERSION").to_string(),
+        agent_harness_id: match &session_source {
+            SessionSource::VSCode => "codex-app".to_string(),
+            SessionSource::Cli
+            | SessionSource::Exec
+            | SessionSource::Mcp
+            | SessionSource::Custom(_)
+            | SessionSource::Internal(_)
+            | SessionSource::SubAgent(_)
+            | SessionSource::Unknown => "codex-cli".to_string(),
+        },
+        running_location: format!("{}-{}", session_source, std::env::consts::OS),
+    }
+}
+
+pub fn encode_ssh_ed25519_public_key(verifying_key: &VerifyingKey) -> String {
+    let mut blob = Vec::with_capacity(4 + 11 + 4 + 32);
+    append_ssh_string(&mut blob, b"ssh-ed25519");
+    append_ssh_string(&mut blob, verifying_key.as_bytes());
+    format!("ssh-ed25519 {}", BASE64_STANDARD.encode(blob))
+}
+
+fn sign_agent_assertion_payload(
+    key: AgentIdentityKey<'_>,
+    task_id: &str,
+    timestamp: &str,
+) -> Result<String> {
+    let signing_key = signing_key_from_private_key_pkcs8_base64(key.private_key_pkcs8_base64)?;
+    let payload = format!("{}:{task_id}:{timestamp}", key.agent_runtime_id);
+    Ok(BASE64_STANDARD.encode(signing_key.sign(payload.as_bytes()).to_bytes()))
+}
+
+fn serialize_agent_assertion(envelope: &AgentAssertionEnvelope) -> Result<String> {
+    let payload = serde_json::to_vec(&BTreeMap::from([
+        ("agent_runtime_id", envelope.agent_runtime_id.as_str()),
+        ("signature", envelope.signature.as_str()),
+        ("task_id", envelope.task_id.as_str()),
+        ("timestamp", envelope.timestamp.as_str()),
+    ]))
+    .context("failed to serialize agent assertion envelope")?;
+    Ok(URL_SAFE_NO_PAD.encode(payload))
+}
+
+fn curve25519_secret_key_from_signing_key(signing_key: &SigningKey) -> Curve25519SecretKey {
+    let digest = Sha512::digest(signing_key.to_bytes());
+    let mut secret_key = [0u8; 32];
+    secret_key.copy_from_slice(&digest[..32]);
+    secret_key[0] &= 248;
+    secret_key[31] &= 127;
+    secret_key[31] |= 64;
+    Curve25519SecretKey::from(secret_key)
+}
+
+fn append_ssh_string(buf: &mut Vec<u8>, value: &[u8]) {
+    buf.extend_from_slice(&(value.len() as u32).to_be_bytes());
+    buf.extend_from_slice(value);
+}
+
+fn signing_key_from_private_key_pkcs8_base64(private_key_pkcs8_base64: &str) -> Result<SigningKey> {
+    let private_key = BASE64_STANDARD
+        .decode(private_key_pkcs8_base64)
+        .context("stored agent identity private key is not valid base64")?;
+    SigningKey::from_pkcs8_der(&private_key)
+        .context("stored agent identity private key is not valid PKCS#8")
+}
+
+#[cfg(test)]
+mod tests {
+    use base64::Engine as _;
+    use ed25519_dalek::Signature;
+    use ed25519_dalek::Verifier as _;
+    use jsonwebtoken::EncodingKey;
+    use jsonwebtoken::Header;
+    use pretty_assertions::assert_eq;
+
+    use codex_protocol::auth::KnownPlan;
+
+    use super::*;
+
+    #[test]
+    fn register_task_request_uses_single_run_task_shape() {
+        let request = RegisterTaskRequest {
+            timestamp: "2026-04-23T00:00:00Z".to_string(),
+            signature: "signature".to_string(),
+        };
+
+        let serialized = serde_json::to_value(request).expect("serialize request");
+
+        assert_eq!(
+            serialized,
+            serde_json::json!({
+                "timestamp": "2026-04-23T00:00:00Z",
+                "signature": "signature",
+            })
+        );
+    }
+
+    #[test]
+    fn authorization_header_for_agent_task_serializes_signed_agent_assertion() {
+        let signing_key = SigningKey::from_bytes(&[7u8; 32]);
+        let private_key = signing_key
+            .to_pkcs8_der()
+            .expect("encode test key material");
+        let key = AgentIdentityKey {
+            agent_runtime_id: "agent-123",
+            private_key_pkcs8_base64: &BASE64_STANDARD.encode(private_key.as_bytes()),
+        };
+
+        let header = authorization_header_for_agent_task(key, "task-123")
+            .expect("build agent assertion header");
+        let token = header
+            .strip_prefix("AgentAssertion ")
+            .expect("agent assertion scheme");
+        let payload = URL_SAFE_NO_PAD
+            .decode(token)
+            .expect("valid base64url payload");
+        let envelope: AgentAssertionEnvelope =
+            serde_json::from_slice(&payload).expect("valid assertion envelope");
+
+        assert_eq!(
+            envelope,
+            AgentAssertionEnvelope {
+                agent_runtime_id: "agent-123".to_string(),
+                task_id: "task-123".to_string(),
+                timestamp: envelope.timestamp.clone(),
+                signature: envelope.signature.clone(),
+            }
+        );
+        let signature_bytes = BASE64_STANDARD
+            .decode(&envelope.signature)
+            .expect("valid base64 signature");
+        let signature = Signature::from_slice(&signature_bytes).expect("valid signature bytes");
+        signing_key
+            .verifying_key()
+            .verify(
+                format!(
+                    "{}:{}:{}",
+                    envelope.agent_runtime_id, envelope.task_id, envelope.timestamp
+                )
+                .as_bytes(),
+                &signature,
+            )
+            .expect("signature should verify");
+    }
+
+    #[test]
+    fn decode_agent_identity_jwt_reads_claims() {
+        let jwt = jwt_with_payload(serde_json::json!({
+            "iss": AGENT_IDENTITY_JWT_ISSUER,
+            "aud": AGENT_IDENTITY_JWT_AUDIENCE,
+            "iat": 1_700_000_000usize,
+            "exp": 4_000_000_000usize,
+            "agent_runtime_id": "agent-runtime-id",
+            "agent_private_key": "private-key",
+            "account_id": "account-id",
+            "chatgpt_user_id": "user-id",
+            "email": "user@example.com",
+            "plan_type": "pro",
+            "chatgpt_account_is_fedramp": false,
+        }));
+
+        let claims = decode_agent_identity_jwt(&jwt, /*jwks*/ None).expect("JWT should decode");
+
+        assert_eq!(
+            claims,
+            AgentIdentityJwtClaims {
+                iss: AGENT_IDENTITY_JWT_ISSUER.to_string(),
+                aud: AGENT_IDENTITY_JWT_AUDIENCE.to_string(),
+                iat: 1_700_000_000,
+                exp: 4_000_000_000,
+                agent_runtime_id: "agent-runtime-id".to_string(),
+                agent_private_key: "private-key".to_string(),
+                account_id: "account-id".to_string(),
+                chatgpt_user_id: "user-id".to_string(),
+                email: Some("user@example.com".to_string()),
+                plan_type: AuthPlanType::Known(KnownPlan::Pro),
+                chatgpt_account_is_fedramp: false,
+            }
+        );
+    }
+
+    #[test]
+    fn decode_agent_identity_jwt_accepts_missing_email() {
+        let jwt = jwt_with_payload(serde_json::json!({
+            "iss": AGENT_IDENTITY_JWT_ISSUER,
+            "aud": AGENT_IDENTITY_JWT_AUDIENCE,
+            "iat": 1_700_000_000usize,
+            "exp": 4_000_000_000usize,
+            "agent_runtime_id": "agent-runtime-id",
+            "agent_private_key": "private-key",
+            "account_id": "account-id",
+            "chatgpt_user_id": "user-id",
+            "plan_type": "pro",
+            "chatgpt_account_is_fedramp": false,
+        }));
+
+        let claims = decode_agent_identity_jwt(&jwt, /*jwks*/ None).expect("JWT should decode");
+
+        assert_eq!(claims.email, None);
+    }
+
+    #[test]
+    fn decode_agent_identity_jwt_maps_raw_plan_aliases() {
+        let jwt = jwt_with_payload(serde_json::json!({
+            "iss": AGENT_IDENTITY_JWT_ISSUER,
+            "aud": AGENT_IDENTITY_JWT_AUDIENCE,
+            "iat": 1_700_000_000usize,
+            "exp": 4_000_000_000usize,
+            "agent_runtime_id": "agent-runtime-id",
+            "agent_private_key": "private-key",
+            "account_id": "account-id",
+            "chatgpt_user_id": "user-id",
+            "email": "user@example.com",
+            "plan_type": "hc",
+            "chatgpt_account_is_fedramp": false,
+        }));
+
+        let claims = decode_agent_identity_jwt(&jwt, /*jwks*/ None).expect("JWT should decode");
+
+        assert_eq!(claims.plan_type, AuthPlanType::Known(KnownPlan::Enterprise));
+    }
+
+    #[test]
+    fn decode_agent_identity_jwt_verifies_when_jwks_is_present() {
+        let jwks = test_jwks("test-key");
+        let claims = AgentIdentityJwtClaims {
+            iss: AGENT_IDENTITY_JWT_ISSUER.to_string(),
+            aud: AGENT_IDENTITY_JWT_AUDIENCE.to_string(),
+            iat: 1_700_000_000,
+            exp: 4_000_000_000,
+            agent_runtime_id: "agent-runtime-id".to_string(),
+            agent_private_key: "private-key".to_string(),
+            account_id: "account-id".to_string(),
+            chatgpt_user_id: "user-id".to_string(),
+            email: Some("user@example.com".to_string()),
+            plan_type: AuthPlanType::Known(KnownPlan::Pro),
+            chatgpt_account_is_fedramp: false,
+        };
+        let jwt = jsonwebtoken::encode(
+            &test_jwt_header("test-key"),
+            &serde_json::json!({
+                "iss": claims.iss,
+                "aud": claims.aud,
+                "iat": claims.iat,
+                "exp": claims.exp,
+                "agent_runtime_id": claims.agent_runtime_id,
+                "agent_private_key": claims.agent_private_key,
+                "account_id": claims.account_id,
+                "chatgpt_user_id": claims.chatgpt_user_id,
+                "email": claims.email,
+                "plan_type": "pro",
+                "chatgpt_account_is_fedramp": claims.chatgpt_account_is_fedramp,
+            }),
+            &test_rsa_encoding_key(),
+        )
+        .expect("JWT should encode");
+
+        let expected_claims = AgentIdentityJwtClaims {
+            iss: AGENT_IDENTITY_JWT_ISSUER.to_string(),
+            aud: AGENT_IDENTITY_JWT_AUDIENCE.to_string(),
+            iat: 1_700_000_000,
+            exp: 4_000_000_000,
+            agent_runtime_id: "agent-runtime-id".to_string(),
+            agent_private_key: "private-key".to_string(),
+            account_id: "account-id".to_string(),
+            chatgpt_user_id: "user-id".to_string(),
+            email: Some("user@example.com".to_string()),
+            plan_type: AuthPlanType::Known(KnownPlan::Pro),
+            chatgpt_account_is_fedramp: false,
+        };
+        assert_eq!(
+            decode_agent_identity_jwt(&jwt, Some(&jwks)).expect("JWT should verify"),
+            expected_claims
+        );
+    }
+
+    #[test]
+    fn decode_agent_identity_jwt_rejects_untrusted_kid() {
+        let jwks = test_jwks("other-key");
+
+        let jwt = jsonwebtoken::encode(
+            &test_jwt_header("test-key"),
+            &serde_json::json!({
+                "iss": AGENT_IDENTITY_JWT_ISSUER,
+                "aud": AGENT_IDENTITY_JWT_AUDIENCE,
+                "iat": 1_700_000_000,
+                "exp": 4_000_000_000usize,
+                "agent_runtime_id": "agent-runtime-id",
+                "agent_private_key": "private-key",
+                "account_id": "account-id",
+                "chatgpt_user_id": "user-id",
+                "email": "user@example.com",
+                "plan_type": "pro",
+                "chatgpt_account_is_fedramp": false,
+            }),
+            &test_rsa_encoding_key(),
+        )
+        .expect("JWT should encode");
+
+        decode_agent_identity_jwt(&jwt, Some(&jwks)).expect_err("JWT should not verify");
+    }
+
+    #[test]
+    fn decode_agent_identity_jwt_requires_issuer_and_audience() {
+        let jwks = test_jwks("test-key");
+        let jwt = jsonwebtoken::encode(
+            &test_jwt_header("test-key"),
+            &serde_json::json!({
+                "iat": 1_700_000_000,
+                "exp": 4_000_000_000usize,
+                "agent_runtime_id": "agent-runtime-id",
+                "agent_private_key": "private-key",
+                "account_id": "account-id",
+                "chatgpt_user_id": "user-id",
+                "email": "user@example.com",
+                "plan_type": "pro",
+                "chatgpt_account_is_fedramp": false,
+            }),
+            &test_rsa_encoding_key(),
+        )
+        .expect("JWT should encode");
+
+        decode_agent_identity_jwt(&jwt, Some(&jwks)).expect_err("JWT should not verify");
+    }
+
+    fn test_jwt_header(kid: &str) -> Header {
+        let mut header = Header::new(Algorithm::RS256);
+        header.kid = Some(kid.to_string());
+        header
+    }
+
+    fn test_rsa_encoding_key() -> EncodingKey {
+        EncodingKey::from_rsa_pem(
+            br#"-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDWpAXYypOsYAwO
+bvBduMk/mxaoYDze0AZSzaSzLuIlcsl2EKDgC3AabhIWXh/qTGEJLOU3VB1e5mO9
+FPbBlmIZSL3FQTbyt/hYutPFKfCou5PLmScw/TzILS3/RhT8UY9kxxZvXiEbTki9
+mvxRuZFpVqDFJHwfitIjKZGhXDCYVKurPTrxetYZJg0h8sQBLKjkZ0BqqaTUkAsg
+0eBgZAlXEzG3By8PGhUqYLt6W1Q3KYw0FmGy/gTyzH1g0ukGgSJvOd8SkNT8MbOs
+zl5kKxDNqpuEE6UZ3jbuJ+5382d31w+rOAJRzbf7QVdI9+luCSwJcDACYPQ4WNBa
+uCpV0ovpAgMBAAECggEAVu84LwZdqYN9XpswX8VoPYrjMm9IODapWQBRpQFoNyK2
+1ksF3bjEPvA2Azk8U/l7k+vLKw22l6lY3EyRZPcz5GnB8xLm3ogE3mtNOp4yCyVu
+RxhQ91aaN7mU17/a4BdorLi2LYVCg3zBmYociD1Q2AluNGsCmwPu+K7tfR2J0Sg8
+NjqiTbDG1XDpR/icwgC9t6vh8lZpCHDhF4tbQfLLVLeA/OdcuzXDyMCXbmdVIdBQ
+rm4aIFmr2e1/2ctTbCg85S6AGFTH+pSLjrwTzyvf+F6NW5uNjLQAQLFj+EznBDxj
+Xdx90cySrjsKK6PVWQF4RiTvkSW8eWL7R6B2FZbGwQKBgQDuVQRj72hWloR7mbEL
+aUEEv3pIXTMXWEsoMBNczos/1L1RnAN1AI44TurznasPZAWvQj+kVbLDR+TAeZrL
+iA8HIWswQUI18hFmgKzSkwIXGtubcKVrgsKeS4lMDKCM/Ef6WAYdeq6ronoY5lCN
+YrJFmGp81W5zcV7lyiycgbSiGwKBgQDmjWYf6pZjrK7Z+OJ3X1AZfi2vss15SCvL
+3fPgzIDbViztpGyQhc3DQZIsBNIu0xZp/veGce9TEeTds2ro9NfdJFeou8+fC7Pq
+sOsM3amGFFi+ZW/9BWyjZEM88bgWWAjqLHbpfHDxjAf5CSxddqxgHlbP0Ytyb1Vg
+gmPDn9YKSwKBgQDbTi3hC35WFuDHn0/zcSHcDZmnFuOZeqyFyV83yfMGhGrEuqvP
+sPgtRikajJ3IZsB4WZyYSidZXEFY/0z6NjOl2xF38MTNQPbT/FmK1q1Yt2UWrlv5
+BvSwlk87RG9D7C0LZo4R+D7cPoDdgqjiwMvMEIkEX5zn641oI1ZTmWKuuwKBgQCD
+KF+3unnRvHRAVoFnTZbA2fJdqMeRvogD04GhGlYX8V9f1hFY6nXTJaNlXVzA/J8c
+r8ra9kgjJuPfZ+ljG58OFFW2DRohLcQtuHYPfK6rMzoFHqnl9EcIcMp7ijuionR3
+29HOJFgQYgxLFXfit9d6WugiE+BTupiEbckZif13HwKBgE/lAlkVHP6YahOO2Ljc
+J1bwkqKZTB5dHolX9A58e/xXnfZ5P8f3Z83+Izap3FwqQulk7b1WO1MQcHuVg2NN
+5da0D4h2rYOXnbYIg0BVu4spQbaM6ewsp66b8+MzLOBvj8SzWdt1Oyw0q/MRyQAR
+8U4M2TSWCKUY/A6sT4W8+mT9
+-----END PRIVATE KEY-----"#,
+        )
+        .expect("test RSA key should parse")
+    }
+
+    fn test_jwks(kid: &str) -> jsonwebtoken::jwk::JwkSet {
+        serde_json::from_value(serde_json::json!({
+            "keys": [{
+                "kty": "RSA",
+                "kid": kid,
+                "use": "sig",
+                "alg": "RS256",
+                "n": "1qQF2MqTrGAMDm7wXbjJP5sWqGA83tAGUs2ksy7iJXLJdhCg4AtwGm4SFl4f6kxhCSzlN1QdXuZjvRT2wZZiGUi9xUE28rf4WLrTxSnwqLuTy5knMP08yC0t_0YU_FGPZMcWb14hG05IvZr8UbmRaVagxSR8H4rSIymRoVwwmFSrqz068XrWGSYNIfLEASyo5GdAaqmk1JALINHgYGQJVxMxtwcvDxoVKmC7eltUNymMNBZhsv4E8sx9YNLpBoEibznfEpDU_DGzrM5eZCsQzaqbhBOlGd427ifud_Nnd9cPqzgCUc23-0FXSPfpbgksCXAwAmD0OFjQWrgqVdKL6Q",
+                "e": "AQAB",
+            }]
+        }))
+        .expect("test JWKS should parse")
+    }
+
+    #[test]
+    fn chatgpt_environment_maps_known_urls_to_authapi() -> anyhow::Result<()> {
+        assert_eq!(
+            ChatGptEnvironment::from_chatgpt_base_url("https://chatgpt.com/backend-api/codex")?,
+            ChatGptEnvironment::Production
+        );
+        assert_eq!(
+            ChatGptEnvironment::Production.agent_identity_authapi_base_url(),
+            "https://auth.openai.com/api/accounts"
+        );
+        assert_eq!(
+            ChatGptEnvironment::from_chatgpt_base_url("https://chatgpt-staging.com/backend-api")?,
+            ChatGptEnvironment::Staging
+        );
+        assert_eq!(
+            ChatGptEnvironment::Staging.agent_identity_authapi_base_url(),
+            "https://auth.api.openai.org/api/accounts"
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn chatgpt_environment_rejects_custom_urls() {
+        assert!(ChatGptEnvironment::from_chatgpt_base_url("http://localhost:8080").is_err(),);
+    }
+
+    #[test]
+    fn agent_registration_url_appends_to_authapi_base_url() {
+        assert_eq!(
+            agent_registration_url("https://auth.openai.com/api/accounts"),
+            "https://auth.openai.com/api/accounts/v1/agent/register"
+        );
+        assert_eq!(
+            agent_registration_url("http://localhost:8080"),
+            "http://localhost:8080/v1/agent/register"
+        );
+        assert_eq!(
+            agent_registration_url("http://localhost:8080/backend-api"),
+            "http://localhost:8080/backend-api/v1/agent/register"
+        );
+    }
+
+    #[test]
+    fn agent_task_registration_url_appends_to_authapi_base_url() {
+        assert_eq!(
+            agent_task_registration_url("https://auth.openai.com/api/accounts", "agent-runtime-id"),
+            "https://auth.openai.com/api/accounts/v1/agent/agent-runtime-id/task/register"
+        );
+        assert_eq!(
+            agent_task_registration_url(
+                "https://auth.openai.com/api/accounts/",
+                "agent-runtime-id"
+            ),
+            "https://auth.openai.com/api/accounts/v1/agent/agent-runtime-id/task/register"
+        );
+        assert_eq!(
+            agent_task_registration_url("http://localhost:8080", "agent-runtime-id"),
+            "http://localhost:8080/v1/agent/agent-runtime-id/task/register"
+        );
+    }
+
+    #[test]
+    fn retryable_registration_error_accepts_429_and_5xx() {
+        let too_many_requests = anyhow::Error::new(AgentIdentityRegistrationHttpError::new(
+            "agent registration",
+            StatusCode::TOO_MANY_REQUESTS,
+            "rate limited".to_string(),
+        ));
+        let unavailable = anyhow::Error::new(AgentIdentityRegistrationHttpError::new(
+            "agent registration",
+            StatusCode::SERVICE_UNAVAILABLE,
+            "try later".to_string(),
+        ));
+
+        assert!(is_retryable_registration_error(&too_many_requests));
+        assert!(is_retryable_registration_error(&unavailable));
+    }
+
+    #[test]
+    fn retryable_registration_error_rejects_hard_failures() {
+        let forbidden = anyhow::Error::new(AgentIdentityRegistrationHttpError::new(
+            "agent registration",
+            StatusCode::FORBIDDEN,
+            "not allowed".to_string(),
+        ));
+        let malformed = anyhow::anyhow!("failed to sign registration request");
+
+        assert!(!is_retryable_registration_error(&forbidden));
+        assert!(!is_retryable_registration_error(&malformed));
+    }
+
+    #[test]
+    fn agent_identity_jwks_url_uses_agent_identity_jwt_route() {
+        assert_eq!(
+            agent_identity_jwks_url("https://chatgpt.com/backend-api"),
+            "https://chatgpt.com/backend-api/wham/agent-identities/jwks"
+        );
+        assert_eq!(
+            agent_identity_jwks_url("https://chatgpt.com/backend-api/"),
+            "https://chatgpt.com/backend-api/wham/agent-identities/jwks"
+        );
+    }
+
+    #[test]
+    fn agent_identity_jwks_url_uses_jwt_issuer_base_url() {
+        assert_eq!(
+            agent_identity_jwks_url("http://localhost:8080/api/codex"),
+            "http://localhost:8080/api/codex/agent-identities/jwks"
+        );
+        assert_eq!(
+            agent_identity_jwks_url("http://localhost:8080/api/codex/"),
+            "http://localhost:8080/api/codex/agent-identities/jwks"
+        );
+    }
+
+    fn jwt_with_payload(payload: serde_json::Value) -> String {
+        let encode = |bytes: &[u8]| URL_SAFE_NO_PAD.encode(bytes);
+        let header_b64 = encode(br#"{"alg":"none","typ":"JWT"}"#);
+        let payload_b64 = encode(&serde_json::to_vec(&payload).expect("payload should serialize"));
+        let signature_b64 = encode(b"sig");
+        format!("{header_b64}.{payload_b64}.{signature_b64}")
+    }
+}

codex-rs/ansi-escape/src/lib.rs

@@ -0,0 +1,58 @@
+use ansi_to_tui::Error;
+use ansi_to_tui::IntoText;
+use ratatui::text::Line;
+use ratatui::text::Text;
+
+// Expand tabs in a best-effort way for transcript rendering.
+// Tabs can interact poorly with left-gutter prefixes in our TUI and CLI
+// transcript views (e.g., `nl` separates line numbers from content with a tab).
+// Replacing tabs with spaces avoids odd visual artifacts without changing
+// semantics for our use cases.
+fn expand_tabs(s: &str) -> std::borrow::Cow<'_, str> {
+    if s.contains('\t') {
+        // Keep it simple: replace each tab with 4 spaces.
+        // We do not try to align to tab stops since most usages (like `nl`)
+        // look acceptable with a fixed substitution and this avoids stateful math
+        // across spans.
+        std::borrow::Cow::Owned(s.replace('\t', "    "))
+    } else {
+        std::borrow::Cow::Borrowed(s)
+    }
+}
+
+/// This function should be used when the contents of `s` are expected to match
+/// a single line. If multiple lines are found, a warning is logged and only the
+/// first line is returned.
+pub fn ansi_escape_line(s: &str) -> Line<'static> {
+    // Normalize tabs to spaces to avoid odd gutter collisions in transcript mode.
+    let s = expand_tabs(s);
+    let text = ansi_escape(&s);
+    match text.lines.as_slice() {
+        [] => "".into(),
+        [only] => only.clone(),
+        [first, rest @ ..] => {
+            tracing::warn!("ansi_escape_line: expected a single line, got {first:?} and {rest:?}");
+            first.clone()
+        }
+    }
+}
+
+pub fn ansi_escape(s: &str) -> Text<'static> {
+    // to_text() claims to be faster, but introduces complex lifetime issues
+    // such that it's not worth it.
+    match s.into_text() {
+        Ok(text) => text,
+        Err(err) => match err {
+            Error::NomError(message) => {
+                tracing::error!(
+                    "ansi_to_tui NomError docs claim should never happen when parsing `{s}`: {message}"
+                );
+                panic!();
+            }
+            Error::Utf8Error(utf8error) => {
+                tracing::error!("Utf8Error: {utf8error}");
+                panic!();
+            }
+        },
+    }
+}

codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d6fb74c9af068055ac5e369ce116c27299e46ad2a0487541a7abbd52761f9832
+size 157496

codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:be380114e24a7541e07df1af9b1d2d10f8749f1d97516496a7e9c59bd395c29d
+size 151569

codex-rs/app-server-transport/src/connection_auth.rs

@@ -0,0 +1,51 @@
+//! Binds a transport connection to the authentication owner that established it.
+//! Owner revisions invalidate queued work even before transport closure is delivered.
+
+use codex_login::AuthChangeState;
+use codex_login::AuthManager;
+use std::io;
+use tokio::sync::watch;
+
+#[derive(Clone, Debug)]
+pub struct ConnectionAuth {
+    changes: watch::Receiver<AuthChangeState>,
+    owner_generation: u64,
+}
+
+impl ConnectionAuth {
+    pub(crate) fn capture(auth_manager: &AuthManager) -> Self {
+        let changes = auth_manager.auth_change_state_receiver();
+        let owner_generation = changes.borrow().owner_generation;
+        Self::new(changes, owner_generation)
+    }
+
+    pub(crate) fn ensure_current(&self) -> io::Result<()> {
+        if self.is_current() {
+            Ok(())
+        } else {
+            Err(io::Error::new(
+                io::ErrorKind::Interrupted,
+                "remote control authentication changed",
+            ))
+        }
+    }
+
+    pub(crate) fn new(changes: watch::Receiver<AuthChangeState>, owner_generation: u64) -> Self {
+        Self {
+            changes,
+            owner_generation,
+        }
+    }
+
+    pub fn is_current(&self) -> bool {
+        self.changes.borrow().owner_generation == self.owner_generation
+            && self.changes.has_changed().is_ok()
+    }
+
+    pub(crate) async fn invalidated(&self) {
+        let mut changes = self.changes.clone();
+        let _ = changes
+            .wait_for(|state| state.owner_generation != self.owner_generation)
+            .await;
+    }
+}

codex-rs/app-server-transport/src/daemon_recovery.rs

@@ -0,0 +1,82 @@
+//! Shared on-disk candidate set for managed daemon restarts.
+
+use std::collections::BTreeMap;
+use std::collections::BTreeSet;
+use std::io;
+use std::path::Path;
+
+use codex_core::path_utils::write_atomically;
+use serde::Deserialize;
+use serde::Serialize;
+
+#[derive(Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
+pub struct RecoverySnapshot {
+    #[serde(skip)]
+    pub loaded: BTreeSet<String>,
+    pub interrupted: BTreeMap<String, InterruptedTurn>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
+pub struct InterruptedTurn {
+    pub turn_id: String,
+    pub output_schema: Option<serde_json::Value>,
+    pub service_tier: Option<String>,
+    pub cyber_access_program: Option<codex_protocol::turn_input::CyberAccessProgram>,
+    /// Only local execution with thread-owned configuration can continue automatically.
+    /// Older snapshots without this identity are reloaded without continuation.
+    pub local_environment: Option<codex_app_server_protocol::ThreadEnvironment>,
+}
+
+// Old servers accept the array and skip this non-thread entry during best-effort
+// restoration. Keeping metadata in the same atomic file avoids stale sidecars.
+const INTERRUPTION_PREFIX: &str = "codex-interrupted-v1:";
+
+pub fn read_snapshot(path: &Path) -> io::Result<RecoverySnapshot> {
+    let mut loaded: BTreeSet<String> = match std::fs::read(path) {
+        Ok(contents) => serde_json::from_slice(&contents).map_err(io::Error::other)?,
+        Err(err) if err.kind() == io::ErrorKind::NotFound => return Ok(RecoverySnapshot::default()),
+        Err(err) => return Err(err),
+    };
+    let mut snapshot = RecoverySnapshot::default();
+    loaded.retain(|entry| {
+        if let Some(metadata) = entry.strip_prefix(INTERRUPTION_PREFIX) {
+            if let Ok(saved) = serde_json::from_str::<RecoverySnapshot>(metadata) {
+                snapshot = saved;
+            }
+            false
+        } else {
+            true
+        }
+    });
+    snapshot.interrupted.retain(|id, _| loaded.contains(id));
+    snapshot.loaded = loaded;
+    Ok(snapshot)
+}
+
+pub fn read_candidates(path: &Path) -> io::Result<BTreeSet<String>> {
+    Ok(read_snapshot(path)?.loaded)
+}
+
+pub fn write_candidates(path: &Path, candidates: &BTreeSet<String>) -> io::Result<()> {
+    write_snapshot(
+        path,
+        &RecoverySnapshot {
+            loaded: candidates.clone(),
+            ..Default::default()
+        },
+    )
+}
+
+pub fn write_snapshot(path: &Path, snapshot: &RecoverySnapshot) -> io::Result<()> {
+    let mut saved = snapshot.loaded.clone();
+    if !snapshot.interrupted.is_empty() {
+        saved.insert(format!(
+            "{INTERRUPTION_PREFIX}{}",
+            serde_json::to_string(snapshot).map_err(io::Error::other)?
+        ));
+    }
+    write_atomically(
+        path,
+        &serde_json::to_string(&saved).map_err(io::Error::other)?,
+    )
+}

codex-rs/app-server-transport/src/daemon_shutdown.rs

@@ -0,0 +1,53 @@
+//! The detached Windows updater has no control socket, so its owner requests
+//! termination through a file in its private state directory. Managed app-server
+//! shutdown instead uses the protected local socket.
+
+use std::io;
+use std::io::Read;
+use std::path::Path;
+#[cfg(windows)]
+use std::path::PathBuf;
+#[cfg(windows)]
+use std::time::Duration;
+
+#[cfg(windows)]
+pub const DAEMON_SHUTDOWN_FILE_ENV: &str = "CODEX_DAEMON_SHUTDOWN_FILE";
+
+/// Waits for and consumes one updater shutdown request.
+#[cfg(windows)]
+pub async fn daemon_shutdown_signal() -> io::Result<()> {
+    let Some(path) = std::env::var_os(DAEMON_SHUTDOWN_FILE_ENV).map(PathBuf::from) else {
+        return std::future::pending().await;
+    };
+    loop {
+        if take_shutdown_request(&path, std::process::id())? {
+            return Ok(());
+        }
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    }
+}
+
+fn take_shutdown_request(path: &Path, pid: u32) -> io::Result<bool> {
+    let file = match std::fs::File::open(path) {
+        Ok(file) => file,
+        Err(err) if err.kind() == io::ErrorKind::NotFound => return Ok(false),
+        Err(err) => return Err(err),
+    };
+    // Descendant app-servers may inherit the control path. Only the intended
+    // process can consume a request. Bound reads to a u32 PID plus one extra byte.
+    let mut contents = Vec::new();
+    file.take(/*limit*/ 11).read_to_end(&mut contents)?;
+    if contents != pid.to_string().as_bytes() {
+        return Ok(false);
+    }
+    // Synchronous consumption cannot lose a request to select cancellation.
+    match std::fs::remove_file(path) {
+        Ok(()) => Ok(true),
+        Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(false),
+        Err(err) => Err(err),
+    }
+}
+
+#[cfg(test)]
+#[path = "daemon_shutdown_tests.rs"]
+mod tests;

codex-rs/app-server-transport/src/daemon_shutdown_tests.rs

@@ -0,0 +1,22 @@
+use super::take_shutdown_request;
+
+#[test]
+fn inherited_control_path_cannot_consume_another_process_request() {
+    let directory = tempfile::tempdir().expect("directory");
+    let request = directory.path().join("shutdown");
+    std::fs::write(&request, "1234").expect("request");
+    assert!(!take_shutdown_request(&request, /*pid*/ 5678).expect("descendant probe"));
+    assert!(take_shutdown_request(&request, /*pid*/ 1234).expect("parent probe"));
+    assert!(!take_shutdown_request(&request, /*pid*/ 1234).expect("already consumed"));
+}
+
+#[test]
+fn incomplete_or_invalid_requests_are_not_consumed() {
+    let directory = tempfile::tempdir().expect("directory");
+    let request = directory.path().join("shutdown");
+    for contents in [b"".as_slice(), b"123", b"1234junk", &[0xff; 20]] {
+        std::fs::write(&request, contents).expect("request");
+        assert!(!take_shutdown_request(&request, /*pid*/ 1234).expect("probe"));
+        assert!(request.exists());
+    }
+}

codex-rs/app-server-transport/src/lib.rs

@@ -0,0 +1,45 @@
+pub mod daemon_recovery;
+#[cfg(any(windows, test))]
+mod daemon_shutdown;
+#[cfg(windows)]
+pub use daemon_shutdown::DAEMON_SHUTDOWN_FILE_ENV;
+#[cfg(windows)]
+pub use daemon_shutdown::daemon_shutdown_signal;
+/// Only managed app-server launches accept the local socket shutdown request.
+pub const DAEMON_SHUTDOWN_SOCKET_ENV: &str = "CODEX_DAEMON_SHUTDOWN_SOCKET";
+mod connection_auth;
+mod outgoing_message;
+mod transport;
+
+pub use connection_auth::ConnectionAuth;
+pub use outgoing_message::ConnectionId;
+pub use outgoing_message::OutgoingError;
+pub use outgoing_message::OutgoingMessage;
+pub use outgoing_message::OutgoingResponse;
+pub use outgoing_message::QueuedOutgoingMessage;
+pub use transport::AppServerStartupLock;
+pub use transport::AppServerTransport;
+pub use transport::AppServerTransportParseError;
+pub use transport::CHANNEL_CAPACITY;
+pub use transport::ConnectionOrigin;
+pub use transport::DaemonShutdownAccess;
+pub use transport::REMOTE_CONTROL_DISABLED_ENV_VAR;
+pub use transport::RemoteControlDisabledByRequirements;
+pub use transport::RemoteControlEnableError;
+pub use transport::RemoteControlHandle;
+pub use transport::RemoteControlPolicy;
+pub use transport::RemoteControlStartConfig;
+pub use transport::RemoteControlStartupMode;
+pub use transport::RemoteControlUnavailable;
+pub use transport::TransportEvent;
+pub use transport::acquire_app_server_startup_lock;
+pub use transport::app_server_control_socket_path;
+pub use transport::app_server_startup_lock_path;
+pub use transport::auth;
+pub use transport::daemon_recovery_file_path;
+pub use transport::prepare_control_socket_path;
+pub use transport::start_control_socket_acceptor;
+pub use transport::start_remote_control;
+pub use transport::start_stdio_connection;
+pub use transport::start_websocket_acceptor;
+pub use transport::take_remote_control_disabled_env;

codex-rs/app-server-transport/src/outgoing_message.rs

@@ -0,0 +1,59 @@
+use std::fmt;
+
+use codex_app_server_protocol::ClientResponsePayload;
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::ServerNotificationEnvelope;
+use codex_app_server_protocol::ServerRequest;
+use serde::Serialize;
+use tokio::sync::oneshot;
+
+/// Stable identifier for a transport connection.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct ConnectionId(pub u64);
+
+impl fmt::Display for ConnectionId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+/// Outgoing message from the server to the client.
+#[derive(Debug, Clone, Serialize)]
+#[serde(untagged)]
+#[allow(clippy::large_enum_variant)]
+pub enum OutgoingMessage {
+    Request(ServerRequest),
+    /// AppServerNotification is specific to the case where this is run as an
+    /// "app server" as opposed to an MCP server.
+    AppServerNotification(ServerNotificationEnvelope),
+    Response(OutgoingResponse),
+    Error(OutgoingError),
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct OutgoingResponse {
+    pub id: RequestId,
+    pub result: Box<ClientResponsePayload>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize)]
+pub struct OutgoingError {
+    pub error: JSONRPCErrorError,
+    pub id: RequestId,
+}
+
+#[derive(Debug)]
+pub struct QueuedOutgoingMessage {
+    pub message: OutgoingMessage,
+    pub write_complete_tx: Option<oneshot::Sender<()>>,
+}
+
+impl QueuedOutgoingMessage {
+    pub fn new(message: OutgoingMessage) -> Self {
+        Self {
+            message,
+            write_complete_tx: None,
+        }
+    }
+}

codex-rs/app-server-transport/src/transport/auth.rs

@@ -0,0 +1,751 @@
+use anyhow::Context;
+use axum::http::HeaderMap;
+use axum::http::StatusCode;
+use axum::http::header::AUTHORIZATION;
+use clap::Args;
+use clap::ValueEnum;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use constant_time_eq::constant_time_eq_32;
+use jsonwebtoken::Algorithm;
+use jsonwebtoken::DecodingKey;
+use jsonwebtoken::Validation;
+use jsonwebtoken::decode;
+use serde::Deserialize;
+use sha2::Digest;
+use sha2::Sha256;
+use std::io;
+use std::io::ErrorKind;
+use std::net::SocketAddr;
+use std::path::Path;
+use std::path::PathBuf;
+use time::OffsetDateTime;
+
+const DEFAULT_MAX_CLOCK_SKEW_SECONDS: u64 = 30;
+const MIN_SIGNED_BEARER_SECRET_BYTES: usize = 32;
+const INVALID_AUTHORIZATION_HEADER_MESSAGE: &str = "invalid authorization header";
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Args)]
+pub struct AppServerWebsocketAuthArgs {
+    /// Websocket auth mode for non-loopback listeners.
+    #[arg(long = "ws-auth", value_name = "MODE", value_enum)]
+    pub ws_auth: Option<WebsocketAuthCliMode>,
+
+    /// Absolute path to the capability-token file.
+    #[arg(long = "ws-token-file", value_name = "PATH")]
+    pub ws_token_file: Option<PathBuf>,
+
+    /// Hex-encoded SHA-256 digest of the capability token.
+    #[arg(long = "ws-token-sha256", value_name = "HEX")]
+    pub ws_token_sha256: Option<String>,
+
+    /// Absolute path to the shared secret file for signed JWT bearer tokens.
+    #[arg(long = "ws-shared-secret-file", value_name = "PATH")]
+    pub ws_shared_secret_file: Option<PathBuf>,
+
+    /// Expected issuer for signed JWT bearer tokens.
+    #[arg(long = "ws-issuer", value_name = "ISSUER")]
+    pub ws_issuer: Option<String>,
+
+    /// Expected audience for signed JWT bearer tokens.
+    #[arg(long = "ws-audience", value_name = "AUDIENCE")]
+    pub ws_audience: Option<String>,
+
+    /// Maximum clock skew when validating signed JWT bearer tokens.
+    #[arg(long = "ws-max-clock-skew-seconds", value_name = "SECONDS")]
+    pub ws_max_clock_skew_seconds: Option<u64>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum WebsocketAuthCliMode {
+    CapabilityToken,
+    SignedBearerToken,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AppServerWebsocketAuthSettings {
+    pub config: Option<AppServerWebsocketAuthConfig>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AppServerWebsocketAuthConfig {
+    CapabilityToken {
+        source: AppServerWebsocketCapabilityTokenSource,
+    },
+    SignedBearerToken {
+        shared_secret_file: AbsolutePathBuf,
+        issuer: Option<String>,
+        audience: Option<String>,
+        max_clock_skew_seconds: u64,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AppServerWebsocketCapabilityTokenSource {
+    TokenFile { token_file: AbsolutePathBuf },
+    TokenSha256 { token_sha256: [u8; 32] },
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct WebsocketAuthPolicy {
+    pub(crate) mode: Option<WebsocketAuthMode>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) enum WebsocketAuthMode {
+    CapabilityToken {
+        token_sha256: [u8; 32],
+    },
+    SignedBearerToken {
+        shared_secret: Vec<u8>,
+        issuer: Option<String>,
+        audience: Option<String>,
+        max_clock_skew_seconds: i64,
+    },
+}
+
+#[derive(Debug)]
+pub(crate) struct WebsocketAuthError {
+    status_code: StatusCode,
+    message: &'static str,
+}
+
+#[derive(Deserialize)]
+struct JwtClaims {
+    exp: i64,
+    nbf: Option<i64>,
+    iss: Option<String>,
+    aud: Option<JwtAudienceClaim>,
+}
+
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum JwtAudienceClaim {
+    Single(String),
+    Multiple(Vec<String>),
+}
+
+impl WebsocketAuthError {
+    pub(crate) fn status_code(&self) -> StatusCode {
+        self.status_code
+    }
+
+    pub(crate) fn message(&self) -> &'static str {
+        self.message
+    }
+}
+
+impl AppServerWebsocketAuthArgs {
+    pub fn try_into_settings(self) -> anyhow::Result<AppServerWebsocketAuthSettings> {
+        let normalize = |value: Option<String>| {
+            value.and_then(|value| {
+                let trimmed = value.trim();
+                (!trimmed.is_empty()).then(|| trimmed.to_string())
+            })
+        };
+
+        let config = match self.ws_auth {
+            Some(WebsocketAuthCliMode::CapabilityToken) => {
+                if self.ws_shared_secret_file.is_some()
+                    || self.ws_issuer.is_some()
+                    || self.ws_audience.is_some()
+                    || self.ws_max_clock_skew_seconds.is_some()
+                {
+                    anyhow::bail!(
+                        "`--ws-shared-secret-file`, `--ws-issuer`, `--ws-audience`, and `--ws-max-clock-skew-seconds` require `--ws-auth signed-bearer-token`"
+                    );
+                }
+                let source = match (self.ws_token_file, self.ws_token_sha256) {
+                    (Some(_), Some(_)) => {
+                        anyhow::bail!(
+                            "`--ws-token-file` and `--ws-token-sha256` are mutually exclusive"
+                        );
+                    }
+                    (Some(token_file), None) => {
+                        AppServerWebsocketCapabilityTokenSource::TokenFile {
+                            token_file: absolute_path_arg("--ws-token-file", token_file)?,
+                        }
+                    }
+                    (None, Some(token_sha256)) => {
+                        AppServerWebsocketCapabilityTokenSource::TokenSha256 {
+                            token_sha256: sha256_digest_arg("--ws-token-sha256", &token_sha256)?,
+                        }
+                    }
+                    (None, None) => {
+                        anyhow::bail!(
+                            "`--ws-token-file` or `--ws-token-sha256` is required when `--ws-auth capability-token` is set"
+                        );
+                    }
+                };
+                Some(AppServerWebsocketAuthConfig::CapabilityToken { source })
+            }
+            Some(WebsocketAuthCliMode::SignedBearerToken) => {
+                if self.ws_token_file.is_some() || self.ws_token_sha256.is_some() {
+                    anyhow::bail!(
+                        "`--ws-token-file` and `--ws-token-sha256` require `--ws-auth capability-token`, not `signed-bearer-token`"
+                    );
+                }
+                let shared_secret_file = self.ws_shared_secret_file.context(
+                    "`--ws-shared-secret-file` is required when `--ws-auth signed-bearer-token` is set",
+                )?;
+                Some(AppServerWebsocketAuthConfig::SignedBearerToken {
+                    shared_secret_file: absolute_path_arg(
+                        "--ws-shared-secret-file",
+                        shared_secret_file,
+                    )?,
+                    issuer: normalize(self.ws_issuer),
+                    audience: normalize(self.ws_audience),
+                    max_clock_skew_seconds: self
+                        .ws_max_clock_skew_seconds
+                        .unwrap_or(DEFAULT_MAX_CLOCK_SKEW_SECONDS),
+                })
+            }
+            None => {
+                if self.ws_token_file.is_some()
+                    || self.ws_token_sha256.is_some()
+                    || self.ws_shared_secret_file.is_some()
+                    || self.ws_issuer.is_some()
+                    || self.ws_audience.is_some()
+                    || self.ws_max_clock_skew_seconds.is_some()
+                {
+                    anyhow::bail!(
+                        "websocket auth flags require `--ws-auth capability-token` or `--ws-auth signed-bearer-token`"
+                    );
+                }
+                None
+            }
+        };
+
+        Ok(AppServerWebsocketAuthSettings { config })
+    }
+}
+
+pub fn policy_from_settings(
+    settings: &AppServerWebsocketAuthSettings,
+) -> io::Result<WebsocketAuthPolicy> {
+    let mode = match settings.config.as_ref() {
+        Some(AppServerWebsocketAuthConfig::CapabilityToken { source }) => match source {
+            AppServerWebsocketCapabilityTokenSource::TokenFile { token_file } => {
+                let token = read_trimmed_secret(token_file.as_ref())?;
+                Some(WebsocketAuthMode::CapabilityToken {
+                    token_sha256: sha256_digest(token.as_bytes()),
+                })
+            }
+            AppServerWebsocketCapabilityTokenSource::TokenSha256 { token_sha256 } => {
+                Some(WebsocketAuthMode::CapabilityToken {
+                    token_sha256: *token_sha256,
+                })
+            }
+        },
+        Some(AppServerWebsocketAuthConfig::SignedBearerToken {
+            shared_secret_file,
+            issuer,
+            audience,
+            max_clock_skew_seconds,
+        }) => {
+            let shared_secret = read_trimmed_secret(shared_secret_file.as_ref())?.into_bytes();
+            validate_signed_bearer_secret(shared_secret_file.as_ref(), &shared_secret)?;
+            let max_clock_skew_seconds = i64::try_from(*max_clock_skew_seconds).map_err(|_| {
+                io::Error::new(
+                    ErrorKind::InvalidInput,
+                    "websocket auth clock skew must fit in a signed 64-bit integer",
+                )
+            })?;
+            Some(WebsocketAuthMode::SignedBearerToken {
+                shared_secret,
+                issuer: issuer.clone(),
+                audience: audience.clone(),
+                max_clock_skew_seconds,
+            })
+        }
+        None => None,
+    };
+
+    Ok(WebsocketAuthPolicy { mode })
+}
+
+pub(crate) fn is_unauthenticated_non_loopback_listener(
+    bind_address: SocketAddr,
+    policy: &WebsocketAuthPolicy,
+) -> bool {
+    !bind_address.ip().is_loopback() && policy.mode.is_none()
+}
+
+pub(crate) fn authorize_upgrade(
+    headers: &HeaderMap,
+    policy: &WebsocketAuthPolicy,
+) -> Result<(), WebsocketAuthError> {
+    let Some(mode) = policy.mode.as_ref() else {
+        return Ok(());
+    };
+
+    let token = bearer_token_from_headers(headers)?;
+    match mode {
+        WebsocketAuthMode::CapabilityToken { token_sha256 } => {
+            let actual_sha256 = sha256_digest(token.as_bytes());
+            if constant_time_eq_32(token_sha256, &actual_sha256) {
+                Ok(())
+            } else {
+                Err(unauthorized("invalid websocket bearer token"))
+            }
+        }
+        WebsocketAuthMode::SignedBearerToken {
+            shared_secret,
+            issuer,
+            audience,
+            max_clock_skew_seconds,
+        } => verify_signed_bearer_token(
+            token,
+            shared_secret,
+            issuer.as_deref(),
+            audience.as_deref(),
+            *max_clock_skew_seconds,
+        ),
+    }
+}
+
+fn verify_signed_bearer_token(
+    token: &str,
+    shared_secret: &[u8],
+    issuer: Option<&str>,
+    audience: Option<&str>,
+    max_clock_skew_seconds: i64,
+) -> Result<(), WebsocketAuthError> {
+    let claims = decode_jwt_claims(token, shared_secret)?;
+    validate_jwt_claims(&claims, issuer, audience, max_clock_skew_seconds)
+}
+
+fn decode_jwt_claims(token: &str, shared_secret: &[u8]) -> Result<JwtClaims, WebsocketAuthError> {
+    let mut validation = Validation::new(Algorithm::HS256);
+    validation.required_spec_claims.clear();
+    validation.validate_exp = false;
+    validation.validate_nbf = false;
+    validation.validate_aud = false;
+
+    decode::<JwtClaims>(token, &DecodingKey::from_secret(shared_secret), &validation)
+        .map(|token_data| token_data.claims)
+        .map_err(|_| unauthorized("invalid websocket jwt"))
+}
+
+fn validate_jwt_claims(
+    claims: &JwtClaims,
+    issuer: Option<&str>,
+    audience: Option<&str>,
+    max_clock_skew_seconds: i64,
+) -> Result<(), WebsocketAuthError> {
+    let now = OffsetDateTime::now_utc().unix_timestamp();
+    if now > claims.exp.saturating_add(max_clock_skew_seconds) {
+        return Err(unauthorized("expired websocket jwt"));
+    }
+    if let Some(nbf) = claims.nbf
+        && now < nbf.saturating_sub(max_clock_skew_seconds)
+    {
+        return Err(unauthorized("websocket jwt is not valid yet"));
+    }
+    if let Some(expected_issuer) = issuer
+        && claims.iss.as_deref() != Some(expected_issuer)
+    {
+        return Err(unauthorized("websocket jwt issuer mismatch"));
+    }
+    if let Some(expected_audience) = audience
+        && !audience_matches(claims.aud.as_ref(), expected_audience)
+    {
+        return Err(unauthorized("websocket jwt audience mismatch"));
+    }
+
+    Ok(())
+}
+
+fn audience_matches(audience: Option<&JwtAudienceClaim>, expected_audience: &str) -> bool {
+    match audience {
+        Some(JwtAudienceClaim::Single(actual)) => actual == expected_audience,
+        Some(JwtAudienceClaim::Multiple(actual)) => {
+            actual.iter().any(|audience| audience == expected_audience)
+        }
+        None => false,
+    }
+}
+
+fn bearer_token_from_headers(headers: &HeaderMap) -> Result<&str, WebsocketAuthError> {
+    let raw_header = headers
+        .get(AUTHORIZATION)
+        .ok_or_else(|| unauthorized("missing websocket bearer token"))?;
+    let header = raw_header
+        .to_str()
+        .map_err(|_| unauthorized(INVALID_AUTHORIZATION_HEADER_MESSAGE))?;
+    let Some((scheme, token)) = header.split_once(' ') else {
+        return Err(unauthorized(INVALID_AUTHORIZATION_HEADER_MESSAGE));
+    };
+    if !scheme.eq_ignore_ascii_case("Bearer") {
+        return Err(unauthorized(INVALID_AUTHORIZATION_HEADER_MESSAGE));
+    }
+    let token = token.trim();
+    if token.is_empty() {
+        return Err(unauthorized(INVALID_AUTHORIZATION_HEADER_MESSAGE));
+    }
+    Ok(token)
+}
+
+fn validate_signed_bearer_secret(path: &Path, shared_secret: &[u8]) -> io::Result<()> {
+    if shared_secret.len() < MIN_SIGNED_BEARER_SECRET_BYTES {
+        return Err(io::Error::new(
+            ErrorKind::InvalidInput,
+            format!(
+                "signed websocket bearer secret {} must be at least {MIN_SIGNED_BEARER_SECRET_BYTES} bytes",
+                path.display()
+            ),
+        ));
+    }
+    Ok(())
+}
+
+fn read_trimmed_secret(path: &std::path::Path) -> io::Result<String> {
+    let raw = std::fs::read_to_string(path).map_err(|err| {
+        io::Error::new(
+            err.kind(),
+            format!(
+                "failed to read websocket auth secret {}: {err}",
+                path.display()
+            ),
+        )
+    })?;
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return Err(io::Error::new(
+            ErrorKind::InvalidInput,
+            format!("websocket auth secret {} must not be empty", path.display()),
+        ));
+    }
+    Ok(trimmed.to_string())
+}
+
+fn absolute_path_arg(flag_name: &str, path: PathBuf) -> anyhow::Result<AbsolutePathBuf> {
+    AbsolutePathBuf::try_from(path).with_context(|| format!("{flag_name} must be an absolute path"))
+}
+
+fn sha256_digest_arg(flag_name: &str, value: &str) -> anyhow::Result<[u8; 32]> {
+    let trimmed = value.trim();
+    if trimmed.len() != 64 {
+        anyhow::bail!("{flag_name} must be a 64-character hex SHA-256 digest");
+    }
+
+    let mut digest = [0u8; 32];
+    for (index, pair) in trimmed.as_bytes().chunks_exact(2).enumerate() {
+        let high = hex_nibble(flag_name, pair[0])?;
+        let low = hex_nibble(flag_name, pair[1])?;
+        digest[index] = (high << 4) | low;
+    }
+    Ok(digest)
+}
+
+fn hex_nibble(flag_name: &str, byte: u8) -> anyhow::Result<u8> {
+    match byte {
+        b'0'..=b'9' => Ok(byte - b'0'),
+        b'a'..=b'f' => Ok(byte - b'a' + 10),
+        b'A'..=b'F' => Ok(byte - b'A' + 10),
+        _ => anyhow::bail!("{flag_name} must be a 64-character hex SHA-256 digest"),
+    }
+}
+
+fn sha256_digest(input: &[u8]) -> [u8; 32] {
+    let mut digest = [0u8; 32];
+    digest.copy_from_slice(&Sha256::digest(input));
+    digest
+}
+
+fn unauthorized(message: &'static str) -> WebsocketAuthError {
+    WebsocketAuthError {
+        status_code: StatusCode::UNAUTHORIZED,
+        message,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use axum::http::HeaderValue;
+    use base64::Engine;
+    use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+    use hmac::Hmac;
+    use hmac::Mac;
+    use serde_json::json;
+
+    type HmacSha256 = Hmac<Sha256>;
+
+    fn signed_token(shared_secret: &[u8], claims: serde_json::Value) -> String {
+        let header = URL_SAFE_NO_PAD.encode(br#"{"alg":"HS256","typ":"JWT"}"#);
+        let claims_segment = URL_SAFE_NO_PAD.encode(serde_json::to_vec(&claims).unwrap());
+        let payload = format!("{header}.{claims_segment}");
+        let mut mac = HmacSha256::new_from_slice(shared_secret).unwrap();
+        mac.update(payload.as_bytes());
+        let signature = URL_SAFE_NO_PAD.encode(mac.finalize().into_bytes());
+        format!("{payload}.{signature}")
+    }
+
+    #[test]
+    fn detects_unauthenticated_non_loopback_listener() {
+        let policy = WebsocketAuthPolicy::default();
+        assert!(is_unauthenticated_non_loopback_listener(
+            "0.0.0.0:8765".parse().unwrap(),
+            &policy,
+        ));
+        assert!(!is_unauthenticated_non_loopback_listener(
+            "127.0.0.1:8765".parse().unwrap(),
+            &policy,
+        ));
+        assert!(!is_unauthenticated_non_loopback_listener(
+            "0.0.0.0:8765".parse().unwrap(),
+            &WebsocketAuthPolicy {
+                mode: Some(WebsocketAuthMode::CapabilityToken {
+                    token_sha256: [0u8; 32],
+                }),
+            },
+        ));
+    }
+
+    #[test]
+    fn capability_token_args_require_token_file_or_hash() {
+        let err = AppServerWebsocketAuthArgs {
+            ws_auth: Some(WebsocketAuthCliMode::CapabilityToken),
+            ..Default::default()
+        }
+        .try_into_settings()
+        .expect_err("capability-token mode should require a token source");
+        assert!(
+            err.to_string().contains("--ws-token-file")
+                && err.to_string().contains("--ws-token-sha256"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn capability_token_args_accept_token_hash() {
+        let settings = AppServerWebsocketAuthArgs {
+            ws_auth: Some(WebsocketAuthCliMode::CapabilityToken),
+            ws_token_sha256: Some("ab".repeat(32)),
+            ..Default::default()
+        }
+        .try_into_settings()
+        .expect("capability-token hash args should parse");
+
+        assert_eq!(
+            settings,
+            AppServerWebsocketAuthSettings {
+                config: Some(AppServerWebsocketAuthConfig::CapabilityToken {
+                    source: AppServerWebsocketCapabilityTokenSource::TokenSha256 {
+                        token_sha256: [0xab; 32],
+                    },
+                }),
+            }
+        );
+    }
+
+    #[test]
+    fn capability_token_args_reject_multiple_token_sources() {
+        let err = AppServerWebsocketAuthArgs {
+            ws_auth: Some(WebsocketAuthCliMode::CapabilityToken),
+            ws_token_file: Some(PathBuf::from("/tmp/token")),
+            ws_token_sha256: Some("ab".repeat(32)),
+            ..Default::default()
+        }
+        .try_into_settings()
+        .expect_err("capability-token mode should reject multiple token sources");
+        assert!(
+            err.to_string().contains("mutually exclusive"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn capability_token_args_reject_malformed_token_hash() {
+        let err = AppServerWebsocketAuthArgs {
+            ws_auth: Some(WebsocketAuthCliMode::CapabilityToken),
+            ws_token_sha256: Some("not-a-sha256".to_string()),
+            ..Default::default()
+        }
+        .try_into_settings()
+        .expect_err("capability-token mode should reject malformed token hashes");
+        assert!(
+            err.to_string().contains("64-character hex"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn capability_token_hash_policy_authorizes_matching_bearer_token() {
+        let settings = AppServerWebsocketAuthSettings {
+            config: Some(AppServerWebsocketAuthConfig::CapabilityToken {
+                source: AppServerWebsocketCapabilityTokenSource::TokenSha256 {
+                    token_sha256: sha256_digest(b"super-secret-token"),
+                },
+            }),
+        };
+        let policy = policy_from_settings(&settings).expect("hash policy should build");
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            AUTHORIZATION,
+            HeaderValue::from_static("Bearer super-secret-token"),
+        );
+        authorize_upgrade(&headers, &policy).expect("matching token should authorize");
+
+        headers.insert(
+            AUTHORIZATION,
+            HeaderValue::from_static("Bearer wrong-token"),
+        );
+        let err = authorize_upgrade(&headers, &policy).expect_err("wrong token should fail");
+        assert_eq!(err.status_code(), StatusCode::UNAUTHORIZED);
+    }
+
+    #[test]
+    fn signed_bearer_args_require_mode_when_mode_specific_flags_are_set() {
+        let err = AppServerWebsocketAuthArgs {
+            ws_shared_secret_file: Some(PathBuf::from("/tmp/secret")),
+            ..Default::default()
+        }
+        .try_into_settings()
+        .expect_err("mode-specific flags should require --ws-auth");
+        assert!(
+            err.to_string().contains("websocket auth flags require"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn signed_bearer_args_default_clock_skew_and_trim_optional_claims() {
+        let settings = AppServerWebsocketAuthArgs {
+            ws_auth: Some(WebsocketAuthCliMode::SignedBearerToken),
+            ws_shared_secret_file: Some(PathBuf::from("/tmp/secret")),
+            ws_issuer: Some(" issuer ".to_string()),
+            ws_audience: Some("   ".to_string()),
+            ..Default::default()
+        }
+        .try_into_settings()
+        .expect("signed bearer args should parse");
+
+        assert_eq!(
+            settings,
+            AppServerWebsocketAuthSettings {
+                config: Some(AppServerWebsocketAuthConfig::SignedBearerToken {
+                    shared_secret_file: AbsolutePathBuf::from_absolute_path("/tmp/secret")
+                        .expect("absolute path"),
+                    issuer: Some("issuer".to_string()),
+                    audience: None,
+                    max_clock_skew_seconds: DEFAULT_MAX_CLOCK_SKEW_SECONDS,
+                }),
+            }
+        );
+    }
+
+    #[test]
+    fn signed_bearer_token_verification_rejects_tampering() {
+        let shared_secret = b"0123456789abcdef0123456789abcdef";
+        let token = signed_token(
+            shared_secret,
+            json!({
+                "exp": OffsetDateTime::now_utc().unix_timestamp() + 60,
+            }),
+        );
+        let tampered = token.replace(".eyJleHAi", ".eyJleHBi");
+        let err = verify_signed_bearer_token(
+            &tampered,
+            shared_secret,
+            /*issuer*/ None,
+            /*audience*/ None,
+            /*max_clock_skew_seconds*/ 30,
+        )
+        .expect_err("tampered jwt should fail");
+        assert_eq!(err.status_code(), StatusCode::UNAUTHORIZED);
+    }
+
+    #[test]
+    fn signed_bearer_token_verification_accepts_valid_token() {
+        let shared_secret = b"0123456789abcdef0123456789abcdef";
+        let token = signed_token(
+            shared_secret,
+            json!({
+                "exp": OffsetDateTime::now_utc().unix_timestamp() + 60,
+                "iss": "issuer",
+                "aud": "audience",
+            }),
+        );
+        verify_signed_bearer_token(
+            &token,
+            shared_secret,
+            Some("issuer"),
+            Some("audience"),
+            /*max_clock_skew_seconds*/ 30,
+        )
+        .expect("valid signed token should verify");
+    }
+
+    #[test]
+    fn signed_bearer_token_verification_accepts_multiple_audiences() {
+        let shared_secret = b"0123456789abcdef0123456789abcdef";
+        let token = signed_token(
+            shared_secret,
+            json!({
+                "exp": OffsetDateTime::now_utc().unix_timestamp() + 60,
+                "aud": ["other-audience", "audience"],
+            }),
+        );
+        verify_signed_bearer_token(
+            &token,
+            shared_secret,
+            /*issuer*/ None,
+            Some("audience"),
+            /*max_clock_skew_seconds*/ 30,
+        )
+        .expect("jwt audience arrays should verify");
+    }
+
+    #[test]
+    fn signed_bearer_token_verification_rejects_alg_none_tokens() {
+        let claims_segment = URL_SAFE_NO_PAD.encode(
+            serde_json::to_vec(&json!({
+                "exp": OffsetDateTime::now_utc().unix_timestamp() + 60,
+            }))
+            .unwrap(),
+        );
+        let header_segment = URL_SAFE_NO_PAD.encode(br#"{"alg":"none","typ":"JWT"}"#);
+        let token = format!("{header_segment}.{claims_segment}.");
+        let err = verify_signed_bearer_token(
+            &token,
+            b"0123456789abcdef0123456789abcdef",
+            /*issuer*/ None,
+            /*audience*/ None,
+            /*max_clock_skew_seconds*/ 30,
+        )
+        .expect_err("alg=none jwt should be rejected");
+        assert_eq!(err.status_code(), StatusCode::UNAUTHORIZED);
+    }
+
+    #[test]
+    fn signed_bearer_token_verification_rejects_missing_exp() {
+        let shared_secret = b"0123456789abcdef0123456789abcdef";
+        let token = signed_token(
+            shared_secret,
+            json!({
+                "iss": "issuer",
+            }),
+        );
+        let err = verify_signed_bearer_token(
+            &token,
+            shared_secret,
+            /*issuer*/ None,
+            /*audience*/ None,
+            /*max_clock_skew_seconds*/ 30,
+        )
+        .expect_err("jwt without exp should be rejected");
+        assert_eq!(err.status_code(), StatusCode::UNAUTHORIZED);
+    }
+
+    #[test]
+    fn validate_signed_bearer_secret_rejects_short_secret() {
+        let err = validate_signed_bearer_secret(Path::new("/tmp/secret"), b"too-short")
+            .expect_err("short shared secret should be rejected");
+        assert_eq!(err.kind(), ErrorKind::InvalidInput);
+        assert!(
+            err.to_string().contains("must be at least 32 bytes"),
+            "unexpected error: {err}"
+        );
+    }
+}

codex-rs/app-server-transport/src/transport/mod.rs

@@ -0,0 +1,602 @@
+pub mod auth;
+
+use crate::outgoing_message::ConnectionId;
+use crate::outgoing_message::OutgoingError;
+use crate::outgoing_message::OutgoingMessage;
+use crate::outgoing_message::QueuedOutgoingMessage;
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::RequestId;
+use codex_core::config::find_codex_home;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use std::net::SocketAddr;
+use std::path::Path;
+use std::path::PathBuf;
+use std::str::FromStr;
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+use tracing::error;
+use tracing::warn;
+
+/// Size of the bounded channels used to communicate between tasks. The value
+/// is a balance between throughput and memory usage - 128 messages should be
+/// plenty for an interactive CLI.
+pub const CHANNEL_CAPACITY: usize = 128;
+
+mod remote_control;
+mod stdio;
+mod unix_socket;
+#[cfg(test)]
+mod unix_socket_tests;
+mod websocket;
+
+pub use remote_control::REMOTE_CONTROL_DISABLED_ENV_VAR;
+pub use remote_control::RemoteControlDisabledByRequirements;
+pub use remote_control::RemoteControlEnableError;
+pub use remote_control::RemoteControlHandle;
+pub use remote_control::RemoteControlPolicy;
+pub use remote_control::RemoteControlStartConfig;
+pub use remote_control::RemoteControlStartupMode;
+pub use remote_control::RemoteControlUnavailable;
+pub use remote_control::start_remote_control;
+pub use remote_control::take_remote_control_disabled_env;
+pub use stdio::start_stdio_connection;
+pub use unix_socket::AppServerStartupLock;
+pub use unix_socket::DaemonShutdownAccess;
+pub use unix_socket::acquire_app_server_startup_lock;
+pub use unix_socket::prepare_control_socket_path;
+pub use unix_socket::start_control_socket_acceptor;
+pub use websocket::start_websocket_acceptor;
+
+const INTERNAL_ERROR_CODE: i64 = -32603;
+const OVERLOADED_ERROR_CODE: i64 = -32001;
+
+const APP_SERVER_CONTROL_SOCKET_DIR_NAME: &str = "app-server-control";
+const APP_SERVER_CONTROL_SOCKET_FILE_NAME: &str = "app-server-control.sock";
+const APP_SERVER_STARTUP_LOCK_FILE_NAME: &str = "app-server-startup.lock";
+const DAEMON_RECOVERY_FILE_NAME: &str = "loaded-threads.json";
+
+pub fn daemon_recovery_file_path(codex_home: &Path) -> PathBuf {
+    codex_home
+        .join("app-server-daemon")
+        .join(DAEMON_RECOVERY_FILE_NAME)
+}
+
+pub fn app_server_control_socket_path(codex_home: &Path) -> std::io::Result<AbsolutePathBuf> {
+    AbsolutePathBuf::from_absolute_path(
+        codex_home
+            .join(APP_SERVER_CONTROL_SOCKET_DIR_NAME)
+            .join(APP_SERVER_CONTROL_SOCKET_FILE_NAME),
+    )
+}
+
+pub fn app_server_startup_lock_path(codex_home: &Path) -> std::io::Result<AbsolutePathBuf> {
+    AbsolutePathBuf::from_absolute_path(
+        codex_home
+            .join(APP_SERVER_CONTROL_SOCKET_DIR_NAME)
+            .join(APP_SERVER_STARTUP_LOCK_FILE_NAME),
+    )
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum AppServerTransport {
+    Stdio,
+    UnixSocket { socket_path: AbsolutePathBuf },
+    WebSocket { bind_address: SocketAddr },
+    Off,
+}
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub enum AppServerTransportParseError {
+    UnsupportedListenUrl(String),
+    InvalidUnixSocketPath { listen_url: String, message: String },
+    InvalidWebSocketListenUrl(String),
+}
+
+impl std::fmt::Display for AppServerTransportParseError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            AppServerTransportParseError::UnsupportedListenUrl(listen_url) => write!(
+                f,
+                "unsupported --listen URL `{listen_url}`; expected `stdio://`, `unix://`, `unix://PATH`, `ws://IP:PORT`, or `off`"
+            ),
+            AppServerTransportParseError::InvalidUnixSocketPath {
+                listen_url,
+                message,
+            } => write!(
+                f,
+                "invalid unix socket --listen URL `{listen_url}`; failed to resolve socket path: {message}"
+            ),
+            AppServerTransportParseError::InvalidWebSocketListenUrl(listen_url) => write!(
+                f,
+                "invalid websocket --listen URL `{listen_url}`; expected `ws://IP:PORT`"
+            ),
+        }
+    }
+}
+
+impl std::error::Error for AppServerTransportParseError {}
+
+impl AppServerTransport {
+    pub const DEFAULT_LISTEN_URL: &'static str = "stdio://";
+
+    pub fn from_listen_url(listen_url: &str) -> Result<Self, AppServerTransportParseError> {
+        if listen_url == Self::DEFAULT_LISTEN_URL {
+            return Ok(Self::Stdio);
+        }
+
+        if let Some(raw_socket_path) = listen_url.strip_prefix("unix://") {
+            let socket_path = if raw_socket_path.is_empty() {
+                let codex_home = find_codex_home().map_err(|err| {
+                    AppServerTransportParseError::InvalidUnixSocketPath {
+                        listen_url: listen_url.to_string(),
+                        message: format!("failed to resolve CODEX_HOME: {err}"),
+                    }
+                })?;
+                app_server_control_socket_path(&codex_home).map_err(|err| {
+                    AppServerTransportParseError::InvalidUnixSocketPath {
+                        listen_url: listen_url.to_string(),
+                        message: err.to_string(),
+                    }
+                })?
+            } else {
+                AbsolutePathBuf::relative_to_current_dir(raw_socket_path).map_err(|err| {
+                    AppServerTransportParseError::InvalidUnixSocketPath {
+                        listen_url: listen_url.to_string(),
+                        message: err.to_string(),
+                    }
+                })?
+            };
+            return Ok(Self::UnixSocket { socket_path });
+        }
+
+        if listen_url == "off" {
+            return Ok(Self::Off);
+        }
+
+        if let Some(socket_addr) = listen_url.strip_prefix("ws://") {
+            let bind_address = socket_addr.parse::<SocketAddr>().map_err(|_| {
+                AppServerTransportParseError::InvalidWebSocketListenUrl(listen_url.to_string())
+            })?;
+            return Ok(Self::WebSocket { bind_address });
+        }
+
+        Err(AppServerTransportParseError::UnsupportedListenUrl(
+            listen_url.to_string(),
+        ))
+    }
+}
+
+impl FromStr for AppServerTransport {
+    type Err = AppServerTransportParseError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Self::from_listen_url(s)
+    }
+}
+
+#[derive(Debug)]
+pub enum TransportEvent {
+    /// Accepted on the managed local control socket, outside JSON-RPC.
+    DaemonShutdown,
+    ConnectionOpened {
+        connection_id: ConnectionId,
+        origin: ConnectionOrigin,
+        auth: Option<crate::ConnectionAuth>,
+        writer: mpsc::Sender<QueuedOutgoingMessage>,
+        disconnect_sender: Option<CancellationToken>,
+    },
+    ConnectionClosed {
+        connection_id: ConnectionId,
+    },
+    IncomingMessage {
+        connection_id: ConnectionId,
+        message: JSONRPCMessage,
+    },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConnectionOrigin {
+    Stdio,
+    InProcess,
+    WebSocket,
+    RemoteControl,
+}
+
+static CONNECTION_ID_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+fn next_connection_id() -> ConnectionId {
+    ConnectionId(CONNECTION_ID_COUNTER.fetch_add(1, Ordering::Relaxed))
+}
+
+async fn forward_incoming_message(
+    transport_event_tx: &mpsc::Sender<TransportEvent>,
+    writer: &mpsc::Sender<QueuedOutgoingMessage>,
+    connection_id: ConnectionId,
+    payload: &str,
+) -> bool {
+    match serde_json::from_str::<JSONRPCMessage>(payload) {
+        Ok(message) => {
+            enqueue_incoming_message(transport_event_tx, writer, connection_id, message).await
+        }
+        Err(err) => {
+            error!("Failed to deserialize JSONRPCMessage: {err}");
+            true
+        }
+    }
+}
+
+async fn enqueue_incoming_message(
+    transport_event_tx: &mpsc::Sender<TransportEvent>,
+    writer: &mpsc::Sender<QueuedOutgoingMessage>,
+    connection_id: ConnectionId,
+    message: JSONRPCMessage,
+) -> bool {
+    let event = TransportEvent::IncomingMessage {
+        connection_id,
+        message,
+    };
+    match transport_event_tx.try_send(event) {
+        Ok(()) => true,
+        Err(mpsc::error::TrySendError::Closed(_)) => false,
+        Err(mpsc::error::TrySendError::Full(TransportEvent::IncomingMessage {
+            connection_id,
+            message: JSONRPCMessage::Request(request),
+        })) => {
+            let overload_error = OutgoingMessage::Error(OutgoingError {
+                id: request.id,
+                error: JSONRPCErrorError {
+                    code: OVERLOADED_ERROR_CODE,
+                    message: "Server overloaded; retry later.".to_string(),
+                    data: None,
+                },
+            });
+            match writer.try_send(QueuedOutgoingMessage::new(overload_error)) {
+                Ok(()) => true,
+                Err(mpsc::error::TrySendError::Closed(_)) => false,
+                Err(mpsc::error::TrySendError::Full(_overload_error)) => {
+                    warn!(
+                        "dropping overload response for connection {:?}: outbound queue is full",
+                        connection_id
+                    );
+                    true
+                }
+            }
+        }
+        Err(mpsc::error::TrySendError::Full(event)) => transport_event_tx.send(event).await.is_ok(),
+    }
+}
+
+fn serialize_outgoing_message(outgoing_message: OutgoingMessage) -> Option<String> {
+    match serde_json::to_string(&outgoing_message) {
+        Ok(json) => Some(json),
+        Err(err) => {
+            error!("Failed to serialize JSONRPCMessage: {err}");
+            let OutgoingMessage::Response(response) = outgoing_message else {
+                return None;
+            };
+            serde_json::to_string(&response_serialization_error(response.id, err))
+                .inspect_err(|err| error!("Failed to serialize JSONRPC error: {err}"))
+                .ok()
+        }
+    }
+}
+
+fn response_serialization_error(
+    request_id: RequestId,
+    err: impl std::fmt::Display,
+) -> OutgoingMessage {
+    OutgoingMessage::Error(OutgoingError {
+        id: request_id,
+        error: JSONRPCErrorError {
+            code: INTERNAL_ERROR_CODE,
+            message: format!("failed to serialize response: {err}"),
+            data: None,
+        },
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::outgoing_message::OutgoingResponse;
+    use codex_app_server_protocol::ClientResponsePayload;
+    use codex_app_server_protocol::ConfigWarningNotification;
+    use codex_app_server_protocol::JSONRPCNotification;
+    use codex_app_server_protocol::JSONRPCRequest;
+    use codex_app_server_protocol::JSONRPCResponse;
+    use codex_app_server_protocol::RequestId;
+    use codex_app_server_protocol::ServerNotification;
+    use codex_app_server_protocol::ServerNotificationEnvelope;
+    use codex_app_server_protocol::ThreadArchiveResponse;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+    use tokio::time::Duration;
+    use tokio::time::timeout;
+
+    #[test]
+    fn listen_off_parses_as_off_transport() {
+        assert_eq!(
+            AppServerTransport::from_listen_url("off"),
+            Ok(AppServerTransport::Off)
+        );
+    }
+
+    #[test]
+    fn serialize_outgoing_message_preserves_wire_shape() {
+        let message = OutgoingMessage::AppServerNotification(ServerNotificationEnvelope {
+            notification: ServerNotification::ConfigWarning(ConfigWarningNotification {
+                summary: "summary".to_string(),
+                details: None,
+                path: None,
+                range: None,
+            }),
+            emitted_at_ms: Some(1_234),
+        });
+
+        let json = serialize_outgoing_message(message).expect("message should serialize");
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&json).expect("message should be valid JSON"),
+            json!({
+                "method": "configWarning",
+                "params": {
+                    "summary": "summary",
+                    "details": null,
+                },
+                "emittedAtMs": 1_234,
+            })
+        );
+    }
+
+    #[test]
+    fn serialize_typed_response_preserves_wire_shape() {
+        let message = OutgoingMessage::Response(OutgoingResponse {
+            id: RequestId::Integer(7),
+            result: Box::new(ClientResponsePayload::ThreadArchive(
+                ThreadArchiveResponse {},
+            )),
+        });
+
+        let json = serialize_outgoing_message(message).expect("message should serialize");
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&json).expect("message should be valid JSON"),
+            json!({ "id": 7, "result": {} })
+        );
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn serialize_invalid_typed_response_returns_jsonrpc_error() {
+        use std::ffi::OsString;
+        use std::os::unix::ffi::OsStringExt;
+        use std::path::PathBuf;
+
+        let codex_home =
+            AbsolutePathBuf::from_absolute_path(PathBuf::from(OsString::from_vec(vec![
+                b'/', b'b', b'a', b'd', 0xff,
+            ])))
+            .expect("non-UTF-8 Unix paths are valid absolute paths");
+        let message = OutgoingMessage::Response(OutgoingResponse {
+            id: RequestId::Integer(7),
+            result: Box::new(ClientResponsePayload::Initialize(
+                codex_app_server_protocol::InitializeResponse {
+                    user_agent: "codex-test-agent".to_string(),
+                    codex_home,
+                    platform_family: "unix".to_string(),
+                    platform_os: "linux".to_string(),
+                },
+            )),
+        });
+
+        let json = serialize_outgoing_message(message)
+            .expect("invalid response should serialize as a JSON-RPC error");
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&json).expect("message should be valid JSON"),
+            json!({
+                "id": 7,
+                "error": {
+                    "code": -32603,
+                    "message": "failed to serialize response: path contains invalid UTF-8 characters",
+                }
+            })
+        );
+    }
+
+    #[tokio::test]
+    async fn enqueue_incoming_request_returns_overload_error_when_queue_is_full() {
+        let connection_id = ConnectionId(42);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(1);
+        let (writer_tx, mut writer_rx) = mpsc::channel(1);
+
+        let first_message = JSONRPCMessage::Notification(JSONRPCNotification {
+            method: "initialized".to_string(),
+            params: None,
+        });
+        transport_event_tx
+            .send(TransportEvent::IncomingMessage {
+                connection_id,
+                message: first_message.clone(),
+            })
+            .await
+            .expect("queue should accept first message");
+
+        let request = JSONRPCMessage::Request(JSONRPCRequest {
+            id: RequestId::Integer(7),
+            method: "config/read".to_string(),
+            params: Some(json!({ "includeLayers": false })),
+            trace: None,
+        });
+        assert!(
+            enqueue_incoming_message(&transport_event_tx, &writer_tx, connection_id, request).await
+        );
+
+        let queued_event = transport_event_rx
+            .recv()
+            .await
+            .expect("first event should stay queued");
+        match queued_event {
+            TransportEvent::IncomingMessage {
+                connection_id: queued_connection_id,
+                message,
+            } => {
+                assert_eq!(queued_connection_id, connection_id);
+                assert_eq!(message, first_message);
+            }
+            _ => panic!("expected queued incoming message"),
+        }
+
+        let overload = writer_rx
+            .recv()
+            .await
+            .expect("request should receive overload error");
+        let overload_json =
+            serde_json::to_value(overload.message).expect("serialize overload error");
+        assert_eq!(
+            overload_json,
+            json!({
+                "id": 7,
+                "error": {
+                    "code": OVERLOADED_ERROR_CODE,
+                    "message": "Server overloaded; retry later."
+                }
+            })
+        );
+    }
+
+    #[tokio::test]
+    async fn enqueue_incoming_response_waits_instead_of_dropping_when_queue_is_full() {
+        let connection_id = ConnectionId(42);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(1);
+        let (writer_tx, _writer_rx) = mpsc::channel(1);
+
+        let first_message = JSONRPCMessage::Notification(JSONRPCNotification {
+            method: "initialized".to_string(),
+            params: None,
+        });
+        transport_event_tx
+            .send(TransportEvent::IncomingMessage {
+                connection_id,
+                message: first_message.clone(),
+            })
+            .await
+            .expect("queue should accept first message");
+
+        let response = JSONRPCMessage::Response(JSONRPCResponse {
+            id: RequestId::Integer(7),
+            result: json!({"ok": true}),
+        });
+        let transport_event_tx_for_enqueue = transport_event_tx.clone();
+        let writer_tx_for_enqueue = writer_tx.clone();
+        let enqueue_handle = tokio::spawn(async move {
+            enqueue_incoming_message(
+                &transport_event_tx_for_enqueue,
+                &writer_tx_for_enqueue,
+                connection_id,
+                response,
+            )
+            .await
+        });
+
+        let queued_event = transport_event_rx
+            .recv()
+            .await
+            .expect("first event should be dequeued");
+        match queued_event {
+            TransportEvent::IncomingMessage {
+                connection_id: queued_connection_id,
+                message,
+            } => {
+                assert_eq!(queued_connection_id, connection_id);
+                assert_eq!(message, first_message);
+            }
+            _ => panic!("expected queued incoming message"),
+        }
+
+        let enqueue_result = enqueue_handle.await.expect("enqueue task should not panic");
+        assert!(enqueue_result);
+
+        let forwarded_event = transport_event_rx
+            .recv()
+            .await
+            .expect("response should be forwarded instead of dropped");
+        match forwarded_event {
+            TransportEvent::IncomingMessage {
+                connection_id: queued_connection_id,
+                message: JSONRPCMessage::Response(JSONRPCResponse { id, result }),
+            } => {
+                assert_eq!(queued_connection_id, connection_id);
+                assert_eq!(id, RequestId::Integer(7));
+                assert_eq!(result, json!({"ok": true}));
+            }
+            _ => panic!("expected forwarded response message"),
+        }
+    }
+
+    #[tokio::test]
+    async fn enqueue_incoming_request_does_not_block_when_writer_queue_is_full() {
+        let connection_id = ConnectionId(42);
+        let (transport_event_tx, _transport_event_rx) = mpsc::channel(1);
+        let (writer_tx, mut writer_rx) = mpsc::channel(1);
+
+        transport_event_tx
+            .send(TransportEvent::IncomingMessage {
+                connection_id,
+                message: JSONRPCMessage::Notification(JSONRPCNotification {
+                    method: "initialized".to_string(),
+                    params: None,
+                }),
+            })
+            .await
+            .expect("transport queue should accept first message");
+
+        writer_tx
+            .send(QueuedOutgoingMessage::new(
+                OutgoingMessage::AppServerNotification(ServerNotificationEnvelope {
+                    notification: ServerNotification::ConfigWarning(ConfigWarningNotification {
+                        summary: "queued".to_string(),
+                        details: None,
+                        path: None,
+                        range: None,
+                    }),
+                    emitted_at_ms: Some(1_234),
+                }),
+            ))
+            .await
+            .expect("writer queue should accept first message");
+
+        let request = JSONRPCMessage::Request(JSONRPCRequest {
+            id: RequestId::Integer(7),
+            method: "config/read".to_string(),
+            params: Some(json!({ "includeLayers": false })),
+            trace: None,
+        });
+
+        let enqueue_result = timeout(
+            Duration::from_millis(100),
+            enqueue_incoming_message(&transport_event_tx, &writer_tx, connection_id, request),
+        )
+        .await
+        .expect("enqueue should not block while writer queue is full");
+        assert!(enqueue_result);
+
+        let queued_outgoing = writer_rx
+            .recv()
+            .await
+            .expect("writer queue should still contain original message");
+        let queued_json =
+            serde_json::to_value(queued_outgoing.message).expect("serialize queued message");
+        assert_eq!(
+            queued_json,
+            json!({
+                "method": "configWarning",
+                "params": {
+                    "summary": "queued",
+                    "details": null,
+                },
+                "emittedAtMs": 1_234,
+            })
+        );
+    }
+}

codex-rs/app-server-transport/src/transport/remote_control/auth.rs

@@ -0,0 +1,282 @@
+//! Credentials and recovery bound to one remote-control login lifetime.
+//! A request can refresh credentials, but cannot adopt a replacement authentication owner.
+
+use axum::http::HeaderMap;
+use axum::http::HeaderValue;
+use codex_api::SharedAuthProvider;
+use codex_login::AuthManager;
+use codex_login::UnauthorizedRecovery;
+use std::io;
+use std::io::ErrorKind;
+use std::sync::Arc;
+use tokio::sync::watch;
+use tracing::info;
+use tracing::warn;
+
+#[derive(Clone)]
+pub(super) struct RemoteControlAuth {
+    manager: Arc<AuthManager>,
+    pub(super) owner: crate::ConnectionAuth,
+}
+
+pub(super) struct RemoteControlRecovery {
+    auth: RemoteControlAuth,
+    recovery: UnauthorizedRecovery,
+}
+
+impl RemoteControlAuth {
+    pub(super) fn capture(manager: Arc<AuthManager>) -> (Self, bool) {
+        loop {
+            let owner = crate::ConnectionAuth::capture(&manager);
+            let authenticated = manager
+                .auth_cached()
+                .is_some_and(|auth| auth.uses_codex_backend() && auth.get_account_id().is_some());
+            if owner.is_current() {
+                return (Self { manager, owner }, authenticated);
+            }
+        }
+    }
+
+    pub(super) fn ensure_current(&self) -> io::Result<()> {
+        self.owner.ensure_current()
+    }
+
+    pub(super) fn unauthorized_recovery(&self) -> RemoteControlRecovery {
+        RemoteControlRecovery {
+            auth: self.clone(),
+            recovery: self.manager.unauthorized_recovery(),
+        }
+    }
+
+    pub(super) fn auth_change_receiver(&self) -> watch::Receiver<u64> {
+        self.manager.auth_change_receiver()
+    }
+}
+
+pub(super) const REMOTE_CONTROL_ACCOUNT_ID_HEADER: &str = "chatgpt-account-id";
+
+pub(super) struct RemoteControlConnectionAuth {
+    pub(super) auth_provider: SharedAuthProvider,
+    pub(super) account_id: String,
+}
+
+impl RemoteControlConnectionAuth {
+    pub(super) fn request_headers(&self) -> io::Result<HeaderMap> {
+        let mut headers = HeaderMap::new();
+        self.auth_provider.add_auth_headers(&mut headers);
+        headers.insert(
+            REMOTE_CONTROL_ACCOUNT_ID_HEADER,
+            HeaderValue::from_str(&self.account_id).map_err(|err| {
+                io::Error::new(
+                    ErrorKind::InvalidInput,
+                    format!("invalid remote control account id header: {err}"),
+                )
+            })?,
+        );
+        Ok(headers)
+    }
+}
+
+pub(super) async fn load_remote_control_auth(
+    auth: &RemoteControlAuth,
+) -> io::Result<RemoteControlConnectionAuth> {
+    auth.ensure_current()?;
+    let credentials = load_auth_manager(&auth.manager).await?;
+    auth.ensure_current()?;
+    Ok(credentials)
+}
+
+async fn load_auth_manager(
+    auth_manager: &Arc<AuthManager>,
+) -> io::Result<RemoteControlConnectionAuth> {
+    let mut reloaded = false;
+    let auth = loop {
+        let Some(auth) = auth_manager.auth().await else {
+            if reloaded {
+                return Err(io::Error::new(
+                    ErrorKind::PermissionDenied,
+                    "remote control requires ChatGPT authentication",
+                ));
+            }
+            auth_manager.reload().await;
+            reloaded = true;
+            continue;
+        };
+        if !auth.uses_codex_backend() {
+            break auth;
+        }
+        if auth.get_account_id().is_none() && !reloaded {
+            auth_manager.reload().await;
+            reloaded = true;
+            continue;
+        }
+        break auth;
+    };
+
+    if !auth.uses_codex_backend() {
+        return Err(io::Error::new(
+            ErrorKind::PermissionDenied,
+            "remote control requires ChatGPT authentication; API key auth is not supported",
+        ));
+    }
+
+    Ok(RemoteControlConnectionAuth {
+        auth_provider: codex_model_provider::auth_provider_from_auth(&auth),
+        account_id: auth.get_account_id().ok_or_else(|| {
+            io::Error::new(
+                ErrorKind::WouldBlock,
+                "remote control enrollment is waiting for a ChatGPT account id",
+            )
+        })?,
+    })
+}
+
+pub(super) async fn recover_remote_control_auth(
+    recovery: &mut RemoteControlRecovery,
+    auth_change_rx: &mut watch::Receiver<u64>,
+) -> bool {
+    if recovery.auth.ensure_current().is_err() {
+        return false;
+    }
+    let auth_recovery = &mut recovery.recovery;
+    if !auth_recovery.has_next() {
+        return false;
+    }
+
+    let mode = auth_recovery.mode_name();
+    let step = auth_recovery.step_name();
+    let auth_change_revision_before_recovery = *auth_change_rx.borrow();
+    match auth_recovery.next().await {
+        Ok(step_result) => {
+            if recovery.auth.ensure_current().is_err() {
+                return false;
+            }
+            if step_result.auth_state_changed() == Some(true) {
+                mark_recovery_auth_change_seen(
+                    auth_change_rx,
+                    auth_change_revision_before_recovery,
+                );
+            }
+            info!(
+                "remote control auth recovery succeeded: mode={mode}, step={step}, auth_state_changed={:?}",
+                step_result.auth_state_changed()
+            );
+            true
+        }
+        Err(err) => {
+            warn!("remote control auth recovery failed: mode={mode}, step={step}: {err}");
+            false
+        }
+    }
+}
+
+pub(super) fn mark_recovery_auth_change_seen(
+    auth_change_rx: &mut watch::Receiver<u64>,
+    auth_change_revision_before_recovery: u64,
+) {
+    let auth_change_revision_after_recovery = *auth_change_rx.borrow();
+    if auth_change_revision_after_recovery == auth_change_revision_before_recovery.wrapping_add(1) {
+        // Recovery updated the same watch that wakes the outer reconnect
+        // loop. Mark only that single revision seen; if more revisions
+        // arrived while recovery was in flight, leave them pending so the
+        // reconnect loop still reacts to the later external auth change.
+        auth_change_rx.borrow_and_update();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use codex_api::AuthProvider;
+    use pretty_assertions::assert_eq;
+
+    #[derive(Debug)]
+    struct TestAuthProvider {
+        account_ids: Vec<&'static str>,
+    }
+
+    impl AuthProvider for TestAuthProvider {
+        fn add_auth_headers(&self, headers: &mut HeaderMap) {
+            headers.insert(
+                axum::http::header::AUTHORIZATION,
+                HeaderValue::from_static("Bearer test-token"),
+            );
+            headers.insert("x-openai-fedramp", HeaderValue::from_static("true"));
+            for account_id in &self.account_ids {
+                headers.append("ChatGPT-Account-ID", HeaderValue::from_static(account_id));
+            }
+        }
+    }
+
+    fn remote_control_auth(
+        account_id: &str,
+        provider_account_ids: Vec<&'static str>,
+    ) -> RemoteControlConnectionAuth {
+        RemoteControlConnectionAuth {
+            auth_provider: Arc::new(TestAuthProvider {
+                account_ids: provider_account_ids,
+            }),
+            account_id: account_id.to_string(),
+        }
+    }
+
+    #[test]
+    fn request_headers_adds_account_header_when_provider_omits_it() {
+        let headers = remote_control_auth("selected-account", Vec::new())
+            .request_headers()
+            .expect("request headers should build");
+
+        assert_eq!(
+            headers
+                .get_all(REMOTE_CONTROL_ACCOUNT_ID_HEADER)
+                .iter()
+                .map(|value| value.to_str().expect("account header should be text"))
+                .collect::<Vec<_>>(),
+            vec!["selected-account"]
+        );
+    }
+
+    #[test]
+    fn request_headers_replaces_provider_accounts_and_preserves_other_headers() {
+        let headers = remote_control_auth(
+            "selected-account",
+            vec!["provider-account-a", "provider-account-b"],
+        )
+        .request_headers()
+        .expect("request headers should build");
+
+        assert_eq!(
+            headers
+                .get_all(REMOTE_CONTROL_ACCOUNT_ID_HEADER)
+                .iter()
+                .map(|value| value.to_str().expect("account header should be text"))
+                .collect::<Vec<_>>(),
+            vec!["selected-account"]
+        );
+        assert_eq!(
+            headers
+                .get(axum::http::header::AUTHORIZATION)
+                .and_then(|value| value.to_str().ok()),
+            Some("Bearer test-token")
+        );
+        assert_eq!(
+            headers
+                .get("x-openai-fedramp")
+                .and_then(|value| value.to_str().ok()),
+            Some("true")
+        );
+    }
+
+    #[test]
+    fn request_headers_rejects_invalid_account_header_value() {
+        let err = remote_control_auth("invalid\naccount", Vec::new())
+            .request_headers()
+            .expect_err("invalid account header should fail");
+
+        assert_eq!(err.kind(), ErrorKind::InvalidInput);
+        assert!(
+            err.to_string()
+                .starts_with("invalid remote control account id header:")
+        );
+    }
+}

codex-rs/app-server-transport/src/transport/remote_control/client_tracker.rs

@@ -0,0 +1,944 @@
+use super::CHANNEL_CAPACITY;
+use super::TransportEvent;
+use super::next_connection_id;
+use super::protocol::ClientEnvelope;
+pub use super::protocol::ClientEvent;
+pub use super::protocol::ClientId;
+use super::protocol::PongStatus;
+use super::protocol::ServerEvent;
+use super::protocol::StreamId;
+use crate::outgoing_message::ConnectionId;
+use crate::outgoing_message::QueuedOutgoingMessage;
+use crate::transport::ConnectionOrigin;
+use crate::transport::remote_control::QueuedServerEnvelope;
+use codex_app_server_protocol::JSONRPCMessage;
+use std::collections::HashMap;
+use tokio::sync::mpsc;
+use tokio::sync::watch;
+use tokio::task::JoinHandle;
+use tokio::task::JoinSet;
+use tokio::time::Duration;
+use tokio::time::Instant;
+use tokio::time::timeout;
+use tokio_util::sync::CancellationToken;
+use tracing::info;
+use tracing::warn;
+
+const REMOTE_CONTROL_CLIENT_IDLE_TIMEOUT: Duration = Duration::from_secs(10 * 60);
+pub(crate) const REMOTE_CONTROL_IDLE_SWEEP_INTERVAL: Duration = Duration::from_secs(30);
+#[cfg(not(test))]
+const REMOTE_CONTROL_TRANSPORT_EVENT_SEND_TIMEOUT: Duration = Duration::from_secs(5);
+#[cfg(test)]
+const REMOTE_CONTROL_TRANSPORT_EVENT_SEND_TIMEOUT: Duration = Duration::from_millis(10);
+
+#[derive(Debug)]
+pub(crate) struct Stopped;
+
+struct ClientState {
+    connection_id: ConnectionId,
+    disconnect_token: CancellationToken,
+    last_activity_at: Instant,
+    last_inbound_seq_id: Option<u64>,
+    status_tx: watch::Sender<PongStatus>,
+}
+
+pub(crate) struct ClientTracker {
+    pub(super) auth: Option<crate::ConnectionAuth>,
+    clients: HashMap<(ClientId, StreamId), ClientState>,
+    legacy_stream_ids: HashMap<ClientId, StreamId>,
+    join_set: JoinSet<(ClientId, StreamId)>,
+    server_event_tx: mpsc::Sender<QueuedServerEnvelope>,
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+    shutdown_token: CancellationToken,
+}
+
+impl ClientTracker {
+    pub(crate) fn new(
+        server_event_tx: mpsc::Sender<QueuedServerEnvelope>,
+        transport_event_tx: mpsc::Sender<TransportEvent>,
+        shutdown_token: &CancellationToken,
+    ) -> Self {
+        Self {
+            auth: None,
+            clients: HashMap::new(),
+            legacy_stream_ids: HashMap::new(),
+            join_set: JoinSet::new(),
+            server_event_tx,
+            transport_event_tx,
+            shutdown_token: shutdown_token.child_token(),
+        }
+    }
+
+    pub(crate) async fn bookkeep_join_set(&mut self) -> Option<(ClientId, StreamId)> {
+        while let Some(join_result) = self.join_set.join_next().await {
+            let Ok(client_key) = join_result else {
+                continue;
+            };
+            return Some(client_key);
+        }
+        futures::future::pending().await
+    }
+
+    pub(crate) async fn shutdown(&mut self) {
+        self.shutdown_token.cancel();
+
+        while let Some(client_key) = self.clients.keys().next().cloned() {
+            let _ = self.close_client(&client_key).await;
+        }
+
+        self.drain_join_set().await;
+    }
+
+    async fn drain_join_set(&mut self) {
+        while self.join_set.join_next().await.is_some() {}
+    }
+
+    pub(crate) async fn handle_message(
+        &mut self,
+        client_envelope: ClientEnvelope,
+    ) -> Result<(), Stopped> {
+        let ClientEnvelope {
+            client_id,
+            event,
+            stream_id,
+            seq_id,
+            cursor: _,
+        } = client_envelope;
+        let is_legacy_stream_id = stream_id.is_none();
+        let is_initialize = matches!(&event, ClientEvent::ClientMessage { message } if remote_control_message_starts_connection(message));
+        let stream_id = match stream_id {
+            Some(stream_id) => stream_id,
+            None if is_initialize => {
+                // TODO(ruslan): delete this fallback once all clients are updated to send stream_id.
+                self.legacy_stream_ids
+                    .remove(&client_id)
+                    .unwrap_or_else(StreamId::new_random)
+            }
+            None => self
+                .legacy_stream_ids
+                .get(&client_id)
+                .cloned()
+                .unwrap_or_else(|| {
+                    if matches!(&event, ClientEvent::Ping) {
+                        StreamId::new_random()
+                    } else {
+                        StreamId(String::new())
+                    }
+                }),
+        };
+        if stream_id.0.is_empty() {
+            return Ok(());
+        }
+        let client_key = (client_id.clone(), stream_id.clone());
+        match event {
+            ClientEvent::ClientMessage { message } => {
+                if let Some(seq_id) = seq_id
+                    && let Some(client) = self.clients.get(&client_key)
+                    && client
+                        .last_inbound_seq_id
+                        .is_some_and(|last_seq_id| last_seq_id >= seq_id)
+                    && !is_initialize
+                {
+                    return Ok(());
+                }
+
+                if is_initialize && self.clients.contains_key(&client_key) {
+                    self.close_client(&client_key).await?;
+                }
+
+                if let Some(connection_id) = self.clients.get_mut(&client_key).map(|client| {
+                    client.last_activity_at = Instant::now();
+                    client.connection_id
+                }) {
+                    self.send_transport_event(TransportEvent::IncomingMessage {
+                        connection_id,
+                        message,
+                    })
+                    .await?;
+                    self.record_inbound_message_delivery(&client_key, seq_id);
+                    return Ok(());
+                }
+
+                if !is_initialize {
+                    return Ok(());
+                }
+
+                let connection_id = next_connection_id();
+                let (writer_tx, writer_rx) =
+                    mpsc::channel::<QueuedOutgoingMessage>(CHANNEL_CAPACITY);
+                let disconnect_token = self.shutdown_token.child_token();
+                self.send_transport_event(TransportEvent::ConnectionOpened {
+                    connection_id,
+                    origin: ConnectionOrigin::RemoteControl,
+                    auth: self.auth.clone(),
+                    writer: writer_tx,
+                    disconnect_sender: Some(disconnect_token.clone()),
+                })
+                .await?;
+
+                let (status_tx, status_rx) = watch::channel(PongStatus::Active);
+                self.join_set.spawn(Self::run_client_outbound(
+                    client_id.clone(),
+                    stream_id.clone(),
+                    self.server_event_tx.clone(),
+                    writer_rx,
+                    status_rx,
+                    disconnect_token.clone(),
+                ));
+                self.clients.insert(
+                    client_key.clone(),
+                    ClientState {
+                        connection_id,
+                        disconnect_token,
+                        last_activity_at: Instant::now(),
+                        last_inbound_seq_id: None,
+                        status_tx,
+                    },
+                );
+                if is_legacy_stream_id {
+                    self.legacy_stream_ids.insert(client_id.clone(), stream_id);
+                }
+                if let Err(err) = self
+                    .send_transport_event(TransportEvent::IncomingMessage {
+                        connection_id,
+                        message,
+                    })
+                    .await
+                {
+                    if let Some(client) = self.remove_client(&client_key) {
+                        client.disconnect_token.cancel();
+                        // The initialize send already timed out on this queue; preserve close
+                        // delivery without blocking reconnect on the same backpressure.
+                        drop(self.spawn_connection_closed(client.connection_id));
+                    }
+                    return Err(err);
+                }
+                if !is_legacy_stream_id {
+                    self.record_inbound_message_delivery(&client_key, seq_id);
+                }
+                Ok(())
+            }
+            ClientEvent::ClientMessageChunk { .. } | ClientEvent::Ack { .. } => Ok(()),
+            ClientEvent::Ping => {
+                if let Some(client) = self.clients.get_mut(&client_key) {
+                    client.last_activity_at = Instant::now();
+                    let _ = client.status_tx.send(PongStatus::Active);
+                    return Ok(());
+                }
+
+                let server_event_tx = self.server_event_tx.clone();
+                tokio::spawn(async move {
+                    let server_envelope = QueuedServerEnvelope {
+                        event: ServerEvent::Pong {
+                            status: PongStatus::Unknown,
+                        },
+                        client_id,
+                        stream_id,
+                        write_complete_tx: None,
+                    };
+                    let _ = server_event_tx.send(server_envelope).await;
+                });
+                Ok(())
+            }
+            ClientEvent::ClientClosed => self.close_client(&client_key).await,
+        }
+    }
+
+    async fn run_client_outbound(
+        client_id: ClientId,
+        stream_id: StreamId,
+        server_event_tx: mpsc::Sender<QueuedServerEnvelope>,
+        mut writer_rx: mpsc::Receiver<QueuedOutgoingMessage>,
+        mut status_rx: watch::Receiver<PongStatus>,
+        disconnect_token: CancellationToken,
+    ) -> (ClientId, StreamId) {
+        loop {
+            let (event, write_complete_tx) = tokio::select! {
+                _ = disconnect_token.cancelled() => {
+                    break;
+                }
+                queued_message = writer_rx.recv() => {
+                    let Some(queued_message) = queued_message else {
+                        break;
+                    };
+                    let event = ServerEvent::ServerMessage {
+                        message: Box::new(queued_message.message),
+                    };
+                    (event, queued_message.write_complete_tx)
+                }
+                changed = status_rx.changed() => {
+                    if changed.is_err() {
+                        break;
+                    }
+                    let event = ServerEvent::Pong { status: status_rx.borrow().clone() };
+                    (event, None)
+                }
+            };
+            let send_result = tokio::select! {
+                _ = disconnect_token.cancelled() => {
+                    break;
+                }
+                send_result = server_event_tx.send(QueuedServerEnvelope {
+                    event,
+                    client_id: client_id.clone(),
+                    stream_id: stream_id.clone(),
+                    write_complete_tx,
+                }) => send_result,
+            };
+            if send_result.is_err() {
+                break;
+            }
+        }
+        (client_id, stream_id)
+    }
+
+    pub(crate) async fn close_expired_clients(
+        &mut self,
+    ) -> Result<Vec<(ClientId, StreamId)>, Stopped> {
+        let now = Instant::now();
+        let expired_client_ids: Vec<(ClientId, StreamId)> = self
+            .clients
+            .iter()
+            .filter_map(|(client_key, client)| {
+                (!remote_control_client_is_alive(client, now)).then_some(client_key.clone())
+            })
+            .collect();
+        for client_key in &expired_client_ids {
+            self.close_client(client_key).await?;
+        }
+        Ok(expired_client_ids)
+    }
+
+    pub(super) async fn close_client(
+        &mut self,
+        client_key: &(ClientId, StreamId),
+    ) -> Result<(), Stopped> {
+        let Some(client) = self.remove_client(client_key) else {
+            return Ok(());
+        };
+        client.disconnect_token.cancel();
+        self.send_transport_event(TransportEvent::ConnectionClosed {
+            connection_id: client.connection_id,
+        })
+        .await
+    }
+
+    fn remove_client(&mut self, client_key: &(ClientId, StreamId)) -> Option<ClientState> {
+        let client = self.clients.remove(client_key)?;
+        if self
+            .legacy_stream_ids
+            .get(&client_key.0)
+            .is_some_and(|stream_id| stream_id == &client_key.1)
+        {
+            self.legacy_stream_ids.remove(&client_key.0);
+        }
+        Some(client)
+    }
+
+    async fn send_transport_event(&self, event: TransportEvent) -> Result<(), Stopped> {
+        let event = match event {
+            TransportEvent::ConnectionClosed { connection_id } => {
+                return self.send_connection_closed(connection_id).await;
+            }
+            event => event,
+        };
+
+        let event_name = transport_event_name(&event);
+        match timeout(
+            REMOTE_CONTROL_TRANSPORT_EVENT_SEND_TIMEOUT,
+            self.transport_event_tx.send(event),
+        )
+        .await
+        {
+            Ok(Ok(())) => Ok(()),
+            Ok(Err(_)) => {
+                warn!(
+                    transport_event = event_name,
+                    "remote control transport event receiver dropped"
+                );
+                Err(Stopped)
+            }
+            Err(_) => {
+                warn!(
+                    transport_event = event_name,
+                    timeout = ?REMOTE_CONTROL_TRANSPORT_EVENT_SEND_TIMEOUT,
+                    "timed out forwarding remote control transport event"
+                );
+                Err(Stopped)
+            }
+        }
+    }
+
+    fn record_inbound_message_delivery(
+        &mut self,
+        client_key: &(ClientId, StreamId),
+        seq_id: Option<u64>,
+    ) {
+        // Timed forwarding can fail, so only dedupe retries after app-server receives it.
+        if let Some(seq_id) = seq_id
+            && let Some(client) = self.clients.get_mut(client_key)
+        {
+            client.last_inbound_seq_id = Some(seq_id);
+        }
+    }
+
+    async fn send_connection_closed(&self, connection_id: ConnectionId) -> Result<(), Stopped> {
+        // Worker shutdown can abort the caller; detach the cleanup event before awaiting it.
+        match self.spawn_connection_closed(connection_id).await {
+            Ok(result) => result,
+            Err(err) => {
+                warn!(
+                    transport_event = "connection_closed",
+                    ?err,
+                    "remote control transport event forwarding task failed"
+                );
+                Err(Stopped)
+            }
+        }
+    }
+
+    fn spawn_connection_closed(
+        &self,
+        connection_id: ConnectionId,
+    ) -> JoinHandle<Result<(), Stopped>> {
+        info!(
+            connection_id = ?connection_id,
+            "forwarding remote control connection closed transport event"
+        );
+        let transport_event_tx = self.transport_event_tx.clone();
+        tokio::spawn(async move {
+            transport_event_tx
+                .send(TransportEvent::ConnectionClosed { connection_id })
+                .await
+                .map_err(|_| {
+                    warn!(
+                        transport_event = "connection_closed",
+                        "remote control transport event receiver dropped"
+                    );
+                    Stopped
+                })
+        })
+    }
+}
+
+fn transport_event_name(event: &TransportEvent) -> &'static str {
+    match event {
+        TransportEvent::ConnectionOpened { .. } => "connection_opened",
+        TransportEvent::ConnectionClosed { .. } => "connection_closed",
+        TransportEvent::IncomingMessage { .. } => "incoming_message",
+        TransportEvent::DaemonShutdown => "daemon_shutdown",
+    }
+}
+
+fn remote_control_message_starts_connection(message: &JSONRPCMessage) -> bool {
+    matches!(
+        message,
+        JSONRPCMessage::Request(codex_app_server_protocol::JSONRPCRequest { method, .. })
+            if method == "initialize"
+    )
+}
+
+fn remote_control_client_is_alive(client: &ClientState, now: Instant) -> bool {
+    now.duration_since(client.last_activity_at) < REMOTE_CONTROL_CLIENT_IDLE_TIMEOUT
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::outgoing_message::OutgoingMessage;
+    use crate::transport::remote_control::protocol::ClientEnvelope;
+    use crate::transport::remote_control::protocol::ClientEvent;
+    use codex_app_server_protocol::ConfigWarningNotification;
+    use codex_app_server_protocol::JSONRPCRequest;
+    use codex_app_server_protocol::RequestId;
+    use codex_app_server_protocol::ServerNotification;
+    use codex_app_server_protocol::ServerNotificationEnvelope;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+    use tokio::time::timeout;
+
+    fn initialize_envelope(client_id: &str) -> ClientEnvelope {
+        initialize_envelope_with_stream_id(client_id, /*stream_id*/ None)
+    }
+
+    fn initialize_envelope_with_stream_id(
+        client_id: &str,
+        stream_id: Option<&str>,
+    ) -> ClientEnvelope {
+        ClientEnvelope {
+            event: ClientEvent::ClientMessage {
+                message: JSONRPCMessage::Request(JSONRPCRequest {
+                    id: RequestId::Integer(1),
+                    method: "initialize".to_string(),
+                    params: Some(json!({
+                        "clientInfo": {
+                            "name": "remote-test-client",
+                            "version": "0.1.0"
+                        }
+                    })),
+                    trace: None,
+                }),
+            },
+            client_id: ClientId(client_id.to_string()),
+            stream_id: stream_id.map(|stream_id| StreamId(stream_id.to_string())),
+            seq_id: Some(0),
+            cursor: None,
+        }
+    }
+
+    fn initialized_notification() -> JSONRPCMessage {
+        JSONRPCMessage::Notification(codex_app_server_protocol::JSONRPCNotification {
+            method: "initialized".to_string(),
+            params: None,
+        })
+    }
+
+    #[tokio::test]
+    async fn cancelled_outbound_task_emits_connection_closed() {
+        let (server_event_tx, _server_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let shutdown_token = CancellationToken::new();
+        let mut client_tracker =
+            ClientTracker::new(server_event_tx, transport_event_tx, &shutdown_token);
+
+        client_tracker
+            .handle_message(initialize_envelope("client-1"))
+            .await
+            .expect("initialize should open client");
+
+        let (connection_id, disconnect_sender) = match transport_event_rx
+            .recv()
+            .await
+            .expect("connection opened should be sent")
+        {
+            TransportEvent::ConnectionOpened {
+                connection_id,
+                disconnect_sender: Some(disconnect_sender),
+                ..
+            } => (connection_id, disconnect_sender),
+            other => panic!("expected connection opened, got {other:?}"),
+        };
+        match transport_event_rx
+            .recv()
+            .await
+            .expect("initialize should be forwarded")
+        {
+            TransportEvent::IncomingMessage {
+                connection_id: incoming_connection_id,
+                ..
+            } => assert_eq!(incoming_connection_id, connection_id),
+            other => panic!("expected incoming initialize, got {other:?}"),
+        }
+
+        disconnect_sender.cancel();
+        let closed_client_id = timeout(Duration::from_secs(1), client_tracker.bookkeep_join_set())
+            .await
+            .expect("bookkeeping should process the closed task")
+            .expect("closed task should return client id");
+        assert_eq!(closed_client_id.0, ClientId("client-1".to_string()));
+        client_tracker
+            .close_client(&closed_client_id)
+            .await
+            .expect("closed client should emit connection closed");
+
+        match transport_event_rx
+            .recv()
+            .await
+            .expect("connection closed should be sent")
+        {
+            TransportEvent::ConnectionClosed {
+                connection_id: closed_connection_id,
+            } => assert_eq!(closed_connection_id, connection_id),
+            other => panic!("expected connection closed, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn shutdown_cancels_blocked_outbound_forwarding() {
+        let (server_event_tx, _server_event_rx) = mpsc::channel(1);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let shutdown_token = CancellationToken::new();
+        let mut client_tracker =
+            ClientTracker::new(server_event_tx.clone(), transport_event_tx, &shutdown_token);
+
+        server_event_tx
+            .send(QueuedServerEnvelope {
+                event: ServerEvent::Pong {
+                    status: PongStatus::Unknown,
+                },
+                client_id: ClientId("queued-client".to_string()),
+                stream_id: StreamId("queued-stream".to_string()),
+                write_complete_tx: None,
+            })
+            .await
+            .expect("server event queue should accept prefill");
+
+        client_tracker
+            .handle_message(initialize_envelope("client-1"))
+            .await
+            .expect("initialize should open client");
+
+        let writer = match transport_event_rx
+            .recv()
+            .await
+            .expect("connection opened should be sent")
+        {
+            TransportEvent::ConnectionOpened { writer, .. } => writer,
+            other => panic!("expected connection opened, got {other:?}"),
+        };
+        let _ = transport_event_rx
+            .recv()
+            .await
+            .expect("initialize should be forwarded");
+
+        writer
+            .send(QueuedOutgoingMessage::new(
+                OutgoingMessage::AppServerNotification(ServerNotificationEnvelope {
+                    notification: ServerNotification::ConfigWarning(ConfigWarningNotification {
+                        summary: "test".to_string(),
+                        details: None,
+                        path: None,
+                        range: None,
+                    }),
+                    emitted_at_ms: Some(1_234),
+                }),
+            ))
+            .await
+            .expect("writer should accept queued message");
+
+        timeout(Duration::from_secs(1), client_tracker.shutdown())
+            .await
+            .expect("shutdown should not hang on blocked server forwarding");
+    }
+
+    #[tokio::test]
+    async fn non_close_transport_event_send_times_out_when_queue_stays_full() {
+        let (server_event_tx, _server_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let (transport_event_tx, _transport_event_rx) = mpsc::channel(1);
+        let shutdown_token = CancellationToken::new();
+        let client_tracker =
+            ClientTracker::new(server_event_tx, transport_event_tx.clone(), &shutdown_token);
+
+        transport_event_tx
+            .send(TransportEvent::ConnectionClosed {
+                connection_id: next_connection_id(),
+            })
+            .await
+            .expect("transport event queue should accept prefill");
+
+        let send_result = client_tracker
+            .send_transport_event(TransportEvent::IncomingMessage {
+                connection_id: next_connection_id(),
+                message: initialized_notification(),
+            })
+            .await;
+
+        assert!(send_result.is_err());
+    }
+
+    #[tokio::test]
+    async fn incoming_message_timeout_does_not_advance_seq_id() {
+        let (server_event_tx, _server_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(2);
+        let shutdown_token = CancellationToken::new();
+        let mut client_tracker =
+            ClientTracker::new(server_event_tx, transport_event_tx.clone(), &shutdown_token);
+
+        client_tracker
+            .handle_message(initialize_envelope_with_stream_id(
+                "client-1",
+                Some("stream-1"),
+            ))
+            .await
+            .expect("initialize should open client");
+        let connection_id = match transport_event_rx.recv().await.expect("open event") {
+            TransportEvent::ConnectionOpened { connection_id, .. } => connection_id,
+            other => panic!("expected connection opened, got {other:?}"),
+        };
+        let _ = transport_event_rx.recv().await.expect("initialize event");
+
+        for _ in 0..2 {
+            transport_event_tx
+                .send(TransportEvent::ConnectionClosed {
+                    connection_id: next_connection_id(),
+                })
+                .await
+                .expect("transport event queue should accept prefill");
+        }
+
+        let retry_envelope = ClientEnvelope {
+            event: ClientEvent::ClientMessage {
+                message: initialized_notification(),
+            },
+            client_id: ClientId("client-1".to_string()),
+            stream_id: Some(StreamId("stream-1".to_string())),
+            seq_id: Some(1),
+            cursor: None,
+        };
+        assert!(
+            client_tracker
+                .handle_message(retry_envelope.clone())
+                .await
+                .is_err()
+        );
+        for _ in 0..2 {
+            let _ = transport_event_rx.recv().await.expect("prefilled event");
+        }
+
+        client_tracker
+            .handle_message(retry_envelope)
+            .await
+            .expect("retry should forward after timeout");
+        match transport_event_rx.recv().await.expect("retried event") {
+            TransportEvent::IncomingMessage {
+                connection_id: queued_connection_id,
+                ..
+            } => assert_eq!(queued_connection_id, connection_id),
+            other => panic!("expected incoming message, got {other:?}"),
+        }
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn initialize_timeout_closes_open_connection() {
+        let (server_event_tx, _server_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(1);
+        let shutdown_token = CancellationToken::new();
+        let client_tracker =
+            ClientTracker::new(server_event_tx, transport_event_tx, &shutdown_token);
+        let handle_message = tokio::spawn(async move {
+            let mut client_tracker = client_tracker;
+            client_tracker
+                .handle_message(initialize_envelope_with_stream_id(
+                    "client-1",
+                    Some("stream-1"),
+                ))
+                .await
+        });
+
+        tokio::task::yield_now().await;
+        tokio::time::advance(
+            REMOTE_CONTROL_TRANSPORT_EVENT_SEND_TIMEOUT + Duration::from_millis(1),
+        )
+        .await;
+
+        assert!(handle_message.await.expect("handle message task").is_err());
+        let connection_id = match transport_event_rx.recv().await.expect("open event") {
+            TransportEvent::ConnectionOpened { connection_id, .. } => connection_id,
+            other => panic!("expected connection opened, got {other:?}"),
+        };
+
+        match transport_event_rx.recv().await.expect("close event") {
+            TransportEvent::ConnectionClosed {
+                connection_id: closed_connection_id,
+            } => assert_eq!(closed_connection_id, connection_id),
+            other => panic!("expected connection closed, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn close_client_waits_for_transport_event_queue_capacity() {
+        let (server_event_tx, _server_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(2);
+        let shutdown_token = CancellationToken::new();
+        let mut client_tracker =
+            ClientTracker::new(server_event_tx, transport_event_tx, &shutdown_token);
+
+        client_tracker
+            .handle_message(initialize_envelope_with_stream_id(
+                "client-1",
+                Some("stream-1"),
+            ))
+            .await
+            .expect("initialize should open client");
+        let connection_id = match transport_event_rx.recv().await.expect("open event") {
+            TransportEvent::ConnectionOpened { connection_id, .. } => connection_id,
+            other => panic!("expected connection opened, got {other:?}"),
+        };
+        let _ = transport_event_rx.recv().await.expect("initialize event");
+
+        for _ in 0..2 {
+            client_tracker
+                .transport_event_tx
+                .send(TransportEvent::IncomingMessage {
+                    connection_id,
+                    message: initialized_notification(),
+                })
+                .await
+                .expect("transport event queue should accept prefill");
+        }
+
+        let client_key = (
+            ClientId("client-1".to_string()),
+            StreamId("stream-1".to_string()),
+        );
+        let close_client = client_tracker.close_client(&client_key);
+        tokio::pin!(close_client);
+        assert!(
+            timeout(Duration::from_millis(20), &mut close_client)
+                .await
+                .is_err()
+        );
+
+        for _ in 0..2 {
+            match transport_event_rx.recv().await.expect("prefilled event") {
+                TransportEvent::IncomingMessage {
+                    connection_id: queued_connection_id,
+                    ..
+                } => assert_eq!(queued_connection_id, connection_id),
+                other => panic!("expected incoming message, got {other:?}"),
+            }
+        }
+
+        close_client
+            .await
+            .expect("close should forward after queue drains");
+        match transport_event_rx.recv().await.expect("close event") {
+            TransportEvent::ConnectionClosed {
+                connection_id: closed_connection_id,
+            } => assert_eq!(closed_connection_id, connection_id),
+            other => panic!("expected connection closed, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn close_client_keeps_forwarding_after_caller_is_aborted() {
+        let (server_event_tx, _server_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(2);
+        let shutdown_token = CancellationToken::new();
+        let mut client_tracker =
+            ClientTracker::new(server_event_tx, transport_event_tx, &shutdown_token);
+
+        client_tracker
+            .handle_message(initialize_envelope_with_stream_id(
+                "client-1",
+                Some("stream-1"),
+            ))
+            .await
+            .expect("initialize should open client");
+        let connection_id = match transport_event_rx.recv().await.expect("open event") {
+            TransportEvent::ConnectionOpened { connection_id, .. } => connection_id,
+            other => panic!("expected connection opened, got {other:?}"),
+        };
+        let _ = transport_event_rx.recv().await.expect("initialize event");
+
+        for _ in 0..2 {
+            client_tracker
+                .transport_event_tx
+                .send(TransportEvent::IncomingMessage {
+                    connection_id,
+                    message: initialized_notification(),
+                })
+                .await
+                .expect("transport event queue should accept prefill");
+        }
+
+        let client_key = (
+            ClientId("client-1".to_string()),
+            StreamId("stream-1".to_string()),
+        );
+        let mut close_client =
+            tokio::spawn(async move { client_tracker.close_client(&client_key).await });
+        assert!(
+            timeout(Duration::from_millis(20), &mut close_client)
+                .await
+                .is_err()
+        );
+        close_client.abort();
+        let _ = close_client.await;
+
+        for _ in 0..2 {
+            let _ = transport_event_rx.recv().await.expect("prefilled event");
+        }
+        match timeout(Duration::from_secs(1), transport_event_rx.recv())
+            .await
+            .expect("close should be delivered")
+            .expect("close event")
+        {
+            TransportEvent::ConnectionClosed {
+                connection_id: closed_connection_id,
+            } => assert_eq!(closed_connection_id, connection_id),
+            other => panic!("expected connection closed, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn initialize_with_new_stream_id_opens_new_connection_for_same_client() {
+        let (server_event_tx, _server_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let shutdown_token = CancellationToken::new();
+        let mut client_tracker =
+            ClientTracker::new(server_event_tx, transport_event_tx, &shutdown_token);
+
+        client_tracker
+            .handle_message(initialize_envelope_with_stream_id(
+                "client-1",
+                Some("stream-1"),
+            ))
+            .await
+            .expect("first initialize should open client");
+        let first_connection_id = match transport_event_rx.recv().await.expect("open event") {
+            TransportEvent::ConnectionOpened { connection_id, .. } => connection_id,
+            other => panic!("expected connection opened, got {other:?}"),
+        };
+        let _ = transport_event_rx.recv().await.expect("initialize event");
+
+        client_tracker
+            .handle_message(initialize_envelope_with_stream_id(
+                "client-1",
+                Some("stream-2"),
+            ))
+            .await
+            .expect("second initialize should open client");
+        let second_connection_id = match transport_event_rx.recv().await.expect("open event") {
+            TransportEvent::ConnectionOpened { connection_id, .. } => connection_id,
+            other => panic!("expected connection opened, got {other:?}"),
+        };
+
+        assert_ne!(first_connection_id, second_connection_id);
+    }
+
+    #[tokio::test]
+    async fn legacy_initialize_without_stream_id_resets_inbound_seq_id() {
+        let (server_event_tx, _server_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let (transport_event_tx, mut transport_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+        let shutdown_token = CancellationToken::new();
+        let mut client_tracker =
+            ClientTracker::new(server_event_tx, transport_event_tx, &shutdown_token);
+
+        client_tracker
+            .handle_message(initialize_envelope("client-1"))
+            .await
+            .expect("initialize should open client");
+        let connection_id = match transport_event_rx.recv().await.expect("open event") {
+            TransportEvent::ConnectionOpened { connection_id, .. } => connection_id,
+            other => panic!("expected connection opened, got {other:?}"),
+        };
+        let _ = transport_event_rx.recv().await.expect("initialize event");
+
+        client_tracker
+            .handle_message(ClientEnvelope {
+                event: ClientEvent::ClientMessage {
+                    message: JSONRPCMessage::Notification(
+                        codex_app_server_protocol::JSONRPCNotification {
+                            method: "initialized".to_string(),
+                            params: None,
+                        },
+                    ),
+                },
+                client_id: ClientId("client-1".to_string()),
+                stream_id: None,
+                seq_id: Some(0),
+                cursor: None,
+            })
+            .await
+            .expect("legacy followup should be forwarded");
+
+        match transport_event_rx.recv().await.expect("followup event") {
+            TransportEvent::IncomingMessage {
+                connection_id: incoming_connection_id,
+                ..
+            } => assert_eq!(incoming_connection_id, connection_id),
+            other => panic!("expected incoming message, got {other:?}"),
+        }
+    }
+}

codex-rs/app-server-transport/src/transport/remote_control/clients.rs

@@ -0,0 +1,303 @@
+use super::auth::RemoteControlAuth;
+use super::auth::RemoteControlConnectionAuth;
+use super::auth::load_remote_control_auth;
+use super::auth::recover_remote_control_auth;
+use super::enroll::format_headers;
+use super::enroll::preview_remote_control_response_body;
+use super::protocol::normalize_remote_control_base_url;
+use axum::http::HeaderMap;
+use codex_app_server_protocol::RemoteControlClient;
+use codex_app_server_protocol::RemoteControlClientsListOrder;
+use codex_app_server_protocol::RemoteControlClientsListParams;
+use codex_app_server_protocol::RemoteControlClientsListResponse;
+use codex_app_server_protocol::RemoteControlClientsRevokeParams;
+use codex_app_server_protocol::RemoteControlClientsRevokeResponse;
+use codex_login::default_client::create_client_without_request_logging;
+use serde::Deserialize;
+use std::io;
+use std::io::ErrorKind;
+use time::OffsetDateTime;
+use time::format_description::well_known::Rfc3339;
+use url::Url;
+
+const REMOTE_CONTROL_CLIENT_MANAGEMENT_TIMEOUT: std::time::Duration =
+    std::time::Duration::from_secs(30);
+
+#[derive(Debug, Deserialize)]
+struct ListRemoteControlClientsResponse {
+    items: Vec<RemoteControlClientResponse>,
+    #[serde(default)]
+    cursor: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct RemoteControlClientResponse {
+    client_id: String,
+    #[serde(default)]
+    display_name: Option<String>,
+    #[serde(default)]
+    device_type: Option<String>,
+    #[serde(default)]
+    platform: Option<String>,
+    #[serde(default)]
+    os_version: Option<String>,
+    #[serde(default)]
+    device_model: Option<String>,
+    #[serde(default)]
+    app_version: Option<String>,
+    #[serde(default)]
+    last_seen_at: Option<String>,
+}
+
+enum ClientManagementRequest<'a> {
+    List {
+        url: &'a Url,
+        params: &'a RemoteControlClientsListParams,
+    },
+    Revoke {
+        url: &'a Url,
+    },
+}
+
+struct ClientManagementResponse {
+    status: axum::http::StatusCode,
+    headers: HeaderMap,
+    body: Vec<u8>,
+}
+
+pub(super) async fn list_remote_control_clients(
+    remote_control_url: &str,
+    auth_manager: &RemoteControlAuth,
+    params: RemoteControlClientsListParams,
+) -> io::Result<RemoteControlClientsListResponse> {
+    if params.environment_id.is_empty() {
+        return Err(io::Error::new(
+            ErrorKind::InvalidInput,
+            "remote control client list requires environmentId",
+        ));
+    }
+    if params
+        .limit
+        .is_some_and(|limit| !(1..=100).contains(&limit))
+    {
+        return Err(io::Error::new(
+            ErrorKind::InvalidInput,
+            "remote control client list limit must be between 1 and 100",
+        ));
+    }
+    let url = environment_clients_url(remote_control_url, &params.environment_id)?;
+    let response = send_client_management_request(
+        auth_manager,
+        ClientManagementRequest::List {
+            url: &url,
+            params: &params,
+        },
+        "list remote control clients",
+    )
+    .await?;
+    let ClientManagementResponse {
+        status,
+        headers,
+        body,
+    } = response;
+    let body_preview = preview_remote_control_response_body(&body);
+    ensure_success_response(status, &headers, &url, &body_preview, "client list")?;
+    let response = serde_json::from_slice::<ListRemoteControlClientsResponse>(&body).map_err(
+        |err| {
+            io::Error::other(format!(
+                "failed to parse remote control client list response from `{url}`: HTTP {status}, {}, body: {body_preview}, decode error: {err}",
+                format_headers(&headers)
+            ))
+        },
+    )?;
+    Ok(RemoteControlClientsListResponse {
+        data: response
+            .items
+            .into_iter()
+            .map(RemoteControlClient::try_from)
+            .collect::<io::Result<_>>()?,
+        next_cursor: response.cursor,
+    })
+}
+
+pub(super) async fn revoke_remote_control_client(
+    remote_control_url: &str,
+    auth_manager: &RemoteControlAuth,
+    params: RemoteControlClientsRevokeParams,
+) -> io::Result<RemoteControlClientsRevokeResponse> {
+    if params.environment_id.is_empty() {
+        return Err(io::Error::new(
+            ErrorKind::InvalidInput,
+            "remote control client revoke requires environmentId",
+        ));
+    }
+    if params.client_id.is_empty() {
+        return Err(io::Error::new(
+            ErrorKind::InvalidInput,
+            "remote control client revoke requires clientId",
+        ));
+    }
+    let mut url = environment_clients_url(remote_control_url, &params.environment_id)?;
+    url.path_segments_mut()
+        .map_err(|()| {
+            io::Error::new(
+                ErrorKind::InvalidInput,
+                "remote control URL cannot be a base",
+            )
+        })?
+        .push(&params.client_id);
+    let response = send_client_management_request(
+        auth_manager,
+        ClientManagementRequest::Revoke { url: &url },
+        "revoke remote control client",
+    )
+    .await?;
+    let ClientManagementResponse {
+        status,
+        headers,
+        body,
+    } = response;
+    let body_preview = preview_remote_control_response_body(&body);
+    ensure_success_response(status, &headers, &url, &body_preview, "client revoke")?;
+    Ok(RemoteControlClientsRevokeResponse {})
+}
+
+async fn send_client_management_request(
+    auth_manager: &RemoteControlAuth,
+    request: ClientManagementRequest<'_>,
+    action: &str,
+) -> io::Result<ClientManagementResponse> {
+    let mut auth_recovery = auth_manager.unauthorized_recovery();
+    let mut auth_change_rx = auth_manager.auth_change_receiver();
+    let auth = load_remote_control_auth(auth_manager).await?;
+    let response = send_client_management_request_once(&auth, &request, action).await?;
+    if response.status.as_u16() != 401
+        || !recover_remote_control_auth(&mut auth_recovery, &mut auth_change_rx).await
+    {
+        return Ok(response);
+    }
+    let auth = load_remote_control_auth(auth_manager).await?;
+    send_client_management_request_once(&auth, &request, action).await
+}
+
+async fn send_client_management_request_once(
+    auth: &RemoteControlConnectionAuth,
+    request: &ClientManagementRequest<'_>,
+    action: &str,
+) -> io::Result<ClientManagementResponse> {
+    let client = create_client_without_request_logging();
+    let auth_headers = auth.request_headers()?;
+    let request = match request {
+        ClientManagementRequest::List { url, params } => {
+            let mut query = Vec::new();
+            if let Some(cursor) = &params.cursor {
+                query.push(("cursor", cursor.clone()));
+            }
+            if let Some(limit) = params.limit {
+                query.push(("limit", limit.to_string()));
+            }
+            if let Some(order) = params.order {
+                query.push((
+                    "order",
+                    match order {
+                        RemoteControlClientsListOrder::Asc => "asc",
+                        RemoteControlClientsListOrder::Desc => "desc",
+                    }
+                    .to_string(),
+                ));
+            }
+            client.get((*url).clone()).query(&query)
+        }
+        ClientManagementRequest::Revoke { url } => client.delete((*url).clone()),
+    };
+    let response = request
+        .timeout(REMOTE_CONTROL_CLIENT_MANAGEMENT_TIMEOUT)
+        .headers(auth_headers)
+        .send()
+        .await
+        .map_err(|err| io::Error::other(format!("failed to {action}: {err}")))?;
+    let headers = response.headers().clone();
+    let status = response.status();
+    let body = response
+        .bytes()
+        .await
+        .map_err(|err| io::Error::other(format!("failed to read {action} response: {err}")))?
+        .to_vec();
+    Ok(ClientManagementResponse {
+        status,
+        headers,
+        body,
+    })
+}
+
+fn ensure_success_response(
+    status: axum::http::StatusCode,
+    headers: &HeaderMap,
+    url: &Url,
+    body_preview: &str,
+    response_kind: &str,
+) -> io::Result<()> {
+    if status.is_success() {
+        return Ok(());
+    }
+    let error_kind = match status.as_u16() {
+        400 => ErrorKind::InvalidInput,
+        401 | 403 => ErrorKind::PermissionDenied,
+        404 => ErrorKind::NotFound,
+        _ => ErrorKind::Other,
+    };
+    Err(io::Error::new(
+        error_kind,
+        format!(
+            "remote control {response_kind} failed at `{url}`: HTTP {status}, {}, body: {body_preview}",
+            format_headers(headers)
+        ),
+    ))
+}
+
+fn environment_clients_url(remote_control_url: &str, environment_id: &str) -> io::Result<Url> {
+    let mut url = normalize_remote_control_base_url(remote_control_url)?
+        .join("wham/remote/control/environments")
+        .map_err(io::Error::other)?;
+    url.path_segments_mut()
+        .map_err(|()| {
+            io::Error::new(
+                ErrorKind::InvalidInput,
+                "remote control URL cannot be a base",
+            )
+        })?
+        .push(environment_id)
+        .push("clients");
+    Ok(url)
+}
+
+impl TryFrom<RemoteControlClientResponse> for RemoteControlClient {
+    type Error = io::Error;
+
+    fn try_from(client: RemoteControlClientResponse) -> Result<Self, Self::Error> {
+        Ok(Self {
+            client_id: client.client_id,
+            display_name: client.display_name,
+            device_type: client.device_type,
+            platform: client.platform,
+            os_version: client.os_version,
+            device_model: client.device_model,
+            app_version: client.app_version,
+            last_seen_at: client
+                .last_seen_at
+                .map(|last_seen_at| {
+                    OffsetDateTime::parse(&last_seen_at, &Rfc3339)
+                        .map(OffsetDateTime::unix_timestamp)
+                        .map_err(|err| {
+                            io::Error::new(
+                                ErrorKind::InvalidData,
+                                format!(
+                                    "failed to parse remote control client last_seen_at `{last_seen_at}`: {err}"
+                                ),
+                            )
+                        })
+                })
+                .transpose()?,
+        })
+    }
+}

codex-rs/app-server-transport/src/transport/remote_control/controller.rs

@@ -0,0 +1,368 @@
+//! Owns the current login's relay session and the process-facing handle.
+//! Replacement happens before cleanup; retired sessions cannot publish into their replacements.
+
+use super::auth::RemoteControlAuth;
+use super::*;
+use futures::FutureExt;
+use std::panic::AssertUnwindSafe;
+use tokio_util::task::TaskTracker;
+
+#[derive(Clone)]
+pub struct RemoteControlHandle {
+    pub(super) inner: Arc<RemoteControl>,
+}
+
+struct CurrentSession {
+    authenticated: bool,
+    session: Arc<RemoteControlSession>,
+}
+
+pub(super) struct RemoteControl {
+    config: RemoteControlStartConfig,
+    state_db: Option<Arc<StateRuntime>>,
+    auth_manager: Arc<AuthManager>,
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+    shutdown: CancellationToken,
+    tasks: TaskTracker,
+    current: StdMutex<Option<CurrentSession>>,
+    startup: RemoteControlDesiredState,
+    persistence: RemoteControlPersistence,
+    client_name: RemoteControlPairingPersistenceKey,
+    requires_client_name: bool,
+    status: watch::Sender<RemoteControlStatusChangedNotification>,
+    session_changed: watch::Sender<()>,
+}
+
+impl RemoteControl {
+    pub(super) fn session(&self) -> Arc<RemoteControlSession> {
+        let mut current = self
+            .current
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Some(current) = current.as_ref()
+            && current.session.auth_manager.owner.is_current()
+        {
+            return current.session.clone();
+        }
+        let (auth, authenticated) = RemoteControlAuth::capture(self.auth_manager.clone());
+        let desired = match current.take() {
+            Some(previous) => {
+                previous.session.shutdown_token.cancel();
+                if previous.authenticated {
+                    RemoteControlDesiredState::Disabled
+                } else {
+                    // Startup or an explicit enable while signed out may wait for first login.
+                    *previous.session.desired_state_tx.borrow()
+                }
+            }
+            None => self.startup,
+        };
+        let session = self.start_session(auth, desired);
+        self.status.send_replace(session.status());
+        *current = Some(CurrentSession {
+            authenticated,
+            session: session.clone(),
+        });
+        self.session_changed.send_replace(());
+        session
+    }
+
+    fn start_session(
+        &self,
+        auth_manager: RemoteControlAuth,
+        desired: RemoteControlDesiredState,
+    ) -> Arc<RemoteControlSession> {
+        let shutdown = self.shutdown.child_token();
+        let (desired_state_tx, _) = watch::channel(desired);
+        let desired_state_tx = Arc::new(desired_state_tx);
+        let current_enrollment =
+            Arc::new(RemoteControlEnrollmentState::new(/*enrollment*/ None));
+        let server_name = gethostname().to_string_lossy().trim().to_string();
+        let (status_tx, _) = watch::channel(RemoteControlStatusChangedNotification {
+            status: if desired.is_enabled() {
+                RemoteControlConnectionStatus::Connecting
+            } else {
+                RemoteControlConnectionStatus::Disabled
+            },
+            server_name: server_name.clone(),
+            installation_id: self.config.installation_id.clone(),
+            environment_id: None,
+        });
+        let session = Arc::new(RemoteControlSession {
+            policy: self.config.policy,
+            shutdown_token: shutdown.clone(),
+            desired_state_tx: desired_state_tx.clone(),
+            desired_state_rpc_lock: Arc::new(Semaphore::new(1)),
+            persistence: self.persistence.clone(),
+            status_tx: Arc::new(status_tx.clone()),
+            state_db: self.state_db.clone(),
+            remote_control_url: self.config.remote_control_url.clone(),
+            current_enrollment: current_enrollment.clone(),
+            pairing_persistence_key: self.client_name.clone(),
+            pairing_persistence_key_required: self.requires_client_name,
+            auth_manager: auth_manager.clone(),
+        });
+        let websocket = RemoteControlWebsocket::new(
+            websocket::RemoteControlWebsocketConfig {
+                remote_control_url: self.config.remote_control_url.clone(),
+                installation_id: self.config.installation_id.clone(),
+                remote_control_target: None,
+                server_name,
+            },
+            self.state_db.clone(),
+            auth_manager,
+            RemoteControlChannels {
+                transport_event_tx: self.transport_event_tx.clone(),
+                status_publisher: RemoteControlStatusPublisher::new(status_tx),
+                current_enrollment,
+                pairing_persistence_key: self.client_name.clone(),
+                persistence: self.persistence.clone(),
+            },
+            shutdown.clone(),
+            desired_state_tx,
+        );
+        let client_name_rx = if self.requires_client_name {
+            let (tx, rx) = oneshot::channel();
+            let mut names = self.client_name.subscribe();
+            self.tasks.spawn(async move {
+                tokio::select! {
+                    _ = shutdown.cancelled() => {}
+                    name = names.wait_for(Option::is_some) => {
+                        if let Ok(name) = name
+                            && let Some(name) = name.as_ref()
+                        {
+                            let _ = tx.send(name.clone());
+                        }
+                    }
+                }
+            });
+            Some(rx)
+        } else {
+            None
+        };
+        let process_shutdown = self.shutdown.clone();
+        let failed_session = session.clone();
+        self.tasks.spawn(async move {
+            if let Err(panic) = AssertUnwindSafe(websocket.run(client_name_rx))
+                .catch_unwind()
+                .await
+            {
+                tracing::error!("remote control websocket task panicked");
+                failed_session.publish_status(RemoteControlConnectionStatus::Disabled);
+                process_shutdown.cancel();
+                std::panic::resume_unwind(panic);
+            }
+        });
+        session
+    }
+}
+
+impl RemoteControlSession {
+    async fn run<T>(
+        &self,
+        operation: impl std::future::Future<Output = io::Result<T>>,
+    ) -> io::Result<T> {
+        self.auth_manager.ensure_current()?;
+        tokio::select! {
+            biased;
+            _ = self.auth_manager.owner.invalidated() => {
+                Err(io::Error::new(io::ErrorKind::Interrupted, "remote control authentication changed"))
+            }
+            result = operation => {
+                self.auth_manager.ensure_current()?;
+                result
+            }
+        }
+    }
+}
+
+impl RemoteControlHandle {
+    pub fn ensure_remote_control_allowed(&self) -> Result<(), RemoteControlDisabledByRequirements> {
+        self.inner.session().ensure_remote_control_allowed()
+    }
+
+    pub fn status(&self) -> RemoteControlStatusChangedNotification {
+        self.inner.session().status()
+    }
+
+    pub fn status_receiver(&self) -> watch::Receiver<RemoteControlStatusChangedNotification> {
+        self.inner.session();
+        self.inner.status.subscribe()
+    }
+
+    pub fn enable_ephemeral(
+        &self,
+    ) -> Result<RemoteControlStatusChangedNotification, RemoteControlEnableError> {
+        self.inner.session().enable_ephemeral()
+    }
+
+    pub async fn disable_ephemeral(&self) -> RemoteControlStatusChangedNotification {
+        self.inner.session().disable_ephemeral().await
+    }
+
+    pub async fn enable(
+        &self,
+        app_server_client_name: Option<&str>,
+    ) -> io::Result<RemoteControlStatusChangedNotification> {
+        let session = self.inner.session();
+        session.run(session.enable(app_server_client_name)).await
+    }
+
+    pub async fn disable(
+        &self,
+        app_server_client_name: Option<&str>,
+    ) -> io::Result<RemoteControlStatusChangedNotification> {
+        let session = self.inner.session();
+        session.run(session.disable(app_server_client_name)).await
+    }
+
+    pub async fn resolve_persisted_preference(
+        &self,
+        app_server_client_name: Option<&str>,
+    ) -> io::Result<bool> {
+        let session = self.inner.session();
+        session
+            .run(session.resolve_persisted_preference(app_server_client_name))
+            .await
+    }
+
+    pub async fn start_pairing(
+        &self,
+        params: RemoteControlPairingStartParams,
+        app_server_client_name: Option<&str>,
+    ) -> io::Result<RemoteControlPairingStartResponse> {
+        let session = self.inner.session();
+        session
+            .run(session.start_pairing(params, app_server_client_name))
+            .await
+    }
+
+    pub async fn pairing_status(
+        &self,
+        params: RemoteControlPairingStatusParams,
+    ) -> io::Result<RemoteControlPairingStatusResponse> {
+        let session = self.inner.session();
+        session.run(session.pairing_status(params)).await
+    }
+
+    pub async fn list_clients(
+        &self,
+        params: RemoteControlClientsListParams,
+    ) -> io::Result<RemoteControlClientsListResponse> {
+        let session = self.inner.session();
+        session.run(session.list_clients(params)).await
+    }
+
+    pub async fn revoke_client(
+        &self,
+        params: RemoteControlClientsRevokeParams,
+    ) -> io::Result<RemoteControlClientsRevokeResponse> {
+        let session = self.inner.session();
+        session.run(session.revoke_client(params)).await
+    }
+}
+
+pub async fn start_remote_control(
+    config: RemoteControlStartConfig,
+    state_db: Option<Arc<StateRuntime>>,
+    auth_manager: Arc<AuthManager>,
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+    shutdown_token: CancellationToken,
+    app_server_client_name_rx: Option<oneshot::Receiver<String>>,
+    startup_mode: RemoteControlStartupMode,
+) -> io::Result<(JoinHandle<()>, RemoteControlHandle)> {
+    let startup =
+        if config.policy == RemoteControlPolicy::DisabledByRequirements || state_db.is_none() {
+            RemoteControlDesiredState::Disabled
+        } else {
+            match startup_mode {
+                RemoteControlStartupMode::ResolvePersisted => RemoteControlDesiredState::Unknown,
+                RemoteControlStartupMode::DisabledEphemeral => RemoteControlDesiredState::Disabled,
+                RemoteControlStartupMode::EnabledEphemeral => {
+                    normalize_remote_control_url(&config.remote_control_url)?;
+                    RemoteControlDesiredState::Enabled {
+                        persistence_preference: None,
+                    }
+                }
+            }
+        };
+    let (status, _) = watch::channel(RemoteControlStatusChangedNotification {
+        status: RemoteControlConnectionStatus::Disabled,
+        server_name: gethostname().to_string_lossy().trim().to_string(),
+        installation_id: config.installation_id.clone(),
+        environment_id: None,
+    });
+    let inner = Arc::new(RemoteControl {
+        config,
+        state_db,
+        auth_manager,
+        transport_event_tx,
+        shutdown: shutdown_token,
+        tasks: TaskTracker::new(),
+        current: StdMutex::new(None),
+        startup,
+        persistence: RemoteControlPersistence::default(),
+        client_name: watch::channel(None).0,
+        requires_client_name: app_server_client_name_rx.is_some(),
+        status,
+        session_changed: watch::channel(()).0,
+    });
+    inner.session();
+    if let Some(rx) = app_server_client_name_rx {
+        let names = inner.client_name.clone();
+        let shutdown = inner.shutdown.clone();
+        inner.tasks.spawn(async move {
+            tokio::select! {
+                _ = shutdown.cancelled() => {}
+                name = rx => match name {
+                    Ok(name) => { names.send_replace(Some(name)); }
+                    Err(_) => shutdown.cancel(),
+                }
+            }
+        });
+    }
+    let handle = RemoteControlHandle {
+        inner: inner.clone(),
+    };
+    let task = tokio::spawn(async move {
+        let mut session_changed = inner.session_changed.subscribe();
+        loop {
+            // Reconcile on both API entry and notification delivery, so watcher latency is harmless.
+            let session = inner.session();
+            let mut status = session.status_receiver();
+            session_changed.borrow_and_update();
+            {
+                let current = inner
+                    .current
+                    .lock()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner);
+                if current
+                    .as_ref()
+                    .is_some_and(|current| Arc::ptr_eq(&current.session, &session))
+                    && session.auth_manager.owner.is_current()
+                {
+                    inner.status.send_if_modified(|current| {
+                        let next = status.borrow_and_update().clone();
+                        if *current == next {
+                            return false;
+                        }
+                        *current = next;
+                        true
+                    });
+                }
+            }
+            tokio::select! {
+                biased;
+                _ = inner.shutdown.cancelled() => break,
+                _ = session.auth_manager.owner.invalidated() => {}
+                _ = session_changed.changed() => {}
+                _ = status.changed() => {}
+            }
+        }
+        inner.tasks.close();
+        inner.tasks.wait().await;
+        inner.persistence.tasks.close();
+        inner.persistence.tasks.wait().await;
+    });
+    Ok((task, handle))
+}

codex-rs/app-server-transport/src/transport/remote_control/desired_state.rs

@@ -0,0 +1,155 @@
+use super::RemoteControlEnableError;
+use super::RemoteControlSession;
+use super::RemoteControlUnavailable;
+use super::protocol::normalize_remote_control_url;
+use super::publish_current_enrollment;
+use super::websocket::RemoteControlStatusPublisher;
+use codex_app_server_protocol::RemoteControlStatusChangedNotification;
+use codex_state::RemoteControlEnrollmentRecord;
+use std::io;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum RemoteControlDesiredState {
+    // `Unknown` exists only on plain startup before auth and enrollment scope resolve. Persisted
+    // `1` is `Enabled { persistence_preference: Some(true) }`; `0`, `NULL`, or no row are
+    // `Disabled`. Runtime-only enable is `Enabled { persistence_preference: None }`, so new rows
+    // keep `NULL`; durable RPC enable uses `Some(true)`, so new rows get `1`. Durable disable writes
+    // `0` before entering `Disabled`; runtime-only disable does not write. `Disabled` carries no
+    // preference because disabled sessions do not create enrollments.
+    Unknown,
+    Disabled,
+    Enabled {
+        persistence_preference: Option<bool>,
+    },
+}
+impl RemoteControlDesiredState {
+    pub(super) fn is_enabled(self) -> bool {
+        matches!(self, Self::Enabled { .. })
+    }
+}
+
+pub(super) fn desired_state_from_persisted_enrollment(
+    enrollment: Option<RemoteControlEnrollmentRecord>,
+) -> RemoteControlDesiredState {
+    if enrollment.and_then(|enrollment| enrollment.remote_control_enabled) == Some(true) {
+        RemoteControlDesiredState::Enabled {
+            persistence_preference: Some(true),
+        }
+    } else {
+        RemoteControlDesiredState::Disabled
+    }
+}
+
+impl RemoteControlSession {
+    pub async fn resolve_persisted_preference(
+        &self,
+        app_server_client_name: Option<&str>,
+    ) -> io::Result<bool> {
+        if self.ensure_remote_control_allowed().is_err() {
+            return Ok(false);
+        }
+        let _transition = self
+            .desired_state_rpc_lock
+            .acquire()
+            .await
+            .unwrap_or_else(|_| unreachable!());
+        if !matches!(
+            *self.desired_state_tx.borrow(),
+            RemoteControlDesiredState::Unknown
+        ) {
+            return Ok(self.desired_state_tx.borrow().is_enabled());
+        }
+
+        let state_db = self
+            .state_db
+            .as_deref()
+            .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, RemoteControlUnavailable))?;
+        let auth = super::auth::load_remote_control_auth(&self.auth_manager).await?;
+        let remote_control_target = normalize_remote_control_url(&self.remote_control_url)?;
+        let app_server_client_name = self.pairing_persistence_key(app_server_client_name)?;
+        let _persistence =
+            super::persistence::read_lock(&self.auth_manager, &self.persistence).await?;
+        let enrollment = state_db
+            .get_remote_control_enrollment(
+                &remote_control_target.websocket_url,
+                &auth.account_id,
+                app_server_client_name.as_deref(),
+            )
+            .await
+            .map_err(io::Error::other)?;
+        let desired_state = desired_state_from_persisted_enrollment(enrollment);
+        self.desired_state_tx.send_if_modified(|state| {
+            if !matches!(*state, RemoteControlDesiredState::Unknown) {
+                return false;
+            }
+            *state = desired_state;
+            true
+        });
+        Ok(self.desired_state_tx.borrow().is_enabled())
+    }
+
+    pub async fn enable(
+        &self,
+        app_server_client_name: Option<&str>,
+    ) -> io::Result<RemoteControlStatusChangedNotification> {
+        self.ensure_remote_control_allowed()
+            .map_err(|err| io::Error::new(io::ErrorKind::PermissionDenied, err))?;
+        let _transition = self
+            .desired_state_rpc_lock
+            .acquire()
+            .await
+            .unwrap_or_else(|_| unreachable!());
+        let state_db = self
+            .state_db
+            .as_deref()
+            .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, RemoteControlUnavailable))?;
+        let mut auth = super::auth::load_remote_control_auth(&self.auth_manager).await?;
+        let remote_control_target = normalize_remote_control_url(&self.remote_control_url)?;
+        let app_server_client_name = self.pairing_persistence_key(app_server_client_name)?;
+        let app_server_client_name = app_server_client_name.as_deref();
+        let status = self.status();
+        let mut current_enrollment = self.current_enrollment.lock().await;
+        let (enrollment, _) = self
+            .load_or_enroll_server(
+                &current_enrollment,
+                &mut auth,
+                &status.installation_id,
+                &status.server_name,
+                app_server_client_name,
+                super::RemoteControlEnrollmentSelection::ReuseOrCreate,
+            )
+            .await?;
+
+        let current_auth = super::auth::load_remote_control_auth(&self.auth_manager).await?;
+        if current_auth.account_id != auth.account_id {
+            return Err(io::Error::new(
+                io::ErrorKind::Interrupted,
+                "remote control account changed during enrollment",
+            ));
+        }
+
+        self.set_preference(
+            state_db,
+            &remote_control_target,
+            &auth.account_id,
+            app_server_client_name,
+            /*enabled*/ true,
+            Some(&enrollment),
+        )
+        .await?;
+        publish_current_enrollment(&mut current_enrollment, &enrollment);
+        self.enable_with_preference(Some(true)).map_err(|err| {
+            let kind = match err {
+                RemoteControlEnableError::Unavailable(_) => io::ErrorKind::NotFound,
+                RemoteControlEnableError::AuthenticationChanged => io::ErrorKind::Interrupted,
+                RemoteControlEnableError::DisabledByRequirements(_) => {
+                    io::ErrorKind::PermissionDenied
+                }
+            };
+            io::Error::new(kind, err)
+        })?;
+        RemoteControlStatusPublisher::new(self.status_tx.as_ref().clone())
+            .publish_environment_id(Some(enrollment.environment_id));
+        Ok(self.status())
+    }
+}

codex-rs/app-server-transport/src/transport/remote_control/enroll.rs

@@ -0,0 +1,770 @@
+use super::pairing_unavailable_error;
+use super::protocol::RemoteControlPairingStatusRequest;
+use super::protocol::RemoteControlPairingStatusResponse as BackendRemoteControlPairingStatusResponse;
+use super::protocol::RemoteControlTarget;
+use super::protocol::StartRemoteControlPairingRequest;
+use super::protocol::StartRemoteControlPairingResponse;
+use super::server_api::RemoteControlServerRequestError;
+use super::server_api::retry_after_with_jitter;
+use axum::http::HeaderMap;
+use axum::http::StatusCode;
+use codex_app_server_protocol::RemoteControlPairingStartResponse;
+use codex_app_server_protocol::RemoteControlPairingStatusResponse;
+use codex_login::default_client::create_client_without_request_logging;
+use codex_state::RemoteControlEnrollmentRecord;
+use codex_state::StateRuntime;
+use std::io;
+use std::io::ErrorKind;
+use time::OffsetDateTime;
+use time::format_description::well_known::Rfc3339;
+use tracing::info;
+use tracing::warn;
+
+const REMOTE_CONTROL_PAIRING_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+const REMOTE_CONTROL_RESPONSE_BODY_MAX_BYTES: usize = 4096;
+const REMOTE_CONTROL_SERVER_TOKEN_REFRESH_SKEW_SECS: i64 = 5 * 60;
+
+const REQUEST_ID_HEADER: &str = "x-request-id";
+const OAI_REQUEST_ID_HEADER: &str = "x-oai-request-id";
+const CF_RAY_HEADER: &str = "cf-ray";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct RemoteControlEnrollment {
+    pub(super) remote_control_target: RemoteControlTarget,
+    pub(super) account_id: String,
+    pub(super) environment_id: String,
+    pub(super) server_id: String,
+    pub(super) server_name: String,
+    pub(super) remote_control_token: Option<String>,
+    pub(super) expires_at: Option<OffsetDateTime>,
+    pub(super) next_refresh_at: Option<OffsetDateTime>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(super) enum RemoteControlServerTokenRefreshRequirement {
+    Required,
+    Proactive,
+    NotNeeded,
+}
+
+impl RemoteControlEnrollment {
+    pub(super) async fn start_pairing(
+        &self,
+        request: StartRemoteControlPairingRequest,
+    ) -> io::Result<RemoteControlPairingStartResponse> {
+        if self.server_token_refresh_requirement()
+            == RemoteControlServerTokenRefreshRequirement::Required
+        {
+            return Err(pairing_unavailable_error());
+        }
+        let remote_control_token = self
+            .remote_control_token
+            .as_deref()
+            .ok_or_else(pairing_unavailable_error)?;
+
+        let response = create_client_without_request_logging()
+            .post(&self.remote_control_target.pair_url)
+            .timeout(REMOTE_CONTROL_PAIRING_TIMEOUT)
+            .bearer_auth(remote_control_token)
+            .json(&request)
+            .send()
+            .await
+            .map_err(|err| {
+                io::Error::other(format!(
+                    "failed to start remote control pairing at `{}`: {err}",
+                    self.remote_control_target.pair_url
+                ))
+            })?;
+        let headers = response.headers().clone();
+        let status = response.status();
+        let retry_at = retry_after_with_jitter(&headers, OffsetDateTime::now_utc());
+        let body = response.bytes().await.map_err(|err| {
+            pairing_response_error(
+                format!(
+                    "failed to read remote control pairing response from `{}`: {err}",
+                    self.remote_control_target.pair_url
+                ),
+                status,
+                retry_at,
+                ErrorKind::Other,
+            )
+        })?;
+        let body_preview = preview_remote_control_response_body(&body);
+        if !status.is_success() {
+            let error_kind = match status.as_u16() {
+                401 | 403 => ErrorKind::PermissionDenied,
+                404 => ErrorKind::NotFound,
+                _ => ErrorKind::Other,
+            };
+            return Err(pairing_response_error(
+                format!(
+                    "remote control pairing failed at `{}`: HTTP {status}, {}, body: {body_preview}",
+                    self.remote_control_target.pair_url,
+                    format_headers(&headers)
+                ),
+                status,
+                retry_at,
+                error_kind,
+            ));
+        }
+
+        let pairing = serde_json::from_slice::<StartRemoteControlPairingResponse>(&body).map_err(
+            |err| {
+                io::Error::other(format!(
+                    "failed to parse remote control pairing response from `{}`: HTTP {status}, {}, body: {body_preview}, decode error: {err}",
+                    self.remote_control_target.pair_url,
+                    format_headers(&headers)
+                ))
+            },
+        )?;
+        let StartRemoteControlPairingResponse {
+            pairing_code,
+            manual_pairing_code,
+            server_id,
+            environment_id,
+            expires_at,
+        } = pairing;
+        if server_id != self.server_id || environment_id != self.environment_id {
+            return Err(io::Error::other(format!(
+                "remote control pairing returned mismatched enrollment: expected server_id={}, environment_id={}; got server_id={}, environment_id={}",
+                self.server_id, self.environment_id, server_id, environment_id
+            )));
+        }
+        let expires_at = OffsetDateTime::parse(&expires_at, &Rfc3339)
+            .map_err(|err| {
+                io::Error::new(
+                    ErrorKind::InvalidData,
+                    format!(
+                        "failed to parse remote control pairing response from `{}`: HTTP {status}, {}, body: {body_preview}, expires_at parse error: {err}",
+                        self.remote_control_target.pair_url,
+                        format_headers(&headers)
+                    ),
+                )
+            })?
+            .unix_timestamp();
+
+        Ok(RemoteControlPairingStartResponse {
+            pairing_code,
+            manual_pairing_code,
+            environment_id,
+            expires_at,
+        })
+    }
+
+    pub(super) async fn pairing_status(
+        &self,
+        request: RemoteControlPairingStatusRequest,
+    ) -> io::Result<RemoteControlPairingStatusResponse> {
+        if self.server_token_refresh_requirement()
+            == RemoteControlServerTokenRefreshRequirement::Required
+        {
+            return Err(pairing_unavailable_error());
+        }
+        let remote_control_token = self
+            .remote_control_token
+            .as_deref()
+            .ok_or_else(pairing_unavailable_error)?;
+
+        let response = create_client_without_request_logging()
+            .post(&self.remote_control_target.pair_status_url)
+            .timeout(REMOTE_CONTROL_PAIRING_TIMEOUT)
+            .bearer_auth(remote_control_token)
+            .json(&request)
+            .send()
+            .await
+            .map_err(|err| {
+                io::Error::other(format!(
+                    "failed to check remote control pairing status at `{}`: {err}",
+                    self.remote_control_target.pair_status_url
+                ))
+            })?;
+        let headers = response.headers().clone();
+        let status = response.status();
+        let retry_at = retry_after_with_jitter(&headers, OffsetDateTime::now_utc());
+        let body = response.bytes().await.map_err(|err| {
+            pairing_response_error(
+                format!(
+                    "failed to read remote control pairing status response from `{}`: {err}",
+                    self.remote_control_target.pair_status_url
+                ),
+                status,
+                retry_at,
+                ErrorKind::Other,
+            )
+        })?;
+        let body_preview = preview_remote_control_response_body(&body);
+        if !status.is_success() {
+            let error_kind = match status.as_u16() {
+                401 | 403 => ErrorKind::PermissionDenied,
+                404 | 410 => ErrorKind::InvalidInput,
+                _ => ErrorKind::Other,
+            };
+            return Err(pairing_response_error(
+                format!(
+                    "remote control pairing status failed at `{}`: HTTP {status}, {}, body: {body_preview}",
+                    self.remote_control_target.pair_status_url,
+                    format_headers(&headers)
+                ),
+                status,
+                retry_at,
+                error_kind,
+            ));
+        }
+
+        let response = serde_json::from_slice::<BackendRemoteControlPairingStatusResponse>(&body)
+            .map_err(|err| {
+                io::Error::other(format!(
+                    "failed to parse remote control pairing status response from `{}`: HTTP {status}, {}, body: {body_preview}, decode error: {err}",
+                    self.remote_control_target.pair_status_url,
+                    format_headers(&headers)
+                ))
+            })?;
+        Ok(RemoteControlPairingStatusResponse {
+            claimed: response.claimed,
+        })
+    }
+
+    pub(super) fn server_token_refresh_requirement(
+        &self,
+    ) -> RemoteControlServerTokenRefreshRequirement {
+        self.server_token_refresh_requirement_at(OffsetDateTime::now_utc())
+    }
+
+    pub(super) fn should_refresh_server_token(&self) -> bool {
+        self.server_token_refresh_requirement()
+            != RemoteControlServerTokenRefreshRequirement::NotNeeded
+    }
+
+    pub(super) fn server_token_refresh_requirement_at(
+        &self,
+        now: OffsetDateTime,
+    ) -> RemoteControlServerTokenRefreshRequirement {
+        let Some(expires_at) = self.remote_control_token.as_ref().and(self.expires_at) else {
+            return RemoteControlServerTokenRefreshRequirement::Required;
+        };
+        if expires_at <= now {
+            return RemoteControlServerTokenRefreshRequirement::Required;
+        }
+        if expires_at > now + time::Duration::seconds(REMOTE_CONTROL_SERVER_TOKEN_REFRESH_SKEW_SECS)
+            || self
+                .next_refresh_at
+                .is_some_and(|next_refresh_at| next_refresh_at > now)
+        {
+            return RemoteControlServerTokenRefreshRequirement::NotNeeded;
+        }
+        RemoteControlServerTokenRefreshRequirement::Proactive
+    }
+
+    pub(super) fn clear_server_token(&mut self) {
+        self.remote_control_token = None;
+        self.expires_at = None;
+    }
+}
+
+fn pairing_response_error(
+    message: String,
+    status: StatusCode,
+    retry_at: Option<OffsetDateTime>,
+    fallback_kind: ErrorKind,
+) -> io::Error {
+    if matches!(
+        status,
+        StatusCode::TOO_MANY_REQUESTS | StatusCode::SERVICE_UNAVAILABLE
+    ) {
+        RemoteControlServerRequestError::io_error(
+            message,
+            Some(status),
+            retry_at,
+            /*timed_out*/ false,
+        )
+    } else {
+        io::Error::new(fallback_kind, message)
+    }
+}
+
+pub(super) async fn load_persisted_remote_control_enrollment(
+    state_db: Option<&StateRuntime>,
+    remote_control_target: &RemoteControlTarget,
+    account_id: &str,
+    app_server_client_name: Option<&str>,
+) -> io::Result<Option<RemoteControlEnrollment>> {
+    let Some(state_db) = state_db else {
+        return Err(io::Error::new(
+            ErrorKind::NotFound,
+            format!(
+                "remote control enrollment cache unavailable because sqlite state db is disabled: websocket_url={}, account_id={}, app_server_client_name={:?}",
+                remote_control_target.websocket_url, account_id, app_server_client_name
+            ),
+        ));
+    };
+    let enrollment = match state_db
+        .get_remote_control_enrollment(
+            &remote_control_target.websocket_url,
+            account_id,
+            app_server_client_name,
+        )
+        .await
+    {
+        Ok(enrollment) => enrollment,
+        Err(err) => {
+            warn!(
+                "failed to load persisted remote control enrollment: websocket_url={}, account_id={}, app_server_client_name={:?}, err={err}",
+                remote_control_target.websocket_url, account_id, app_server_client_name
+            );
+            return Err(io::Error::other(err));
+        }
+    };
+
+    match enrollment {
+        Some(enrollment) => {
+            info!(
+                "reusing persisted remote control enrollment: websocket_url={}, account_id={}, app_server_client_name={:?}, server_id={}, environment_id={}",
+                remote_control_target.websocket_url,
+                account_id,
+                app_server_client_name,
+                enrollment.server_id,
+                enrollment.environment_id
+            );
+            Ok(Some(RemoteControlEnrollment {
+                remote_control_target: remote_control_target.clone(),
+                account_id: enrollment.account_id,
+                environment_id: enrollment.environment_id,
+                server_id: enrollment.server_id,
+                server_name: enrollment.server_name,
+                remote_control_token: None,
+                expires_at: None,
+                next_refresh_at: None,
+            }))
+        }
+        None => {
+            info!(
+                "no persisted remote control enrollment found: websocket_url={}, account_id={}, app_server_client_name={:?}",
+                remote_control_target.websocket_url, account_id, app_server_client_name
+            );
+            Ok(None)
+        }
+    }
+}
+
+pub(super) async fn update_persisted_remote_control_enrollment(
+    state_db: Option<&StateRuntime>,
+    remote_control_target: &RemoteControlTarget,
+    account_id: &str,
+    app_server_client_name: Option<&str>,
+    enrollment: Option<&RemoteControlEnrollment>,
+    remote_control_enabled: Option<bool>,
+) -> io::Result<()> {
+    let Some(state_db) = state_db else {
+        return Err(io::Error::new(
+            ErrorKind::NotFound,
+            format!(
+                "remote control enrollment persistence unavailable because sqlite state db is disabled: websocket_url={}, account_id={}, app_server_client_name={:?}, has_enrollment={}",
+                remote_control_target.websocket_url,
+                account_id,
+                app_server_client_name,
+                enrollment.is_some()
+            ),
+        ));
+    };
+    if let &Some(enrollment) = &enrollment
+        && enrollment.account_id != account_id
+    {
+        return Err(io::Error::other(format!(
+            "enrollment account_id does not match expected account_id `{account_id}`"
+        )));
+    }
+
+    if let Some(enrollment) = enrollment {
+        state_db
+            .upsert_remote_control_enrollment(&RemoteControlEnrollmentRecord {
+                websocket_url: remote_control_target.websocket_url.clone(),
+                account_id: account_id.to_string(),
+                app_server_client_name: app_server_client_name.map(str::to_string),
+                server_id: enrollment.server_id.clone(),
+                environment_id: enrollment.environment_id.clone(),
+                server_name: enrollment.server_name.clone(),
+                remote_control_enabled,
+            })
+            .await
+            .map_err(io::Error::other)?;
+        info!(
+            "persisted remote control enrollment: websocket_url={}, account_id={}, app_server_client_name={:?}, server_id={}, environment_id={}",
+            remote_control_target.websocket_url,
+            account_id,
+            app_server_client_name,
+            enrollment.server_id,
+            enrollment.environment_id
+        );
+        Ok(())
+    } else {
+        let rows_affected = state_db
+            .delete_remote_control_enrollment(
+                &remote_control_target.websocket_url,
+                account_id,
+                app_server_client_name,
+            )
+            .await
+            .map_err(io::Error::other)?;
+        info!(
+            "cleared persisted remote control enrollment: websocket_url={}, account_id={}, app_server_client_name={:?}, rows_affected={rows_affected}",
+            remote_control_target.websocket_url, account_id, app_server_client_name
+        );
+        Ok(())
+    }
+}
+
+pub(crate) fn preview_remote_control_response_body(body: &[u8]) -> String {
+    let body = String::from_utf8_lossy(body);
+    let trimmed = body.trim();
+    if trimmed.is_empty() {
+        return "<empty>".to_string();
+    }
+    let redacted = redact_remote_control_response_body(trimmed);
+    if redacted.len() <= REMOTE_CONTROL_RESPONSE_BODY_MAX_BYTES {
+        return redacted;
+    }
+
+    let mut cut = REMOTE_CONTROL_RESPONSE_BODY_MAX_BYTES;
+    while !redacted.is_char_boundary(cut) {
+        cut = cut.saturating_sub(1);
+    }
+    let mut truncated = redacted[..cut].to_string();
+    truncated.push_str("...");
+    truncated
+}
+
+fn redact_remote_control_response_body(body: &str) -> String {
+    let Ok(mut body_json) = serde_json::from_str::<serde_json::Value>(body) else {
+        return body.to_string();
+    };
+    let Some(body_object) = body_json.as_object_mut() else {
+        return body.to_string();
+    };
+    for sensitive_field in [
+        "remote_control_token",
+        "pairing_code",
+        "manual_pairing_code",
+    ] {
+        if let Some(value) = body_object.get_mut(sensitive_field) {
+            *value = serde_json::Value::String("<redacted>".to_string());
+        }
+    }
+    body_json.to_string()
+}
+
+pub(crate) fn format_headers(headers: &HeaderMap) -> String {
+    let request_id_str = headers
+        .get(REQUEST_ID_HEADER)
+        .or_else(|| headers.get(OAI_REQUEST_ID_HEADER))
+        .map(|value| value.to_str().unwrap_or("<invalid utf-8>").to_owned())
+        .unwrap_or_else(|| "<none>".to_owned());
+    let cf_ray_str = headers
+        .get(CF_RAY_HEADER)
+        .map(|value| value.to_str().unwrap_or("<invalid utf-8>").to_owned())
+        .unwrap_or_else(|| "<none>".to_owned());
+    format!("request-id: {request_id_str}, cf-ray: {cf_ray_str}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::transport::remote_control::auth::RemoteControlConnectionAuth;
+    use crate::transport::remote_control::protocol::normalize_remote_control_url;
+    use crate::transport::remote_control::server_api::enroll_remote_control_server;
+    use codex_state::StateRuntime;
+    use codex_utils_absolute_path::test_support::PathExt;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+    use std::sync::Arc;
+    use tempfile::TempDir;
+    use tokio::io::AsyncBufReadExt;
+    use tokio::io::AsyncWriteExt;
+    use tokio::io::BufReader;
+    use tokio::net::TcpListener;
+    use tokio::net::TcpStream;
+    use tokio::time::Duration;
+    use tokio::time::timeout;
+
+    async fn remote_control_state_runtime(codex_home: &TempDir) -> Arc<StateRuntime> {
+        StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(codex_home.path().abs()),
+            "test-provider".to_string(),
+        )
+        .await
+        .expect("state runtime should initialize")
+    }
+
+    #[test]
+    fn preview_remote_control_response_body_redacts_server_token() {
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&preview_remote_control_response_body(
+                br#"{"server_id":"srv_e_test","remote_control_token":"secret","pairing_code":"pairing-code","manual_pairing_code":"ABCD-EFGH"}"#
+            ))
+            .expect("redacted response preview should stay valid json"),
+            json!({
+                "server_id": "srv_e_test",
+                "remote_control_token": "<redacted>",
+                "pairing_code": "<redacted>",
+                "manual_pairing_code": "<redacted>",
+            })
+        );
+    }
+
+    #[tokio::test]
+    async fn persisted_remote_control_enrollment_round_trips_by_target_and_account() {
+        let codex_home = TempDir::new().expect("temp dir should create");
+        let state_db = remote_control_state_runtime(&codex_home).await;
+        let first_target = normalize_remote_control_url("https://chatgpt.com/remote/control")
+            .expect("first target should parse");
+        let second_target =
+            normalize_remote_control_url("https://api.chatgpt-staging.com/other/control")
+                .expect("second target should parse");
+        let first_enrollment = RemoteControlEnrollment {
+            remote_control_target: first_target.clone(),
+            account_id: "account-a".to_string(),
+            environment_id: "env_first".to_string(),
+            server_id: "srv_e_first".to_string(),
+            server_name: "first-server".to_string(),
+            remote_control_token: None,
+            expires_at: None,
+            next_refresh_at: None,
+        };
+        let second_enrollment = RemoteControlEnrollment {
+            remote_control_target: second_target.clone(),
+            account_id: "account-a".to_string(),
+            environment_id: "env_second".to_string(),
+            server_id: "srv_e_second".to_string(),
+            server_name: "second-server".to_string(),
+            remote_control_token: None,
+            expires_at: None,
+            next_refresh_at: None,
+        };
+
+        update_persisted_remote_control_enrollment(
+            Some(state_db.as_ref()),
+            &first_target,
+            "account-a",
+            Some("desktop-client"),
+            Some(&first_enrollment),
+            /*remote_control_enabled*/ None,
+        )
+        .await
+        .expect("first enrollment should persist");
+        update_persisted_remote_control_enrollment(
+            Some(state_db.as_ref()),
+            &second_target,
+            "account-a",
+            Some("desktop-client"),
+            Some(&second_enrollment),
+            /*remote_control_enabled*/ None,
+        )
+        .await
+        .expect("second enrollment should persist");
+
+        assert_eq!(
+            load_persisted_remote_control_enrollment(
+                Some(state_db.as_ref()),
+                &first_target,
+                "account-a",
+                Some("desktop-client"),
+            )
+            .await
+            .expect("first enrollment should load"),
+            Some(first_enrollment.clone())
+        );
+        assert_eq!(
+            load_persisted_remote_control_enrollment(
+                Some(state_db.as_ref()),
+                &first_target,
+                "account-b",
+                Some("desktop-client"),
+            )
+            .await
+            .expect("missing account should load"),
+            None
+        );
+        assert_eq!(
+            load_persisted_remote_control_enrollment(
+                Some(state_db.as_ref()),
+                &second_target,
+                "account-a",
+                Some("desktop-client"),
+            )
+            .await
+            .expect("second enrollment should load"),
+            Some(second_enrollment)
+        );
+    }
+
+    #[tokio::test]
+    async fn clearing_persisted_remote_control_enrollment_removes_only_matching_entry() {
+        let codex_home = TempDir::new().expect("temp dir should create");
+        let state_db = remote_control_state_runtime(&codex_home).await;
+        let first_target = normalize_remote_control_url("https://chatgpt.com/remote/control")
+            .expect("first target should parse");
+        let second_target =
+            normalize_remote_control_url("https://api.chatgpt-staging.com/other/control")
+                .expect("second target should parse");
+        let first_enrollment = RemoteControlEnrollment {
+            remote_control_target: first_target.clone(),
+            account_id: "account-a".to_string(),
+            environment_id: "env_first".to_string(),
+            server_id: "srv_e_first".to_string(),
+            server_name: "first-server".to_string(),
+            remote_control_token: None,
+            expires_at: None,
+            next_refresh_at: None,
+        };
+        let second_enrollment = RemoteControlEnrollment {
+            remote_control_target: second_target.clone(),
+            account_id: "account-a".to_string(),
+            environment_id: "env_second".to_string(),
+            server_id: "srv_e_second".to_string(),
+            server_name: "second-server".to_string(),
+            remote_control_token: None,
+            expires_at: None,
+            next_refresh_at: None,
+        };
+
+        update_persisted_remote_control_enrollment(
+            Some(state_db.as_ref()),
+            &first_target,
+            "account-a",
+            /*app_server_client_name*/ None,
+            Some(&first_enrollment),
+            /*remote_control_enabled*/ None,
+        )
+        .await
+        .expect("first enrollment should persist");
+        update_persisted_remote_control_enrollment(
+            Some(state_db.as_ref()),
+            &second_target,
+            "account-a",
+            /*app_server_client_name*/ None,
+            Some(&second_enrollment),
+            /*remote_control_enabled*/ None,
+        )
+        .await
+        .expect("second enrollment should persist");
+
+        update_persisted_remote_control_enrollment(
+            Some(state_db.as_ref()),
+            &first_target,
+            "account-a",
+            /*app_server_client_name*/ None,
+            /*enrollment*/ None,
+            /*remote_control_enabled*/ None,
+        )
+        .await
+        .expect("matching enrollment should clear");
+
+        assert_eq!(
+            load_persisted_remote_control_enrollment(
+                Some(state_db.as_ref()),
+                &first_target,
+                "account-a",
+                /*app_server_client_name*/ None,
+            )
+            .await
+            .expect("cleared enrollment should load"),
+            None
+        );
+        assert_eq!(
+            load_persisted_remote_control_enrollment(
+                Some(state_db.as_ref()),
+                &second_target,
+                "account-a",
+                /*app_server_client_name*/ None,
+            )
+            .await
+            .expect("remaining enrollment should load"),
+            Some(second_enrollment)
+        );
+    }
+
+    #[tokio::test]
+    async fn enroll_remote_control_server_parse_failure_includes_response_body() {
+        let listener = TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("listener should bind");
+        let remote_control_url = format!(
+            "http://127.0.0.1:{}/backend-api/",
+            listener
+                .local_addr()
+                .expect("listener should have a local addr")
+                .port()
+        );
+        let remote_control_target =
+            normalize_remote_control_url(&remote_control_url).expect("target should parse");
+        let enroll_url = remote_control_target.enroll_url.clone();
+        let response_body = json!({
+            "server_id": "srv_e_test",
+            "environment_id": "env_test",
+        });
+        let expected_body = response_body.to_string();
+        let server_task = tokio::spawn(async move {
+            let stream = accept_http_request(&listener).await;
+            respond_with_json(stream, response_body).await;
+        });
+
+        let err = enroll_remote_control_server(
+            &remote_control_target,
+            &RemoteControlConnectionAuth {
+                auth_provider: codex_model_provider::unauthenticated_auth_provider(),
+                account_id: "account_id".to_string(),
+            },
+            "11111111-1111-4111-8111-111111111111",
+            "test-server",
+        )
+        .await
+        .expect_err("invalid response should fail to parse");
+
+        server_task.await.expect("server task should succeed");
+        assert_eq!(
+            err.to_string(),
+            format!(
+                "failed to parse remote control server enrollment response from `{enroll_url}`: HTTP 200 OK, request-id: <none>, cf-ray: <none>, body: {expected_body}, decode error: missing field `remote_control_token` at line 1 column {}",
+                expected_body.len()
+            )
+        );
+    }
+
+    async fn accept_http_request(listener: &TcpListener) -> TcpStream {
+        let (stream, _) = timeout(Duration::from_secs(5), listener.accept())
+            .await
+            .expect("HTTP request should arrive in time")
+            .expect("listener accept should succeed");
+        let mut reader = BufReader::new(stream);
+
+        let mut request_line = String::new();
+        reader
+            .read_line(&mut request_line)
+            .await
+            .expect("request line should read");
+        loop {
+            let mut line = String::new();
+            reader
+                .read_line(&mut line)
+                .await
+                .expect("header line should read");
+            if line == "\r\n" {
+                break;
+            }
+        }
+
+        reader.into_inner()
+    }
+
+    async fn respond_with_json(mut stream: TcpStream, body: serde_json::Value) {
+        let body = body.to_string();
+        let response = format!(
+            "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{body}",
+            body.len()
+        );
+        stream
+            .write_all(response.as_bytes())
+            .await
+            .expect("response should write");
+        stream.flush().await.expect("response should flush");
+    }
+}

codex-rs/app-server-transport/src/transport/remote_control/host_device.rs

@@ -0,0 +1,74 @@
+#[cfg(any(target_os = "macos", test))]
+use serde::Deserialize;
+
+pub(super) const REMOTE_CONTROL_HOST_DEVICE_KIND_HEADER: &str = "x-codex-host-device-kind";
+#[cfg(any(target_os = "macos", test))]
+const MAC_MINI_HOST_DEVICE_KIND: &str = "mac_mini";
+
+#[cfg(any(target_os = "macos", test))]
+#[derive(Deserialize)]
+struct MacHardwareProfile {
+    #[serde(rename = "SPHardwareDataType")]
+    hardware: Vec<MacHardware>,
+}
+
+#[cfg(any(target_os = "macos", test))]
+#[derive(Deserialize)]
+struct MacHardware {
+    machine_name: String,
+}
+
+#[cfg(any(target_os = "macos", test))]
+fn host_device_kind_from_profile(profile: &[u8]) -> serde_json::Result<Option<&'static str>> {
+    let profile: MacHardwareProfile = serde_json::from_slice(profile)?;
+    Ok(profile
+        .hardware
+        .first()
+        .is_some_and(|hardware| hardware.machine_name == "Mac mini")
+        .then_some(MAC_MINI_HOST_DEVICE_KIND))
+}
+
+#[cfg(target_os = "macos")]
+pub(super) async fn host_device_kind() -> Option<&'static str> {
+    use std::process::Stdio;
+    use std::time::Duration;
+    use tokio::process::Command;
+    use tokio::sync::OnceCell;
+
+    static HOST_DEVICE_KIND: OnceCell<Option<&'static str>> = OnceCell::const_new();
+
+    HOST_DEVICE_KIND
+        .get_or_try_init(|| async {
+            let output = tokio::time::timeout(
+                Duration::from_secs(2),
+                Command::new("/usr/sbin/system_profiler")
+                    .args(["-detailLevel", "mini", "SPHardwareDataType", "-json"])
+                    .stdin(Stdio::null())
+                    .stderr(Stdio::null())
+                    .kill_on_drop(true)
+                    .output(),
+            )
+            .await
+            .map_err(|_| ())?
+            .map_err(|_| ())?;
+
+            if !output.status.success() {
+                return Err(());
+            }
+
+            host_device_kind_from_profile(&output.stdout).map_err(|_| ())
+        })
+        .await
+        .ok()
+        .copied()
+        .flatten()
+}
+
+#[cfg(not(target_os = "macos"))]
+pub(super) async fn host_device_kind() -> Option<&'static str> {
+    None
+}
+
+#[cfg(test)]
+#[path = "host_device_tests.rs"]
+mod tests;

codex-rs/app-server-transport/src/transport/remote_control/host_device_tests.rs

@@ -0,0 +1,38 @@
+use super::host_device_kind_from_profile;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn recognizes_only_the_exact_mac_mini_hardware_name() {
+    let mac_mini_profile = br#"{"SPHardwareDataType":[{"machine_name":"Mac mini"}]}"#;
+    let macbook_profile = br#"{"SPHardwareDataType":[{"machine_name":"MacBook Pro"}]}"#;
+    let misleading_profile = br#"{"SPHardwareDataType":[{"machine_name":"Not a Mac mini"}]}"#;
+
+    assert_eq!(
+        host_device_kind_from_profile(mac_mini_profile).expect("valid Mac mini hardware profile"),
+        Some("mac_mini")
+    );
+    assert_eq!(
+        host_device_kind_from_profile(macbook_profile).expect("valid MacBook hardware profile"),
+        None
+    );
+    assert_eq!(
+        host_device_kind_from_profile(misleading_profile)
+            .expect("valid non-Mac-mini hardware profile"),
+        None
+    );
+}
+
+#[test]
+fn ignores_missing_hardware_profiles() {
+    assert_eq!(
+        host_device_kind_from_profile(br#"{"SPHardwareDataType":[]}"#)
+            .expect("valid empty hardware profile"),
+        None
+    );
+}
+
+#[test]
+fn rejects_malformed_hardware_profiles_so_they_remain_retryable() {
+    assert!(host_device_kind_from_profile(br#"{"machine_name":"Mac mini"}"#).is_err());
+    assert!(host_device_kind_from_profile(b"not json").is_err());
+}

codex-rs/app-server-transport/src/transport/remote_control/mod.rs

@@ -0,0 +1,1002 @@
+mod auth;
+mod client_tracker;
+mod clients;
+mod controller;
+mod persistence;
+pub use controller::RemoteControlHandle;
+pub use controller::start_remote_control;
+mod desired_state;
+mod enroll;
+mod host_device;
+mod protocol;
+mod segment;
+mod server_api;
+mod websocket;
+
+use self::auth::load_remote_control_auth;
+use self::auth::recover_remote_control_auth;
+use self::desired_state::RemoteControlDesiredState;
+use self::enroll::RemoteControlEnrollment;
+use self::enroll::load_persisted_remote_control_enrollment;
+use self::persistence::RemoteControlPersistence;
+use self::server_api::enroll_remote_control_server;
+use self::server_api::refresh_remote_control_server;
+use crate::transport::remote_control::websocket::RemoteControlChannels;
+use crate::transport::remote_control::websocket::RemoteControlStatusPublisher;
+use crate::transport::remote_control::websocket::RemoteControlWebsocket;
+
+pub use self::protocol::ClientId;
+use self::protocol::RemoteControlPairingStatusCode;
+use self::protocol::ServerEvent;
+use self::protocol::StreamId;
+use self::protocol::normalize_remote_control_url;
+use super::CHANNEL_CAPACITY;
+use super::TransportEvent;
+use super::next_connection_id;
+use codex_app_server_protocol::RemoteControlClientsListParams;
+use codex_app_server_protocol::RemoteControlClientsListResponse;
+use codex_app_server_protocol::RemoteControlClientsRevokeParams;
+use codex_app_server_protocol::RemoteControlClientsRevokeResponse;
+use codex_app_server_protocol::RemoteControlConnectionStatus;
+use codex_app_server_protocol::RemoteControlPairingStartParams;
+use codex_app_server_protocol::RemoteControlPairingStartResponse;
+use codex_app_server_protocol::RemoteControlPairingStatusParams;
+use codex_app_server_protocol::RemoteControlPairingStatusResponse;
+use codex_app_server_protocol::RemoteControlStatusChangedNotification;
+use codex_login::AuthManager;
+use codex_state::StateRuntime;
+use gethostname::gethostname;
+use std::error::Error;
+use std::fmt;
+use std::io;
+use std::ops::Deref;
+use std::ops::DerefMut;
+use std::sync::Arc;
+use std::sync::Mutex as StdMutex;
+use tokio::sync::Semaphore;
+use tokio::sync::SemaphorePermit;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+use tokio::sync::watch;
+use tokio::task::JoinHandle;
+use tokio_util::sync::CancellationToken;
+use tracing::info;
+use tracing::warn;
+
+pub struct RemoteControlStartConfig {
+    pub remote_control_url: String,
+    pub installation_id: String,
+    pub policy: RemoteControlPolicy,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteControlPolicy {
+    #[default]
+    Allowed,
+    DisabledByRequirements,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteControlStartupMode {
+    ResolvePersisted,
+    DisabledEphemeral,
+    EnabledEphemeral,
+}
+
+/// Internal marker used by the daemon to disable remote control without requiring a new CLI flag.
+pub const REMOTE_CONTROL_DISABLED_ENV_VAR: &str =
+    "CODEX_INTERNAL_APP_SERVER_REMOTE_CONTROL_DISABLED";
+
+/// Reads and removes the daemon's internal disabled-start marker before worker threads start.
+pub fn take_remote_control_disabled_env() -> bool {
+    let disabled =
+        std::env::var_os(REMOTE_CONTROL_DISABLED_ENV_VAR).is_some_and(|value| value == "1");
+    // SAFETY: app-server calls this synchronously at process startup, before spawning threads.
+    unsafe { std::env::remove_var(REMOTE_CONTROL_DISABLED_ENV_VAR) };
+    disabled
+}
+
+pub(super) struct QueuedServerEnvelope {
+    pub(super) event: ServerEvent,
+    pub(super) client_id: ClientId,
+    pub(super) stream_id: StreamId,
+    pub(super) write_complete_tx: Option<oneshot::Sender<()>>,
+}
+
+#[derive(Clone)]
+struct RemoteControlSession {
+    policy: RemoteControlPolicy,
+    shutdown_token: CancellationToken,
+    desired_state_tx: Arc<watch::Sender<RemoteControlDesiredState>>,
+    desired_state_rpc_lock: Arc<Semaphore>,
+    persistence: RemoteControlPersistence,
+    status_tx: Arc<watch::Sender<RemoteControlStatusChangedNotification>>,
+    state_db: Option<Arc<StateRuntime>>,
+    remote_control_url: String,
+    current_enrollment: CurrentRemoteControlEnrollment,
+    pairing_persistence_key: RemoteControlPairingPersistenceKey,
+    pairing_persistence_key_required: bool,
+    auth_manager: auth::RemoteControlAuth,
+}
+
+// Pairing and websocket connect share one selected server so they cannot enroll or replace
+// different persisted rows while either path is awaiting backend I/O.
+type CurrentRemoteControlEnrollment = Arc<RemoteControlEnrollmentState>;
+type RemoteControlPairingPersistenceKey = watch::Sender<Option<String>>;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum RemoteControlEnrollmentSelection {
+    ReuseOrCreate,
+    ReplaceExisting,
+}
+
+struct RemoteControlEnrollmentState {
+    enrollment: StdMutex<Option<RemoteControlEnrollment>>,
+    // Keep an observed server deadline across enrollment replacement and enable transitions.
+    retry_at: StdMutex<Option<time::OffsetDateTime>>,
+    lock: Semaphore,
+}
+
+impl RemoteControlEnrollmentState {
+    fn new(enrollment: Option<RemoteControlEnrollment>) -> Self {
+        Self {
+            enrollment: StdMutex::new(enrollment),
+            retry_at: StdMutex::new(None),
+            lock: Semaphore::new(1),
+        }
+    }
+
+    async fn lock_for_request(&self) -> io::Result<RemoteControlEnrollmentLease<'_>> {
+        self.check_retry_after()?;
+        let lease = self.lock().await;
+        self.check_retry_after()?;
+        Ok(lease)
+    }
+
+    // Check immediately before admitting network work. Requests admitted before
+    // an overload response publishes its deadline may finish concurrently.
+    fn check_retry_after(&self) -> io::Result<()> {
+        let retry_at = *self
+            .retry_at
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Some(retry_at) = retry_at
+            && retry_at > time::OffsetDateTime::now_utc()
+        {
+            return Err(server_api::RemoteControlServerRequestError::retry_deferred(
+                retry_at,
+            ));
+        }
+        Ok(())
+    }
+
+    fn record_retry_after<T>(&self, result: io::Result<T>) -> io::Result<T> {
+        if let Err(err) = &result
+            && let Some(retry_at) = server_api::remote_control_retry_at(err)
+        {
+            let mut current_retry_at = self
+                .retry_at
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            *current_retry_at = Some(current_retry_at.map_or(retry_at, |at| at.max(retry_at)));
+        }
+        result
+    }
+
+    async fn lock(&self) -> RemoteControlEnrollmentLease<'_> {
+        let permit = match self.lock.acquire().await {
+            Ok(permit) => permit,
+            Err(_) => unreachable!("remote control enrollment lock should stay open"),
+        };
+        RemoteControlEnrollmentLease {
+            state: self,
+            enrollment: self.snapshot(),
+            _permit: permit,
+        }
+    }
+
+    fn snapshot(&self) -> Option<RemoteControlEnrollment> {
+        self.enrollment
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone()
+    }
+}
+
+struct RemoteControlEnrollmentLease<'a> {
+    state: &'a RemoteControlEnrollmentState,
+    enrollment: Option<RemoteControlEnrollment>,
+    _permit: SemaphorePermit<'a>,
+}
+
+impl Deref for RemoteControlEnrollmentLease<'_> {
+    type Target = Option<RemoteControlEnrollment>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.enrollment
+    }
+}
+
+impl DerefMut for RemoteControlEnrollmentLease<'_> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.enrollment
+    }
+}
+
+impl Drop for RemoteControlEnrollmentLease<'_> {
+    fn drop(&mut self) {
+        *self
+            .state
+            .enrollment
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner) = self.enrollment.take();
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RemoteControlUnavailable;
+
+impl fmt::Display for RemoteControlUnavailable {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "remote control cannot be enabled because sqlite state db is unavailable"
+        )
+    }
+}
+
+impl Error for RemoteControlUnavailable {}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RemoteControlDisabledByRequirements;
+
+impl fmt::Display for RemoteControlDisabledByRequirements {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "remote control is disabled by managed requirements")
+    }
+}
+
+impl Error for RemoteControlDisabledByRequirements {}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteControlEnableError {
+    Unavailable(RemoteControlUnavailable),
+    DisabledByRequirements(RemoteControlDisabledByRequirements),
+    AuthenticationChanged,
+}
+
+impl fmt::Display for RemoteControlEnableError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Unavailable(err) => err.fmt(f),
+            Self::DisabledByRequirements(err) => err.fmt(f),
+            Self::AuthenticationChanged => f.write_str("remote control authentication changed"),
+        }
+    }
+}
+
+impl Error for RemoteControlEnableError {}
+
+impl RemoteControlSession {
+    pub fn ensure_remote_control_allowed(&self) -> Result<(), RemoteControlDisabledByRequirements> {
+        match self.policy {
+            RemoteControlPolicy::Allowed => Ok(()),
+            RemoteControlPolicy::DisabledByRequirements => Err(RemoteControlDisabledByRequirements),
+        }
+    }
+
+    fn ensure_remote_control_allowed_io(&self) -> io::Result<()> {
+        self.ensure_remote_control_allowed()
+            .map_err(|err| io::Error::new(io::ErrorKind::PermissionDenied, err))
+    }
+
+    pub fn enable_ephemeral(
+        &self,
+    ) -> Result<RemoteControlStatusChangedNotification, RemoteControlEnableError> {
+        self.enable_with_preference(/*persistence_preference*/ None)
+    }
+
+    fn enable_with_preference(
+        &self,
+        persistence_preference: Option<bool>,
+    ) -> Result<RemoteControlStatusChangedNotification, RemoteControlEnableError> {
+        self.ensure_remote_control_allowed()
+            .map_err(RemoteControlEnableError::DisabledByRequirements)?;
+        if self.state_db.is_none() {
+            warn!("remote control cannot be enabled because sqlite state db is unavailable");
+            return Err(RemoteControlEnableError::Unavailable(
+                RemoteControlUnavailable,
+            ));
+        }
+
+        let mut effective_persistence_preference = persistence_preference;
+        self.auth_manager
+            .ensure_current()
+            .map_err(|_| RemoteControlEnableError::AuthenticationChanged)?;
+        let desired_state_changed = self.desired_state_tx.send_if_modified(|state| {
+            if effective_persistence_preference.is_none()
+                && matches!(
+                    *state,
+                    RemoteControlDesiredState::Enabled {
+                        persistence_preference: Some(true)
+                    }
+                )
+            {
+                effective_persistence_preference = Some(true);
+            }
+            let next_state = RemoteControlDesiredState::Enabled {
+                persistence_preference: effective_persistence_preference,
+            };
+            let changed = *state != next_state;
+            *state = next_state;
+            changed
+        });
+
+        let status = self.status();
+        info!(
+            desired_state_changed,
+            ?effective_persistence_preference,
+            current_status = ?status.status,
+            environment_id = ?status.environment_id,
+            installation_id = %status.installation_id,
+            server_name = %status.server_name,
+            "remote control enable requested"
+        );
+        if matches!(
+            status.status,
+            RemoteControlConnectionStatus::Connected | RemoteControlConnectionStatus::Connecting
+        ) {
+            return Ok(status);
+        }
+
+        Ok(self.publish_status(RemoteControlConnectionStatus::Connecting))
+    }
+
+    pub async fn disable(
+        &self,
+        app_server_client_name: Option<&str>,
+    ) -> io::Result<RemoteControlStatusChangedNotification> {
+        self.ensure_remote_control_allowed_io()?;
+        let _transition = self
+            .desired_state_rpc_lock
+            .acquire()
+            .await
+            .unwrap_or_else(|_| unreachable!());
+        self.persist_preference(
+            app_server_client_name,
+            /*remote_control_enabled*/ false,
+        )
+        .await?;
+        Ok(self.transition_disabled())
+    }
+
+    pub async fn disable_ephemeral(&self) -> RemoteControlStatusChangedNotification {
+        let _transition = self
+            .desired_state_rpc_lock
+            .acquire()
+            .await
+            .unwrap_or_else(|_| unreachable!());
+        let _persistence = self.persistence.lock().await;
+        self.transition_disabled()
+    }
+
+    fn transition_disabled(&self) -> RemoteControlStatusChangedNotification {
+        let desired_state_changed = self.desired_state_tx.send_if_modified(|state| {
+            let changed = *state != RemoteControlDesiredState::Disabled;
+            *state = RemoteControlDesiredState::Disabled;
+            changed
+        });
+        let status = self.status();
+        info!(
+            desired_state_changed,
+            current_status = ?status.status,
+            environment_id = ?status.environment_id,
+            installation_id = %status.installation_id,
+            server_name = %status.server_name,
+            "remote control disable requested"
+        );
+        self.publish_status(RemoteControlConnectionStatus::Disabled)
+    }
+
+    async fn persist_preference(
+        &self,
+        app_server_client_name: Option<&str>,
+        remote_control_enabled: bool,
+    ) -> io::Result<()> {
+        let state_db = self
+            .state_db
+            .as_deref()
+            .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, RemoteControlUnavailable))?;
+        let auth = load_remote_control_auth(&self.auth_manager).await?;
+        let remote_control_target = normalize_remote_control_url(&self.remote_control_url)?;
+        let app_server_client_name = self.pairing_persistence_key(app_server_client_name)?;
+        self.set_preference(
+            state_db,
+            &remote_control_target,
+            &auth.account_id,
+            app_server_client_name.as_deref(),
+            remote_control_enabled,
+            /*fallback_enrollment*/ None,
+        )
+        .await?;
+        Ok(())
+    }
+
+    pub fn status(&self) -> RemoteControlStatusChangedNotification {
+        self.status_tx.borrow().clone()
+    }
+
+    pub fn status_receiver(&self) -> watch::Receiver<RemoteControlStatusChangedNotification> {
+        self.status_tx.subscribe()
+    }
+
+    pub async fn start_pairing(
+        &self,
+        params: RemoteControlPairingStartParams,
+        app_server_client_name: Option<&str>,
+    ) -> io::Result<RemoteControlPairingStartResponse> {
+        self.ensure_remote_control_allowed_io()?;
+        if !self.desired_state_tx.borrow().is_enabled() {
+            return Err(Self::pairing_disabled_error());
+        }
+        let mut current_enrollment = self.current_enrollment.lock_for_request().await?;
+        let mut auth = load_remote_control_auth(&self.auth_manager)
+            .await
+            .map_err(|_| pairing_unavailable_error())?;
+        let status = self.status();
+        let installation_id = status.installation_id;
+        let app_server_client_name = self.pairing_persistence_key(app_server_client_name)?;
+        let app_server_client_name = app_server_client_name.as_deref();
+        let mut enrollment = self
+            .load_or_enroll_pairing_server(
+                &mut current_enrollment,
+                &mut auth,
+                &installation_id,
+                &status.server_name,
+                app_server_client_name,
+                RemoteControlEnrollmentSelection::ReuseOrCreate,
+            )
+            .await?;
+        if enrollment.should_refresh_server_token() {
+            let refresh_result = refresh_pairing_enrollment(
+                &mut current_enrollment,
+                &self.auth_manager,
+                &mut auth,
+                &installation_id,
+                &mut enrollment,
+            )
+            .await;
+            if refresh_result
+                .as_ref()
+                .is_err_and(|err| err.kind() == io::ErrorKind::NotFound)
+            {
+                enrollment = self
+                    .load_or_enroll_pairing_server(
+                        &mut current_enrollment,
+                        &mut auth,
+                        &installation_id,
+                        &status.server_name,
+                        app_server_client_name,
+                        RemoteControlEnrollmentSelection::ReplaceExisting,
+                    )
+                    .await?;
+            } else {
+                refresh_result?;
+            }
+        }
+        let pairing_request = || protocol::StartRemoteControlPairingRequest {
+            manual_code: params.manual_code,
+        };
+        self.current_enrollment.check_retry_after()?;
+        let pairing_response = match enrollment.start_pairing(pairing_request()).await {
+            Err(err) if err.kind() == io::ErrorKind::PermissionDenied => {
+                clear_pairing_server_token(&mut current_enrollment, &mut enrollment)?;
+                refresh_pairing_enrollment(
+                    &mut current_enrollment,
+                    &self.auth_manager,
+                    &mut auth,
+                    &installation_id,
+                    &mut enrollment,
+                )
+                .await?;
+                self.current_enrollment.check_retry_after()?;
+                enrollment.start_pairing(pairing_request()).await
+            }
+            Err(err) if err.kind() == io::ErrorKind::NotFound => {
+                enrollment = self
+                    .load_or_enroll_pairing_server(
+                        &mut current_enrollment,
+                        &mut auth,
+                        &installation_id,
+                        &status.server_name,
+                        app_server_client_name,
+                        RemoteControlEnrollmentSelection::ReplaceExisting,
+                    )
+                    .await?;
+                self.current_enrollment.check_retry_after()?;
+                enrollment.start_pairing(pairing_request()).await
+            }
+            pairing_response => pairing_response,
+        };
+        if let Err(err) = &pairing_response {
+            if server_api::remote_control_retry_at(err).is_some() {
+                return self.current_enrollment.record_retry_after(pairing_response);
+            }
+            match err.kind() {
+                io::ErrorKind::NotFound => {
+                    self.load_or_enroll_pairing_server(
+                        &mut current_enrollment,
+                        &mut auth,
+                        &installation_id,
+                        &status.server_name,
+                        app_server_client_name,
+                        RemoteControlEnrollmentSelection::ReplaceExisting,
+                    )
+                    .await?;
+                    return Err(pairing_unavailable_error());
+                }
+                io::ErrorKind::PermissionDenied => {
+                    clear_pairing_server_token(&mut current_enrollment, &mut enrollment)?;
+                    return Err(pairing_unavailable_error());
+                }
+                _ => {}
+            }
+        }
+        let current_auth = load_remote_control_auth(&self.auth_manager)
+            .await
+            .map_err(|_| pairing_unavailable_error())?;
+        if current_auth.account_id != auth.account_id {
+            return Err(pairing_unavailable_error());
+        }
+        if !self.desired_state_tx.borrow().is_enabled() {
+            return Err(Self::pairing_disabled_error());
+        }
+        pairing_response
+    }
+
+    async fn load_or_enroll_pairing_server(
+        &self,
+        current_enrollment: &mut Option<RemoteControlEnrollment>,
+        auth: &mut auth::RemoteControlConnectionAuth,
+        installation_id: &str,
+        server_name: &str,
+        app_server_client_name: Option<&str>,
+        selection: RemoteControlEnrollmentSelection,
+    ) -> io::Result<RemoteControlEnrollment> {
+        let (enrollment, created) = self
+            .load_or_enroll_server(
+                current_enrollment,
+                auth,
+                installation_id,
+                server_name,
+                app_server_client_name,
+                selection,
+            )
+            .await?;
+        if !created {
+            publish_current_enrollment(current_enrollment, &enrollment);
+            return Ok(enrollment);
+        }
+
+        let state_db = self
+            .state_db
+            .as_deref()
+            .ok_or_else(pairing_unavailable_error)?;
+        persistence::save_enrollment(
+            &self.auth_manager,
+            &self.persistence,
+            state_db,
+            &enrollment,
+            app_server_client_name,
+            &self.desired_state_tx,
+        )
+        .await?;
+        publish_current_enrollment(current_enrollment, &enrollment);
+        Ok(enrollment)
+    }
+
+    async fn load_or_enroll_server(
+        &self,
+        current_enrollment: &Option<RemoteControlEnrollment>,
+        auth: &mut auth::RemoteControlConnectionAuth,
+        installation_id: &str,
+        server_name: &str,
+        app_server_client_name: Option<&str>,
+        selection: RemoteControlEnrollmentSelection,
+    ) -> io::Result<(RemoteControlEnrollment, bool)> {
+        let remote_control_target = normalize_remote_control_url(&self.remote_control_url)?;
+        match selection {
+            RemoteControlEnrollmentSelection::ReuseOrCreate => {
+                if let Some(enrollment) = current_enrollment
+                    .as_ref()
+                    .filter(|enrollment| enrollment.account_id == auth.account_id)
+                    .cloned()
+                {
+                    return Ok((enrollment, false));
+                }
+
+                let state_db = self
+                    .state_db
+                    .as_deref()
+                    .ok_or_else(pairing_unavailable_error)?;
+                let _persistence =
+                    persistence::read_lock(&self.auth_manager, &self.persistence).await?;
+                if let Some(mut enrollment) = load_persisted_remote_control_enrollment(
+                    Some(state_db),
+                    &remote_control_target,
+                    &auth.account_id,
+                    app_server_client_name,
+                )
+                .await?
+                {
+                    enrollment.server_name = server_name.to_string();
+                    return Ok((enrollment, false));
+                }
+            }
+            RemoteControlEnrollmentSelection::ReplaceExisting => {}
+        }
+
+        self.current_enrollment.check_retry_after()?;
+        // Reused enrollments must still reach durable persistence during shutdown.
+        let enrollment = tokio::select! {
+            biased;
+            _ = self.shutdown_token.cancelled() => {
+                return Err(io::Error::new(
+                    io::ErrorKind::Interrupted,
+                    "remote control is shutting down",
+                ));
+            }
+            result = enroll_pairing_server(
+                &self.current_enrollment,
+                &self.auth_manager,
+                auth,
+                &remote_control_target,
+                installation_id,
+                server_name,
+            ) => self.current_enrollment.record_retry_after(result)?,
+        };
+        Ok((enrollment, true))
+    }
+
+    fn pairing_persistence_key(
+        &self,
+        app_server_client_name: Option<&str>,
+    ) -> io::Result<Option<String>> {
+        if self.pairing_persistence_key_required && self.pairing_persistence_key.borrow().is_none()
+        {
+            let app_server_client_name =
+                app_server_client_name.ok_or_else(pairing_unavailable_error)?;
+            self.pairing_persistence_key
+                .send_replace(Some(app_server_client_name.to_string()));
+        }
+        Ok(self.pairing_persistence_key.borrow().clone())
+    }
+
+    pub async fn pairing_status(
+        &self,
+        params: RemoteControlPairingStatusParams,
+    ) -> io::Result<RemoteControlPairingStatusResponse> {
+        self.ensure_remote_control_allowed_io()?;
+        if !self.desired_state_tx.borrow().is_enabled() {
+            return Err(Self::pairing_disabled_error());
+        }
+        let mut current_enrollment = self.current_enrollment.lock_for_request().await?;
+        let mut auth = load_remote_control_auth(&self.auth_manager)
+            .await
+            .map_err(|_| pairing_unavailable_error())?;
+        let app_server_client_name = self.pairing_persistence_key.borrow().clone();
+        let app_server_client_name = app_server_client_name.as_deref();
+        let mut enrollment = current_enrollment
+            .as_ref()
+            .filter(|enrollment| enrollment.account_id == auth.account_id)
+            .cloned()
+            .ok_or_else(pairing_unavailable_error)?;
+        let status = self.status();
+        let installation_id = status.installation_id;
+        let server_name = status.server_name;
+        if enrollment.should_refresh_server_token() {
+            let refresh_result = refresh_pairing_enrollment(
+                &mut current_enrollment,
+                &self.auth_manager,
+                &mut auth,
+                &installation_id,
+                &mut enrollment,
+            )
+            .await;
+            if refresh_result
+                .as_ref()
+                .is_err_and(|err| err.kind() == io::ErrorKind::NotFound)
+            {
+                self.load_or_enroll_pairing_server(
+                    &mut current_enrollment,
+                    &mut auth,
+                    &installation_id,
+                    &server_name,
+                    app_server_client_name,
+                    RemoteControlEnrollmentSelection::ReplaceExisting,
+                )
+                .await?;
+                return Err(pairing_unavailable_error());
+            }
+            refresh_result?;
+        }
+        let status_code = remote_control_pairing_status_code(&params)?;
+        let pairing_status_request =
+            || protocol::RemoteControlPairingStatusRequest::from(status_code.clone());
+        self.current_enrollment.check_retry_after()?;
+        let pairing_status_response =
+            match enrollment.pairing_status(pairing_status_request()).await {
+                Err(err) if err.kind() == io::ErrorKind::PermissionDenied => {
+                    clear_pairing_server_token(&mut current_enrollment, &mut enrollment)?;
+                    refresh_pairing_enrollment(
+                        &mut current_enrollment,
+                        &self.auth_manager,
+                        &mut auth,
+                        &installation_id,
+                        &mut enrollment,
+                    )
+                    .await?;
+                    self.current_enrollment.check_retry_after()?;
+                    enrollment.pairing_status(pairing_status_request()).await
+                }
+                pairing_status_response => pairing_status_response,
+            };
+        if let Err(err) = &pairing_status_response {
+            if server_api::remote_control_retry_at(err).is_some() {
+                return self
+                    .current_enrollment
+                    .record_retry_after(pairing_status_response);
+            }
+            match err.kind() {
+                io::ErrorKind::NotFound => {
+                    self.load_or_enroll_pairing_server(
+                        &mut current_enrollment,
+                        &mut auth,
+                        &installation_id,
+                        &server_name,
+                        app_server_client_name,
+                        RemoteControlEnrollmentSelection::ReplaceExisting,
+                    )
+                    .await?;
+                    return Err(pairing_unavailable_error());
+                }
+                io::ErrorKind::PermissionDenied => {
+                    clear_pairing_server_token(&mut current_enrollment, &mut enrollment)?;
+                    return Err(pairing_unavailable_error());
+                }
+                _ => {}
+            }
+        }
+        if !self.desired_state_tx.borrow().is_enabled() {
+            return Err(Self::pairing_disabled_error());
+        }
+        let current_auth = load_remote_control_auth(&self.auth_manager)
+            .await
+            .map_err(|_| pairing_unavailable_error())?;
+        if current_auth.account_id != auth.account_id {
+            return Err(pairing_unavailable_error());
+        }
+        pairing_status_response
+    }
+
+    pub async fn list_clients(
+        &self,
+        params: RemoteControlClientsListParams,
+    ) -> io::Result<RemoteControlClientsListResponse> {
+        self.ensure_remote_control_allowed_io()?;
+        clients::list_remote_control_clients(&self.remote_control_url, &self.auth_manager, params)
+            .await
+    }
+
+    pub async fn revoke_client(
+        &self,
+        params: RemoteControlClientsRevokeParams,
+    ) -> io::Result<RemoteControlClientsRevokeResponse> {
+        self.ensure_remote_control_allowed_io()?;
+        clients::revoke_remote_control_client(&self.remote_control_url, &self.auth_manager, params)
+            .await
+    }
+
+    fn pairing_disabled_error() -> io::Error {
+        io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "remote control pairing requires remote control to be enabled",
+        )
+    }
+
+    fn publish_status(
+        &self,
+        connection_status: RemoteControlConnectionStatus,
+    ) -> RemoteControlStatusChangedNotification {
+        let mut status_change = None;
+        self.status_tx.send_if_modified(|status| {
+            let next_status =
+                remote_control_status_with_connection_status(status, connection_status);
+            if *status == next_status {
+                return false;
+            }
+
+            status_change = Some((status.clone(), next_status.clone()));
+            *status = next_status;
+            true
+        });
+        if let Some((previous_status, next_status)) = status_change {
+            info!(
+                previous_status = ?previous_status.status,
+                next_status = ?next_status.status,
+                previous_environment_id = ?previous_status.environment_id,
+                next_environment_id = ?next_status.environment_id,
+                installation_id = %next_status.installation_id,
+                server_name = %next_status.server_name,
+                "remote control handle status changed"
+            );
+        }
+        self.status()
+    }
+}
+
+async fn enroll_pairing_server(
+    current_enrollment: &RemoteControlEnrollmentState,
+    auth_manager: &auth::RemoteControlAuth,
+    auth: &mut auth::RemoteControlConnectionAuth,
+    remote_control_target: &protocol::RemoteControlTarget,
+    installation_id: &str,
+    server_name: &str,
+) -> io::Result<RemoteControlEnrollment> {
+    match enroll_remote_control_server(remote_control_target, auth, installation_id, server_name)
+        .await
+    {
+        Ok(enrollment) => return Ok(enrollment),
+        Err(err) if err.kind() == io::ErrorKind::PermissionDenied => {
+            let mut auth_recovery = auth_manager.unauthorized_recovery();
+            let mut auth_change_rx = auth_manager.auth_change_receiver();
+            if !recover_remote_control_auth(&mut auth_recovery, &mut auth_change_rx).await {
+                return Err(err);
+            }
+            *auth = load_remote_control_auth(auth_manager)
+                .await
+                .map_err(|_| pairing_unavailable_error())?;
+        }
+        Err(err) => return Err(err),
+    }
+    current_enrollment.check_retry_after()?;
+    enroll_remote_control_server(remote_control_target, auth, installation_id, server_name).await
+}
+
+fn remote_control_pairing_status_code(
+    params: &RemoteControlPairingStatusParams,
+) -> io::Result<RemoteControlPairingStatusCode> {
+    match (&params.pairing_code, &params.manual_pairing_code) {
+        (Some(pairing_code), None) => Ok(RemoteControlPairingStatusCode::PairingCode(
+            pairing_code.clone(),
+        )),
+        (None, Some(manual_pairing_code)) => Ok(RemoteControlPairingStatusCode::ManualPairingCode(
+            manual_pairing_code.clone(),
+        )),
+        (Some(_), Some(_)) => Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "remote control pairing status accepts either pairingCode or manualPairingCode, not both",
+        )),
+        (None, None) => Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "remote control pairing status requires pairingCode or manualPairingCode",
+        )),
+    }
+}
+
+async fn refresh_pairing_enrollment(
+    current_enrollment: &mut RemoteControlEnrollmentLease<'_>,
+    auth_manager: &auth::RemoteControlAuth,
+    auth: &mut auth::RemoteControlConnectionAuth,
+    installation_id: &str,
+    enrollment: &mut RemoteControlEnrollment,
+) -> io::Result<()> {
+    current_enrollment.state.check_retry_after()?;
+    let mut refresh_result = refresh_remote_control_server(auth, installation_id, enrollment).await;
+    if refresh_result
+        .as_ref()
+        .is_err_and(|err| err.kind() == io::ErrorKind::PermissionDenied)
+    {
+        let mut auth_recovery = auth_manager.unauthorized_recovery();
+        let mut auth_change_rx = auth_manager.auth_change_receiver();
+        if recover_remote_control_auth(&mut auth_recovery, &mut auth_change_rx).await {
+            match load_remote_control_auth(auth_manager).await {
+                Ok(recovered_auth) if recovered_auth.account_id == enrollment.account_id => {
+                    *auth = recovered_auth;
+                    current_enrollment.state.check_retry_after()?;
+                    refresh_result =
+                        refresh_remote_control_server(auth, installation_id, enrollment).await;
+                }
+                Ok(_) | Err(_) => {
+                    enrollment.clear_server_token();
+                    refresh_result = Err(pairing_unavailable_error());
+                }
+            }
+        } else {
+            enrollment.clear_server_token();
+        }
+    }
+    if refresh_result
+        .as_ref()
+        .is_err_and(|err| err.kind() == io::ErrorKind::PermissionDenied)
+    {
+        enrollment.clear_server_token();
+    }
+    if !replace_current_enrollment(current_enrollment, enrollment) {
+        Err(pairing_unavailable_error())
+    } else {
+        current_enrollment.state.record_retry_after(refresh_result)
+    }
+}
+
+fn clear_pairing_server_token(
+    current_enrollment: &mut Option<RemoteControlEnrollment>,
+    enrollment: &mut RemoteControlEnrollment,
+) -> io::Result<()> {
+    enrollment.clear_server_token();
+    if replace_current_enrollment(current_enrollment, enrollment) {
+        Ok(())
+    } else {
+        Err(pairing_unavailable_error())
+    }
+}
+
+fn pairing_unavailable_error() -> io::Error {
+    io::Error::new(
+        io::ErrorKind::InvalidInput,
+        "remote control pairing is unavailable until enrollment completes",
+    )
+}
+
+fn remote_control_status_with_connection_status(
+    status: &RemoteControlStatusChangedNotification,
+    connection_status: RemoteControlConnectionStatus,
+) -> RemoteControlStatusChangedNotification {
+    RemoteControlStatusChangedNotification {
+        status: connection_status,
+        server_name: status.server_name.clone(),
+        installation_id: status.installation_id.clone(),
+        environment_id: if connection_status == RemoteControlConnectionStatus::Disabled {
+            None
+        } else {
+            status.environment_id.clone()
+        },
+    }
+}
+
+fn publish_current_enrollment(
+    current_enrollment: &mut Option<RemoteControlEnrollment>,
+    enrollment: &RemoteControlEnrollment,
+) {
+    *current_enrollment = Some(enrollment.clone());
+}
+
+fn replace_current_enrollment(
+    current_enrollment: &mut Option<RemoteControlEnrollment>,
+    enrollment: &RemoteControlEnrollment,
+) -> bool {
+    if !current_enrollment
+        .as_ref()
+        .is_some_and(|current| same_remote_control_enrollment(current, enrollment))
+    {
+        return false;
+    }
+    *current_enrollment = Some(enrollment.clone());
+    true
+}
+
+fn same_remote_control_enrollment(
+    left: &RemoteControlEnrollment,
+    right: &RemoteControlEnrollment,
+) -> bool {
+    // A refresh rotates only the bearer. Pairing remains current while the same persisted server
+    // record is still selected for the current account.
+    left.account_id == right.account_id
+        && left.server_id == right.server_id
+        && left.environment_id == right.environment_id
+}
+
+#[cfg(test)]
+mod segment_tests;
+#[cfg(test)]
+mod tests;

codex-rs/app-server-transport/src/transport/remote_control/persistence.rs

@@ -0,0 +1,165 @@
+//! Serializes enrollment storage across login sessions.
+//! An admitted SQLite write keeps its permit until completion even if its caller is cancelled.
+//! Process shutdown drains admitted writes after stopping the session workers.
+
+use super::RemoteControlSession;
+use super::auth::RemoteControlAuth;
+use super::desired_state::RemoteControlDesiredState;
+use super::enroll::RemoteControlEnrollment;
+use super::enroll::update_persisted_remote_control_enrollment;
+use super::protocol::RemoteControlTarget;
+use codex_state::StateRuntime;
+use std::future::Future;
+use std::io;
+use std::sync::Arc;
+use tokio::sync::Semaphore;
+use tokio::sync::SemaphorePermit;
+use tokio::sync::watch;
+use tokio_util::task::TaskTracker;
+
+#[cfg(test)]
+#[path = "persistence_tests.rs"]
+mod tests;
+
+#[derive(Clone)]
+pub(super) struct RemoteControlPersistence {
+    semaphore: Arc<Semaphore>,
+    pub(super) tasks: TaskTracker,
+}
+
+impl Default for RemoteControlPersistence {
+    fn default() -> Self {
+        Self {
+            semaphore: Arc::new(Semaphore::new(1)),
+            tasks: TaskTracker::new(),
+        }
+    }
+}
+
+impl RemoteControlPersistence {
+    pub(super) async fn lock(&self) -> SemaphorePermit<'_> {
+        self.semaphore
+            .acquire()
+            .await
+            .unwrap_or_else(|_| unreachable!())
+    }
+}
+
+pub(super) async fn read_lock<'a>(
+    auth: &RemoteControlAuth,
+    lock: &'a RemoteControlPersistence,
+) -> io::Result<SemaphorePermit<'a>> {
+    let permit = lock.lock().await;
+    auth.ensure_current()?;
+    Ok(permit)
+}
+
+async fn commit<T: Send + 'static>(
+    auth: &RemoteControlAuth,
+    lock: &RemoteControlPersistence,
+    operation: impl Future<Output = io::Result<T>> + Send + 'static,
+) -> io::Result<T> {
+    // Register before checking admission. Shutdown either observes this token or rejects us.
+    let task = lock.tasks.token();
+    if lock.tasks.is_closed() {
+        return Err(io::Error::new(
+            io::ErrorKind::Interrupted,
+            "remote control is shutting down",
+        ));
+    }
+    let auth = auth.clone();
+    let semaphore = lock.semaphore.clone();
+    tokio::spawn(async move {
+        let _task = task;
+        let _permit = semaphore.acquire_owned().await.map_err(io::Error::other)?;
+        auth.ensure_current()?;
+        operation.await
+    })
+    .await
+    .map_err(io::Error::other)?
+}
+
+pub(super) async fn save_enrollment(
+    auth: &RemoteControlAuth,
+    lock: &RemoteControlPersistence,
+    state_db: &StateRuntime,
+    enrollment: &RemoteControlEnrollment,
+    client_name: Option<&str>,
+    desired: &watch::Sender<RemoteControlDesiredState>,
+) -> io::Result<()> {
+    let state_db = state_db.clone();
+    let enrollment = enrollment.clone();
+    let client_name = client_name.map(str::to_owned);
+    let desired = desired.clone();
+    commit(auth, lock, async move {
+        let preference = match *desired.borrow() {
+            RemoteControlDesiredState::Enabled {
+                persistence_preference,
+            } => persistence_preference,
+            RemoteControlDesiredState::Disabled | RemoteControlDesiredState::Unknown => {
+                return Err(io::Error::new(
+                    io::ErrorKind::Interrupted,
+                    "remote control disabled during enrollment",
+                ));
+            }
+        };
+        update_persisted_remote_control_enrollment(
+            Some(&state_db),
+            &enrollment.remote_control_target,
+            &enrollment.account_id,
+            client_name.as_deref(),
+            Some(&enrollment),
+            preference,
+        )
+        .await
+    })
+    .await
+}
+
+impl RemoteControlSession {
+    pub(super) async fn set_preference(
+        &self,
+        state_db: &StateRuntime,
+        target: &RemoteControlTarget,
+        account_id: &str,
+        client_name: Option<&str>,
+        enabled: bool,
+        fallback_enrollment: Option<&RemoteControlEnrollment>,
+    ) -> io::Result<()> {
+        let state_db = state_db.clone();
+        let target = target.clone();
+        let account_id = account_id.to_owned();
+        let client_name = client_name.map(str::to_owned);
+        let enrollment = fallback_enrollment.cloned();
+        let desired = self.desired_state_tx.as_ref().clone();
+        commit(&self.auth_manager, &self.persistence, async move {
+            let updated = state_db
+                .set_remote_control_enabled(
+                    &target.websocket_url,
+                    &account_id,
+                    client_name.as_deref(),
+                    enabled,
+                )
+                .await
+                .map_err(io::Error::other)?;
+            if updated == 0
+                && let Some(enrollment) = enrollment
+            {
+                update_persisted_remote_control_enrollment(
+                    Some(&state_db),
+                    &target,
+                    &account_id,
+                    client_name.as_deref(),
+                    Some(&enrollment),
+                    Some(enabled),
+                )
+                .await?;
+            }
+            if !enabled {
+                desired.send_replace(RemoteControlDesiredState::Disabled);
+            }
+            Ok(())
+        })
+        .await
+    }
+}

codex-rs/app-server-transport/src/transport/remote_control/persistence_tests.rs

@@ -0,0 +1,51 @@
+//! Checks the persistence boundary when an operation loses its caller.
+
+use super::*;
+use codex_core::test_support::auth_manager_from_auth;
+use codex_login::CodexAuth;
+use futures::poll;
+use pretty_assertions::assert_eq;
+use tokio::sync::oneshot;
+
+#[tokio::test]
+async fn cancelled_commit_keeps_its_permit_and_is_drained() -> io::Result<()> {
+    let auth = RemoteControlAuth::capture(auth_manager_from_auth(
+        CodexAuth::create_dummy_chatgpt_auth_for_testing(),
+    ))
+    .0;
+    let persistence = RemoteControlPersistence::default();
+    let writes = Arc::new(tokio::sync::Mutex::new(Vec::new()));
+    let (started_tx, started_rx) = oneshot::channel();
+    let (release_tx, release_rx) = oneshot::channel();
+    let old_writes = writes.clone();
+    let mut old = Box::pin(commit(&auth, &persistence, async move {
+        started_tx.send(()).expect("test receiver is open");
+        release_rx.await.map_err(io::Error::other)?;
+        old_writes.lock().await.push("old");
+        Ok(())
+    }));
+    assert!(poll!(&mut old).is_pending());
+    started_rx.await.map_err(io::Error::other)?;
+    drop(old);
+
+    let new_writes = writes.clone();
+    let mut new = Box::pin(commit(&auth, &persistence, async move {
+        new_writes.lock().await.push("new");
+        Ok(())
+    }));
+    assert!(poll!(&mut new).is_pending());
+    persistence.tasks.close();
+    let mut drained = Box::pin(persistence.tasks.wait());
+    assert!(poll!(&mut drained).is_pending());
+    release_tx.send(()).expect("commit still owns its receiver");
+    tokio::time::timeout(std::time::Duration::from_secs(5), drained).await?;
+    new.await?;
+    assert_eq!(*writes.lock().await, vec!["old", "new"]);
+    let error = commit::<()>(&auth, &persistence, async {
+        panic!("closed storage must reject new work")
+    })
+    .await
+    .expect_err("shutdown closes admission");
+    assert_eq!(error.kind(), io::ErrorKind::Interrupted);
+    Ok(())
+}

codex-rs/app-server-transport/src/transport/remote_control/protocol.rs

@@ -0,0 +1,401 @@
+use crate::outgoing_message::OutgoingMessage;
+use codex_app_server_protocol::JSONRPCMessage;
+use serde::Deserialize;
+use serde::Serialize;
+use std::io;
+use std::io::ErrorKind;
+use url::Host;
+use url::Url;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct RemoteControlTarget {
+    pub(super) websocket_url: String,
+    pub(super) enroll_url: String,
+    pub(super) refresh_url: String,
+    pub(super) pair_url: String,
+    pub(super) pair_status_url: String,
+}
+
+#[derive(Debug, Serialize)]
+pub(super) struct EnrollRemoteServerRequest {
+    pub(super) name: String,
+    pub(super) os: &'static str,
+    pub(super) arch: &'static str,
+    pub(super) app_server_version: &'static str,
+    pub(super) installation_id: String,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct EnrollRemoteServerResponse {
+    pub(super) server_id: String,
+    pub(super) environment_id: String,
+    pub(super) remote_control_token: String,
+    pub(super) expires_at: String,
+}
+
+#[derive(Debug, Serialize)]
+pub(super) struct RefreshRemoteServerRequest {
+    pub(super) server_id: String,
+    pub(super) installation_id: String,
+}
+
+#[derive(Debug, Serialize)]
+pub(super) struct StartRemoteControlPairingRequest {
+    pub(super) manual_code: bool,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct StartRemoteControlPairingResponse {
+    pub(super) pairing_code: String,
+    pub(super) manual_pairing_code: Option<String>,
+    pub(super) server_id: String,
+    pub(super) environment_id: String,
+    pub(super) expires_at: String,
+}
+
+#[derive(Debug, Serialize)]
+pub(super) struct RemoteControlPairingStatusRequest {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) pairing_code: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) manual_pairing_code: Option<String>,
+}
+
+#[derive(Clone)]
+pub(super) enum RemoteControlPairingStatusCode {
+    PairingCode(String),
+    ManualPairingCode(String),
+}
+
+impl From<RemoteControlPairingStatusCode> for RemoteControlPairingStatusRequest {
+    fn from(code: RemoteControlPairingStatusCode) -> Self {
+        match code {
+            RemoteControlPairingStatusCode::PairingCode(pairing_code) => Self {
+                pairing_code: Some(pairing_code),
+                manual_pairing_code: None,
+            },
+            RemoteControlPairingStatusCode::ManualPairingCode(manual_pairing_code) => Self {
+                pairing_code: None,
+                manual_pairing_code: Some(manual_pairing_code),
+            },
+        }
+    }
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct RemoteControlPairingStatusResponse {
+    pub(super) claimed: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct ClientId(pub String);
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct StreamId(pub String);
+
+impl StreamId {
+    pub fn new_random() -> Self {
+        Self(uuid::Uuid::now_v7().to_string())
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ClientEvent {
+    ClientMessage {
+        message: JSONRPCMessage,
+    },
+    ClientMessageChunk {
+        segment_id: usize,
+        segment_count: usize,
+        message_size_bytes: usize,
+        message_chunk_base64: String,
+    },
+    /// Backend-generated acknowledgement for all server envelopes addressed to
+    /// `client_id` and `stream_id` whose envelope `seq_id` is less than or equal
+    /// to this ack's `seq_id`. Chunk acknowledgements carry `segment_id` so the
+    /// sender can retain only the still-unacked wire chunks on reconnect.
+    Ack {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        segment_id: Option<usize>,
+    },
+    Ping,
+    ClientClosed,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) struct ClientEnvelope {
+    #[serde(flatten)]
+    pub(crate) event: ClientEvent,
+    #[serde(rename = "client_id")]
+    pub(crate) client_id: ClientId,
+    #[serde(rename = "stream_id", skip_serializing_if = "Option::is_none")]
+    pub(crate) stream_id: Option<StreamId>,
+    /// For `Ack`, this is the backend-generated per-stream cursor over
+    /// `ServerEnvelope.seq_id`.
+    #[serde(rename = "seq_id", skip_serializing_if = "Option::is_none")]
+    pub(crate) seq_id: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) cursor: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PongStatus {
+    Active,
+    Unknown,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ServerEvent {
+    ServerMessage {
+        message: Box<OutgoingMessage>,
+    },
+    ServerMessageChunk {
+        segment_id: usize,
+        segment_count: usize,
+        message_size_bytes: usize,
+        message_chunk_base64: String,
+    },
+    #[allow(dead_code)]
+    Ack,
+    Pong {
+        status: PongStatus,
+    },
+}
+
+impl ServerEvent {
+    pub(crate) fn segment_id(&self) -> Option<usize> {
+        match self {
+            Self::ServerMessageChunk { segment_id, .. } => Some(*segment_id),
+            Self::ServerMessage { .. } | Self::Ack | Self::Pong { .. } => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) struct ServerEnvelope {
+    #[serde(flatten)]
+    pub(crate) event: ServerEvent,
+    #[serde(rename = "client_id")]
+    pub(crate) client_id: ClientId,
+    #[serde(rename = "stream_id")]
+    pub(crate) stream_id: StreamId,
+    #[serde(rename = "seq_id")]
+    pub(crate) seq_id: u64,
+}
+
+fn is_allowed_remote_control_chatgpt_host(host: &Option<Host<&str>>) -> bool {
+    let Some(Host::Domain(host)) = *host else {
+        return false;
+    };
+    host == "chatgpt.com"
+        || host == "chatgpt-staging.com"
+        || host.ends_with(".chatgpt.com")
+        || host.ends_with(".chatgpt-staging.com")
+}
+
+fn is_localhost(host: &Option<Host<&str>>) -> bool {
+    match host {
+        Some(Host::Domain("localhost")) => true,
+        Some(Host::Ipv4(ip)) => ip.is_loopback(),
+        Some(Host::Ipv6(ip)) => ip.is_loopback(),
+        _ => false,
+    }
+}
+
+pub(super) fn normalize_remote_control_url(
+    remote_control_url: &str,
+) -> io::Result<RemoteControlTarget> {
+    let remote_control_url = normalize_remote_control_base_url(remote_control_url)?;
+    let map_url_parse_error = |err: url::ParseError| -> io::Error {
+        io::Error::new(
+            ErrorKind::InvalidInput,
+            format!("invalid remote control URL `{remote_control_url}`: {err}"),
+        )
+    };
+
+    let enroll_url = remote_control_url
+        .join("wham/remote/control/server/enroll")
+        .map_err(map_url_parse_error)?;
+    let refresh_url = remote_control_url
+        .join("wham/remote/control/server/refresh")
+        .map_err(map_url_parse_error)?;
+    let pair_url = remote_control_url
+        .join("wham/remote/control/server/pair")
+        .map_err(map_url_parse_error)?;
+    let pair_status_url = remote_control_url
+        .join("wham/remote/control/server/pair/status")
+        .map_err(map_url_parse_error)?;
+    let mut websocket_url = remote_control_url
+        .join("wham/remote/control/server")
+        .map_err(map_url_parse_error)?;
+    websocket_url
+        .set_scheme(if enroll_url.scheme() == "https" {
+            "wss"
+        } else {
+            "ws"
+        })
+        .map_err(|()| {
+            io::Error::new(
+                ErrorKind::InvalidInput,
+                format!("invalid remote control URL `{remote_control_url}`"),
+            )
+        })?;
+
+    Ok(RemoteControlTarget {
+        websocket_url: websocket_url.to_string(),
+        enroll_url: enroll_url.to_string(),
+        refresh_url: refresh_url.to_string(),
+        pair_url: pair_url.to_string(),
+        pair_status_url: pair_status_url.to_string(),
+    })
+}
+
+pub(super) fn normalize_remote_control_base_url(remote_control_url: &str) -> io::Result<Url> {
+    let map_url_parse_error = |err: url::ParseError| -> io::Error {
+        io::Error::new(
+            ErrorKind::InvalidInput,
+            format!("invalid remote control URL `{remote_control_url}`: {err}"),
+        )
+    };
+    let map_scheme_error = |_: ()| -> io::Error {
+        io::Error::new(
+            ErrorKind::InvalidInput,
+            format!(
+                "invalid remote control URL `{remote_control_url}`; expected HTTPS URL for chatgpt.com or chatgpt-staging.com, or HTTP/HTTPS URL for localhost"
+            ),
+        )
+    };
+
+    let mut remote_control_url = Url::parse(remote_control_url).map_err(map_url_parse_error)?;
+    if !remote_control_url.path().ends_with('/') {
+        let normalized_path = format!("{}/", remote_control_url.path());
+        remote_control_url.set_path(&normalized_path);
+    }
+
+    let host = remote_control_url.host();
+    match remote_control_url.scheme() {
+        "https" if is_localhost(&host) || is_allowed_remote_control_chatgpt_host(&host) => {}
+        "http" if is_localhost(&host) => {}
+        _ => return Err(map_scheme_error(())),
+    }
+
+    Ok(remote_control_url)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn normalize_remote_control_url_accepts_chatgpt_https_urls() {
+        assert_eq!(
+            normalize_remote_control_url("https://chatgpt.com/backend-api")
+                .expect("chatgpt.com URL should normalize"),
+            RemoteControlTarget {
+                websocket_url: "wss://chatgpt.com/backend-api/wham/remote/control/server"
+                    .to_string(),
+                enroll_url: "https://chatgpt.com/backend-api/wham/remote/control/server/enroll"
+                    .to_string(),
+                refresh_url: "https://chatgpt.com/backend-api/wham/remote/control/server/refresh"
+                    .to_string(),
+                pair_url: "https://chatgpt.com/backend-api/wham/remote/control/server/pair"
+                    .to_string(),
+                pair_status_url:
+                    "https://chatgpt.com/backend-api/wham/remote/control/server/pair/status"
+                        .to_string(),
+            }
+        );
+        assert_eq!(
+            normalize_remote_control_url("https://api.chatgpt-staging.com/backend-api")
+                .expect("chatgpt-staging.com subdomain URL should normalize"),
+            RemoteControlTarget {
+                websocket_url:
+                    "wss://api.chatgpt-staging.com/backend-api/wham/remote/control/server"
+                        .to_string(),
+                enroll_url:
+                    "https://api.chatgpt-staging.com/backend-api/wham/remote/control/server/enroll"
+                        .to_string(),
+                refresh_url:
+                    "https://api.chatgpt-staging.com/backend-api/wham/remote/control/server/refresh"
+                        .to_string(),
+                pair_url:
+                    "https://api.chatgpt-staging.com/backend-api/wham/remote/control/server/pair"
+                        .to_string(),
+                pair_status_url:
+                    "https://api.chatgpt-staging.com/backend-api/wham/remote/control/server/pair/status"
+                        .to_string(),
+            }
+        );
+    }
+
+    #[test]
+    fn normalize_remote_control_url_accepts_localhost_urls() {
+        assert_eq!(
+            normalize_remote_control_url("http://localhost:8080/backend-api")
+                .expect("localhost http URL should normalize"),
+            RemoteControlTarget {
+                websocket_url: "ws://localhost:8080/backend-api/wham/remote/control/server"
+                    .to_string(),
+                enroll_url: "http://localhost:8080/backend-api/wham/remote/control/server/enroll"
+                    .to_string(),
+                refresh_url: "http://localhost:8080/backend-api/wham/remote/control/server/refresh"
+                    .to_string(),
+                pair_url: "http://localhost:8080/backend-api/wham/remote/control/server/pair"
+                    .to_string(),
+                pair_status_url:
+                    "http://localhost:8080/backend-api/wham/remote/control/server/pair/status"
+                        .to_string(),
+            }
+        );
+        assert_eq!(
+            normalize_remote_control_url("https://localhost:8443/backend-api")
+                .expect("localhost https URL should normalize"),
+            RemoteControlTarget {
+                websocket_url: "wss://localhost:8443/backend-api/wham/remote/control/server"
+                    .to_string(),
+                enroll_url: "https://localhost:8443/backend-api/wham/remote/control/server/enroll"
+                    .to_string(),
+                refresh_url:
+                    "https://localhost:8443/backend-api/wham/remote/control/server/refresh"
+                        .to_string(),
+                pair_url: "https://localhost:8443/backend-api/wham/remote/control/server/pair"
+                    .to_string(),
+                pair_status_url:
+                    "https://localhost:8443/backend-api/wham/remote/control/server/pair/status"
+                        .to_string(),
+            }
+        );
+    }
+
+    #[test]
+    fn normalize_remote_control_url_rejects_unsupported_urls() {
+        for remote_control_url in [
+            "http://chatgpt.com/backend-api",
+            "http://example.com/backend-api",
+            "https://example.com/backend-api",
+            "https://chat.openai.com/backend-api",
+            "https://chatgpt.com.evil.com/backend-api",
+            "https://evilchatgpt.com/backend-api",
+            "https://foo.localhost/backend-api",
+        ] {
+            let err = normalize_remote_control_url(remote_control_url)
+                .expect_err("unsupported URL should be rejected");
+
+            assert_eq!(err.kind(), ErrorKind::InvalidInput);
+            assert_eq!(
+                err.to_string(),
+                format!(
+                    "invalid remote control URL `{remote_control_url}`; expected HTTPS URL for chatgpt.com or chatgpt-staging.com, or HTTP/HTTPS URL for localhost"
+                )
+            );
+        }
+    }
+}

codex-rs/app-server-transport/src/transport/remote_control/segment.rs

@@ -0,0 +1,469 @@
+use super::protocol::ClientEnvelope;
+use super::protocol::ClientEvent;
+use super::protocol::ClientId;
+use super::protocol::ServerEnvelope;
+use super::protocol::ServerEvent;
+use super::protocol::StreamId;
+use crate::outgoing_message::OutgoingMessage;
+use crate::transport::response_serialization_error;
+use base64::DecodeSliceError;
+use base64::Engine;
+use codex_app_server_protocol::JSONRPCMessage;
+use std::collections::HashMap;
+use std::io;
+use std::io::ErrorKind;
+use std::io::Write;
+use tokio::time::Instant;
+use tracing::warn;
+
+pub(super) const REMOTE_CONTROL_SEGMENT_TARGET_BYTES: usize = 100 * 1024;
+pub(super) const REMOTE_CONTROL_SEGMENT_MAX_BYTES: usize = 150 * 1024;
+pub(super) const REMOTE_CONTROL_REASSEMBLED_MAX_BYTES: usize = 100 * 1024 * 1024;
+pub(super) const REMOTE_CONTROL_SEGMENT_COUNT_MAX: usize = 1024;
+const REMOTE_CONTROL_SEGMENT_ASSEMBLY_MAX_COUNT: usize = 128;
+
+#[derive(Debug)]
+struct ClientSegmentAssembly {
+    stream_id: StreamId,
+    metadata: ClientSegmentMetadata,
+    raw: Vec<u8>,
+    next_segment_id: usize,
+    last_chunk_seen_at: Instant,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct ClientSegmentMetadata {
+    seq_id: u64,
+    segment_count: usize,
+    message_size_bytes: usize,
+}
+
+#[derive(Default)]
+pub(super) struct ClientSegmentReassembler {
+    assemblies: HashMap<ClientId, ClientSegmentAssembly>,
+}
+
+pub(super) enum ClientSegmentObservation {
+    Forward(Box<ClientEnvelope>),
+    Pending,
+    Dropped,
+}
+
+impl ClientSegmentReassembler {
+    pub(super) fn observe(&mut self, envelope: ClientEnvelope) -> ClientSegmentObservation {
+        let ClientEvent::ClientMessageChunk {
+            segment_id,
+            segment_count,
+            message_size_bytes,
+            message_chunk_base64,
+        } = &envelope.event
+        else {
+            return ClientSegmentObservation::Forward(Box::new(envelope));
+        };
+        let segment_id = *segment_id;
+        let segment_count = *segment_count;
+        let message_size_bytes = *message_size_bytes;
+
+        let Some(metadata) = ClientSegmentMetadata::from_envelope(&envelope) else {
+            warn!(
+                client_id = envelope.client_id.0.as_str(),
+                "dropping segmented remote-control client envelope without seq_id"
+            );
+            return ClientSegmentObservation::Dropped;
+        };
+        let Some(stream_id) = envelope.stream_id.clone() else {
+            warn!(
+                client_id = envelope.client_id.0.as_str(),
+                "dropping segmented remote-control client envelope without stream_id"
+            );
+            return ClientSegmentObservation::Dropped;
+        };
+        if self.should_ignore_chunk(&envelope.client_id, &stream_id, metadata.seq_id, segment_id) {
+            return ClientSegmentObservation::Dropped;
+        }
+        if segment_count == 0
+            || segment_count > REMOTE_CONTROL_SEGMENT_COUNT_MAX
+            || segment_id >= segment_count
+            || message_size_bytes == 0
+            || message_size_bytes > REMOTE_CONTROL_REASSEMBLED_MAX_BYTES
+            || message_chunk_base64.is_empty()
+        {
+            warn!(
+                client_id = envelope.client_id.0.as_str(),
+                "dropping invalid segmented remote-control client envelope"
+            );
+            self.remove_assembly(&envelope.client_id, &stream_id);
+            return ClientSegmentObservation::Dropped;
+        }
+
+        let now = Instant::now();
+        match self.assemblies.get(&envelope.client_id) {
+            Some(assembly) if assembly.stream_id != stream_id => {
+                warn!(
+                    client_id = envelope.client_id.0.as_str(),
+                    "resetting segmented remote-control client envelope after stream change"
+                );
+                self.assemblies.insert(
+                    envelope.client_id.clone(),
+                    ClientSegmentAssembly {
+                        stream_id: stream_id.clone(),
+                        metadata: metadata.clone(),
+                        raw: Vec::new(),
+                        next_segment_id: 0,
+                        last_chunk_seen_at: now,
+                    },
+                );
+            }
+            Some(_) => {}
+            None => {
+                self.evict_assemblies_if_full();
+                self.assemblies.insert(
+                    envelope.client_id.clone(),
+                    ClientSegmentAssembly {
+                        stream_id: stream_id.clone(),
+                        metadata: metadata.clone(),
+                        raw: Vec::new(),
+                        next_segment_id: 0,
+                        last_chunk_seen_at: now,
+                    },
+                );
+            }
+        }
+        let result = {
+            let Some(assembly) = self.assemblies.get_mut(&envelope.client_id) else {
+                warn!(
+                    client_id = envelope.client_id.0.as_str(),
+                    "dropping segmented remote-control client envelope without assembly"
+                );
+                return ClientSegmentObservation::Dropped;
+            };
+            if metadata.seq_id < assembly.metadata.seq_id {
+                AssemblyUpdate::Ignore
+            } else if assembly.metadata != metadata {
+                warn!(
+                    client_id = envelope.client_id.0.as_str(),
+                    "resetting segmented remote-control client envelope after metadata mismatch"
+                );
+                AssemblyUpdate::Drop
+            } else if segment_id < assembly.next_segment_id {
+                AssemblyUpdate::Pending
+            } else if segment_id != assembly.next_segment_id {
+                warn!(
+                    client_id = envelope.client_id.0.as_str(),
+                    "dropping out-of-order segmented remote-control client envelope"
+                );
+                AssemblyUpdate::Drop
+            } else {
+                assembly.last_chunk_seen_at = now;
+                let chunk_start = assembly.raw.len();
+                let decoded_chunk_len = base64::decoded_len_estimate(message_chunk_base64.len());
+                let chunk_end = usize::min(
+                    message_size_bytes,
+                    chunk_start.saturating_add(decoded_chunk_len),
+                );
+                assembly.raw.resize(chunk_end, 0);
+                match base64::engine::general_purpose::STANDARD.decode_slice(
+                    message_chunk_base64.as_bytes(),
+                    &mut assembly.raw[chunk_start..],
+                ) {
+                    Ok(decoded_chunk_len) => {
+                        assembly.raw.truncate(chunk_start + decoded_chunk_len);
+                        assembly.next_segment_id += 1;
+                        if assembly.next_segment_id < segment_count {
+                            AssemblyUpdate::Pending
+                        } else if assembly.raw.len() != message_size_bytes {
+                            warn!(
+                                client_id = envelope.client_id.0.as_str(),
+                                "dropping reassembled remote-control client envelope with mismatched size"
+                            );
+                            AssemblyUpdate::Drop
+                        } else {
+                            match serde_json::from_slice::<JSONRPCMessage>(&assembly.raw) {
+                                Ok(message) => AssemblyUpdate::Complete(message),
+                                Err(err) => {
+                                    warn!(
+                                        client_id = envelope.client_id.0.as_str(),
+                                        "dropping invalid reassembled remote-control client envelope: {err}"
+                                    );
+                                    AssemblyUpdate::Drop
+                                }
+                            }
+                        }
+                    }
+                    Err(DecodeSliceError::OutputSliceTooSmall) => {
+                        warn!(
+                            client_id = envelope.client_id.0.as_str(),
+                            "dropping segmented remote-control client envelope after size overflow"
+                        );
+                        AssemblyUpdate::Drop
+                    }
+                    Err(err) => {
+                        warn!(
+                            client_id = envelope.client_id.0.as_str(),
+                            "dropping segmented remote-control client envelope with invalid base64: {err}"
+                        );
+                        AssemblyUpdate::Drop
+                    }
+                }
+            }
+        };
+
+        match result {
+            AssemblyUpdate::Pending => ClientSegmentObservation::Pending,
+            AssemblyUpdate::Ignore => ClientSegmentObservation::Dropped,
+            AssemblyUpdate::Drop => {
+                self.remove_assembly(&envelope.client_id, &stream_id);
+                ClientSegmentObservation::Dropped
+            }
+            AssemblyUpdate::Complete(message) => {
+                self.remove_assembly(&envelope.client_id, &stream_id);
+                ClientSegmentObservation::Forward(Box::new(ClientEnvelope {
+                    event: ClientEvent::ClientMessage { message },
+                    ..envelope
+                }))
+            }
+        }
+    }
+
+    pub(super) fn invalidate_stream(&mut self, client_id: &ClientId, stream_id: &StreamId) {
+        self.remove_assembly(client_id, stream_id);
+    }
+
+    pub(super) fn invalidate_client(&mut self, client_id: &ClientId) {
+        self.assemblies.remove(client_id);
+    }
+
+    pub(super) fn should_ignore_chunk(
+        &self,
+        client_id: &ClientId,
+        stream_id: &StreamId,
+        seq_id: u64,
+        segment_id: usize,
+    ) -> bool {
+        self.assemblies.get(client_id).is_some_and(|assembly| {
+            assembly.stream_id == *stream_id
+                && (seq_id < assembly.metadata.seq_id
+                    || (seq_id == assembly.metadata.seq_id
+                        && segment_id < assembly.next_segment_id))
+        })
+    }
+
+    fn remove_assembly(&mut self, client_id: &ClientId, stream_id: &StreamId) {
+        if self
+            .assemblies
+            .get(client_id)
+            .is_some_and(|assembly| &assembly.stream_id == stream_id)
+        {
+            self.assemblies.remove(client_id);
+        }
+    }
+
+    fn evict_assemblies_if_full(&mut self) {
+        while self.assemblies.len() >= REMOTE_CONTROL_SEGMENT_ASSEMBLY_MAX_COUNT {
+            let Some(client_id) = self
+                .assemblies
+                .iter()
+                .min_by_key(|(_, assembly)| assembly.last_chunk_seen_at)
+                .map(|(client_id, _)| client_id.clone())
+            else {
+                return;
+            };
+            self.assemblies.remove(&client_id);
+        }
+    }
+}
+
+enum AssemblyUpdate {
+    Pending,
+    Ignore,
+    Drop,
+    Complete(JSONRPCMessage),
+}
+
+impl ClientSegmentMetadata {
+    fn from_envelope(envelope: &ClientEnvelope) -> Option<Self> {
+        let ClientEvent::ClientMessageChunk {
+            segment_count,
+            message_size_bytes,
+            ..
+        } = &envelope.event
+        else {
+            return None;
+        };
+        Some(Self {
+            seq_id: envelope.seq_id?,
+            segment_count: *segment_count,
+            message_size_bytes: *message_size_bytes,
+        })
+    }
+}
+
+pub(super) fn split_server_envelope_for_transport(
+    envelope: ServerEnvelope,
+) -> io::Result<Vec<ServerEnvelope>> {
+    if !matches!(envelope.event, ServerEvent::ServerMessage { .. }) {
+        return Ok(vec![envelope]);
+    }
+
+    let envelope_size_bytes = match serialized_len(&envelope) {
+        Ok(envelope_size_bytes) => envelope_size_bytes,
+        Err(err) => {
+            let ServerEvent::ServerMessage { message } = envelope.event else {
+                unreachable!("server message variant checked above");
+            };
+            let OutgoingMessage::Response(response) = *message else {
+                return Err(err);
+            };
+            return Ok(vec![ServerEnvelope {
+                event: ServerEvent::ServerMessage {
+                    message: Box::new(response_serialization_error(response.id, err)),
+                },
+                client_id: envelope.client_id,
+                stream_id: envelope.stream_id,
+                seq_id: envelope.seq_id,
+            }]);
+        }
+    };
+    if envelope_size_bytes <= REMOTE_CONTROL_SEGMENT_MAX_BYTES {
+        return Ok(vec![envelope]);
+    }
+
+    let ServerEvent::ServerMessage { message } = envelope.event.clone() else {
+        unreachable!("server message variant checked above");
+    };
+    let raw = serde_json::to_vec(message.as_ref()).map_err(io::Error::other)?;
+    let message_size_bytes = raw.len();
+    if message_size_bytes > REMOTE_CONTROL_REASSEMBLED_MAX_BYTES {
+        warn!("dropping remote-control server envelope that exceeds reassembled size limit");
+        return Ok(Vec::new());
+    }
+
+    let minimal_segment_count =
+        usize::min(message_size_bytes.max(1), REMOTE_CONTROL_SEGMENT_COUNT_MAX);
+    let minimal_chunk = &raw[..usize::min(raw.len(), 1)];
+    if serialized_chunk_len(
+        &envelope,
+        /*segment_id*/ 0,
+        minimal_segment_count,
+        message_size_bytes,
+        minimal_chunk,
+    )? > REMOTE_CONTROL_SEGMENT_MAX_BYTES
+    {
+        warn!("dropping remote-control server envelope that cannot fit within segment size limit");
+        return Ok(Vec::new());
+    }
+
+    let mut segment_count = usize::max(
+        2,
+        message_size_bytes.div_ceil(REMOTE_CONTROL_SEGMENT_TARGET_BYTES),
+    );
+    loop {
+        let chunk_size = usize::max(1, message_size_bytes.div_ceil(segment_count));
+        segment_count = message_size_bytes.div_ceil(chunk_size);
+        let segments_fit = raw
+            .chunks(chunk_size)
+            .enumerate()
+            .all(|(segment_id, chunk)| {
+                serialized_chunk_len(
+                    &envelope,
+                    segment_id,
+                    segment_count,
+                    message_size_bytes,
+                    chunk,
+                )
+                .is_ok_and(|size| size <= REMOTE_CONTROL_SEGMENT_MAX_BYTES)
+            });
+        if segments_fit {
+            return raw
+                .chunks(chunk_size)
+                .enumerate()
+                .map(|(segment_id, chunk)| {
+                    build_chunk_envelope(
+                        &envelope,
+                        segment_id,
+                        segment_count,
+                        message_size_bytes,
+                        chunk,
+                    )
+                })
+                .collect();
+        }
+        if chunk_size == 1 {
+            warn!(
+                "dropping remote-control server envelope that cannot fit within segment size limit"
+            );
+            return Ok(Vec::new());
+        }
+        let next_segment_count = segment_count + 1;
+        let next_chunk_size = usize::max(1, message_size_bytes.div_ceil(next_segment_count));
+        segment_count = if next_chunk_size == chunk_size {
+            message_size_bytes
+        } else {
+            next_segment_count
+        };
+    }
+}
+
+fn serialized_chunk_len(
+    envelope: &ServerEnvelope,
+    segment_id: usize,
+    segment_count: usize,
+    message_size_bytes: usize,
+    chunk: &[u8],
+) -> io::Result<usize> {
+    serialized_len(&build_chunk_envelope(
+        envelope,
+        segment_id,
+        segment_count,
+        message_size_bytes,
+        chunk,
+    )?)
+}
+
+#[derive(Default)]
+struct CountingWriter {
+    len: usize,
+}
+
+impl Write for CountingWriter {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        self.len += buf.len();
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+fn serialized_len(value: &impl serde::Serialize) -> io::Result<usize> {
+    let mut writer = CountingWriter::default();
+    serde_json::to_writer(&mut writer, value).map_err(io::Error::other)?;
+    Ok(writer.len)
+}
+
+fn build_chunk_envelope(
+    envelope: &ServerEnvelope,
+    segment_id: usize,
+    segment_count: usize,
+    message_size_bytes: usize,
+    chunk: &[u8],
+) -> io::Result<ServerEnvelope> {
+    if segment_count > REMOTE_CONTROL_SEGMENT_COUNT_MAX {
+        return Err(io::Error::new(
+            ErrorKind::InvalidData,
+            "remote-control segment count exceeds maximum",
+        ));
+    }
+    Ok(ServerEnvelope {
+        event: ServerEvent::ServerMessageChunk {
+            segment_id,
+            segment_count,
+            message_size_bytes,
+            message_chunk_base64: base64::engine::general_purpose::STANDARD.encode(chunk),
+        },
+        client_id: envelope.client_id.clone(),
+        stream_id: envelope.stream_id.clone(),
+        seq_id: envelope.seq_id,
+    })
+}

codex-rs/app-server-transport/src/transport/remote_control/segment_tests.rs

@@ -0,0 +1,450 @@
+use super::protocol::ClientEnvelope;
+use super::protocol::ClientEvent;
+use super::protocol::ClientId;
+use super::protocol::ServerEnvelope;
+use super::protocol::ServerEvent;
+use super::protocol::StreamId;
+use super::segment::ClientSegmentObservation;
+use super::segment::ClientSegmentReassembler;
+use super::segment::REMOTE_CONTROL_SEGMENT_MAX_BYTES;
+use super::segment::split_server_envelope_for_transport;
+use crate::outgoing_message::OutgoingMessage;
+#[cfg(unix)]
+use crate::outgoing_message::OutgoingResponse;
+use base64::Engine;
+#[cfg(unix)]
+use codex_app_server_protocol::ClientResponsePayload;
+use codex_app_server_protocol::ConfigWarningNotification;
+#[cfg(unix)]
+use codex_app_server_protocol::InitializeResponse;
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::JSONRPCNotification;
+#[cfg(unix)]
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ServerNotificationEnvelope;
+#[cfg(unix)]
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+#[cfg(unix)]
+use serde_json::json;
+
+#[test]
+fn reassembles_client_message_chunks() {
+    let message = JSONRPCMessage::Notification(JSONRPCNotification {
+        method: "initialized".to_string(),
+        params: None,
+    });
+    let raw = serde_json::to_vec(&message).expect("message should serialize");
+    let split = raw.len() / 2;
+    let client_id = ClientId("client-1".to_string());
+    let stream_id = Some(StreamId("stream-1".to_string()));
+    let mut reassembler = ClientSegmentReassembler::default();
+
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            stream_id.clone(),
+            /*seq_id*/ 7,
+            /*segment_id*/ 0,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[..split],
+        )),
+        ClientSegmentObservation::Pending
+    ));
+    let reassembled = match reassembler.observe(chunk_envelope(
+        client_id.clone(),
+        stream_id,
+        /*seq_id*/ 7,
+        /*segment_id*/ 1,
+        /*segment_count*/ 2,
+        raw.len(),
+        &raw[split..],
+    )) {
+        ClientSegmentObservation::Forward(reassembled) => *reassembled,
+        ClientSegmentObservation::Pending | ClientSegmentObservation::Dropped => {
+            panic!("message should reassemble")
+        }
+    };
+    assert_eq!(reassembled.client_id, client_id);
+    assert_eq!(
+        reassembled.stream_id,
+        Some(StreamId("stream-1".to_string()))
+    );
+    assert_eq!(reassembled.seq_id, Some(7));
+    assert_eq!(reassembled.cursor, None);
+    match reassembled.event {
+        ClientEvent::ClientMessage {
+            message: reassembled_message,
+        } => assert_eq!(reassembled_message, message),
+        other => panic!("expected client message, got {other:?}"),
+    }
+}
+
+#[test]
+fn splits_large_server_messages_into_wire_chunks() {
+    let envelope = ServerEnvelope {
+        event: ServerEvent::ServerMessage {
+            message: Box::new(OutgoingMessage::AppServerNotification(
+                ServerNotificationEnvelope {
+                    notification: ServerNotification::ConfigWarning(ConfigWarningNotification {
+                        summary: "x".repeat(REMOTE_CONTROL_SEGMENT_MAX_BYTES),
+                        details: None,
+                        path: None,
+                        range: None,
+                    }),
+                    emitted_at_ms: Some(1_234),
+                },
+            )),
+        },
+        client_id: ClientId("client-1".to_string()),
+        stream_id: StreamId("stream-1".to_string()),
+        seq_id: 9,
+    };
+
+    let segments = split_server_envelope_for_transport(envelope).expect("split should succeed");
+
+    assert!(segments.len() > 1);
+    assert!(
+        segments
+            .iter()
+            .all(|segment| matches!(segment.event, ServerEvent::ServerMessageChunk { .. }))
+    );
+    assert!(segments.iter().all(|segment| segment.seq_id == 9));
+    assert!(segments.iter().all(|segment| {
+        serde_json::to_vec(segment)
+            .expect("segment should serialize")
+            .len()
+            <= REMOTE_CONTROL_SEGMENT_MAX_BYTES
+    }));
+}
+
+#[cfg(unix)]
+#[test]
+fn invalid_response_becomes_remote_control_jsonrpc_error() {
+    use std::ffi::OsString;
+    use std::os::unix::ffi::OsStringExt;
+    use std::path::PathBuf;
+
+    let codex_home = AbsolutePathBuf::from_absolute_path(PathBuf::from(OsString::from_vec(vec![
+        b'/', b'b', b'a', b'd', 0xff,
+    ])))
+    .expect("non-UTF-8 Unix paths are valid absolute paths");
+    let envelope = ServerEnvelope {
+        event: ServerEvent::ServerMessage {
+            message: Box::new(OutgoingMessage::Response(OutgoingResponse {
+                id: RequestId::Integer(7),
+                result: Box::new(ClientResponsePayload::Initialize(InitializeResponse {
+                    user_agent: "codex-test-agent".to_string(),
+                    codex_home,
+                    platform_family: "unix".to_string(),
+                    platform_os: "linux".to_string(),
+                })),
+            })),
+        },
+        client_id: ClientId("client-1".to_string()),
+        stream_id: StreamId("stream-1".to_string()),
+        seq_id: 9,
+    };
+
+    let envelopes = split_server_envelope_for_transport(envelope)
+        .expect("invalid response should become a remote-control JSON-RPC error");
+    assert_eq!(
+        serde_json::to_value(envelopes).expect("error envelope should serialize"),
+        json!([{
+            "type": "server_message",
+            "client_id": "client-1",
+            "stream_id": "stream-1",
+            "seq_id": 9,
+            "message": {
+                "id": 7,
+                "error": {
+                    "code": -32603,
+                    "message": "failed to serialize response: path contains invalid UTF-8 characters",
+                }
+            }
+        }])
+    );
+}
+
+#[test]
+fn invalidates_incomplete_stream_assemblies() {
+    let message = JSONRPCMessage::Notification(JSONRPCNotification {
+        method: "initialized".to_string(),
+        params: None,
+    });
+    let raw = serde_json::to_vec(&message).expect("message should serialize");
+    let split = raw.len() / 2;
+    let client_id = ClientId("client-1".to_string());
+    let stream_id = StreamId("stream-1".to_string());
+    let mut reassembler = ClientSegmentReassembler::default();
+
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            Some(stream_id.clone()),
+            /*seq_id*/ 7,
+            /*segment_id*/ 0,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[..split],
+        )),
+        ClientSegmentObservation::Pending
+    ));
+    reassembler.invalidate_stream(&client_id, &stream_id);
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id,
+            Some(stream_id),
+            /*seq_id*/ 7,
+            /*segment_id*/ 1,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[split..],
+        )),
+        ClientSegmentObservation::Dropped
+    ));
+}
+
+#[test]
+fn resets_incomplete_client_assembly_when_stream_changes() {
+    let message = JSONRPCMessage::Notification(JSONRPCNotification {
+        method: "initialized".to_string(),
+        params: None,
+    });
+    let raw = serde_json::to_vec(&message).expect("message should serialize");
+    let split = raw.len() / 2;
+    let client_id = ClientId("client-1".to_string());
+    let first_stream_id = StreamId("stream-1".to_string());
+    let second_stream_id = StreamId("stream-2".to_string());
+    let mut reassembler = ClientSegmentReassembler::default();
+
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            Some(first_stream_id.clone()),
+            /*seq_id*/ 7,
+            /*segment_id*/ 0,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[..split],
+        )),
+        ClientSegmentObservation::Pending
+    ));
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            Some(second_stream_id.clone()),
+            /*seq_id*/ 8,
+            /*segment_id*/ 0,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[..split],
+        )),
+        ClientSegmentObservation::Pending
+    ));
+    let reassembled = match reassembler.observe(chunk_envelope(
+        client_id.clone(),
+        Some(second_stream_id),
+        /*seq_id*/ 8,
+        /*segment_id*/ 1,
+        /*segment_count*/ 2,
+        raw.len(),
+        &raw[split..],
+    )) {
+        ClientSegmentObservation::Forward(reassembled) => *reassembled,
+        ClientSegmentObservation::Pending | ClientSegmentObservation::Dropped => {
+            panic!("replacement stream should reassemble")
+        }
+    };
+    assert_eq!(
+        reassembled.stream_id,
+        Some(StreamId("stream-2".to_string()))
+    );
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id,
+            Some(first_stream_id),
+            /*seq_id*/ 7,
+            /*segment_id*/ 1,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[split..],
+        )),
+        ClientSegmentObservation::Dropped
+    ));
+}
+
+#[test]
+fn ignores_stale_chunks_without_dropping_newer_assembly() {
+    let message = JSONRPCMessage::Notification(JSONRPCNotification {
+        method: "initialized".to_string(),
+        params: None,
+    });
+    let raw = serde_json::to_vec(&message).expect("message should serialize");
+    let split = raw.len() / 2;
+    let client_id = ClientId("client-1".to_string());
+    let stream_id = Some(StreamId("stream-1".to_string()));
+    let mut reassembler = ClientSegmentReassembler::default();
+
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            stream_id.clone(),
+            /*seq_id*/ 8,
+            /*segment_id*/ 0,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[..split],
+        )),
+        ClientSegmentObservation::Pending
+    ));
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            stream_id.clone(),
+            /*seq_id*/ 7,
+            /*segment_id*/ 0,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[..split],
+        )),
+        ClientSegmentObservation::Dropped
+    ));
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id,
+            stream_id,
+            /*seq_id*/ 8,
+            /*segment_id*/ 1,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[split..],
+        )),
+        ClientSegmentObservation::Forward(_)
+    ));
+}
+
+#[test]
+fn ignores_invalid_stale_chunks_without_dropping_newer_assembly() {
+    let message = JSONRPCMessage::Notification(JSONRPCNotification {
+        method: "initialized".to_string(),
+        params: None,
+    });
+    let raw = serde_json::to_vec(&message).expect("message should serialize");
+    let split = raw.len() / 2;
+    let client_id = ClientId("client-1".to_string());
+    let stream_id = Some(StreamId("stream-1".to_string()));
+    let mut reassembler = ClientSegmentReassembler::default();
+
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            stream_id.clone(),
+            /*seq_id*/ 8,
+            /*segment_id*/ 0,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[..split],
+        )),
+        ClientSegmentObservation::Pending
+    ));
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            stream_id.clone(),
+            /*seq_id*/ 7,
+            /*segment_id*/ 1,
+            /*segment_count*/ 2,
+            raw.len(),
+            b"",
+        )),
+        ClientSegmentObservation::Dropped
+    ));
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id,
+            stream_id,
+            /*seq_id*/ 8,
+            /*segment_id*/ 1,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[split..],
+        )),
+        ClientSegmentObservation::Forward(_)
+    ));
+}
+
+#[test]
+fn ignores_invalid_duplicate_chunks_without_dropping_current_assembly() {
+    let message = JSONRPCMessage::Notification(JSONRPCNotification {
+        method: "initialized".to_string(),
+        params: None,
+    });
+    let raw = serde_json::to_vec(&message).expect("message should serialize");
+    let split = raw.len() / 2;
+    let client_id = ClientId("client-1".to_string());
+    let stream_id = Some(StreamId("stream-1".to_string()));
+    let mut reassembler = ClientSegmentReassembler::default();
+
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            stream_id.clone(),
+            /*seq_id*/ 8,
+            /*segment_id*/ 0,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[..split],
+        )),
+        ClientSegmentObservation::Pending
+    ));
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id.clone(),
+            stream_id.clone(),
+            /*seq_id*/ 8,
+            /*segment_id*/ 0,
+            /*segment_count*/ 2,
+            raw.len(),
+            b"",
+        )),
+        ClientSegmentObservation::Dropped
+    ));
+    assert!(matches!(
+        reassembler.observe(chunk_envelope(
+            client_id,
+            stream_id,
+            /*seq_id*/ 8,
+            /*segment_id*/ 1,
+            /*segment_count*/ 2,
+            raw.len(),
+            &raw[split..],
+        )),
+        ClientSegmentObservation::Forward(_)
+    ));
+}
+
+fn chunk_envelope(
+    client_id: ClientId,
+    stream_id: Option<StreamId>,
+    seq_id: u64,
+    segment_id: usize,
+    segment_count: usize,
+    message_size_bytes: usize,
+    chunk: &[u8],
+) -> ClientEnvelope {
+    ClientEnvelope {
+        event: ClientEvent::ClientMessageChunk {
+            segment_id,
+            segment_count,
+            message_size_bytes,
+            message_chunk_base64: base64::engine::general_purpose::STANDARD.encode(chunk),
+        },
+        client_id,
+        stream_id,
+        seq_id: Some(seq_id),
+        cursor: None,
+    }
+}

codex-rs/app-server-transport/src/transport/remote_control/server_api.rs

@@ -0,0 +1,382 @@
+use super::auth::RemoteControlConnectionAuth;
+use super::enroll::RemoteControlEnrollment;
+use super::enroll::RemoteControlServerTokenRefreshRequirement;
+use super::enroll::format_headers;
+use super::enroll::preview_remote_control_response_body;
+use super::protocol::EnrollRemoteServerRequest;
+use super::protocol::EnrollRemoteServerResponse;
+use super::protocol::RefreshRemoteServerRequest;
+use super::protocol::RemoteControlTarget;
+use axum::http::HeaderMap;
+use axum::http::StatusCode;
+use codex_login::default_client::create_client_without_request_logging;
+use rand::Rng;
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+use std::fmt;
+use std::io;
+use std::io::ErrorKind;
+use std::time::Duration;
+use time::OffsetDateTime;
+use time::format_description::well_known::Rfc3339;
+use tracing::warn;
+
+const REMOTE_CONTROL_RETRY_AFTER_JITTER_MAX_MILLIS: u64 = 30_000;
+
+const REMOTE_CONTROL_ENROLL_TIMEOUT: Duration = Duration::from_secs(30);
+const REMOTE_CONTROL_SERVER_TOKEN_REFRESH_BACKOFF_MIN_SECS: u64 = 24;
+const REMOTE_CONTROL_SERVER_TOKEN_REFRESH_BACKOFF_MAX_SECS: u64 = 36;
+
+pub(super) const REMOTE_CONTROL_INSTALLATION_ID_HEADER: &str = "x-codex-installation-id";
+
+#[derive(Debug)]
+pub(super) struct RemoteControlServerRequestError {
+    message: String,
+    status: Option<StatusCode>,
+    retry_at: Option<OffsetDateTime>,
+}
+
+impl RemoteControlServerRequestError {
+    pub(super) fn retry_deferred(retry_at: OffsetDateTime) -> io::Error {
+        io::Error::new(
+            ErrorKind::WouldBlock,
+            Self {
+                message: format!("remote control retry deferred until {retry_at}"),
+                status: None,
+                retry_at: Some(retry_at),
+            },
+        )
+    }
+
+    pub(super) fn io_error(
+        message: String,
+        status: Option<StatusCode>,
+        retry_at: Option<OffsetDateTime>,
+        timed_out: bool,
+    ) -> io::Error {
+        let kind = match status {
+            Some(StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN) => ErrorKind::PermissionDenied,
+            Some(StatusCode::NOT_FOUND) => ErrorKind::NotFound,
+            Some(status) if timed_out && !status.is_client_error() => ErrorKind::TimedOut,
+            None if timed_out => ErrorKind::TimedOut,
+            Some(_) | None => ErrorKind::Other,
+        };
+        io::Error::new(
+            kind,
+            Self {
+                message,
+                status,
+                retry_at,
+            },
+        )
+    }
+
+    fn is_transient(&self, kind: ErrorKind) -> bool {
+        kind == ErrorKind::TimedOut
+            || self.status.is_none()
+            || self.status.is_some_and(|status| {
+                status == StatusCode::TOO_MANY_REQUESTS || status.is_server_error()
+            })
+    }
+}
+
+impl fmt::Display for RemoteControlServerRequestError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for RemoteControlServerRequestError {}
+
+pub(super) async fn enroll_remote_control_server(
+    remote_control_target: &RemoteControlTarget,
+    auth: &RemoteControlConnectionAuth,
+    installation_id: &str,
+    server_name: &str,
+) -> io::Result<RemoteControlEnrollment> {
+    let enroll_url = &remote_control_target.enroll_url;
+    let request = EnrollRemoteServerRequest {
+        name: server_name.to_string(),
+        os: std::env::consts::OS,
+        arch: std::env::consts::ARCH,
+        app_server_version: env!("CARGO_PKG_VERSION"),
+        installation_id: installation_id.to_string(),
+    };
+    let enrollment_response = send_remote_control_server_request::<_, EnrollRemoteServerResponse>(
+        enroll_url,
+        auth,
+        installation_id,
+        &request,
+        "enroll",
+        "server enrollment",
+        REMOTE_CONTROL_ENROLL_TIMEOUT,
+    )
+    .await?;
+    let mut enrollment = RemoteControlEnrollment {
+        remote_control_target: remote_control_target.clone(),
+        account_id: auth.account_id.clone(),
+        environment_id: enrollment_response.environment_id,
+        server_id: enrollment_response.server_id,
+        server_name: server_name.to_string(),
+        remote_control_token: None,
+        expires_at: None,
+        next_refresh_at: None,
+    };
+    update_remote_control_server_token(
+        &mut enrollment,
+        enroll_url,
+        enrollment_response.remote_control_token,
+        enrollment_response.expires_at,
+    )?;
+    Ok(enrollment)
+}
+
+pub(super) async fn refresh_remote_control_server(
+    auth: &RemoteControlConnectionAuth,
+    installation_id: &str,
+    enrollment: &mut RemoteControlEnrollment,
+) -> io::Result<()> {
+    let now = OffsetDateTime::now_utc();
+    let refresh_requirement = enrollment.server_token_refresh_requirement_at(now);
+    if refresh_requirement == RemoteControlServerTokenRefreshRequirement::NotNeeded {
+        return Ok(());
+    }
+    if refresh_requirement == RemoteControlServerTokenRefreshRequirement::Required
+        && let Some(next_refresh_at) = enrollment.next_refresh_at
+        && next_refresh_at > now
+    {
+        return Err(RemoteControlServerRequestError::retry_deferred(
+            next_refresh_at,
+        ));
+    }
+    let refresh_url = enrollment.remote_control_target.refresh_url.clone();
+    let request = RefreshRemoteServerRequest {
+        server_id: enrollment.server_id.clone(),
+        installation_id: installation_id.to_string(),
+    };
+    let refreshed = match send_remote_control_server_request::<_, EnrollRemoteServerResponse>(
+        &refresh_url,
+        auth,
+        installation_id,
+        &request,
+        "refresh",
+        "server refresh",
+        REMOTE_CONTROL_ENROLL_TIMEOUT,
+    )
+    .await
+    {
+        Ok(refreshed) => refreshed,
+        Err(err) => {
+            let Some(refresh_error) = remote_control_server_request_error(&err) else {
+                return Err(err);
+            };
+            if !refresh_error.is_transient(err.kind()) {
+                return Err(err);
+            }
+            let now = OffsetDateTime::now_utc();
+            let refresh_is_required = enrollment.server_token_refresh_requirement_at(now)
+                == RemoteControlServerTokenRefreshRequirement::Required;
+            let (refresh_delay, next_refresh_at) = refresh_deferral(refresh_error.retry_at, now);
+            enrollment.next_refresh_at = Some(next_refresh_at);
+            // An explicit server deadline takes precedence over valid-token fallback.
+            // Keep the token, but let callers defer new requests until this deadline.
+            if refresh_is_required
+                || refresh_error
+                    .retry_at
+                    .is_some_and(|retry_at| retry_at > now)
+            {
+                warn!(
+                    refresh_url,
+                    server_id = %enrollment.server_id,
+                    environment_id = %enrollment.environment_id,
+                    error = %err,
+                    ?refresh_delay,
+                    %next_refresh_at,
+                    "remote control server token refresh failed; deferring new requests"
+                );
+                return Err(err);
+            }
+            warn!(
+                refresh_url,
+                server_id = %enrollment.server_id,
+                environment_id = %enrollment.environment_id,
+                error = %err,
+                ?refresh_delay,
+                %next_refresh_at,
+                "proactive remote control server token refresh failed; continuing with valid token"
+            );
+            return Ok(());
+        }
+    };
+    if refreshed.server_id != enrollment.server_id
+        || refreshed.environment_id != enrollment.environment_id
+    {
+        return Err(io::Error::other(format!(
+            "remote control server refresh returned mismatched enrollment: expected server_id={}, environment_id={}; got server_id={}, environment_id={}",
+            enrollment.server_id,
+            enrollment.environment_id,
+            refreshed.server_id,
+            refreshed.environment_id
+        )));
+    }
+
+    update_remote_control_server_token(
+        enrollment,
+        &refresh_url,
+        refreshed.remote_control_token,
+        refreshed.expires_at,
+    )
+}
+
+async fn send_remote_control_server_request<Request, Response>(
+    url: &str,
+    auth: &RemoteControlConnectionAuth,
+    installation_id: &str,
+    request: &Request,
+    action: &str,
+    response_kind: &str,
+    timeout: Duration,
+) -> io::Result<Response>
+where
+    Request: Serialize,
+    Response: DeserializeOwned,
+{
+    let client = create_client_without_request_logging();
+    let auth_headers = auth.request_headers()?;
+    let response = client
+        .post(url)
+        .timeout(timeout)
+        .headers(auth_headers)
+        .header(REMOTE_CONTROL_INSTALLATION_ID_HEADER, installation_id)
+        .json(request)
+        .send()
+        .await
+        .map_err(|err| {
+            let timed_out = err.is_timeout();
+            RemoteControlServerRequestError::io_error(
+                format!("failed to {action} remote control server at `{url}`: {err}"),
+                /*status*/ None,
+                /*retry_at*/ None,
+                timed_out,
+            )
+        })?;
+    let headers = response.headers().clone();
+    let status = response.status();
+    let retry_at = retry_after_with_jitter(&headers, OffsetDateTime::now_utc());
+    let body = response.bytes().await.map_err(|err| {
+        let timed_out = err.is_timeout();
+        RemoteControlServerRequestError::io_error(
+            format!("failed to read remote control {response_kind} response from `{url}`: {err}"),
+            Some(status),
+            retry_at,
+            timed_out,
+        )
+    })?;
+    let body_preview = preview_remote_control_response_body(&body);
+    if !status.is_success() {
+        let headers_str = format_headers(&headers);
+        return Err(RemoteControlServerRequestError::io_error(
+            format!(
+                "remote control {response_kind} failed at `{url}`: HTTP {status}, {headers_str}, body: {body_preview}"
+            ),
+            Some(status),
+            retry_at,
+            /*timed_out*/ false,
+        ));
+    }
+
+    serde_json::from_slice::<Response>(&body).map_err(|err| {
+        let headers_str = format_headers(&headers);
+        io::Error::other(format!(
+            "failed to parse remote control {response_kind} response from `{url}`: HTTP {status}, {headers_str}, body: {body_preview}, decode error: {err}"
+        ))
+    })
+}
+
+fn update_remote_control_server_token(
+    enrollment: &mut RemoteControlEnrollment,
+    url: &str,
+    token: String,
+    expires_at: String,
+) -> io::Result<()> {
+    let expires_at = OffsetDateTime::parse(&expires_at, &Rfc3339).map_err(|err| {
+        io::Error::other(format!(
+            "failed to parse remote control server token expiry from `{url}`: {err}"
+        ))
+    })?;
+    enrollment.remote_control_token = Some(token);
+    enrollment.expires_at = Some(expires_at);
+    enrollment.next_refresh_at = None;
+    Ok(())
+}
+
+fn remote_control_server_request_error(
+    err: &io::Error,
+) -> Option<&RemoteControlServerRequestError> {
+    err.get_ref()?.downcast_ref()
+}
+
+pub(super) fn remote_control_retry_at(err: &io::Error) -> Option<OffsetDateTime> {
+    let request_error = remote_control_server_request_error(err)?;
+    if !request_error.is_transient(err.kind()) {
+        return None;
+    }
+    request_error.retry_at
+}
+
+pub(super) fn remote_control_retry_delay(err: &io::Error) -> Option<Duration> {
+    Duration::try_from(remote_control_retry_at(err)? - OffsetDateTime::now_utc()).ok()
+}
+
+pub(super) fn retry_after_with_jitter(
+    headers: &HeaderMap,
+    received_at: OffsetDateTime,
+) -> Option<OffsetDateTime> {
+    let retry_at = parse_retry_after(headers, received_at)?;
+    // Keep the server's deadline as a lower bound, then spread clients across
+    // the next 30 seconds. Sample once per response so retries share a deadline.
+    let jitter = time::Duration::milliseconds(
+        rand::rng().random_range(0..=REMOTE_CONTROL_RETRY_AFTER_JITTER_MAX_MILLIS) as i64,
+    );
+    Some(retry_at.checked_add(jitter).unwrap_or(retry_at))
+}
+
+fn parse_retry_after(headers: &HeaderMap, received_at: OffsetDateTime) -> Option<OffsetDateTime> {
+    let retry_after = headers
+        .get(axum::http::header::RETRY_AFTER)?
+        .to_str()
+        .ok()?;
+    let retry_at = if let Ok(seconds) = retry_after.parse::<u64>() {
+        let seconds = i64::try_from(seconds).ok()?;
+        received_at.checked_add(time::Duration::seconds(seconds))?
+    } else {
+        OffsetDateTime::from(httpdate::parse_http_date(retry_after).ok()?)
+    };
+    (retry_at >= received_at).then_some(retry_at)
+}
+
+fn refresh_deferral(
+    retry_at: Option<OffsetDateTime>,
+    now: OffsetDateTime,
+) -> (Duration, OffsetDateTime) {
+    if let Some(retry_at) = retry_at
+        && let Ok(delay) = Duration::try_from(retry_at - now)
+        && !delay.is_zero()
+    {
+        return (delay, retry_at);
+    }
+    let delay = remote_control_server_token_refresh_backoff();
+    let next_refresh_at = now + time::Duration::seconds(delay.as_secs() as i64);
+    (delay, next_refresh_at)
+}
+
+fn remote_control_server_token_refresh_backoff() -> Duration {
+    Duration::from_secs(rand::rng().random_range(
+        REMOTE_CONTROL_SERVER_TOKEN_REFRESH_BACKOFF_MIN_SECS
+            ..=REMOTE_CONTROL_SERVER_TOKEN_REFRESH_BACKOFF_MAX_SECS,
+    ))
+}
+
+#[cfg(test)]
+#[path = "server_api_tests.rs"]
+mod tests;

codex-rs/app-server-transport/src/transport/remote_control/server_api_tests.rs

@@ -0,0 +1,321 @@
+use super::*;
+use crate::transport::remote_control::protocol::normalize_remote_control_url;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use std::time::SystemTime;
+use tokio::io::AsyncWriteExt;
+use tokio::net::TcpListener;
+use tokio::sync::oneshot;
+
+const TEST_REQUEST_TIMEOUT: Duration = Duration::from_millis(100);
+
+fn auth() -> RemoteControlConnectionAuth {
+    RemoteControlConnectionAuth {
+        auth_provider: codex_model_provider::unauthenticated_auth_provider(),
+        account_id: "account-a".to_string(),
+    }
+}
+
+fn assert_transient_timeout(err: &io::Error, expected_status: Option<StatusCode>) {
+    let request_error = remote_control_server_request_error(err)
+        .expect("request error should preserve refresh metadata");
+    assert_eq!(
+        (
+            err.kind(),
+            request_error.status,
+            request_error.is_transient(err.kind()),
+        ),
+        (ErrorKind::TimedOut, expected_status, true)
+    );
+}
+
+async fn timed_out_request(partial_response: Option<&'static [u8]>) -> io::Error {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let url = format!(
+        "http://{}/backend-api/wham/remote/control/server/refresh",
+        listener
+            .local_addr()
+            .expect("listener should have a local address")
+    );
+    let (request_done_tx, request_done_rx) = oneshot::channel();
+    let server_task = tokio::spawn(async move {
+        let (mut stream, _) = listener.accept().await.expect("request should connect");
+        if let Some(partial_response) = partial_response {
+            stream
+                .write_all(partial_response)
+                .await
+                .expect("partial response should write");
+        }
+        request_done_rx
+            .await
+            .expect("test should report request completion");
+    });
+
+    let err = send_remote_control_server_request::<_, serde_json::Value>(
+        &url,
+        &auth(),
+        "installation-id",
+        &json!({"server_id": "server-id"}),
+        "refresh",
+        "server refresh",
+        TEST_REQUEST_TIMEOUT,
+    )
+    .await
+    .expect_err("incomplete response should time out");
+    request_done_tx
+        .send(())
+        .expect("server should wait for request completion");
+    server_task.await.expect("server task should finish");
+    err
+}
+
+fn enrollment(now: OffsetDateTime) -> RemoteControlEnrollment {
+    RemoteControlEnrollment {
+        remote_control_target: normalize_remote_control_url("http://localhost/backend-api/")
+            .expect("target should normalize"),
+        account_id: "account-a".to_string(),
+        environment_id: "env_first".to_string(),
+        server_id: "srv_e_first".to_string(),
+        server_name: "first-server".to_string(),
+        remote_control_token: Some("token".to_string()),
+        expires_at: Some(now + time::Duration::seconds(300)),
+        next_refresh_at: None,
+    }
+}
+
+#[test]
+fn remote_control_enrollment_classifies_server_token_refresh_requirement() {
+    let now =
+        OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("test timestamp should parse");
+    let enrollment = enrollment(now);
+    let cases = [
+        (
+            enrollment.clone(),
+            RemoteControlServerTokenRefreshRequirement::Proactive,
+        ),
+        (
+            RemoteControlEnrollment {
+                expires_at: Some(now + time::Duration::seconds(301)),
+                ..enrollment.clone()
+            },
+            RemoteControlServerTokenRefreshRequirement::NotNeeded,
+        ),
+        (
+            RemoteControlEnrollment {
+                next_refresh_at: Some(now + time::Duration::seconds(30)),
+                ..enrollment.clone()
+            },
+            RemoteControlServerTokenRefreshRequirement::NotNeeded,
+        ),
+        (
+            RemoteControlEnrollment {
+                next_refresh_at: Some(now),
+                ..enrollment.clone()
+            },
+            RemoteControlServerTokenRefreshRequirement::Proactive,
+        ),
+        (
+            RemoteControlEnrollment {
+                remote_control_token: None,
+                ..enrollment.clone()
+            },
+            RemoteControlServerTokenRefreshRequirement::Required,
+        ),
+        (
+            RemoteControlEnrollment {
+                expires_at: None,
+                ..enrollment.clone()
+            },
+            RemoteControlServerTokenRefreshRequirement::Required,
+        ),
+        (
+            RemoteControlEnrollment {
+                expires_at: Some(now),
+                next_refresh_at: Some(now + time::Duration::hours(1)),
+                ..enrollment
+            },
+            RemoteControlServerTokenRefreshRequirement::Required,
+        ),
+    ];
+
+    for (enrollment, expected) in cases {
+        assert_eq!(
+            enrollment.server_token_refresh_requirement_at(now),
+            expected
+        );
+    }
+}
+
+#[test]
+fn remote_control_server_request_error_classifies_status_before_timeout() {
+    let cases = [
+        (None, true, ErrorKind::TimedOut, true),
+        (Some(StatusCode::OK), true, ErrorKind::TimedOut, true),
+        (
+            Some(StatusCode::TOO_MANY_REQUESTS),
+            false,
+            ErrorKind::Other,
+            true,
+        ),
+        (Some(StatusCode::BAD_GATEWAY), false, ErrorKind::Other, true),
+        (
+            Some(StatusCode::UNAUTHORIZED),
+            true,
+            ErrorKind::PermissionDenied,
+            false,
+        ),
+        (
+            Some(StatusCode::FORBIDDEN),
+            true,
+            ErrorKind::PermissionDenied,
+            false,
+        ),
+        (
+            Some(StatusCode::NOT_FOUND),
+            true,
+            ErrorKind::NotFound,
+            false,
+        ),
+        (Some(StatusCode::BAD_REQUEST), true, ErrorKind::Other, false),
+        (None, false, ErrorKind::Other, true),
+    ];
+
+    for (status, timed_out, expected_kind, expected_transient) in cases {
+        let err = RemoteControlServerRequestError::io_error(
+            String::new(),
+            status,
+            /*retry_at*/ None,
+            timed_out,
+        );
+        let request_error = remote_control_server_request_error(&err)
+            .expect("request error should preserve refresh metadata");
+        assert_eq!(
+            (err.kind(), request_error.is_transient(err.kind())),
+            (expected_kind, expected_transient)
+        );
+    }
+}
+
+#[tokio::test]
+async fn request_timeout_before_response_headers_is_transient() {
+    let err = timed_out_request(/*partial_response*/ None).await;
+    assert_transient_timeout(&err, /*expected_status*/ None);
+}
+
+#[tokio::test]
+async fn response_body_timeout_is_transient() {
+    let err = timed_out_request(Some(b"HTTP/1.1 200 OK\r\nContent-Length: 20\r\n\r\n{")).await;
+    assert_transient_timeout(&err, Some(StatusCode::OK));
+}
+
+#[test]
+fn retry_after_supports_delta_seconds_and_http_dates() {
+    let now =
+        OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("test timestamp should parse");
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        axum::http::header::RETRY_AFTER,
+        axum::http::HeaderValue::from_static("120"),
+    );
+    assert_eq!(
+        parse_retry_after(&headers, now),
+        Some(now + time::Duration::seconds(120))
+    );
+
+    let retry_at = now + time::Duration::seconds(90);
+    let retry_at_system = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_090);
+    headers.insert(
+        axum::http::header::RETRY_AFTER,
+        httpdate::fmt_http_date(retry_at_system)
+            .parse()
+            .expect("HTTP date should be a valid header value"),
+    );
+    assert_eq!(parse_retry_after(&headers, now), Some(retry_at));
+}
+
+#[test]
+fn invalid_or_expired_retry_after_uses_bounded_fallback() {
+    let now =
+        OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("test timestamp should parse");
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        axum::http::header::RETRY_AFTER,
+        axum::http::HeaderValue::from_static("invalid"),
+    );
+    assert_eq!(parse_retry_after(&headers, now), None);
+
+    headers.insert(
+        axum::http::header::RETRY_AFTER,
+        httpdate::fmt_http_date(SystemTime::UNIX_EPOCH + Duration::from_secs(1_699_999_999))
+            .parse()
+            .expect("HTTP date should be a valid header value"),
+    );
+    assert_eq!(parse_retry_after(&headers, now), None);
+
+    let expired_while_reading_body = Some(now + time::Duration::seconds(1));
+    for retry_at in [None, expired_while_reading_body] {
+        let deferred_at = now + time::Duration::seconds(2);
+        let (delay, next_refresh_at) = refresh_deferral(retry_at, deferred_at);
+        assert!(
+            (Duration::from_secs(REMOTE_CONTROL_SERVER_TOKEN_REFRESH_BACKOFF_MIN_SECS)
+                ..=Duration::from_secs(REMOTE_CONTROL_SERVER_TOKEN_REFRESH_BACKOFF_MAX_SECS,))
+                .contains(&delay)
+        );
+        assert_eq!(
+            next_refresh_at,
+            deferred_at + time::Duration::seconds(delay.as_secs() as i64)
+        );
+    }
+}
+
+#[test]
+fn http_date_retry_after_preserves_absolute_deadline() {
+    let received_at =
+        OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("test timestamp should parse");
+    let retry_at = received_at + time::Duration::seconds(120);
+    let body_read_at = received_at + time::Duration::seconds(30);
+
+    assert_eq!(
+        refresh_deferral(Some(retry_at), body_read_at),
+        (Duration::from_secs(90), retry_at)
+    );
+}
+
+#[test]
+fn retry_after_jitter_never_shortens_the_server_deadline() {
+    let now =
+        OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("test timestamp should parse");
+    for value in ["120", "Tue, 14 Nov 2023 22:15:20 GMT"] {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::RETRY_AFTER,
+            value.parse().expect("retry hint should be a valid header"),
+        );
+        let deadline = retry_after_with_jitter(&headers, now)
+            .expect("a valid retry hint should produce a deadline");
+        assert!(
+            (now + time::Duration::seconds(120)..=now + time::Duration::seconds(150))
+                .contains(&deadline)
+        );
+        // Reading the response body must not start a new relative wait or resample jitter.
+        let (delay, deferred_until) =
+            refresh_deferral(Some(deadline), now + time::Duration::seconds(30));
+        assert_eq!(deferred_until, deadline);
+        assert!((Duration::from_secs(90)..=Duration::from_secs(120)).contains(&delay));
+    }
+}
+
+#[test]
+fn zero_retry_after_preserves_bounded_jitter() {
+    let now = OffsetDateTime::UNIX_EPOCH;
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        axum::http::header::RETRY_AFTER,
+        axum::http::HeaderValue::from_static("0"),
+    );
+    let deadline = retry_after_with_jitter(&headers, now)
+        .expect("a zero-second retry hint should produce a deadline");
+    assert!((now..=now + time::Duration::seconds(30)).contains(&deadline));
+}

codex-rs/app-server-transport/src/transport/remote_control/tests/clients_tests.rs

@@ -0,0 +1,416 @@
+use super::super::clients::list_remote_control_clients;
+use super::super::clients::revoke_remote_control_client;
+use super::*;
+use codex_app_server_protocol::RemoteControlClient;
+use codex_app_server_protocol::RemoteControlClientsListOrder;
+use codex_app_server_protocol::RemoteControlClientsListParams;
+use codex_app_server_protocol::RemoteControlClientsListResponse;
+use codex_app_server_protocol::RemoteControlClientsRevokeParams;
+use codex_app_server_protocol::RemoteControlClientsRevokeResponse;
+use codex_login::AuthKeyringBackendKind;
+use pretty_assertions::assert_eq;
+
+fn client_management_handle(
+    remote_control_url: String,
+    auth_manager: Arc<AuthManager>,
+) -> RemoteControlSession {
+    let desired_state_tx = watch::channel(RemoteControlDesiredState::Disabled).0;
+    let (status_tx, _status_rx) = watch::channel(RemoteControlStatusChangedNotification {
+        status: RemoteControlConnectionStatus::Disabled,
+        server_name: test_server_name(),
+        installation_id: TEST_INSTALLATION_ID.to_string(),
+        environment_id: None,
+    });
+    RemoteControlSession {
+        policy: RemoteControlPolicy::Allowed,
+        shutdown_token: CancellationToken::new(),
+        desired_state_tx: Arc::new(desired_state_tx),
+        desired_state_rpc_lock: Arc::new(Semaphore::new(1)),
+        persistence: RemoteControlPersistence::default(),
+        status_tx: Arc::new(status_tx),
+        state_db: None,
+        remote_control_url,
+        current_enrollment: Arc::new(RemoteControlEnrollmentState::new(/*enrollment*/ None)),
+        pairing_persistence_key: watch::channel(None).0,
+        pairing_persistence_key_required: false,
+        auth_manager: auth::RemoteControlAuth::capture(auth_manager).0,
+    }
+}
+
+fn empty_client_list() -> serde_json::Value {
+    json!({
+        "items": [],
+        "cursor": null,
+    })
+}
+
+#[tokio::test]
+async fn remote_control_handle_lists_clients_while_disabled() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let request = accept_http_request(&listener).await;
+        assert_eq!(
+            request.request_line,
+            "GET /backend-api/wham/remote/control/environments/env%20%2F%3F/clients?cursor=cursor+%2F%3F&limit=10&order=asc HTTP/1.1"
+        );
+        assert_eq!(
+            request.headers.get("authorization"),
+            Some(&"Bearer Access Token".to_string())
+        );
+        assert_eq!(
+            request.headers.get_all(REMOTE_CONTROL_ACCOUNT_ID_HEADER),
+            vec!["account_id"]
+        );
+        respond_with_json(
+            request.stream,
+            json!({
+                "items": [{
+                    "client_id": "client-123",
+                    "account_user_id": "user-123",
+                    "enrollment_status": "enrolled_device_key",
+                    "display_name": "Anton Phone",
+                    "device_type": "phone",
+                    "platform": "ios",
+                    "os_version": "19.0",
+                    "device_model": "iPhone",
+                    "app_version": "1.2.3",
+                    "last_seen_at": "2026-03-05T07:00:00Z",
+                    "last_seen_city": "San Francisco",
+                }],
+                "cursor": "next-cursor",
+            }),
+        )
+        .await;
+    });
+    let handle = client_management_handle(remote_control_url, remote_control_auth_manager());
+
+    let response = handle
+        .list_clients(RemoteControlClientsListParams {
+            environment_id: "env /?".to_string(),
+            cursor: Some("cursor /?".to_string()),
+            limit: Some(10),
+            order: Some(RemoteControlClientsListOrder::Asc),
+        })
+        .await
+        .expect("client list should succeed while remote control is disabled");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(
+        response,
+        RemoteControlClientsListResponse {
+            data: vec![RemoteControlClient {
+                client_id: "client-123".to_string(),
+                display_name: Some("Anton Phone".to_string()),
+                device_type: Some("phone".to_string()),
+                platform: Some("ios".to_string()),
+                os_version: Some("19.0".to_string()),
+                device_model: Some("iPhone".to_string()),
+                app_version: Some("1.2.3".to_string()),
+                last_seen_at: Some(1_772_694_000),
+            }],
+            next_cursor: Some("next-cursor".to_string()),
+        }
+    );
+}
+
+#[tokio::test]
+async fn remote_control_handle_revokes_client_while_disabled() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let request = accept_http_request(&listener).await;
+        assert_eq!(
+            request.request_line,
+            "DELETE /backend-api/wham/remote/control/environments/env%20%2F%3F/clients/client%20%2F%3F HTTP/1.1"
+        );
+        assert_eq!(
+            request.headers.get("authorization"),
+            Some(&"Bearer Access Token".to_string())
+        );
+        assert_eq!(
+            request.headers.get_all(REMOTE_CONTROL_ACCOUNT_ID_HEADER),
+            vec!["account_id"]
+        );
+        respond_with_status(request.stream, "204 No Content", "").await;
+    });
+    let handle = client_management_handle(remote_control_url, remote_control_auth_manager());
+
+    let response = handle
+        .revoke_client(RemoteControlClientsRevokeParams {
+            environment_id: "env /?".to_string(),
+            client_id: "client /?".to_string(),
+        })
+        .await
+        .expect("client revoke should succeed while remote control is disabled");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(response, RemoteControlClientsRevokeResponse {});
+}
+
+#[tokio::test]
+async fn list_remote_control_clients_recovers_auth_after_unauthorized() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let stale_request = accept_http_request(&listener).await;
+        assert_eq!(
+            stale_request.headers.get("authorization"),
+            Some(&"Bearer stale-token".to_string())
+        );
+        assert_eq!(
+            stale_request
+                .headers
+                .get_all(REMOTE_CONTROL_ACCOUNT_ID_HEADER),
+            vec!["account_id"]
+        );
+        respond_with_status(stale_request.stream, "401 Unauthorized", "").await;
+
+        let recovered_request = accept_http_request(&listener).await;
+        assert_eq!(
+            recovered_request.headers.get("authorization"),
+            Some(&"Bearer fresh-token".to_string())
+        );
+        assert_eq!(
+            recovered_request
+                .headers
+                .get_all(REMOTE_CONTROL_ACCOUNT_ID_HEADER),
+            vec!["account_id"]
+        );
+        respond_with_json(recovered_request.stream, empty_client_list()).await;
+    });
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let mut stale_auth = remote_control_auth_dot_json(Some("account_id"));
+    stale_auth
+        .tokens
+        .as_mut()
+        .expect("stale auth should include tokens")
+        .access_token = "stale-token".to_string();
+    save_auth(
+        codex_home.path(),
+        &stale_auth,
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("stale auth should save");
+    let auth_manager = AuthManager::shared(
+        codex_home.path().to_path_buf(),
+        /*enable_codex_api_key_env*/ false,
+        AuthCredentialsStoreMode::File,
+        /*forced_chatgpt_workspace_id*/ None,
+        /*chatgpt_base_url*/ None,
+        AuthKeyringBackendKind::default(),
+        codex_login::test_support::transport_default_auth_route_config(),
+    )
+    .await;
+    let mut fresh_auth = remote_control_auth_dot_json(Some("account_id"));
+    fresh_auth
+        .tokens
+        .as_mut()
+        .expect("fresh auth should include tokens")
+        .access_token = "fresh-token".to_string();
+    save_auth(
+        codex_home.path(),
+        &fresh_auth,
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("fresh auth should save");
+
+    let response = list_remote_control_clients(
+        &remote_control_url,
+        &auth::RemoteControlAuth::capture(auth_manager.clone()).0,
+        RemoteControlClientsListParams {
+            environment_id: "env-123".to_string(),
+            ..Default::default()
+        },
+    )
+    .await
+    .expect("client list should recover auth");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(
+        response,
+        RemoteControlClientsListResponse {
+            data: Vec::new(),
+            next_cursor: None,
+        }
+    );
+}
+
+#[tokio::test]
+async fn list_remote_control_clients_retries_unauthorized_only_once() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let stale_request = accept_http_request(&listener).await;
+        assert_eq!(
+            stale_request.headers.get("authorization"),
+            Some(&"Bearer stale-token".to_string())
+        );
+        assert_eq!(
+            stale_request
+                .headers
+                .get_all(REMOTE_CONTROL_ACCOUNT_ID_HEADER),
+            vec!["account_id"]
+        );
+        respond_with_status(stale_request.stream, "401 Unauthorized", "").await;
+
+        let recovered_request = accept_http_request(&listener).await;
+        assert_eq!(
+            recovered_request.headers.get("authorization"),
+            Some(&"Bearer fresh-token".to_string())
+        );
+        assert_eq!(
+            recovered_request
+                .headers
+                .get_all(REMOTE_CONTROL_ACCOUNT_ID_HEADER),
+            vec!["account_id"]
+        );
+        respond_with_status(recovered_request.stream, "401 Unauthorized", "").await;
+
+        assert!(
+            timeout(Duration::from_millis(100), accept_http_request(&listener))
+                .await
+                .is_err()
+        );
+    });
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let mut stale_auth = remote_control_auth_dot_json(Some("account_id"));
+    stale_auth
+        .tokens
+        .as_mut()
+        .expect("stale auth should include tokens")
+        .access_token = "stale-token".to_string();
+    save_auth(
+        codex_home.path(),
+        &stale_auth,
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("stale auth should save");
+    let auth_manager = AuthManager::shared(
+        codex_home.path().to_path_buf(),
+        /*enable_codex_api_key_env*/ false,
+        AuthCredentialsStoreMode::File,
+        /*forced_chatgpt_workspace_id*/ None,
+        /*chatgpt_base_url*/ None,
+        AuthKeyringBackendKind::default(),
+        codex_login::test_support::transport_default_auth_route_config(),
+    )
+    .await;
+    let mut fresh_auth = remote_control_auth_dot_json(Some("account_id"));
+    fresh_auth
+        .tokens
+        .as_mut()
+        .expect("fresh auth should include tokens")
+        .access_token = "fresh-token".to_string();
+    save_auth(
+        codex_home.path(),
+        &fresh_auth,
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("fresh auth should save");
+
+    let err = list_remote_control_clients(
+        &remote_control_url,
+        &auth::RemoteControlAuth::capture(auth_manager.clone()).0,
+        RemoteControlClientsListParams {
+            environment_id: "env-123".to_string(),
+            ..Default::default()
+        },
+    )
+    .await
+    .expect_err("second unauthorized response should fail");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(err.kind(), std::io::ErrorKind::PermissionDenied);
+}
+
+#[tokio::test]
+async fn revoke_remote_control_client_does_not_retry_forbidden() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let request = accept_http_request(&listener).await;
+        assert_eq!(
+            request.headers.get("authorization"),
+            Some(&"Bearer Access Token".to_string())
+        );
+        assert_eq!(
+            request.headers.get_all(REMOTE_CONTROL_ACCOUNT_ID_HEADER),
+            vec!["account_id"]
+        );
+        respond_with_status_and_headers(
+            request.stream,
+            "403 Forbidden",
+            &[("x-request-id", "request-123"), ("cf-ray", "ray-123")],
+            "forbidden",
+        )
+        .await;
+    });
+
+    let err = revoke_remote_control_client(
+        &remote_control_url,
+        &auth::RemoteControlAuth::capture(remote_control_auth_manager()).0,
+        RemoteControlClientsRevokeParams {
+            environment_id: "env-123".to_string(),
+            client_id: "client-123".to_string(),
+        },
+    )
+    .await
+    .expect_err("forbidden revoke should fail");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(err.kind(), std::io::ErrorKind::PermissionDenied);
+    assert_eq!(
+        err.to_string(),
+        format!(
+            "remote control client revoke failed at `{remote_control_url}wham/remote/control/environments/env-123/clients/client-123`: HTTP 403 Forbidden, request-id: request-123, cf-ray: ray-123, body: forbidden"
+        )
+    );
+}
+
+#[tokio::test]
+async fn list_remote_control_clients_preserves_decode_error_context() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let request = accept_http_request(&listener).await;
+        respond_with_status(request.stream, "200 OK", "{").await;
+    });
+
+    let err = list_remote_control_clients(
+        &remote_control_url,
+        &auth::RemoteControlAuth::capture(remote_control_auth_manager()).0,
+        RemoteControlClientsListParams {
+            environment_id: "env-123".to_string(),
+            ..Default::default()
+        },
+    )
+    .await
+    .expect_err("malformed client list should fail");
+    server_task.await.expect("server task should finish");
+
+    assert!(
+        err.to_string().contains(
+            "failed to parse remote control client list response from `http://127.0.0.1:"
+        )
+    );
+    assert!(err.to_string().contains("HTTP 200 OK"));
+    assert!(err.to_string().contains("body: {"));
+    assert!(err.to_string().contains("decode error:"));
+}

codex-rs/app-server-transport/src/transport/remote_control/tests/pairing_tests.rs

@@ -0,0 +1,1137 @@
+use super::super::protocol::RemoteControlPairingStatusRequest;
+use super::super::protocol::StartRemoteControlPairingRequest;
+use super::*;
+use codex_login::AuthKeyringBackendKind;
+use pretty_assertions::assert_eq;
+use std::io;
+
+fn remote_control_enrollment(
+    remote_control_url: &str,
+    remote_control_token: &str,
+) -> RemoteControlEnrollment {
+    RemoteControlEnrollment {
+        remote_control_target: normalize_remote_control_url(remote_control_url)
+            .expect("target should normalize"),
+        account_id: "account-id".to_string(),
+        environment_id: "environment-id".to_string(),
+        server_id: "server-id".to_string(),
+        server_name: "server-name".to_string(),
+        remote_control_token: Some(remote_control_token.to_string()),
+        expires_at: Some(
+            OffsetDateTime::from_unix_timestamp(33_336_362_096)
+                .expect("future timestamp should parse"),
+        ),
+        next_refresh_at: None,
+    }
+}
+
+async fn auth_manager_with_replacement(
+    codex_home: &TempDir,
+    replacement_account_id: &str,
+) -> Arc<AuthManager> {
+    let mut stale_auth = remote_control_auth_dot_json(Some("account_id"));
+    stale_auth
+        .tokens
+        .as_mut()
+        .expect("stale auth should include tokens")
+        .access_token = "stale-token".to_string();
+    save_auth(
+        codex_home.path(),
+        &stale_auth,
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("stale auth should save");
+    let auth_manager = AuthManager::shared(
+        codex_home.path().to_path_buf(),
+        /*enable_codex_api_key_env*/ false,
+        AuthCredentialsStoreMode::File,
+        /*forced_chatgpt_workspace_id*/ None,
+        /*chatgpt_base_url*/ None,
+        AuthKeyringBackendKind::default(),
+        codex_login::test_support::transport_default_auth_route_config(),
+    )
+    .await;
+    let mut replacement_auth = remote_control_auth_dot_json(Some(replacement_account_id));
+    replacement_auth
+        .tokens
+        .as_mut()
+        .expect("replacement auth should include tokens")
+        .access_token = "fresh-token".to_string();
+    save_auth(
+        codex_home.path(),
+        &replacement_auth,
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("replacement auth should save");
+    auth_manager
+}
+
+fn pairing_response_json(server_id: &str, environment_id: &str) -> serde_json::Value {
+    json!({
+        "pairing_code": "pairing-code",
+        "manual_pairing_code": "ABCD-EFGH",
+        "server_id": server_id,
+        "environment_id": environment_id,
+        "expires_at": "3026-05-22T12:34:56Z",
+    })
+}
+
+fn pairing_response(environment_id: &str) -> RemoteControlPairingStartResponse {
+    RemoteControlPairingStartResponse {
+        pairing_code: "pairing-code".to_string(),
+        manual_pairing_code: Some("ABCD-EFGH".to_string()),
+        environment_id: environment_id.to_string(),
+        expires_at: 33_336_362_096,
+    }
+}
+
+async fn pairing_error(status: &'static str, body: &'static str) -> (String, String) {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let expected_pair_url = normalize_remote_control_url(&remote_control_url)
+        .expect("target should normalize")
+        .pair_url;
+    let server_task = tokio::spawn(async move {
+        let pairing_request = accept_http_request(&listener).await;
+        respond_with_status_and_headers(
+            pairing_request.stream,
+            status,
+            &[("x-request-id", "request-123"), ("cf-ray", "ray-123")],
+            body,
+        )
+        .await;
+    });
+
+    let err = remote_control_enrollment(&remote_control_url, "remote-control-token")
+        .start_pairing(StartRemoteControlPairingRequest { manual_code: false })
+        .await
+        .expect_err("pairing should fail");
+    server_task.await.expect("server task should finish");
+    (err.to_string(), expected_pair_url)
+}
+
+async fn pairing_response_error(body: serde_json::Value) -> String {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let pairing_request = accept_http_request(&listener).await;
+        respond_with_json(pairing_request.stream, body).await;
+    });
+
+    let err = remote_control_enrollment(&remote_control_url, "remote-control-token")
+        .start_pairing(StartRemoteControlPairingRequest { manual_code: false })
+        .await
+        .expect_err("pairing should fail");
+    server_task.await.expect("server task should finish");
+    err.to_string()
+}
+
+async fn pairing_status_error(status: &'static str, body: &'static str) -> (io::Error, String) {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let expected_status_url = normalize_remote_control_url(&remote_control_url)
+        .expect("target should normalize")
+        .pair_status_url;
+    let server_task = tokio::spawn(async move {
+        let status_request = accept_http_request(&listener).await;
+        respond_with_status_and_headers(
+            status_request.stream,
+            status,
+            &[("x-request-id", "request-123"), ("cf-ray", "ray-123")],
+            body,
+        )
+        .await;
+    });
+
+    let err = remote_control_enrollment(&remote_control_url, "remote-control-token")
+        .pairing_status(RemoteControlPairingStatusRequest {
+            pairing_code: Some("pairing-code".to_string()),
+            manual_pairing_code: None,
+        })
+        .await
+        .expect_err("pairing status should fail");
+    server_task.await.expect("server task should finish");
+    (err, expected_status_url)
+}
+
+#[tokio::test]
+async fn remote_control_handle_starts_pairing_before_websocket_connects() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            refresh_request.request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&refresh_request.body)
+                .expect("refresh request body should deserialize"),
+            json!({
+                "server_id": "srv_e_test",
+                "installation_id": TEST_INSTALLATION_ID,
+            })
+        );
+        respond_with_json(
+            refresh_request.stream,
+            remote_control_server_token_response(
+                "srv_e_test",
+                "env_test",
+                TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN,
+            ),
+        )
+        .await;
+
+        let pairing_request = accept_http_request(&listener).await;
+        assert_eq!(
+            pairing_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+        );
+        assert_eq!(
+            pairing_request.headers.get("authorization"),
+            Some(&format!(
+                "Bearer {TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN}"
+            ))
+        );
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&pairing_request.body)
+                .expect("pairing request body should deserialize"),
+            json!({ "manual_code": true })
+        );
+        respond_with_json(
+            pairing_request.stream,
+            pairing_response_json("srv_e_test", "env_test"),
+        )
+        .await;
+    });
+    let remote_handle = remote_control_handle_with_current_enrollment(
+        &remote_control_url,
+        remote_control_auth_manager(),
+    );
+    remote_handle
+        .current_enrollment
+        .lock()
+        .await
+        .as_mut()
+        .expect("current enrollment should exist")
+        .expires_at = Some(OffsetDateTime::now_utc() + time::Duration::seconds(29));
+
+    let response = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams { manual_code: true },
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect("pairing should use the current server before websocket connect");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(response, pairing_response("env_test"));
+}
+
+#[tokio::test]
+async fn proactive_refresh_rate_limit_uses_valid_token_for_pairing() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            refresh_request.request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        respond_with_status_and_headers(
+            refresh_request.stream,
+            "429 Too Many Requests",
+            &[],
+            "rate limited",
+        )
+        .await;
+
+        let pairing_request = accept_http_request(&listener).await;
+        assert_eq!(
+            pairing_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+        );
+        assert_eq!(
+            pairing_request.headers.get("authorization"),
+            Some(&format!("Bearer {TEST_REMOTE_CONTROL_SERVER_TOKEN}"))
+        );
+        respond_with_json(
+            pairing_request.stream,
+            pairing_response_json("srv_e_test", "env_test"),
+        )
+        .await;
+    });
+    let remote_handle = remote_control_handle_with_current_enrollment(
+        &remote_control_url,
+        remote_control_auth_manager(),
+    );
+    remote_handle
+        .current_enrollment
+        .lock()
+        .await
+        .as_mut()
+        .expect("current enrollment should exist")
+        .expires_at = Some(OffsetDateTime::now_utc() + time::Duration::minutes(4));
+
+    let response = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect("valid token should allow pairing after proactive refresh failure");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(response, pairing_response("env_test"));
+    assert!(
+        remote_handle
+            .current_enrollment
+            .snapshot()
+            .and_then(|enrollment| enrollment.next_refresh_at)
+            .is_some()
+    );
+}
+
+#[tokio::test]
+async fn required_refresh_deadline_blocks_pairing_without_request() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            refresh_request.request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        respond_with_status_and_headers(
+            refresh_request.stream,
+            "502 Bad Gateway",
+            &[("retry-after", "120")],
+            "upstream unavailable",
+        )
+        .await;
+        listener
+    });
+    let remote_handle = remote_control_handle_with_current_enrollment(
+        &remote_control_url,
+        remote_control_auth_manager(),
+    );
+    remote_handle
+        .current_enrollment
+        .lock()
+        .await
+        .as_mut()
+        .expect("current enrollment should exist")
+        .expires_at = Some(OffsetDateTime::now_utc() - time::Duration::seconds(1));
+
+    let refresh_err = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect_err("required refresh failure should block pairing");
+    let listener = server_task.await.expect("server task should finish");
+    let next_refresh_at = remote_handle
+        .current_enrollment
+        .snapshot()
+        .and_then(|enrollment| enrollment.next_refresh_at)
+        .expect("required pairing refresh should preserve the retry deadline");
+    let deferred_err = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect_err("required refresh deadline should block pairing");
+
+    assert!(refresh_err.to_string().contains("HTTP 502 Bad Gateway"));
+    assert_eq!(deferred_err.kind(), io::ErrorKind::WouldBlock);
+    assert!(
+        deferred_err
+            .to_string()
+            .contains(&next_refresh_at.to_string())
+    );
+    timeout(Duration::from_millis(100), listener.accept())
+        .await
+        .expect_err("pairing should not issue a request before the refresh deadline");
+}
+
+#[tokio::test]
+async fn remote_control_pairing_status_returns_pending() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let status_request = accept_http_request(&listener).await;
+        assert_eq!(
+            status_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair/status HTTP/1.1"
+        );
+        assert_eq!(
+            status_request.headers.get("authorization"),
+            Some(&"Bearer remote-control-token".to_string())
+        );
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&status_request.body)
+                .expect("status request body should deserialize"),
+            json!({ "pairing_code": "pairing-code" })
+        );
+        respond_with_json(status_request.stream, json!({ "claimed": false })).await;
+    });
+
+    let response = remote_control_enrollment(&remote_control_url, "remote-control-token")
+        .pairing_status(RemoteControlPairingStatusRequest {
+            pairing_code: Some("pairing-code".to_string()),
+            manual_pairing_code: None,
+        })
+        .await
+        .expect("pairing status should succeed");
+    server_task.await.expect("server task should finish");
+
+    assert!(!response.claimed);
+}
+
+#[tokio::test]
+async fn remote_control_pairing_status_accepts_manual_pairing_code() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let status_request = accept_http_request(&listener).await;
+        assert_eq!(
+            status_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair/status HTTP/1.1"
+        );
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&status_request.body)
+                .expect("status request body should deserialize"),
+            json!({ "manual_pairing_code": "ABCD-EFGH" })
+        );
+        respond_with_json(status_request.stream, json!({ "claimed": false })).await;
+    });
+
+    let response = remote_control_enrollment(&remote_control_url, "remote-control-token")
+        .pairing_status(RemoteControlPairingStatusRequest {
+            pairing_code: None,
+            manual_pairing_code: Some("ABCD-EFGH".to_string()),
+        })
+        .await
+        .expect("pairing status should succeed");
+    server_task.await.expect("server task should finish");
+
+    assert!(!response.claimed);
+}
+
+#[tokio::test]
+async fn remote_control_pairing_status_returns_claimed() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let status_request = accept_http_request(&listener).await;
+        assert_eq!(
+            status_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair/status HTTP/1.1"
+        );
+        respond_with_json(status_request.stream, json!({ "claimed": true })).await;
+    });
+
+    let response = remote_control_enrollment(&remote_control_url, "remote-control-token")
+        .pairing_status(RemoteControlPairingStatusRequest {
+            pairing_code: Some("pairing-code".to_string()),
+            manual_pairing_code: None,
+        })
+        .await
+        .expect("pairing status should succeed");
+    server_task.await.expect("server task should finish");
+
+    assert!(response.claimed);
+}
+
+#[tokio::test]
+async fn remote_control_handle_refreshes_after_pairing_status_auth_failure() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let stale_status_request = accept_http_request(&listener).await;
+        assert_eq!(
+            stale_status_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair/status HTTP/1.1"
+        );
+        assert_eq!(
+            stale_status_request.headers.get("authorization"),
+            Some(&format!("Bearer {TEST_REMOTE_CONTROL_SERVER_TOKEN}"))
+        );
+        respond_with_status(stale_status_request.stream, "401 Unauthorized", "").await;
+
+        let refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            refresh_request.request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        respond_with_json(
+            refresh_request.stream,
+            remote_control_server_token_response(
+                "srv_e_test",
+                "env_test",
+                TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN,
+            ),
+        )
+        .await;
+
+        let refreshed_status_request = accept_http_request(&listener).await;
+        assert_eq!(
+            refreshed_status_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair/status HTTP/1.1"
+        );
+        assert_eq!(
+            refreshed_status_request.headers.get("authorization"),
+            Some(&format!(
+                "Bearer {TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN}"
+            ))
+        );
+        respond_with_json(refreshed_status_request.stream, json!({ "claimed": true })).await;
+    });
+    let remote_handle = remote_control_handle_with_current_enrollment(
+        &remote_control_url,
+        remote_control_auth_manager(),
+    );
+
+    let response = remote_handle
+        .pairing_status(RemoteControlPairingStatusParams {
+            pairing_code: Some("pairing-code".to_string()),
+            manual_pairing_code: None,
+        })
+        .await
+        .expect("pairing status should refresh after server token auth failure");
+    server_task.await.expect("server task should finish");
+
+    assert!(response.claimed);
+}
+
+#[tokio::test]
+async fn remote_control_pairing_status_maps_user_actionable_backend_errors() {
+    for (status, expected_kind) in [
+        ("403 Forbidden", io::ErrorKind::PermissionDenied),
+        ("404 Not Found", io::ErrorKind::InvalidInput),
+        ("410 Gone", io::ErrorKind::InvalidInput),
+    ] {
+        let (err, _expected_status_url) = pairing_status_error(status, "not available").await;
+        assert_eq!(err.kind(), expected_kind);
+    }
+}
+
+#[tokio::test]
+async fn remote_control_pairing_status_preserves_decode_error_context() {
+    let (err, expected_status_url) = pairing_status_error("200 OK", "{").await;
+    let err = err.to_string();
+
+    assert!(err.contains(&format!(
+        "failed to parse remote control pairing status response from `{expected_status_url}`: HTTP 200 OK"
+    )));
+    assert!(err.contains("request-id: request-123"));
+    assert!(err.contains("cf-ray: ray-123"));
+    assert!(err.contains("body: {"));
+    assert!(err.contains("decode error:"));
+}
+
+#[tokio::test]
+async fn remote_control_handle_refreshes_after_pairing_auth_failure() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let stale_pairing_request = accept_http_request(&listener).await;
+        assert_eq!(
+            stale_pairing_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+        );
+        assert_eq!(
+            stale_pairing_request.headers.get("authorization"),
+            Some(&format!("Bearer {TEST_REMOTE_CONTROL_SERVER_TOKEN}"))
+        );
+        respond_with_status(stale_pairing_request.stream, "401 Unauthorized", "").await;
+
+        let refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            refresh_request.request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        assert_eq!(
+            refresh_request.headers.get("authorization"),
+            Some(&"Bearer Access Token".to_string())
+        );
+        respond_with_json(
+            refresh_request.stream,
+            remote_control_server_token_response(
+                "srv_e_test",
+                "env_test",
+                TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN,
+            ),
+        )
+        .await;
+
+        let refreshed_pairing_request = accept_http_request(&listener).await;
+        assert_eq!(
+            refreshed_pairing_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+        );
+        assert_eq!(
+            refreshed_pairing_request.headers.get("authorization"),
+            Some(&format!(
+                "Bearer {TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN}"
+            ))
+        );
+        respond_with_json(
+            refreshed_pairing_request.stream,
+            pairing_response_json("srv_e_test", "env_test"),
+        )
+        .await;
+    });
+    let remote_handle = remote_control_handle_with_current_enrollment(
+        &remote_control_url,
+        remote_control_auth_manager(),
+    );
+
+    let response = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect("pairing should refresh after server token auth failure");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(response, pairing_response("env_test"));
+}
+
+#[tokio::test]
+async fn pairing_auth_failure_preserves_refresh_deadline() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let pairing_request = accept_http_request(&listener).await;
+        assert_eq!(
+            pairing_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+        );
+        respond_with_status(pairing_request.stream, "401 Unauthorized", "").await;
+    });
+    let remote_handle = remote_control_handle_with_current_enrollment(
+        &remote_control_url,
+        remote_control_auth_manager(),
+    );
+    let next_refresh_at = OffsetDateTime::now_utc() + time::Duration::minutes(2);
+    remote_handle
+        .current_enrollment
+        .lock()
+        .await
+        .as_mut()
+        .expect("current enrollment should exist")
+        .next_refresh_at = Some(next_refresh_at);
+    let mut expected_enrollment = remote_handle
+        .current_enrollment
+        .snapshot()
+        .expect("current enrollment should exist");
+    expected_enrollment.clear_server_token();
+
+    let err = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect_err("refresh deadline should throttle recovery after token rejection");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(err.kind(), io::ErrorKind::WouldBlock);
+    assert_eq!(
+        remote_handle.current_enrollment.snapshot(),
+        Some(expected_enrollment)
+    );
+}
+
+#[tokio::test]
+async fn remote_control_handle_recovers_auth_before_refreshing_pairing() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let stale_refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            stale_refresh_request.request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        assert_eq!(
+            stale_refresh_request.headers.get("authorization"),
+            Some(&"Bearer stale-token".to_string())
+        );
+        respond_with_status(stale_refresh_request.stream, "401 Unauthorized", "").await;
+
+        let recovered_refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            recovered_refresh_request.request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        assert_eq!(
+            recovered_refresh_request.headers.get("authorization"),
+            Some(&"Bearer fresh-token".to_string())
+        );
+        respond_with_json(
+            recovered_refresh_request.stream,
+            remote_control_server_token_response(
+                "srv_e_test",
+                "env_test",
+                TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN,
+            ),
+        )
+        .await;
+
+        let pairing_request = accept_http_request(&listener).await;
+        assert_eq!(
+            pairing_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+        );
+        assert_eq!(
+            pairing_request.headers.get("authorization"),
+            Some(&format!(
+                "Bearer {TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN}"
+            ))
+        );
+        respond_with_json(
+            pairing_request.stream,
+            pairing_response_json("srv_e_test", "env_test"),
+        )
+        .await;
+    });
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let auth_manager = auth_manager_with_replacement(&codex_home, "account_id").await;
+    let remote_handle =
+        remote_control_handle_with_current_enrollment(&remote_control_url, auth_manager);
+    remote_handle
+        .current_enrollment
+        .lock()
+        .await
+        .as_mut()
+        .expect("current enrollment should exist")
+        .expires_at = Some(OffsetDateTime::now_utc() + time::Duration::seconds(29));
+
+    let response = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect("pairing should refresh after auth recovery");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(response, pairing_response("env_test"));
+}
+
+#[tokio::test]
+async fn pairing_publishes_refresh_deferral_after_auth_recovery() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let stale_refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            stale_refresh_request.headers.get("authorization"),
+            Some(&"Bearer stale-token".to_string())
+        );
+        respond_with_status(stale_refresh_request.stream, "401 Unauthorized", "").await;
+
+        let recovered_refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            recovered_refresh_request.headers.get("authorization"),
+            Some(&"Bearer fresh-token".to_string())
+        );
+        let response_started_at = OffsetDateTime::now_utc();
+        respond_with_status_and_headers(
+            recovered_refresh_request.stream,
+            "502 Bad Gateway",
+            &[("retry-after", "120")],
+            "upstream unavailable",
+        )
+        .await;
+        response_started_at
+    });
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let auth_manager = auth_manager_with_replacement(&codex_home, "account_id").await;
+    let remote_handle =
+        remote_control_handle_with_current_enrollment(&remote_control_url, auth_manager);
+    remote_handle
+        .current_enrollment
+        .lock()
+        .await
+        .as_mut()
+        .expect("current enrollment should exist")
+        .expires_at = Some(OffsetDateTime::now_utc() - time::Duration::seconds(1));
+
+    let refresh_err = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect_err("required refresh should remain strict after auth recovery");
+    let refresh_completed_at = OffsetDateTime::now_utc();
+    let deferred_err = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect_err("published deadline should throttle the next pairing refresh");
+    let response_started_at = server_task.await.expect("server task should finish");
+
+    assert!(refresh_err.to_string().contains("HTTP 502 Bad Gateway"));
+    assert_eq!(deferred_err.kind(), io::ErrorKind::WouldBlock);
+    let next_refresh_at = remote_handle
+        .current_enrollment
+        .snapshot()
+        .and_then(|enrollment| enrollment.next_refresh_at)
+        .expect("required refresh failure should publish its retry deadline");
+    assert!(
+        (response_started_at + time::Duration::seconds(120)
+            ..=refresh_completed_at + time::Duration::seconds(150))
+            .contains(&next_refresh_at)
+    );
+}
+
+#[tokio::test]
+async fn pairing_auth_recovery_failure_publishes_cleared_server_token() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let server_task = tokio::spawn(async move {
+        let stale_refresh_request = accept_http_request(&listener).await;
+        assert_eq!(
+            stale_refresh_request.request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        assert_eq!(
+            stale_refresh_request.headers.get("authorization"),
+            Some(&"Bearer stale-token".to_string())
+        );
+        respond_with_status(stale_refresh_request.stream, "401 Unauthorized", "").await;
+    });
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let auth_manager = auth_manager_with_replacement(&codex_home, "different_account_id").await;
+    let remote_handle =
+        remote_control_handle_with_current_enrollment(&remote_control_url, auth_manager);
+    remote_handle
+        .current_enrollment
+        .lock()
+        .await
+        .as_mut()
+        .expect("current enrollment should exist")
+        .expires_at = Some(OffsetDateTime::now_utc() + time::Duration::seconds(29));
+    let mut expected_enrollment = remote_handle
+        .current_enrollment
+        .snapshot()
+        .expect("current enrollment should exist");
+    expected_enrollment.clear_server_token();
+
+    let err = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect_err("pairing should fail after auth changes account");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(err.kind(), io::ErrorKind::PermissionDenied);
+    assert_eq!(
+        remote_handle.current_enrollment.snapshot(),
+        Some(expected_enrollment)
+    );
+}
+
+#[tokio::test]
+async fn start_remote_control_pairing_preserves_backend_error_context() {
+    let (err, expected_pair_url) =
+        pairing_error("503 Service Unavailable", "pairing unavailable").await;
+
+    assert_eq!(
+        err,
+        format!(
+            "remote control pairing failed at `{expected_pair_url}`: HTTP 503 Service Unavailable, request-id: request-123, cf-ray: ray-123, body: pairing unavailable"
+        )
+    );
+}
+
+#[tokio::test]
+async fn start_remote_control_pairing_preserves_decode_error_context() {
+    let (err, expected_pair_url) = pairing_error("200 OK", "{").await;
+    assert!(err.contains(&format!(
+        "failed to parse remote control pairing response from `{expected_pair_url}`: HTTP 200 OK"
+    )));
+    assert!(err.contains("request-id: request-123"));
+    assert!(err.contains("cf-ray: ray-123"));
+    assert!(err.contains("body: {"));
+    assert!(err.contains("decode error:"));
+}
+
+#[tokio::test]
+async fn start_remote_control_pairing_rejects_mismatched_backend_enrollment() {
+    assert_eq!(
+        pairing_response_error(json!({
+            "pairing_code": "pairing-code",
+            "manual_pairing_code": "ABCD-EFGH",
+            "server_id": "other-server-id",
+            "environment_id": "other-environment-id",
+            "expires_at": "3026-05-22T12:34:56Z",
+        }))
+        .await,
+        "remote control pairing returned mismatched enrollment: expected server_id=server-id, environment_id=environment-id; got server_id=other-server-id, environment_id=other-environment-id"
+    );
+}
+
+#[tokio::test]
+async fn start_remote_control_pairing_preserves_expiry_parse_error_context() {
+    let err = pairing_response_error(json!({
+        "pairing_code": "pairing-code",
+        "manual_pairing_code": "ABCD-EFGH",
+        "server_id": "server-id",
+        "environment_id": "environment-id",
+        "expires_at": "not-a-timestamp",
+    }))
+    .await;
+
+    assert!(err.contains("failed to parse remote control pairing response"));
+    assert!(err.contains("HTTP 200 OK"));
+    assert!(err.contains("request-id: <none>"));
+    assert!(err.contains("cf-ray: <none>"));
+    assert!(err.contains("\"expires_at\":\"not-a-timestamp\""));
+    assert!(err.contains("expires_at parse error:"));
+}
+
+#[tokio::test]
+async fn remote_control_handle_disable_keeps_current_enrollment() {
+    let remote_handle = remote_control_handle_with_current_enrollment(
+        TEST_REMOTE_CONTROL_URL,
+        remote_control_auth_manager(),
+    );
+
+    remote_handle
+        .desired_state_tx
+        .send_replace(RemoteControlDesiredState::Disabled);
+    assert!(
+        remote_handle.current_enrollment.lock().await.is_some(),
+        "disabled remote control should keep the selected pairing server"
+    );
+}
+
+#[tokio::test]
+async fn remote_control_handle_reenrolls_after_stale_pairing_enrollment() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let state_db = remote_control_state_runtime(&codex_home).await;
+    let mut remote_handle = remote_control_handle_with_current_enrollment(
+        &remote_control_url,
+        remote_control_auth_manager_with_home(&codex_home),
+    );
+    remote_handle.state_db = Some(state_db.clone());
+    let stale_enrollment = remote_handle
+        .current_enrollment
+        .lock()
+        .await
+        .clone()
+        .expect("current enrollment should exist");
+    let remote_control_target = stale_enrollment.remote_control_target.clone();
+    let refreshed_enrollment = RemoteControlEnrollment {
+        remote_control_target: remote_control_target.clone(),
+        account_id: "account_id".to_string(),
+        environment_id: "env_refreshed".to_string(),
+        server_id: "srv_e_refreshed".to_string(),
+        server_name: test_server_name(),
+        remote_control_token: None,
+        expires_at: None,
+        next_refresh_at: None,
+    };
+    update_persisted_remote_control_enrollment(
+        Some(state_db.as_ref()),
+        &remote_control_target,
+        "account_id",
+        /*app_server_client_name*/ None,
+        Some(&stale_enrollment),
+        /*remote_control_enabled*/ Some(true),
+    )
+    .await
+    .expect("stale enrollment should save");
+    remote_handle
+        .desired_state_tx
+        .send_replace(RemoteControlDesiredState::Enabled {
+            persistence_preference: Some(true),
+        });
+    let server_refreshed_enrollment = refreshed_enrollment.clone();
+    let server_task = tokio::spawn(async move {
+        let stale_pairing_request = accept_http_request(&listener).await;
+        assert_eq!(
+            stale_pairing_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+        );
+        assert_eq!(
+            stale_pairing_request.headers.get("authorization"),
+            Some(&format!("Bearer {TEST_REMOTE_CONTROL_SERVER_TOKEN}"))
+        );
+        respond_with_status(stale_pairing_request.stream, "404 Not Found", "").await;
+
+        let enroll_request = accept_http_request(&listener).await;
+        assert_eq!(
+            enroll_request.request_line,
+            "POST /backend-api/wham/remote/control/server/enroll HTTP/1.1"
+        );
+        respond_with_json(
+            enroll_request.stream,
+            remote_control_server_token_response(
+                &server_refreshed_enrollment.server_id,
+                &server_refreshed_enrollment.environment_id,
+                TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN,
+            ),
+        )
+        .await;
+
+        let refreshed_pairing_request = accept_http_request(&listener).await;
+        assert_eq!(
+            refreshed_pairing_request.request_line,
+            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+        );
+        assert_eq!(
+            refreshed_pairing_request.headers.get("authorization"),
+            Some(&format!(
+                "Bearer {TEST_REFRESHED_REMOTE_CONTROL_SERVER_TOKEN}"
+            ))
+        );
+        respond_with_json(
+            refreshed_pairing_request.stream,
+            pairing_response_json(
+                &server_refreshed_enrollment.server_id,
+                &server_refreshed_enrollment.environment_id,
+            ),
+        )
+        .await;
+    });
+    let response = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect("pairing should re-enroll after stale enrollment");
+    server_task.await.expect("server task should finish");
+
+    assert_eq!(response, pairing_response("env_refreshed"));
+    assert_eq!(
+        state_db
+            .get_remote_control_enrollment(
+                &remote_control_target.websocket_url,
+                "account_id",
+                /*app_server_client_name*/ None,
+            )
+            .await
+            .expect("refreshed enrollment should load")
+            .expect("refreshed enrollment should exist")
+            .remote_control_enabled,
+        Some(true)
+    );
+}
+
+#[tokio::test]
+async fn remote_control_handle_discards_pairing_response_after_auth_change() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let codex_home = TempDir::new().expect("temp dir should create");
+    save_auth(
+        codex_home.path(),
+        &remote_control_auth_dot_json(Some("account_id")),
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("initial auth should save");
+    let auth_manager = AuthManager::shared(
+        codex_home.path().to_path_buf(),
+        /*enable_codex_api_key_env*/ false,
+        AuthCredentialsStoreMode::File,
+        /*forced_chatgpt_workspace_id*/ None,
+        /*chatgpt_base_url*/ None,
+        AuthKeyringBackendKind::default(),
+        codex_login::test_support::transport_default_auth_route_config(),
+    )
+    .await;
+    let remote_handle =
+        remote_control_handle_with_current_enrollment(&remote_control_url, auth_manager.clone());
+    let pairing_task = tokio::spawn({
+        let remote_handle = remote_handle.clone();
+        async move {
+            remote_handle
+                .start_pairing(
+                    RemoteControlPairingStartParams::default(),
+                    /*app_server_client_name*/ None,
+                )
+                .await
+        }
+    });
+
+    let pairing_request = accept_http_request(&listener).await;
+    save_auth(
+        codex_home.path(),
+        &remote_control_auth_dot_json(Some("next_account_id")),
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("next auth should save");
+    auth_manager.reload().await;
+    respond_with_json(
+        pairing_request.stream,
+        json!({
+            "pairing_code": "stale-pairing-code",
+            "manual_pairing_code": "ABCD-EFGH",
+            "server_id": "srv_e_test",
+            "environment_id": "env_test",
+            "expires_at": "3026-05-22T12:34:56Z",
+        }),
+    )
+    .await;
+
+    assert_eq!(
+        pairing_task
+            .await
+            .expect("pairing task should join")
+            .expect_err("stale pairing response should be discarded")
+            .to_string(),
+        "remote control pairing is unavailable until enrollment completes"
+    );
+}

codex-rs/app-server-transport/src/transport/remote_control/tests/retry_tests.rs

@@ -0,0 +1,203 @@
+//! Exercises overload retry deadlines over HTTP and WebSocket connections.
+//! Auth reloads must respect the deadline; shutdown must remain prompt.
+
+use super::*;
+use pretty_assertions::assert_eq;
+
+#[tokio::test]
+async fn rate_limited_enrollment_respects_retry_after() {
+    assert_overload_retry_after("429 Too Many Requests", /*reject_enrollment*/ true).await;
+}
+
+#[tokio::test]
+async fn rate_limited_websocket_respects_retry_after() {
+    assert_overload_retry_after("429 Too Many Requests", /*reject_enrollment*/ false).await;
+}
+
+#[tokio::test]
+async fn enrollment_resumes_after_retry_after() {
+    assert_overload_retry_after("503 Service Unavailable", /*reject_enrollment*/ true).await;
+}
+
+#[tokio::test]
+async fn websocket_resumes_after_retry_after() {
+    assert_overload_retry_after("503 Service Unavailable", /*reject_enrollment*/ false).await;
+}
+
+async fn assert_overload_retry_after(status: &str, reject_enrollment: bool) {
+    let verify_recovery = status == "503 Service Unavailable";
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let (transport_event_tx, _transport_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+    let shutdown_token = CancellationToken::new();
+    let auth_manager = remote_control_auth_manager_with_home(&codex_home);
+    let mut initial_auth = remote_control_auth_dot_json(Some("account_id"));
+    initial_auth
+        .tokens
+        .as_mut()
+        .expect("fixture should contain tokens")
+        .access_token = "Initial Access Token".to_string();
+    save_auth(
+        codex_home.path(),
+        &initial_auth,
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("initial credentials should save");
+    auth_manager.reload().await;
+    let (remote_task, remote_handle) = start_remote_control(
+        RemoteControlStartConfig {
+            remote_control_url: remote_control_url_for_listener(&listener),
+            installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
+        },
+        Some(remote_control_state_runtime(&codex_home).await),
+        auth_manager.clone(),
+        transport_event_tx,
+        shutdown_token.clone(),
+        /*app_server_client_name_rx*/ None,
+        RemoteControlStartupMode::EnabledEphemeral,
+    )
+    .await
+    .expect("remote control should start");
+    let mut status_rx = remote_handle.status_receiver();
+    let mut rejected_request = accept_http_request(&listener).await;
+    assert_eq!(
+        rejected_request.request_line,
+        "POST /backend-api/wham/remote/control/server/enroll HTTP/1.1"
+    );
+    if !reject_enrollment {
+        respond_with_json(
+            rejected_request.stream,
+            remote_control_server_token_response(
+                "srv_e_test",
+                "env_test",
+                TEST_REMOTE_CONTROL_SERVER_TOKEN,
+            ),
+        )
+        .await;
+        rejected_request = accept_http_request(&listener).await;
+        assert_eq!(
+            rejected_request.request_line,
+            "GET /backend-api/wham/remote/control/server HTTP/1.1"
+        );
+    }
+    let response_started_at = std::time::Instant::now();
+    respond_with_status_and_headers(
+        rejected_request.stream,
+        status,
+        &[("Retry-After", if verify_recovery { "3" } else { "120" })],
+        "overloaded",
+    )
+    .await;
+    timeout(
+        Duration::from_secs(5),
+        status_rx.wait_for(|status| status.status == RemoteControlConnectionStatus::Errored),
+    )
+    .await
+    .expect("the overload response should be processed")
+    .expect("the status channel should remain open");
+
+    let auth_changes = auth_manager.auth_change_receiver();
+    save_auth(
+        codex_home.path(),
+        &remote_control_auth_dot_json(Some("account_id")),
+        AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )
+    .expect("updated credentials should save");
+    auth_manager.reload().await;
+    assert!(
+        auth_changes
+            .has_changed()
+            .expect("auth watch should remain open")
+    );
+
+    if !verify_recovery {
+        let pairing_error = timeout(
+            Duration::from_secs(1),
+            remote_handle.start_pairing(
+                RemoteControlPairingStartParams::default(),
+                /*app_server_client_name*/ None,
+            ),
+        )
+        .await
+        .expect("pairing should report the active retry delay promptly")
+        .expect_err("pairing must respect the shared server retry delay");
+        let retry_delay = server_api::remote_control_retry_delay(&pairing_error)
+            .expect("pairing should preserve the overload retry deadline");
+        assert!(
+            retry_delay >= Duration::from_secs(120).saturating_sub(response_started_at.elapsed()),
+            "pairing must preserve the full remaining Retry-After interval"
+        );
+        assert!(
+            timeout(Duration::from_secs(2), listener.accept())
+                .await
+                .is_err(),
+            "no enrollment, refresh or handshake should retry before Retry-After ({status})"
+        );
+        remote_handle.disable_ephemeral().await;
+        assert!(
+            timeout(Duration::from_secs(2), listener.accept())
+                .await
+                .is_err(),
+            "disabling remote control must stop connection attempts"
+        );
+        remote_handle
+            .enable_ephemeral()
+            .expect("remote control should enable again");
+        assert!(
+            timeout(Duration::from_secs(2), listener.accept())
+                .await
+                .is_err(),
+            "re-enabling remote control must preserve the server retry delay"
+        );
+    }
+    if !reject_enrollment {
+        assert_eq!(
+            remote_handle
+                .inner
+                .session()
+                .current_enrollment
+                .snapshot()
+                .and_then(|enrollment| enrollment.remote_control_token),
+            Some(TEST_REMOTE_CONTROL_SERVER_TOKEN.to_string()),
+            "overload must preserve the enrolled token"
+        );
+    }
+    if verify_recovery {
+        remote_handle.disable_ephemeral().await;
+        remote_handle
+            .enable_ephemeral()
+            .expect("remote control should enable again");
+        let (stream, _) = timeout(Duration::from_secs(45), listener.accept())
+            .await
+            .expect("retry should resume after the server delay and bounded jitter")
+            .expect("retry connection should succeed");
+        assert!(
+            response_started_at.elapsed() >= Duration::from_secs(3),
+            "the retry must wait for the full Retry-After interval"
+        );
+        let mut reader = BufReader::new(stream);
+        let mut request_line = String::new();
+        timeout(Duration::from_secs(5), reader.read_line(&mut request_line))
+            .await
+            .expect("retry should send the request promptly")
+            .expect("retry request should read");
+        assert_eq!(
+            request_line.trim_end(),
+            if reject_enrollment {
+                "POST /backend-api/wham/remote/control/server/enroll HTTP/1.1"
+            } else {
+                "GET /backend-api/wham/remote/control/server HTTP/1.1"
+            }
+        );
+    }
+    shutdown_token.cancel();
+    timeout(Duration::from_secs(1), remote_task)
+        .await
+        .expect("shutdown must interrupt the server retry delay")
+        .expect("remote task should finish");
+}

codex-rs/app-server-transport/src/transport/remote_control/websocket_refresh_tests.rs

@@ -0,0 +1,768 @@
+use super::tests::TEST_HTTP_ACCEPT_TIMEOUT;
+use super::tests::TEST_INSTALLATION_ID;
+use super::tests::TEST_REMOTE_CONTROL_SERVER_TOKEN;
+use super::tests::accept_http_request;
+use super::tests::enabled_desired_state_sender;
+use super::tests::remote_control_auth_dot_json;
+use super::tests::remote_control_auth_manager;
+use super::tests::remote_control_enrollment;
+use super::tests::remote_control_state_runtime;
+use super::tests::remote_control_status_channel;
+use super::tests::remote_control_url_for_listener;
+use super::tests::respond_with_status_and_headers;
+use super::tests::test_current_enrollment;
+use super::*;
+use crate::transport::remote_control::protocol::normalize_remote_control_url;
+use crate::transport::remote_control::server_api::remote_control_retry_at;
+use crate::transport::remote_control::tests::remote_control_handle_with_current_enrollment;
+use codex_app_server_protocol::RemoteControlPairingStartParams;
+use codex_app_server_protocol::RemoteControlPairingStatusParams;
+use codex_config::types::AuthCredentialsStoreMode;
+use codex_login::AuthKeyringBackendKind;
+use codex_login::AuthManager;
+use codex_login::save_auth;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+use tokio::io::AsyncWriteExt;
+use tokio::net::TcpListener;
+use tokio::net::TcpStream;
+use tokio::time::Duration;
+use tokio::time::timeout;
+use tokio_tungstenite::WebSocketStream;
+use tokio_tungstenite::accept_async;
+
+async fn connect_test_websocket(
+    remote_control_target: &RemoteControlTarget,
+    state_db: &StateRuntime,
+    auth_manager: &Arc<AuthManager>,
+    current_enrollment: &CurrentRemoteControlEnrollment,
+) -> io::Result<()> {
+    let session_auth = RemoteControlAuth::capture(auth_manager.clone()).0;
+    let mut auth_recovery = session_auth.unauthorized_recovery();
+    let mut auth_change_rx = auth_manager.auth_change_receiver();
+    let (status_publisher, _) = remote_control_status_channel();
+    let desired_state_tx = enabled_desired_state_sender();
+    let persistence = RemoteControlPersistence::default();
+    connect_remote_control_websocket(
+        remote_control_target,
+        Some(state_db),
+        RemoteControlAuthContext {
+            auth_manager: &session_auth,
+            auth_recovery: &mut auth_recovery,
+            auth_change_rx: &mut auth_change_rx,
+        },
+        current_enrollment,
+        RemoteControlConnectOptions {
+            installation_id: TEST_INSTALLATION_ID,
+            server_name: "test-server",
+            subscribe_cursor: None,
+            app_server_client_name: None,
+            desired_state_tx: &desired_state_tx,
+            persistence: &persistence,
+        },
+        &status_publisher,
+    )
+    .await
+    .map(|_| ())
+}
+
+#[tokio::test]
+async fn proactive_refresh_failure_uses_valid_token_for_websocket_connect() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let remote_control_target =
+        normalize_remote_control_url(&remote_control_url).expect("target should parse");
+    let server_task = tokio::spawn(async move {
+        let (stream, request_line) = accept_http_request(&listener).await;
+        assert_eq!(
+            request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        respond_with_status_and_headers(stream, "502 Bad Gateway", &[], "upstream unavailable")
+            .await;
+        accept_test_websocket(&listener).await
+    });
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let state_db = remote_control_state_runtime(&codex_home).await;
+    let auth_manager = remote_control_auth_manager();
+    let mut enrollment = remote_control_enrollment(Some(TEST_REMOTE_CONTROL_SERVER_TOKEN));
+    enrollment.expires_at = Some(time::OffsetDateTime::now_utc() + time::Duration::minutes(4));
+    let current_enrollment = test_current_enrollment(Some(enrollment));
+
+    let refresh_started_at = time::OffsetDateTime::now_utc();
+    connect_test_websocket(
+        &remote_control_target,
+        state_db.as_ref(),
+        &auth_manager,
+        &current_enrollment,
+    )
+    .await
+    .expect("valid token should allow websocket connect after proactive refresh failure");
+    let refresh_completed_at = time::OffsetDateTime::now_utc();
+    let server_websocket = server_task.await.expect("server task should succeed");
+
+    let enrollment = current_enrollment
+        .lock()
+        .await
+        .clone()
+        .expect("enrollment should remain available");
+    assert_eq!(
+        enrollment.remote_control_token.as_deref(),
+        Some(TEST_REMOTE_CONTROL_SERVER_TOKEN)
+    );
+    let next_refresh_at = enrollment
+        .next_refresh_at
+        .expect("transient refresh should set a retry deadline");
+    assert!(
+        (refresh_started_at + time::Duration::seconds(24)
+            ..=refresh_completed_at + time::Duration::seconds(36))
+            .contains(&next_refresh_at)
+    );
+    drop(server_websocket);
+}
+
+#[tokio::test]
+async fn proactive_refresh_connection_failure_uses_valid_token_for_websocket_connect() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let remote_control_target =
+        normalize_remote_control_url(&remote_control_url).expect("target should parse");
+    let server_task = tokio::spawn(async move {
+        let (stream, request_line) = accept_http_request(&listener).await;
+        assert_eq!(
+            request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        drop(stream);
+        accept_test_websocket(&listener).await
+    });
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let state_db = remote_control_state_runtime(&codex_home).await;
+    let auth_manager = remote_control_auth_manager();
+    let mut enrollment = remote_control_enrollment(Some(TEST_REMOTE_CONTROL_SERVER_TOKEN));
+    enrollment.expires_at = Some(time::OffsetDateTime::now_utc() + time::Duration::minutes(4));
+    let current_enrollment = test_current_enrollment(Some(enrollment));
+
+    connect_test_websocket(
+        &remote_control_target,
+        state_db.as_ref(),
+        &auth_manager,
+        &current_enrollment,
+    )
+    .await
+    .expect("valid token should allow websocket connect after refresh connection failure");
+    let server_websocket = server_task.await.expect("server task should succeed");
+
+    assert!(
+        current_enrollment
+            .snapshot()
+            .and_then(|enrollment| enrollment.next_refresh_at)
+            .is_some(),
+        "connection failure should set a retry deadline"
+    );
+    drop(server_websocket);
+}
+
+#[tokio::test]
+async fn websocket_retry_after_throttles_pairing_refresh() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let remote_control_target =
+        normalize_remote_control_url(&remote_control_url).expect("target should parse");
+    let server_task = tokio::spawn(async move {
+        let (stream, request_line) = accept_http_request(&listener).await;
+        assert_eq!(
+            request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        respond_with_status_and_headers(
+            stream,
+            "502 Bad Gateway",
+            &[("retry-after", "120")],
+            "upstream unavailable",
+        )
+        .await;
+        listener
+    });
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let state_db = remote_control_state_runtime(&codex_home).await;
+    let auth_manager = remote_control_auth_manager();
+    let mut remote_handle =
+        remote_control_handle_with_current_enrollment(&remote_control_url, auth_manager.clone());
+    remote_handle.state_db = Some(state_db.clone());
+    remote_handle
+        .current_enrollment
+        .lock()
+        .await
+        .as_mut()
+        .expect("current enrollment should exist")
+        .expires_at = Some(time::OffsetDateTime::now_utc() + time::Duration::minutes(4));
+    let current_enrollment = remote_handle.current_enrollment.clone();
+    let refresh_started_at = time::OffsetDateTime::now_utc();
+    let refresh_error = connect_test_websocket(
+        &remote_control_target,
+        state_db.as_ref(),
+        &auth_manager,
+        &current_enrollment,
+    )
+    .await
+    .expect_err("an explicit server deadline must defer the handshake even with a valid token");
+    let refresh_completed_at = time::OffsetDateTime::now_utc();
+    let next_refresh_at = current_enrollment
+        .snapshot()
+        .and_then(|enrollment| enrollment.next_refresh_at)
+        .expect("Retry-After should set a retry deadline");
+    assert!(
+        (refresh_started_at + time::Duration::seconds(120)
+            ..=refresh_completed_at + time::Duration::seconds(150))
+            .contains(&next_refresh_at)
+    );
+
+    let pairing_error = remote_handle
+        .start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        )
+        .await
+        .expect_err("the refresh deadline must also defer pairing");
+    let listener = server_task.await.expect("server task should succeed");
+    assert_eq!(
+        remote_control_retry_at(&refresh_error),
+        Some(next_refresh_at)
+    );
+    assert_eq!(
+        remote_control_retry_at(&pairing_error),
+        Some(next_refresh_at)
+    );
+    assert_eq!(
+        current_enrollment
+            .snapshot()
+            .and_then(|enrollment| enrollment.remote_control_token),
+        Some(TEST_REMOTE_CONTROL_SERVER_TOKEN.to_string())
+    );
+    timeout(Duration::from_millis(100), listener.accept())
+        .await
+        .expect_err("no handshake or pairing should bypass the proactive refresh deadline");
+}
+
+#[tokio::test]
+async fn pairing_http_date_retry_after_throttles_websocket_refresh() {
+    for status in [
+        "429 Too Many Requests",
+        "503 Service Unavailable",
+        "502 Bad Gateway",
+    ] {
+        let listener = TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("listener should bind");
+        let remote_control_url = remote_control_url_for_listener(&listener);
+        let remote_control_target =
+            normalize_remote_control_url(&remote_control_url).expect("target should parse");
+        let retry_after =
+            httpdate::fmt_http_date(std::time::SystemTime::now() + Duration::from_secs(120));
+        let expected_next_refresh_at = time::OffsetDateTime::from(
+            httpdate::parse_http_date(&retry_after).expect("Retry-After date should parse"),
+        );
+        let server_task = tokio::spawn(async move {
+            let (refresh_stream, request_line) = accept_http_request(&listener).await;
+            assert_eq!(
+                request_line,
+                "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+            );
+            respond_with_status_and_headers(
+                refresh_stream,
+                status,
+                &[("retry-after", &retry_after)],
+                "upstream unavailable",
+            )
+            .await;
+            listener
+        });
+        let codex_home = TempDir::new().expect("temp dir should create");
+        let state_db = remote_control_state_runtime(&codex_home).await;
+        let auth_manager = remote_control_auth_manager();
+        let mut remote_handle = remote_control_handle_with_current_enrollment(
+            &remote_control_url,
+            auth_manager.clone(),
+        );
+        remote_handle.state_db = Some(state_db.clone());
+        remote_handle
+            .current_enrollment
+            .lock()
+            .await
+            .as_mut()
+            .expect("current enrollment should exist")
+            .expires_at = Some(time::OffsetDateTime::now_utc() + time::Duration::minutes(4));
+        let current_enrollment = remote_handle.current_enrollment.clone();
+
+        let refresh_error = remote_handle
+            .start_pairing(
+                RemoteControlPairingStartParams::default(),
+                /*app_server_client_name*/ None,
+            )
+            .await
+            .expect_err("an explicit server deadline must defer pairing even with a valid token");
+        let listener = server_task.await.expect("server task should succeed");
+        let retry_at = remote_control_retry_at(&refresh_error)
+            .expect("the proactive refresh response should preserve its deadline");
+        let enrollment = current_enrollment
+            .snapshot()
+            .expect("enrollment should remain");
+        assert_eq!(enrollment.next_refresh_at, Some(retry_at));
+        assert_eq!(
+            enrollment.remote_control_token.as_deref(),
+            Some(TEST_REMOTE_CONTROL_SERVER_TOKEN)
+        );
+        assert!(
+            (expected_next_refresh_at..=expected_next_refresh_at + time::Duration::seconds(30))
+                .contains(&retry_at)
+        );
+        let connect_error = connect_test_websocket(
+            &remote_control_target,
+            state_db.as_ref(),
+            &auth_manager,
+            &current_enrollment,
+        )
+        .await
+        .expect_err("the refresh deadline must also defer the handshake");
+        assert_eq!(remote_control_retry_at(&connect_error), Some(retry_at));
+        let pairing_error = remote_handle
+            .start_pairing(
+                RemoteControlPairingStartParams::default(),
+                /*app_server_client_name*/ None,
+            )
+            .await
+            .expect_err("another pairing request must retain the same deadline");
+        assert_eq!(remote_control_retry_at(&pairing_error), Some(retry_at));
+        timeout(Duration::from_millis(100), listener.accept())
+            .await
+            .expect_err("no pairing, refresh or handshake should bypass the deadline");
+    }
+}
+
+#[tokio::test]
+async fn pairing_during_pending_handshake_respects_later_overload() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let remote_control_target =
+        normalize_remote_control_url(&remote_control_url).expect("target should parse");
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let state_db = remote_control_state_runtime(&codex_home).await;
+    let auth_manager = remote_control_auth_manager();
+    let mut remote_handle =
+        remote_control_handle_with_current_enrollment(&remote_control_url, auth_manager.clone());
+    remote_handle.state_db = Some(state_db.clone());
+    let current_enrollment = remote_handle.current_enrollment.clone();
+    let connect = connect_test_websocket(
+        &remote_control_target,
+        state_db.as_ref(),
+        &auth_manager,
+        &current_enrollment,
+    );
+    tokio::pin!(connect);
+    let (handshake_stream, request_line) = tokio::select! {
+        result = &mut connect => panic!("handshake should wait for its response: {result:?}"),
+        request = accept_http_request(&listener) => request,
+    };
+    assert_eq!(
+        request_line,
+        "GET /backend-api/wham/remote/control/server HTTP/1.1"
+    );
+
+    let pairing = remote_handle.start_pairing(
+        RemoteControlPairingStartParams::default(),
+        /*app_server_client_name*/ None,
+    );
+    tokio::pin!(pairing);
+    let (pairing_stream, request_line) = tokio::select! {
+        result = &mut pairing => panic!("pairing should wait for its response: {result:?}"),
+        request = accept_http_request(&listener) => request,
+    };
+    assert_eq!(
+        request_line,
+        "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+    );
+    respond_with_status_and_headers(
+        pairing_stream,
+        "200 OK",
+        &[],
+        r#"{"pairing_code":"pairing-code","manual_pairing_code":"ABCD-EFGH","server_id":"srv_e_test","environment_id":"env_test","expires_at":"3026-05-22T12:34:56Z"}"#,
+    )
+    .await;
+    timeout(Duration::from_secs(1), pairing)
+        .await
+        .expect("pairing must stay responsive while the handshake is pending")
+        .expect("pairing should succeed before any overload is observed");
+    respond_with_status_and_headers(
+        handshake_stream,
+        "503 Service Unavailable",
+        &[("Retry-After", "120")],
+        "overloaded",
+    )
+    .await;
+    let connect_error = connect
+        .await
+        .expect_err("the handshake should report overload");
+    let retry_at = remote_control_retry_at(&connect_error)
+        .expect("the handshake should preserve its retry deadline");
+    let pairing_error = timeout(
+        Duration::from_secs(1),
+        remote_handle.start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        ),
+    )
+    .await
+    .expect("new pairing should report the deadline promptly")
+    .expect_err("new pairing must honor the handshake deadline");
+    assert_eq!(remote_control_retry_at(&pairing_error), Some(retry_at));
+    timeout(Duration::from_millis(100), listener.accept())
+        .await
+        .expect_err("new pairing must not bypass the newly recorded deadline");
+}
+
+#[tokio::test]
+async fn pairing_auth_recovery_respects_concurrent_handshake_overload() {
+    for (pairing_status, auth_endpoint) in
+        [("401 Unauthorized", "refresh"), ("404 Not Found", "enroll")]
+    {
+        let listener = TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("listener should bind");
+        let remote_control_url = remote_control_url_for_listener(&listener);
+        let remote_control_target =
+            normalize_remote_control_url(&remote_control_url).expect("target should parse");
+        let codex_home = TempDir::new().expect("temp dir should create");
+        save_auth(
+            codex_home.path(),
+            &remote_control_auth_dot_json("stale-token"),
+            AuthCredentialsStoreMode::File,
+            AuthKeyringBackendKind::default(),
+        )
+        .expect("stale auth should save");
+        let auth_manager = AuthManager::shared(
+            codex_home.path().to_path_buf(),
+            /*enable_codex_api_key_env*/ false,
+            AuthCredentialsStoreMode::File,
+            /*forced_chatgpt_workspace_id*/ None,
+            /*chatgpt_base_url*/ None,
+            AuthKeyringBackendKind::default(),
+            codex_login::test_support::transport_default_auth_route_config(),
+        )
+        .await;
+        let state_db = remote_control_state_runtime(&codex_home).await;
+        let mut remote_handle = remote_control_handle_with_current_enrollment(
+            &remote_control_url,
+            auth_manager.clone(),
+        );
+        remote_handle.state_db = Some(state_db.clone());
+        let current_enrollment = remote_handle.current_enrollment.clone();
+        let connect = connect_test_websocket(
+            &remote_control_target,
+            state_db.as_ref(),
+            &auth_manager,
+            &current_enrollment,
+        );
+        tokio::pin!(connect);
+        let (handshake_stream, request_line) = tokio::select! {
+            result = &mut connect => panic!("handshake should wait for its response: {result:?}"),
+            request = accept_http_request(&listener) => request,
+        };
+        assert_eq!(
+            request_line,
+            "GET /backend-api/wham/remote/control/server HTTP/1.1"
+        );
+
+        let pairing = remote_handle.start_pairing(
+            RemoteControlPairingStartParams::default(),
+            /*app_server_client_name*/ None,
+        );
+        tokio::pin!(pairing);
+        let (pairing_stream, request_line) = tokio::select! {
+            result = &mut pairing => panic!("pairing should wait for its response: {result:?}"),
+            request = accept_http_request(&listener) => request,
+        };
+        assert_eq!(
+            request_line,
+            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+        );
+        respond_with_status_and_headers(pairing_stream, pairing_status, &[], "retry auth").await;
+        let (auth_stream, request_line) = tokio::select! {
+            result = &mut pairing => panic!("auth should wait for its response: {result:?}"),
+            request = accept_http_request(&listener) => request,
+        };
+        assert_eq!(
+            request_line,
+            format!("POST /backend-api/wham/remote/control/server/{auth_endpoint} HTTP/1.1")
+        );
+
+        respond_with_status_and_headers(
+            handshake_stream,
+            "503 Service Unavailable",
+            &[("Retry-After", "120")],
+            "overloaded",
+        )
+        .await;
+        let connect_error = connect
+            .await
+            .expect_err("the handshake should report overload");
+        let retry_at = remote_control_retry_at(&connect_error)
+            .expect("the handshake should preserve its retry deadline");
+        save_auth(
+            codex_home.path(),
+            &remote_control_auth_dot_json("fresh-token"),
+            AuthCredentialsStoreMode::File,
+            AuthKeyringBackendKind::default(),
+        )
+        .expect("replacement auth should save");
+        respond_with_status_and_headers(auth_stream, "401 Unauthorized", &[], "stale auth").await;
+        let pairing_error = timeout(TEST_HTTP_ACCEPT_TIMEOUT, pairing)
+            .await
+            .expect("auth recovery should report the deadline promptly")
+            .expect_err("auth recovery must honor the handshake deadline");
+        assert_eq!(remote_control_retry_at(&pairing_error), Some(retry_at));
+        timeout(Duration::from_millis(100), listener.accept())
+            .await
+            .expect_err("auth recovery must not send another request during overload");
+    }
+}
+
+#[tokio::test]
+async fn pairing_overload_defers_pairing_and_websocket_requests() {
+    for status in ["429 Too Many Requests", "503 Service Unavailable"] {
+        for check_status in [false, true] {
+            for incomplete_body in [false, true] {
+                let listener = TcpListener::bind("127.0.0.1:0")
+                    .await
+                    .expect("listener should bind");
+                let remote_control_url = remote_control_url_for_listener(&listener);
+                let remote_control_target =
+                    normalize_remote_control_url(&remote_control_url).expect("target should parse");
+                let server_task = tokio::spawn(async move {
+                    let (mut stream, request_line) = accept_http_request(&listener).await;
+                    assert_eq!(
+                        request_line,
+                        if check_status {
+                            "POST /backend-api/wham/remote/control/server/pair/status HTTP/1.1"
+                        } else {
+                            "POST /backend-api/wham/remote/control/server/pair HTTP/1.1"
+                        }
+                    );
+                    if incomplete_body {
+                        stream.write_all(format!(
+                            "HTTP/1.1 {status}\r\nContent-Length: 100\r\nRetry-After: 120\r\nConnection: close\r\n\r\npartial"
+                        ).as_bytes()).await.expect("partial response should send");
+                        stream.shutdown().await.expect("response should close");
+                    } else {
+                        respond_with_status_and_headers(
+                            stream,
+                            status,
+                            &[("Retry-After", "120")],
+                            "overloaded",
+                        )
+                        .await;
+                    }
+                    listener
+                });
+                let codex_home = TempDir::new().expect("temp dir should create");
+                let state_db = remote_control_state_runtime(&codex_home).await;
+                let auth_manager = remote_control_auth_manager();
+                let mut remote_handle = remote_control_handle_with_current_enrollment(
+                    &remote_control_url,
+                    auth_manager.clone(),
+                );
+                remote_handle.state_db = Some(state_db.clone());
+                let current_enrollment = remote_handle.current_enrollment.clone();
+                let status_params = || RemoteControlPairingStatusParams {
+                    pairing_code: Some("pairing-code".to_string()),
+                    manual_pairing_code: None,
+                };
+                let response = if check_status {
+                    remote_handle
+                        .pairing_status(status_params())
+                        .await
+                        .map(|_| ())
+                } else {
+                    remote_handle
+                        .start_pairing(
+                            RemoteControlPairingStartParams::default(),
+                            /*app_server_client_name*/ None,
+                        )
+                        .await
+                        .map(|_| ())
+                };
+                let error = response.expect_err("pairing should report overload");
+                let listener = server_task.await.expect("server task should succeed");
+                let retry_at = remote_control_retry_at(&error)
+                    .expect("even a partial response must preserve the retry deadline");
+                let pairing_error = remote_handle
+                    .start_pairing(
+                        RemoteControlPairingStartParams::default(),
+                        /*app_server_client_name*/ None,
+                    )
+                    .await
+                    .expect_err("pairing must wait for the server deadline");
+                let status_error = remote_handle
+                    .pairing_status(status_params())
+                    .await
+                    .expect_err("pairing status must wait for the server deadline");
+                let connect_error = connect_test_websocket(
+                    &remote_control_target,
+                    state_db.as_ref(),
+                    &auth_manager,
+                    &current_enrollment,
+                )
+                .await
+                .expect_err("the handshake must wait for the same deadline");
+                for error in [pairing_error, status_error, connect_error] {
+                    assert_eq!(remote_control_retry_at(&error), Some(retry_at));
+                }
+                assert_eq!(
+                    current_enrollment
+                        .snapshot()
+                        .and_then(|enrollment| enrollment.remote_control_token),
+                    Some(TEST_REMOTE_CONTROL_SERVER_TOKEN.to_string()),
+                );
+                timeout(Duration::from_millis(100), listener.accept())
+                    .await
+                    .expect_err("no remote-control request should bypass the pairing deadline");
+            }
+        }
+    }
+}
+
+async fn assert_refresh_failure_blocks_websocket(
+    expires_in: time::Duration,
+    response_delay: Duration,
+) {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let remote_control_target =
+        normalize_remote_control_url(&remote_control_url).expect("target should parse");
+    let (connects_done_tx, connects_done_rx) = oneshot::channel();
+    let server_task = tokio::spawn(async move {
+        let (stream, request_line) = accept_http_request(&listener).await;
+        assert_eq!(
+            request_line,
+            "POST /backend-api/wham/remote/control/server/refresh HTTP/1.1"
+        );
+        tokio::time::sleep(response_delay).await;
+        respond_with_status_and_headers(
+            stream,
+            "502 Bad Gateway",
+            &[("retry-after", "120")],
+            "upstream unavailable",
+        )
+        .await;
+        assert_no_connection_until_connect_finishes(&listener, connects_done_rx).await;
+    });
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let state_db = remote_control_state_runtime(&codex_home).await;
+    let auth_manager = remote_control_auth_manager();
+    let mut enrollment = remote_control_enrollment(Some(TEST_REMOTE_CONTROL_SERVER_TOKEN));
+    enrollment.expires_at = Some(time::OffsetDateTime::now_utc() + expires_in);
+    let current_enrollment = test_current_enrollment(Some(enrollment));
+
+    let refresh_started_at = time::OffsetDateTime::now_utc();
+    let refresh_err = connect_test_websocket(
+        &remote_control_target,
+        state_db.as_ref(),
+        &auth_manager,
+        &current_enrollment,
+    )
+    .await
+    .expect_err("required refresh failure should block websocket connect");
+    let refresh_completed_at = time::OffsetDateTime::now_utc();
+    let deferred_err = connect_test_websocket(
+        &remote_control_target,
+        state_db.as_ref(),
+        &auth_manager,
+        &current_enrollment,
+    )
+    .await
+    .expect_err("required refresh deadline should block websocket reconnect");
+    connects_done_tx
+        .send(())
+        .expect("server should wait for connect attempts to finish");
+
+    server_task.await.expect("server task should succeed");
+    assert!(refresh_err.to_string().contains("HTTP 502 Bad Gateway"));
+    assert_eq!(deferred_err.kind(), io::ErrorKind::WouldBlock);
+    let retry_at = remote_control_retry_at(&refresh_err)
+        .expect("the overload response should retain its retry deadline");
+    assert_eq!(remote_control_retry_at(&deferred_err), Some(retry_at));
+    let next_refresh_at = current_enrollment
+        .snapshot()
+        .and_then(|enrollment| enrollment.next_refresh_at)
+        .expect("required refresh failure should set a retry deadline");
+    assert!(
+        (refresh_started_at + time::Duration::seconds(120)
+            ..=refresh_completed_at + time::Duration::seconds(150))
+            .contains(&next_refresh_at)
+    );
+}
+
+#[tokio::test]
+async fn expired_token_refresh_failure_throttles_reconnect_without_websocket() {
+    assert_refresh_failure_blocks_websocket(-time::Duration::seconds(1), Duration::ZERO).await;
+}
+
+#[tokio::test]
+async fn token_expiring_during_refresh_failure_throttles_reconnect_without_websocket() {
+    assert_refresh_failure_blocks_websocket(
+        time::Duration::seconds(1),
+        Duration::from_millis(1_200),
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn websocket_auth_failure_does_not_clear_rotated_server_token() {
+    let attempted_enrollment = remote_control_enrollment(Some("old-token"));
+    let mut rotated_enrollment = attempted_enrollment.clone();
+    rotated_enrollment.remote_control_token = Some("new-token".to_string());
+    rotated_enrollment.expires_at =
+        Some(time::OffsetDateTime::now_utc() + time::Duration::hours(1));
+    let current_enrollment = test_current_enrollment(Some(rotated_enrollment.clone()));
+
+    clear_remote_control_server_token_if_matches(&current_enrollment, &attempted_enrollment)
+        .await
+        .expect("matching enrollment identity should remain available");
+
+    assert_eq!(current_enrollment.snapshot(), Some(rotated_enrollment));
+}
+
+async fn accept_test_websocket(listener: &TcpListener) -> WebSocketStream<TcpStream> {
+    let (stream, _) = timeout(TEST_HTTP_ACCEPT_TIMEOUT, listener.accept())
+        .await
+        .expect("websocket request should arrive in time")
+        .expect("listener accept should succeed");
+    accept_async(stream)
+        .await
+        .expect("websocket handshake should succeed")
+}
+
+async fn assert_no_connection_until_connect_finishes(
+    listener: &TcpListener,
+    mut connect_done_rx: oneshot::Receiver<()>,
+) {
+    tokio::select! {
+        accepted = listener.accept() => {
+            accepted.expect("unexpected websocket connection should be accepted");
+            panic!("required refresh failure must not proceed to websocket connect");
+        }
+        connect_done = &mut connect_done_rx => {
+            connect_done.expect("connect completion should be reported");
+        }
+    }
+}

codex-rs/app-server-transport/src/transport/stdio.rs

@@ -0,0 +1,194 @@
+//! Stdio transport with EOF cleanup and Unix SIGTERM shutdown. Dedicated I/O
+//! threads let SIGTERM abandon blocked pipes without holding the runtime open.
+//! A dedicated signal thread arms the shared EOF/SIGTERM deadline even when
+//! logging or the Tokio runtime is blocked.
+
+use super::CHANNEL_CAPACITY;
+use super::ConnectionOrigin;
+use super::TransportEvent;
+use super::forward_incoming_message;
+use super::next_connection_id;
+use super::serialize_outgoing_message;
+use crate::outgoing_message::QueuedOutgoingMessage;
+use codex_app_server_protocol::InitializeParams;
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::JSONRPCRequest;
+use std::io::BufRead;
+use std::io::ErrorKind;
+use std::io::Result as IoResult;
+use std::io::Write;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+use tokio::task::JoinHandle;
+use tokio_util::sync::CancellationToken;
+use tracing::debug;
+use tracing::error;
+use tracing::info;
+
+pub async fn start_stdio_connection(
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+    initialize_client_name_tx: oneshot::Sender<String>,
+    install_shutdown_signal_handler: bool,
+) -> IoResult<JoinHandle<()>> {
+    let shutdown_signal = CancellationToken::new();
+    #[cfg(unix)]
+    if install_shutdown_signal_handler {
+        use signal_hook::consts::SIGTERM;
+        use signal_hook::iterator::Signals;
+
+        // Register before accepting requests. Receiving SIGTERM and arming the
+        // watchdog must not depend on Tokio or synchronous transport logging.
+        let mut signals = Signals::new([SIGTERM])?;
+        let shutdown_signal = shutdown_signal.clone();
+        std::thread::Builder::new()
+            .name("app-server-signal".to_string())
+            .spawn(move || {
+                if signals.forever().next().is_some() {
+                    start_shutdown_watchdog();
+                    shutdown_signal.cancel();
+                }
+            })?;
+    }
+    let connection_id = next_connection_id();
+    let (writer_tx, mut writer_rx) = mpsc::channel::<QueuedOutgoingMessage>(CHANNEL_CAPACITY);
+    let writer_tx_for_reader = writer_tx.clone();
+    transport_event_tx
+        .send(TransportEvent::ConnectionOpened {
+            connection_id,
+            origin: ConnectionOrigin::Stdio,
+            auth: None,
+            writer: writer_tx,
+            disconnect_sender: None,
+        })
+        .await
+        .map_err(|_| std::io::Error::new(ErrorKind::BrokenPipe, "processor unavailable"))?;
+
+    // Tokio's stdin uses an uncancellable blocking task, which keeps its runtime
+    // alive while the client leaves stdin open. This process-owned thread may
+    // remain blocked until process exit, but is not joined by the runtime.
+    let (stdin_tx, mut stdin_rx) = mpsc::channel(/*buffer*/ 1);
+    std::thread::Builder::new()
+        .name("app-server-stdin".to_string())
+        .spawn(move || {
+            for line in std::io::stdin().lock().lines() {
+                if stdin_tx.blocking_send(line).is_err() {
+                    break;
+                }
+            }
+        })?;
+
+    // Keep stdout's blocking writes off Tokio's pool too. The forwarding future
+    // owns writer_rx so cancelling it also releases producers stuck on a full queue.
+    let (stdout_tx, mut stdout_rx) =
+        mpsc::channel::<(String, oneshot::Sender<()>)>(/*buffer*/ 1);
+    std::thread::Builder::new()
+        .name("app-server-stdout".to_string())
+        .spawn(move || {
+            let mut stdout = std::io::stdout().lock();
+            while let Some((json, written_tx)) = stdout_rx.blocking_recv() {
+                if let Err(err) = stdout.write_all(json.as_bytes()) {
+                    error!("Failed to write to stdout: {err}");
+                    break;
+                }
+                let _ = written_tx.send(());
+            }
+        })?;
+
+    let transport_event_tx_for_reader = transport_event_tx.clone();
+    let read_messages = async move {
+        let mut initialize_client_name_tx = Some(initialize_client_name_tx);
+        while let Some(line) = stdin_rx.recv().await {
+            let line = match line {
+                Ok(line) => line,
+                Err(err) => {
+                    error!("Failed reading stdin: {err}");
+                    break;
+                }
+            };
+            if let Some(client_name) = stdio_initialize_client_name(&line)
+                && let Some(initialize_client_name_tx) = initialize_client_name_tx.take()
+            {
+                let _ = initialize_client_name_tx.send(client_name);
+            }
+            if !forward_incoming_message(
+                &transport_event_tx_for_reader,
+                &writer_tx_for_reader,
+                connection_id,
+                &line,
+            )
+            .await
+            {
+                break;
+            }
+        }
+
+        // EOF can finish the transport before RPC or runtime cleanup. Start
+        // the same process deadline even if no SIGTERM arrives.
+        if cfg!(unix) && install_shutdown_signal_handler {
+            start_shutdown_watchdog();
+        }
+        let _ = transport_event_tx_for_reader
+            .send(TransportEvent::ConnectionClosed { connection_id })
+            .await;
+        debug!("stdin reader finished (EOF)");
+    };
+
+    let write_messages = async move {
+        while let Some(queued_message) = writer_rx.recv().await {
+            let Some(mut json) = serialize_outgoing_message(queued_message.message) else {
+                continue;
+            };
+            json.push('\n');
+            let (written_tx, written_rx) = oneshot::channel();
+            if stdout_tx.send((json, written_tx)).await.is_err() || written_rx.await.is_err() {
+                break;
+            }
+            if let Some(write_complete_tx) = queued_message.write_complete_tx {
+                let _ = write_complete_tx.send(());
+            }
+        }
+        info!("stdout writer exited (channel closed)");
+    };
+
+    Ok(tokio::spawn(async move {
+        tokio::select! {
+            _ = shutdown_signal.cancelled() => {
+                // Cancelling both forwarding futures drops their queues before
+                // connection teardown, including when EOF already began draining.
+                info!("SIGTERM received; closing stdio connection (45s shutdown deadline)");
+                let _ = transport_event_tx
+                    .send(TransportEvent::ConnectionClosed { connection_id })
+                    .await;
+            }
+            _ = async move { tokio::join!(read_messages, write_messages); } => {}
+        }
+    }))
+}
+
+fn start_shutdown_watchdog() {
+    // EOF and SIGTERM can both start cleanup; keep the first process deadline.
+    static STARTED: std::sync::Once = std::sync::Once::new();
+    STARTED.call_once(|| {
+        std::thread::Builder::new()
+            .name("app-server-shutdown".to_string())
+            .spawn(|| {
+                // Allow the processor's 30s RPC drain, then bound even Tokio's
+                // runtime teardown. Do not log here: stderr may also be blocked.
+                std::thread::sleep(std::time::Duration::from_secs(45));
+                std::process::exit(/*code*/ 1);
+            })
+            .unwrap_or_else(|_| std::process::exit(/*code*/ 1));
+    });
+}
+
+fn stdio_initialize_client_name(line: &str) -> Option<String> {
+    let message = serde_json::from_str::<JSONRPCMessage>(line).ok()?;
+    let JSONRPCMessage::Request(JSONRPCRequest { method, params, .. }) = message else {
+        return None;
+    };
+    if method != "initialize" {
+        return None;
+    }
+    let params = serde_json::from_value::<InitializeParams>(params?).ok()?;
+    Some(params.client_info.name)
+}

codex-rs/app-server-transport/src/transport/unix_socket.rs

@@ -0,0 +1,265 @@
+//! Control socket startup, guarded rendezvous paths, and WebSocket acceptance.
+
+use std::fs::OpenOptions;
+use std::io::ErrorKind;
+use std::io::Result as IoResult;
+use std::path::Path;
+
+use super::TransportEvent;
+use crate::transport::websocket::run_websocket_connection;
+use codex_uds::UnixListener;
+use codex_uds::UnixStream;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use futures::SinkExt;
+use futures::StreamExt;
+use tokio::sync::mpsc;
+use tokio::task::JoinHandle;
+use tokio::time::Duration;
+use tokio_tungstenite::accept_hdr_async;
+use tokio_tungstenite::tungstenite::Message;
+use tokio_tungstenite::tungstenite::http::Response;
+use tokio_tungstenite::tungstenite::http::StatusCode;
+use tokio_util::sync::CancellationToken;
+use tracing::error;
+use tracing::info;
+use tracing::warn;
+
+#[cfg(unix)]
+const CONTROL_SOCKET_MODE: u32 = 0o600;
+
+#[derive(Clone, Copy)]
+pub enum DaemonShutdownAccess {
+    Disabled,
+    Managed,
+}
+
+pub async fn start_control_socket_acceptor(
+    socket_path: AbsolutePathBuf,
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+    shutdown_token: CancellationToken,
+    daemon_shutdown_access: DaemonShutdownAccess,
+) -> IoResult<JoinHandle<()>> {
+    #[cfg(windows)]
+    let (socket_path, directory_guard) = {
+        if let Some(parent) = socket_path.as_path().parent() {
+            codex_uds::prepare_private_socket_directory(parent).await?;
+        }
+        let (path, guard) = codex_uds::validate_private_socket_path(socket_path.as_path())?;
+        (AbsolutePathBuf::from_absolute_path_checked(path)?, guard)
+    };
+    prepare_control_socket_path(socket_path.as_path()).await?;
+    let listener = UnixListener::bind(socket_path.as_path()).await?;
+    let socket_guard = ControlSocketFileGuard {
+        socket_path,
+        #[cfg(windows)]
+        _directory_guard: directory_guard,
+    };
+    set_control_socket_permissions(socket_guard.socket_path.as_path()).await?;
+    info!(
+        socket_path = %socket_guard.socket_path.display(),
+        "app-server control socket listening"
+    );
+
+    Ok(tokio::spawn(run_control_socket_acceptor(
+        listener,
+        transport_event_tx,
+        shutdown_token,
+        socket_guard,
+        daemon_shutdown_access,
+    )))
+}
+
+async fn run_control_socket_acceptor(
+    mut listener: UnixListener,
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+    shutdown_token: CancellationToken,
+    socket_guard: ControlSocketFileGuard,
+    daemon_shutdown_access: DaemonShutdownAccess,
+) {
+    let _socket_guard = socket_guard;
+    loop {
+        let stream = tokio::select! {
+            _ = shutdown_token.cancelled() => {
+                break;
+            }
+            result = listener.accept() => {
+                match result {
+                    Ok(stream) => stream,
+                    Err(err) => {
+                        if matches!(
+                            err.kind(),
+                            ErrorKind::ConnectionAborted | ErrorKind::ConnectionReset | ErrorKind::Interrupted
+                        ) {
+                            warn!("recoverable control socket accept error: {err}");
+                            continue;
+                        }
+                        error!("control socket accept error: {err}");
+                        tokio::time::sleep(Duration::from_secs(1)).await;
+                        continue;
+                    }
+                }
+            }
+        };
+
+        let transport_event_tx = transport_event_tx.clone();
+        tokio::spawn(async move {
+            let mut shutdown_request = false;
+            let websocket_stream = match accept_hdr_async(
+                stream,
+                |request: &tokio_tungstenite::tungstenite::handshake::server::Request, response| {
+                    if request.uri().path() == "/daemon/shutdown" {
+                        if !matches!(daemon_shutdown_access, DaemonShutdownAccess::Managed) {
+                            let mut rejection = Response::new(Some("unmanaged server".to_string()));
+                            *rejection.status_mut() = StatusCode::FORBIDDEN;
+                            return Err(rejection);
+                        }
+                        shutdown_request = true;
+                    }
+                    Ok(response)
+                },
+            )
+            .await
+            {
+                Ok(websocket_stream) => websocket_stream,
+                Err(err) => {
+                    warn!("failed to upgrade control socket websocket connection: {err}");
+                    return;
+                }
+            };
+            if shutdown_request {
+                run_daemon_shutdown(websocket_stream, transport_event_tx).await;
+                return;
+            }
+            let (websocket_writer, websocket_reader) = websocket_stream.split();
+            run_websocket_connection(websocket_writer, websocket_reader, transport_event_tx).await;
+        });
+    }
+    info!("control socket acceptor shutting down");
+}
+
+async fn run_daemon_shutdown(
+    mut websocket: tokio_tungstenite::WebSocketStream<UnixStream>,
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+) {
+    let pid = std::process::id().to_string();
+    if !matches!(websocket.next().await, Some(Ok(Message::Text(request))) if request == pid) {
+        return;
+    }
+    if websocket.send(Message::Text(pid.into())).await.is_err() {
+        return;
+    }
+    // Let the manager receive the acknowledgment before the main loop closes connections.
+    let _ = tokio::time::timeout(Duration::from_secs(2), websocket.next()).await;
+    let _ = transport_event_tx
+        .send(TransportEvent::DaemonShutdown)
+        .await;
+}
+
+pub async fn prepare_control_socket_path(socket_path: &Path) -> IoResult<()> {
+    if let Some(parent) = socket_path.parent() {
+        codex_uds::prepare_private_socket_directory(parent).await?;
+    }
+
+    #[cfg(windows)]
+    let (socket_path, _directory_guard) = codex_uds::validate_private_socket_path(socket_path)?;
+    #[cfg(windows)]
+    let socket_path = AbsolutePathBuf::from_absolute_path_checked(socket_path)?;
+    #[cfg(windows)]
+    let socket_path = socket_path.as_path();
+
+    match UnixStream::connect(socket_path).await {
+        Ok(_stream) => {
+            return Err(std::io::Error::new(
+                ErrorKind::AddrInUse,
+                format!(
+                    "app-server control socket is already in use at {}",
+                    socket_path.display()
+                ),
+            ));
+        }
+        Err(err) if err.kind() == ErrorKind::NotFound => return Ok(()),
+        Err(err) if err.kind() == ErrorKind::ConnectionRefused => {}
+        Err(err) => {
+            if !socket_path.exists() {
+                return Ok(());
+            }
+            return Err(err);
+        }
+    }
+
+    if !socket_path.try_exists()? {
+        return Ok(());
+    }
+
+    if !codex_uds::is_stale_socket_path(socket_path).await? {
+        return Err(std::io::Error::new(
+            ErrorKind::AlreadyExists,
+            format!(
+                "app-server control socket path exists and is not a socket: {}",
+                socket_path.display()
+            ),
+        ));
+    }
+    tokio::fs::remove_file(socket_path).await
+}
+
+pub struct AppServerStartupLock {
+    _file: std::fs::File,
+}
+
+pub async fn acquire_app_server_startup_lock(
+    startup_lock_path: AbsolutePathBuf,
+) -> IoResult<AppServerStartupLock> {
+    if let Some(parent) = startup_lock_path.as_path().parent() {
+        codex_uds::prepare_private_socket_directory(parent).await?;
+    }
+    tokio::task::spawn_blocking(move || {
+        let file = OpenOptions::new()
+            .create(true)
+            .truncate(false)
+            .read(true)
+            .write(true)
+            .open(startup_lock_path.as_path())?;
+        file.lock()?;
+        Ok(AppServerStartupLock { _file: file })
+    })
+    .await
+    .map_err(|err| std::io::Error::other(format!("startup lock task failed: {err}")))?
+}
+
+#[cfg(unix)]
+async fn set_control_socket_permissions(socket_path: &Path) -> IoResult<()> {
+    use std::os::unix::fs::PermissionsExt;
+
+    tokio::fs::set_permissions(
+        socket_path,
+        std::fs::Permissions::from_mode(CONTROL_SOCKET_MODE),
+    )
+    .await
+}
+
+#[cfg(not(unix))]
+async fn set_control_socket_permissions(_socket_path: &Path) -> IoResult<()> {
+    Ok(())
+}
+
+struct ControlSocketFileGuard {
+    socket_path: AbsolutePathBuf,
+    // Keep the directory pinned until after the socket file is removed in Drop.
+    #[cfg(windows)]
+    _directory_guard: std::os::windows::io::OwnedHandle,
+}
+
+impl Drop for ControlSocketFileGuard {
+    fn drop(&mut self) {
+        if let Err(err) = std::fs::remove_file(self.socket_path.as_path())
+            && err.kind() != ErrorKind::NotFound
+        {
+            warn!(
+                socket_path = %self.socket_path.display(),
+                %err,
+                "failed to remove app-server control socket file"
+            );
+        }
+    }
+}

codex-rs/app-server-transport/src/transport/unix_socket_tests.rs

@@ -0,0 +1,340 @@
+use super::AppServerTransport;
+use super::CHANNEL_CAPACITY;
+use super::DaemonShutdownAccess;
+use super::TransportEvent;
+use super::acquire_app_server_startup_lock;
+use super::app_server_control_socket_path;
+use super::start_control_socket_acceptor;
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::JSONRPCNotification;
+use codex_core::config::find_codex_home;
+use codex_uds::UnixStream;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use futures::SinkExt;
+use futures::StreamExt;
+use pretty_assertions::assert_eq;
+use std::io::Result as IoResult;
+use std::path::Path;
+use tokio::sync::mpsc;
+use tokio::time::Duration;
+use tokio::time::timeout;
+use tokio_tungstenite::client_async;
+use tokio_tungstenite::tungstenite::Bytes;
+use tokio_tungstenite::tungstenite::Message as WebSocketMessage;
+use tokio_util::sync::CancellationToken;
+
+#[test]
+fn listen_unix_socket_parses_as_unix_socket_transport() {
+    assert_eq!(
+        AppServerTransport::from_listen_url("unix://"),
+        Ok(AppServerTransport::UnixSocket {
+            socket_path: default_control_socket_path()
+        })
+    );
+}
+
+#[test]
+fn listen_unix_socket_accepts_absolute_custom_path() {
+    assert_eq!(
+        AppServerTransport::from_listen_url("unix:///tmp/codex.sock"),
+        Ok(AppServerTransport::UnixSocket {
+            socket_path: absolute_path("/tmp/codex.sock")
+        })
+    );
+}
+
+#[test]
+fn listen_unix_socket_accepts_relative_custom_path() {
+    assert_eq!(
+        AppServerTransport::from_listen_url("unix://codex.sock"),
+        Ok(AppServerTransport::UnixSocket {
+            socket_path: AbsolutePathBuf::relative_to_current_dir("codex.sock")
+                .expect("relative path should resolve")
+        })
+    );
+}
+
+#[tokio::test]
+async fn control_socket_acceptor_upgrades_and_forwards_websocket_text_messages_and_pings() {
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    let socket_path = test_socket_path(temp_dir.path());
+    let (transport_event_tx, mut transport_event_rx) =
+        mpsc::channel::<TransportEvent>(CHANNEL_CAPACITY);
+    let shutdown_token = CancellationToken::new();
+    let accept_handle = start_control_socket_acceptor(
+        socket_path.clone(),
+        transport_event_tx,
+        shutdown_token.clone(),
+        DaemonShutdownAccess::Disabled,
+    )
+    .await
+    .expect("control socket acceptor should start");
+
+    let stream = connect_to_socket(socket_path.as_path())
+        .await
+        .expect("client should connect");
+    let (mut websocket, response) = client_async("ws://localhost/rpc", stream)
+        .await
+        .expect("websocket upgrade should complete");
+    assert_eq!(response.status().as_u16(), 101);
+
+    let opened = timeout(Duration::from_secs(1), transport_event_rx.recv())
+        .await
+        .expect("connection opened event should arrive")
+        .expect("connection opened event");
+    let connection_id = match opened {
+        TransportEvent::ConnectionOpened { connection_id, .. } => connection_id,
+        _ => panic!("expected connection opened event"),
+    };
+
+    let notification = JSONRPCMessage::Notification(JSONRPCNotification {
+        method: "initialized".to_string(),
+        params: None,
+    });
+    websocket
+        .send(WebSocketMessage::Text(
+            serde_json::to_string(&notification)
+                .expect("notification should serialize")
+                .into(),
+        ))
+        .await
+        .expect("notification should send");
+
+    let incoming = timeout(Duration::from_secs(1), transport_event_rx.recv())
+        .await
+        .expect("incoming message event should arrive")
+        .expect("incoming message event");
+    assert_eq!(
+        match incoming {
+            TransportEvent::IncomingMessage {
+                connection_id: incoming_connection_id,
+                message,
+            } => (incoming_connection_id, message),
+            _ => panic!("expected incoming message event"),
+        },
+        (connection_id, notification)
+    );
+
+    websocket
+        .send(WebSocketMessage::Ping(Bytes::from_static(b"check")))
+        .await
+        .expect("ping should send");
+    let pong = timeout(Duration::from_secs(1), websocket.next())
+        .await
+        .expect("pong should arrive")
+        .expect("pong frame")
+        .expect("pong should be valid");
+    assert_eq!(pong, WebSocketMessage::Pong(Bytes::from_static(b"check")));
+
+    websocket.close(None).await.expect("close should send");
+    let closed = timeout(Duration::from_secs(1), transport_event_rx.recv())
+        .await
+        .expect("connection closed event should arrive")
+        .expect("connection closed event");
+    assert!(matches!(
+        closed,
+        TransportEvent::ConnectionClosed {
+            connection_id: closed_connection_id,
+        } if closed_connection_id == connection_id
+    ));
+
+    shutdown_token.cancel();
+    accept_handle.await.expect("acceptor should join");
+    assert_socket_path_removed(socket_path.as_path());
+}
+
+#[tokio::test]
+async fn shutdown_is_only_accepted_on_managed_local_socket_for_its_own_pid() {
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    let socket_path = test_socket_path(temp_dir.path());
+    let (tx, mut rx) = mpsc::channel(CHANNEL_CAPACITY);
+    let shutdown = CancellationToken::new();
+    let acceptor = start_control_socket_acceptor(
+        socket_path.clone(),
+        tx,
+        shutdown.clone(),
+        DaemonShutdownAccess::Disabled,
+    )
+    .await
+    .expect("acceptor");
+
+    let stream = connect_to_socket(socket_path.as_path())
+        .await
+        .expect("connect");
+    assert!(
+        client_async("ws://localhost/daemon/shutdown", stream)
+            .await
+            .is_err()
+    );
+    assert!(rx.try_recv().is_err());
+    shutdown.cancel();
+    acceptor.await.expect("acceptor shutdown");
+
+    let (tx, mut rx) = mpsc::channel(CHANNEL_CAPACITY);
+    let shutdown = CancellationToken::new();
+    let acceptor = start_control_socket_acceptor(
+        socket_path.clone(),
+        tx,
+        shutdown.clone(),
+        DaemonShutdownAccess::Managed,
+    )
+    .await
+    .expect("managed acceptor");
+    let stream = connect_to_socket(socket_path.as_path())
+        .await
+        .expect("connect");
+    let (mut websocket, _) = client_async("ws://localhost/daemon/shutdown", stream)
+        .await
+        .expect("upgrade");
+    websocket
+        .send(WebSocketMessage::Text("0".into()))
+        .await
+        .expect("wrong pid");
+    assert!(!matches!(
+        websocket.next().await,
+        Some(Ok(WebSocketMessage::Text(_)))
+    ));
+    assert!(rx.try_recv().is_err());
+
+    let stream = connect_to_socket(socket_path.as_path())
+        .await
+        .expect("connect");
+    let (mut websocket, _) = client_async("ws://localhost/daemon/shutdown", stream)
+        .await
+        .expect("upgrade");
+    let pid = std::process::id().to_string();
+    websocket
+        .send(WebSocketMessage::Text(pid.clone().into()))
+        .await
+        .expect("request");
+    assert_eq!(
+        websocket.next().await.expect("ack").expect("ack frame"),
+        WebSocketMessage::Text(pid.into())
+    );
+    assert!(
+        rx.try_recv().is_err(),
+        "server must wait until the ack is received"
+    );
+    websocket.close(None).await.expect("confirm receipt");
+    assert!(matches!(
+        timeout(Duration::from_secs(2), rx.recv()).await,
+        Ok(Some(TransportEvent::DaemonShutdown))
+    ));
+    shutdown.cancel();
+    acceptor.await.expect("acceptor shutdown");
+}
+
+#[tokio::test]
+async fn app_server_startup_lock_serializes_waiters() {
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    let lock_path = test_startup_lock_path(temp_dir.path());
+    let first_lock = acquire_app_server_startup_lock(lock_path.clone())
+        .await
+        .expect("first startup lock should succeed");
+    let mut second_lock = tokio::spawn(acquire_app_server_startup_lock(lock_path));
+
+    assert!(
+        timeout(Duration::from_millis(100), &mut second_lock)
+            .await
+            .is_err()
+    );
+
+    drop(first_lock);
+    second_lock
+        .await
+        .expect("second startup lock task should join")
+        .expect("second startup lock should succeed");
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn control_socket_file_is_private_after_bind() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    let socket_path = test_socket_path(temp_dir.path());
+    let (transport_event_tx, _transport_event_rx) =
+        mpsc::channel::<TransportEvent>(CHANNEL_CAPACITY);
+    let shutdown_token = CancellationToken::new();
+    let accept_handle = start_control_socket_acceptor(
+        socket_path.clone(),
+        transport_event_tx,
+        shutdown_token.clone(),
+        DaemonShutdownAccess::Disabled,
+    )
+    .await
+    .expect("control socket acceptor should start");
+
+    let metadata = tokio::fs::metadata(socket_path.as_path())
+        .await
+        .expect("socket metadata should exist");
+    assert_eq!(metadata.permissions().mode() & 0o777, 0o600);
+
+    shutdown_token.cancel();
+    accept_handle.await.expect("acceptor should join");
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn control_socket_pins_directory_until_shutdown() {
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    let socket_path = test_socket_path(temp_dir.path());
+    let directory = socket_path.as_path().parent().unwrap();
+    let moved = temp_dir.path().join("moved");
+    let (tx, _rx) = mpsc::channel::<TransportEvent>(CHANNEL_CAPACITY);
+    let shutdown = CancellationToken::new();
+    let acceptor = start_control_socket_acceptor(
+        socket_path.clone(),
+        tx,
+        shutdown.clone(),
+        DaemonShutdownAccess::Disabled,
+    )
+    .await
+    .expect("acceptor");
+    assert!(std::fs::rename(directory, &moved).is_err());
+    shutdown.cancel();
+    acceptor.await.expect("shutdown");
+    std::fs::rename(directory, moved).expect("directory unpinned after cleanup");
+}
+
+fn absolute_path(path: &str) -> AbsolutePathBuf {
+    AbsolutePathBuf::from_absolute_path(path).expect("absolute path")
+}
+
+fn default_control_socket_path() -> AbsolutePathBuf {
+    let codex_home = find_codex_home().expect("codex home");
+    app_server_control_socket_path(&codex_home).expect("default control socket path")
+}
+
+fn test_socket_path(temp_dir: &Path) -> AbsolutePathBuf {
+    AbsolutePathBuf::from_absolute_path(
+        temp_dir
+            .join("app-server-control")
+            .join("app-server-control.sock"),
+    )
+    .expect("socket path should resolve")
+}
+
+fn test_startup_lock_path(temp_dir: &Path) -> AbsolutePathBuf {
+    AbsolutePathBuf::from_absolute_path(
+        temp_dir
+            .join("app-server-control")
+            .join("app-server-startup.lock"),
+    )
+    .expect("startup lock path should resolve")
+}
+
+async fn connect_to_socket(socket_path: &Path) -> IoResult<UnixStream> {
+    UnixStream::connect(socket_path).await
+}
+
+#[cfg(unix)]
+fn assert_socket_path_removed(socket_path: &Path) {
+    assert!(!socket_path.exists());
+}
+
+#[cfg(windows)]
+fn assert_socket_path_removed(_socket_path: &Path) {
+    // uds_windows uses a regular filesystem path as its rendezvous point,
+    // but there is no Unix socket filesystem node to assert on.
+}

codex-rs/app-server-transport/src/transport/websocket.rs

@@ -0,0 +1,389 @@
+use super::CHANNEL_CAPACITY;
+use super::ConnectionOrigin;
+use super::TransportEvent;
+use super::auth::WebsocketAuthPolicy;
+use super::auth::authorize_upgrade;
+use super::auth::is_unauthenticated_non_loopback_listener;
+use super::forward_incoming_message;
+use super::next_connection_id;
+use super::serialize_outgoing_message;
+use crate::outgoing_message::ConnectionId;
+use crate::outgoing_message::QueuedOutgoingMessage;
+use axum::Router;
+use axum::body::Body;
+use axum::body::Bytes;
+use axum::extract::ConnectInfo;
+use axum::extract::State;
+use axum::extract::ws::Message as AxumWebSocketMessage;
+use axum::extract::ws::WebSocketUpgrade;
+use axum::http::HeaderMap;
+use axum::http::Request;
+use axum::http::StatusCode;
+use axum::http::header::ORIGIN;
+use axum::middleware;
+use axum::middleware::Next;
+use axum::response::IntoResponse;
+use axum::response::Response;
+use axum::routing::any;
+use axum::routing::get;
+use futures::SinkExt;
+use futures::StreamExt;
+use owo_colors::OwoColorize;
+use owo_colors::Stream;
+use owo_colors::Style;
+use std::io::Result as IoResult;
+use std::net::SocketAddr;
+use std::sync::Arc;
+use tokio::net::TcpListener;
+use tokio::sync::mpsc;
+use tokio::task::JoinHandle;
+use tokio_tungstenite::tungstenite::Message as TungsteniteWebSocketMessage;
+use tokio_util::sync::CancellationToken;
+use tracing::error;
+use tracing::info;
+use tracing::warn;
+
+/// WebSocket clients can briefly lag behind normal turn output bursts while the
+/// writer task is healthy, so give them more headroom than internal channels.
+const WEBSOCKET_OUTBOUND_CHANNEL_CAPACITY: usize = 32 * 1024;
+const _: () = assert!(WEBSOCKET_OUTBOUND_CHANNEL_CAPACITY > CHANNEL_CAPACITY);
+
+fn colorize(text: &str, style: Style) -> String {
+    text.if_supports_color(Stream::Stderr, |value| value.style(style))
+        .to_string()
+}
+
+#[allow(clippy::print_stderr)]
+fn print_websocket_startup_banner(addr: SocketAddr) {
+    let title = colorize("codex app-server (WebSockets)", Style::new().bold().cyan());
+    let listening_label = colorize("listening on:", Style::new().dimmed());
+    let listen_url = colorize(&format!("ws://{addr}"), Style::new().green());
+    let ready_label = colorize("readyz:", Style::new().dimmed());
+    let ready_url = colorize(&format!("http://{addr}/readyz"), Style::new().green());
+    let health_label = colorize("healthz:", Style::new().dimmed());
+    let health_url = colorize(&format!("http://{addr}/healthz"), Style::new().green());
+    let note_label = colorize("note:", Style::new().dimmed());
+    eprintln!("{title}");
+    eprintln!("  {listening_label} {listen_url}");
+    eprintln!("  {ready_label} {ready_url}");
+    eprintln!("  {health_label} {health_url}");
+    if addr.ip().is_loopback() {
+        eprintln!(
+            "  {note_label} binds localhost only (use SSH port-forwarding for remote access)"
+        );
+    } else {
+        eprintln!("  {note_label} websocket auth is required for non-localhost listeners");
+    }
+}
+
+#[derive(Clone)]
+struct WebSocketListenerState {
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+    auth_policy: Arc<WebsocketAuthPolicy>,
+}
+
+async fn health_check_handler() -> StatusCode {
+    StatusCode::OK
+}
+
+async fn reject_requests_with_origin_header(
+    request: Request<Body>,
+    next: Next,
+) -> Result<Response, StatusCode> {
+    if request.headers().contains_key(ORIGIN) {
+        warn!(
+            method = %request.method(),
+            uri = %request.uri(),
+            "rejecting websocket listener request with Origin header"
+        );
+        Err(StatusCode::FORBIDDEN)
+    } else {
+        Ok(next.run(request).await)
+    }
+}
+
+async fn websocket_upgrade_handler(
+    websocket: WebSocketUpgrade,
+    ConnectInfo(peer_addr): ConnectInfo<SocketAddr>,
+    State(state): State<WebSocketListenerState>,
+    headers: HeaderMap,
+) -> impl IntoResponse {
+    if let Err(err) = authorize_upgrade(&headers, state.auth_policy.as_ref()) {
+        warn!(
+            %peer_addr,
+            message = err.message(),
+            "rejecting websocket client during upgrade"
+        );
+        return (err.status_code(), err.message()).into_response();
+    }
+    info!(%peer_addr, "websocket client connected");
+    websocket
+        .on_upgrade(move |stream| async move {
+            let (websocket_writer, websocket_reader) = stream.split();
+            run_websocket_connection(websocket_writer, websocket_reader, state.transport_event_tx)
+                .await;
+        })
+        .into_response()
+}
+
+pub async fn start_websocket_acceptor(
+    bind_address: SocketAddr,
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+    shutdown_token: CancellationToken,
+    auth_policy: WebsocketAuthPolicy,
+) -> IoResult<JoinHandle<()>> {
+    if is_unauthenticated_non_loopback_listener(bind_address, &auth_policy) {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidInput,
+            format!(
+                "refusing to start non-loopback websocket listener {bind_address} without auth; configure `--ws-auth capability-token` or `--ws-auth signed-bearer-token`"
+            ),
+        ));
+    }
+    let listener = TcpListener::bind(bind_address).await?;
+    let local_addr = listener.local_addr()?;
+    print_websocket_startup_banner(local_addr);
+    info!("app-server websocket listening on ws://{local_addr}");
+
+    let router = Router::new()
+        .route("/readyz", get(health_check_handler))
+        .route("/healthz", get(health_check_handler))
+        .fallback(any(websocket_upgrade_handler))
+        .layer(middleware::from_fn(reject_requests_with_origin_header))
+        .with_state(WebSocketListenerState {
+            transport_event_tx,
+            auth_policy: Arc::new(auth_policy),
+        });
+    let server = axum::serve(
+        listener,
+        router.into_make_service_with_connect_info::<SocketAddr>(),
+    )
+    .with_graceful_shutdown(async move {
+        shutdown_token.cancelled().await;
+    });
+    Ok(tokio::spawn(async move {
+        if let Err(err) = server.await {
+            error!("websocket acceptor failed: {err}");
+        }
+        info!("websocket acceptor shutting down");
+    }))
+}
+
+pub(crate) async fn run_websocket_connection<M, SinkError, StreamError>(
+    websocket_writer: impl futures::sink::Sink<M, Error = SinkError> + Send + 'static,
+    websocket_reader: impl futures::stream::Stream<Item = Result<M, StreamError>> + Send + 'static,
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+) where
+    M: AppServerWebSocketMessage + Send + 'static,
+    SinkError: Send + 'static,
+    StreamError: std::fmt::Display + Send + 'static,
+{
+    let connection_id = next_connection_id();
+    let (writer_tx, writer_rx) =
+        mpsc::channel::<QueuedOutgoingMessage>(WEBSOCKET_OUTBOUND_CHANNEL_CAPACITY);
+    let writer_tx_for_reader = writer_tx.clone();
+    let disconnect_token = CancellationToken::new();
+    if transport_event_tx
+        .send(TransportEvent::ConnectionOpened {
+            connection_id,
+            origin: ConnectionOrigin::WebSocket,
+            auth: None,
+            writer: writer_tx,
+            disconnect_sender: Some(disconnect_token.clone()),
+        })
+        .await
+        .is_err()
+    {
+        return;
+    }
+
+    let (writer_control_tx, writer_control_rx) = mpsc::channel::<M>(CHANNEL_CAPACITY);
+    let mut outbound_task = tokio::spawn(run_websocket_outbound_loop(
+        websocket_writer,
+        writer_rx,
+        writer_control_rx,
+        disconnect_token.clone(),
+    ));
+    let mut inbound_task = tokio::spawn(run_websocket_inbound_loop(
+        websocket_reader,
+        transport_event_tx.clone(),
+        writer_tx_for_reader,
+        writer_control_tx,
+        connection_id,
+        disconnect_token.clone(),
+    ));
+
+    tokio::select! {
+        _ = &mut outbound_task => {
+            disconnect_token.cancel();
+            inbound_task.abort();
+        }
+        _ = &mut inbound_task => {
+            disconnect_token.cancel();
+            outbound_task.abort();
+        }
+    }
+
+    let _ = transport_event_tx
+        .send(TransportEvent::ConnectionClosed { connection_id })
+        .await;
+}
+
+pub(crate) enum IncomingWebSocketMessage {
+    Text(String),
+    Binary,
+    Ping(Bytes),
+    Pong,
+    Close,
+}
+
+/// Converts concrete WebSocket message types into the small message surface the
+/// app-server transport needs, and constructs the only outbound frames it
+/// sends directly.
+pub(crate) trait AppServerWebSocketMessage: Sized {
+    fn text(text: String) -> Self;
+    fn pong(payload: Bytes) -> Self;
+    fn into_incoming(self) -> Option<IncomingWebSocketMessage>;
+}
+
+impl AppServerWebSocketMessage for AxumWebSocketMessage {
+    fn text(text: String) -> Self {
+        Self::Text(text.into())
+    }
+
+    fn pong(payload: Bytes) -> Self {
+        Self::Pong(payload)
+    }
+
+    fn into_incoming(self) -> Option<IncomingWebSocketMessage> {
+        Some(match self {
+            Self::Text(text) => IncomingWebSocketMessage::Text(text.to_string()),
+            Self::Binary(_) => IncomingWebSocketMessage::Binary,
+            Self::Ping(payload) => IncomingWebSocketMessage::Ping(payload),
+            Self::Pong(_) => IncomingWebSocketMessage::Pong,
+            Self::Close(_) => IncomingWebSocketMessage::Close,
+        })
+    }
+}
+
+impl AppServerWebSocketMessage for TungsteniteWebSocketMessage {
+    fn text(text: String) -> Self {
+        Self::Text(text.into())
+    }
+
+    fn pong(payload: Bytes) -> Self {
+        Self::Pong(payload)
+    }
+
+    fn into_incoming(self) -> Option<IncomingWebSocketMessage> {
+        Some(match self {
+            Self::Text(text) => IncomingWebSocketMessage::Text(text.to_string()),
+            Self::Binary(_) => IncomingWebSocketMessage::Binary,
+            Self::Ping(payload) => IncomingWebSocketMessage::Ping(payload),
+            Self::Pong(_) => IncomingWebSocketMessage::Pong,
+            Self::Close(_) => IncomingWebSocketMessage::Close,
+            Self::Frame(_) => return None,
+        })
+    }
+}
+
+async fn run_websocket_outbound_loop<M, SinkError>(
+    websocket_writer: impl futures::sink::Sink<M, Error = SinkError> + Send + 'static,
+    mut writer_rx: mpsc::Receiver<QueuedOutgoingMessage>,
+    mut writer_control_rx: mpsc::Receiver<M>,
+    disconnect_token: CancellationToken,
+) where
+    M: AppServerWebSocketMessage + Send + 'static,
+    SinkError: Send + 'static,
+{
+    tokio::pin!(websocket_writer);
+    loop {
+        tokio::select! {
+            _ = disconnect_token.cancelled() => {
+                break;
+            }
+            message = writer_control_rx.recv() => {
+                let Some(message) = message else {
+                    break;
+                };
+                if websocket_writer.send(message).await.is_err() {
+                    break;
+                }
+            }
+            queued_message = writer_rx.recv() => {
+                let Some(queued_message) = queued_message else {
+                    break;
+                };
+                let Some(json) = serialize_outgoing_message(queued_message.message) else {
+                    continue;
+                };
+                if websocket_writer.send(M::text(json)).await.is_err() {
+                    break;
+                }
+                if let Some(write_complete_tx) = queued_message.write_complete_tx {
+                    let _ = write_complete_tx.send(());
+                }
+            }
+        }
+    }
+}
+
+async fn run_websocket_inbound_loop<M, StreamError>(
+    websocket_reader: impl futures::stream::Stream<Item = Result<M, StreamError>> + Send + 'static,
+    transport_event_tx: mpsc::Sender<TransportEvent>,
+    writer_tx_for_reader: mpsc::Sender<QueuedOutgoingMessage>,
+    writer_control_tx: mpsc::Sender<M>,
+    connection_id: ConnectionId,
+    disconnect_token: CancellationToken,
+) where
+    M: AppServerWebSocketMessage + Send + 'static,
+    StreamError: std::fmt::Display + Send + 'static,
+{
+    tokio::pin!(websocket_reader);
+    loop {
+        tokio::select! {
+            _ = disconnect_token.cancelled() => {
+                break;
+            }
+            incoming_message = websocket_reader.next() => {
+                match incoming_message {
+                    Some(Ok(message)) => match message.into_incoming() {
+                        Some(IncomingWebSocketMessage::Text(text))
+                            if !forward_incoming_message(
+                                &transport_event_tx,
+                                &writer_tx_for_reader,
+                                connection_id,
+                                &text,
+                            )
+                            .await
+                        => {
+                            break;
+                        }
+                        Some(IncomingWebSocketMessage::Text(_)) => {}
+                        Some(IncomingWebSocketMessage::Ping(payload)) => {
+                            match writer_control_tx.try_send(M::pong(payload)) {
+                                Ok(()) => {}
+                                Err(tokio::sync::mpsc::error::TrySendError::Closed(_)) => break,
+                                Err(tokio::sync::mpsc::error::TrySendError::Full(_)) => {
+                                    warn!("websocket control queue full while replying to ping; closing connection");
+                                    break;
+                                }
+                            }
+                        }
+                        Some(IncomingWebSocketMessage::Pong) => {}
+                        Some(IncomingWebSocketMessage::Close) => break,
+                        Some(IncomingWebSocketMessage::Binary) => {
+                            warn!("dropping unsupported binary websocket message");
+                        }
+                        None => {}
+                    },
+                    None => break,
+                    Some(Err(err)) => {
+                        warn!("websocket receive error: {err}");
+                        break;
+                    }
+                }
+            }
+        }
+    }
+}

codex-rs/bwrap/src/main.rs

@@ -0,0 +1,45 @@
+#[cfg(all(target_os = "linux", bwrap_available))]
+fn main() {
+    use std::ffi::CStr;
+    use std::ffi::CString;
+    use std::os::raw::c_char;
+    use std::os::unix::ffi::OsStrExt;
+
+    unsafe extern "C" {
+        fn bwrap_main(argc: libc::c_int, argv: *const *const c_char) -> libc::c_int;
+    }
+
+    let cstrings = std::env::args_os()
+        .map(|arg| {
+            CString::new(arg.as_os_str().as_bytes())
+                .unwrap_or_else(|err| panic!("failed to convert argv to CString: {err}"))
+        })
+        .collect::<Vec<_>>();
+    let mut argv_ptrs = cstrings
+        .iter()
+        .map(CString::as_c_str)
+        .map(CStr::as_ptr)
+        .collect::<Vec<*const c_char>>();
+    argv_ptrs.push(std::ptr::null());
+
+    // SAFETY: We provide a null-terminated argv vector whose pointers remain
+    // valid for the duration of the call.
+    let exit_code = unsafe { bwrap_main(cstrings.len() as libc::c_int, argv_ptrs.as_ptr()) };
+    std::process::exit(exit_code);
+}
+
+#[cfg(all(target_os = "linux", not(bwrap_available)))]
+fn main() {
+    panic!(
+        r#"bubblewrap is not available in this build.
+Notes:
+- ensure the target OS is Linux
+- libcap headers must be available via pkg-config
+- bubblewrap sources expected at codex-rs/vendor/bubblewrap (default)"#
+    );
+}
+
+#[cfg(not(target_os = "linux"))]
+fn main() {
+    panic!("bwrap is only supported on Linux");
+}

codex-rs/codex-mcp/src/agent_plugin_config.rs

@@ -0,0 +1,532 @@
+use super::PluginMcpConfigParseOutcome;
+use super::PluginMcpServerParseError;
+use codex_config::McpServerConfig;
+use serde::Deserialize;
+use serde_json::Map as JsonMap;
+use serde_json::Value as JsonValue;
+use std::collections::BTreeMap;
+use std::ffi::OsString;
+use std::path::Path;
+use std::path::PathBuf;
+use url::Host;
+
+// Published Agent Plugins v1 MCP schema:
+// https://github.com/agentplugins/agent-plugins-spec/blob/main/schemas/1.0.0/mcp.schema.json
+const AGENT_PLUGIN_MCP_SCHEMA_URI: &str = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+const SUPPORTED_AGENT_PLUGIN_MCP_SCHEMA_URIS: &[&str] = &[AGENT_PLUGIN_MCP_SCHEMA_URI];
+const PLUGIN_ROOT_VARIABLE: &str = "PLUGIN_ROOT";
+const PLUGIN_DATA_VARIABLE: &str = "PLUGIN_DATA";
+const CLIENT_OWNED_HTTP_HEADERS: &[&str] = &[
+    "accept",
+    "authorization",
+    "connection",
+    "content-encoding",
+    "content-length",
+    "content-type",
+    "host",
+    "last-event-id",
+    "mcp-protocol-version",
+    "mcp-session-id",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "user-agent",
+];
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct AgentPluginMcpFile {
+    #[serde(rename = "$schema")]
+    schema: String,
+    mcp_servers: BTreeMap<String, JsonValue>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(tag = "type", deny_unknown_fields)]
+enum AgentPluginMcpServer {
+    #[serde(rename = "stdio")]
+    Stdio {
+        command: String,
+        #[serde(default)]
+        args: Vec<String>,
+        #[serde(default)]
+        env: BTreeMap<String, String>,
+        cwd: Option<String>,
+    },
+    #[serde(rename = "streamable-http")]
+    StreamableHttp {
+        url: String,
+        headers: Option<BTreeMap<String, String>>,
+    },
+    #[serde(rename = "sse")]
+    Sse {
+        #[serde(rename = "url")]
+        _url: String,
+        #[serde(rename = "headers")]
+        _headers: Option<BTreeMap<String, String>>,
+    },
+}
+
+/// Translates an Agent Plugins `mcp.json` into Codex MCP configuration.
+pub fn parse_agent_plugin_mcp_config(
+    plugin_root: &Path,
+    plugin_data_root: &Path,
+    contents: &str,
+) -> Result<PluginMcpConfigParseOutcome, serde_json::Error> {
+    parse_agent_plugin_mcp_config_from(contents, plugin_root, plugin_data_root)
+}
+
+fn parse_agent_plugin_mcp_config_from(
+    contents: &str,
+    plugin_root: &Path,
+    plugin_data_root: &Path,
+) -> Result<PluginMcpConfigParseOutcome, serde_json::Error> {
+    let AgentPluginMcpFile {
+        schema,
+        mcp_servers,
+    } = serde_json::from_str(contents)?;
+    if !SUPPORTED_AGENT_PLUGIN_MCP_SCHEMA_URIS.contains(&schema.as_str()) {
+        return Err(plugin_mcp_json_error(format!(
+            "unsupported Agent Plugins MCP schema `{schema}`; supported schemas: {}",
+            SUPPORTED_AGENT_PLUGIN_MCP_SCHEMA_URIS.join(", ")
+        )));
+    }
+
+    let mut outcome = PluginMcpConfigParseOutcome::default();
+    for (name, value) in mcp_servers {
+        match normalize_agent_plugin_mcp_server(value, plugin_root, plugin_data_root) {
+            Ok(config) => {
+                outcome.servers.insert(name, config);
+            }
+            Err(message) => outcome
+                .errors
+                .push(PluginMcpServerParseError { name, message }),
+        }
+    }
+    Ok(outcome)
+}
+
+fn normalize_agent_plugin_mcp_server(
+    value: JsonValue,
+    plugin_root: &Path,
+    plugin_data_root: &Path,
+) -> Result<McpServerConfig, String> {
+    let object = value
+        .as_object()
+        .ok_or_else(|| "Agent Plugins MCP server must be an object".to_string())?;
+    match object.get("type").and_then(JsonValue::as_str) {
+        Some("stdio") => reject_explicit_null(object, "cwd")?,
+        Some("streamable-http" | "sse") => reject_explicit_null(object, "headers")?,
+        _ => {}
+    }
+    let server =
+        serde_json::from_value::<AgentPluginMcpServer>(value).map_err(|err| err.to_string())?;
+    let object = match server {
+        AgentPluginMcpServer::Stdio {
+            command,
+            args,
+            env,
+            cwd,
+        } => normalize_agent_plugin_stdio_server(
+            command,
+            args,
+            env,
+            cwd,
+            plugin_root,
+            plugin_data_root,
+        )?,
+        AgentPluginMcpServer::StreamableHttp { url, headers } => {
+            normalize_agent_plugin_http_server(url, headers)?
+        }
+        AgentPluginMcpServer::Sse { .. } => {
+            return Err("Agent Plugins legacy SSE transport is not supported by Codex".to_string());
+        }
+    };
+    serde_json::from_value(JsonValue::Object(object)).map_err(|err| err.to_string())
+}
+
+fn normalize_agent_plugin_stdio_server(
+    mut command: String,
+    mut args: Vec<String>,
+    mut env: BTreeMap<String, String>,
+    cwd: Option<String>,
+    plugin_root: &Path,
+    plugin_data_root: &Path,
+) -> Result<JsonMap<String, JsonValue>, String> {
+    #[cfg(windows)]
+    let has_windows_path_prefix = matches!(
+        Path::new(&command).components().next(),
+        Some(std::path::Component::Prefix(_))
+    );
+    #[cfg(not(windows))]
+    let has_windows_path_prefix = false;
+    let is_bare_command = !command.is_empty()
+        && !command.contains('/')
+        && !command.contains('\\')
+        && !has_windows_path_prefix;
+    let is_plugin_relative_command =
+        command.starts_with("./") && is_portable_relative_path(&command);
+    if !is_bare_command && !is_plugin_relative_command {
+        return Err(
+            "Agent Plugins stdio command must be a bare executable name or a contained `./` path"
+                .to_string(),
+        );
+    }
+    for reserved in [PLUGIN_ROOT_VARIABLE, PLUGIN_DATA_VARIABLE] {
+        if env
+            .keys()
+            .any(|name| environment_variable_names_match(name, reserved))
+        {
+            return Err(format!(
+                "Agent Plugins stdio `env` cannot override reserved variable `{reserved}`"
+            ));
+        }
+    }
+    #[cfg(windows)]
+    {
+        let mut normalized_env = BTreeMap::new();
+        for (name, value) in env {
+            let normalized_name = name.to_ascii_uppercase();
+            if normalized_env.insert(normalized_name, value).is_some() {
+                return Err(format!(
+                    "duplicate case-insensitive Agent Plugins environment variable `{name}`"
+                ));
+            }
+        }
+        env = normalized_env;
+    }
+
+    let root_path = absolute_plugin_path(plugin_root)?;
+    let data_root_path = absolute_plugin_path(plugin_data_root)?;
+    let root = host_path_string(&root_path);
+    let data_root = host_path_string(&data_root_path);
+    if command.starts_with("./") {
+        command = host_path_string(&resolve_contained_host_path(
+            &command, &root_path, &root_path,
+        )?);
+    }
+    for arg in &mut args {
+        *arg = expand_agent_plugin_placeholders(arg, &root, &data_root);
+    }
+    for value in env.values_mut() {
+        *value = expand_agent_plugin_placeholders(value, &root, &data_root);
+    }
+
+    let cwd = cwd.as_deref().unwrap_or("${PLUGIN_ROOT}");
+    let Some(cwd_root) = parse_agent_plugin_cwd(cwd) else {
+        return Err(
+            "Agent Plugins stdio `cwd` must be a contained `./`, `${PLUGIN_ROOT}`, or `${PLUGIN_DATA}` path"
+                .to_string(),
+        );
+    };
+    let cwd = expand_agent_plugin_placeholders(cwd, &root, &data_root);
+    let cwd_root = match cwd_root {
+        AgentPluginCwdRoot::Package => &root_path,
+        AgentPluginCwdRoot::Data => &data_root_path,
+    };
+    env.insert(PLUGIN_ROOT_VARIABLE.to_string(), root);
+    env.insert(PLUGIN_DATA_VARIABLE.to_string(), data_root);
+
+    Ok(JsonMap::from_iter([
+        ("command".to_string(), JsonValue::String(command)),
+        (
+            "args".to_string(),
+            JsonValue::Array(args.into_iter().map(JsonValue::String).collect()),
+        ),
+        ("env".to_string(), string_map_value(env)),
+        (
+            "cwd".to_string(),
+            JsonValue::String(host_path_string(&resolve_contained_host_path(
+                &cwd, cwd_root, cwd_root,
+            )?)),
+        ),
+    ]))
+}
+
+fn reject_explicit_null(object: &JsonMap<String, JsonValue>, field: &str) -> Result<(), String> {
+    if object.get(field).is_some_and(JsonValue::is_null) {
+        return Err(format!(
+            "Agent Plugins MCP `{field}` must use its declared type when present"
+        ));
+    }
+    Ok(())
+}
+
+fn environment_variable_names_match(left: &str, right: &str) -> bool {
+    if cfg!(windows) {
+        left.eq_ignore_ascii_case(right)
+    } else {
+        left == right
+    }
+}
+
+fn normalize_agent_plugin_http_server(
+    url: String,
+    mut headers: Option<BTreeMap<String, String>>,
+) -> Result<JsonMap<String, JsonValue>, String> {
+    validate_agent_plugin_url(&url)?;
+    if let Some(configured_headers) = headers.as_mut() {
+        validate_agent_plugin_headers(configured_headers)?;
+        configured_headers.retain(|name, _| {
+            !CLIENT_OWNED_HTTP_HEADERS
+                .iter()
+                .any(|owned| name.eq_ignore_ascii_case(owned))
+        });
+    }
+    let mut object = JsonMap::from_iter([("url".to_string(), JsonValue::String(url))]);
+    if let Some(headers) = headers.filter(|headers| !headers.is_empty()) {
+        object.insert("http_headers".to_string(), string_map_value(headers));
+    }
+    Ok(object)
+}
+
+fn validate_agent_plugin_url(raw_url: &str) -> Result<(), String> {
+    if raw_url.is_empty() {
+        return Err("Agent Plugins HTTP server requires a non-empty `url`".to_string());
+    }
+    let parsed = url::Url::parse(raw_url)
+        .map_err(|err| format!("invalid Agent Plugins MCP URL `{raw_url}`: {err}"))?;
+    if !matches!(parsed.scheme(), "http" | "https") || parsed.host_str().is_none() {
+        return Err("Agent Plugins MCP URL must be absolute HTTP or HTTPS".to_string());
+    }
+    if !parsed.username().is_empty() || parsed.password().is_some() || parsed.fragment().is_some() {
+        return Err(
+            "Agent Plugins MCP URL must not contain user information or a fragment".to_string(),
+        );
+    }
+    let is_loopback = match parsed.host() {
+        Some(Host::Domain(host)) => host == "localhost",
+        Some(Host::Ipv4(address)) => address.is_loopback(),
+        Some(Host::Ipv6(address)) => address.is_loopback(),
+        None => false,
+    };
+    if parsed.scheme() == "http" && !is_loopback {
+        return Err("non-loopback Agent Plugins MCP endpoints must use HTTPS".to_string());
+    }
+    Ok(())
+}
+
+fn validate_agent_plugin_headers(headers: &BTreeMap<String, String>) -> Result<(), String> {
+    let mut seen = std::collections::HashSet::new();
+    for (name, value) in headers {
+        if !seen.insert(name.to_ascii_lowercase()) {
+            return Err(format!(
+                "duplicate case-insensitive Agent Plugins HTTP header `{name}`"
+            ));
+        }
+        if !is_valid_http_header_name(name) {
+            return Err(format!("invalid Agent Plugins HTTP header name `{name}`"));
+        }
+        if value
+            .bytes()
+            .any(|byte| (byte < 32 && byte != b'\t') || byte == 127)
+        {
+            return Err(format!(
+                "invalid Agent Plugins HTTP header value for `{name}`"
+            ));
+        }
+    }
+    Ok(())
+}
+
+fn string_map_value(values: BTreeMap<String, String>) -> JsonValue {
+    JsonValue::Object(
+        values
+            .into_iter()
+            .map(|(name, value)| (name, JsonValue::String(value)))
+            .collect(),
+    )
+}
+
+#[derive(Clone, Copy, Debug)]
+enum AgentPluginCwdRoot {
+    Package,
+    Data,
+}
+
+fn parse_agent_plugin_cwd(value: &str) -> Option<AgentPluginCwdRoot> {
+    if value == "./" {
+        return Some(AgentPluginCwdRoot::Package);
+    }
+    if let Some(relative) = value.strip_prefix("./")
+        && is_portable_path_suffix(relative)
+    {
+        return Some(AgentPluginCwdRoot::Package);
+    }
+    for (placeholder, root) in [
+        ("${PLUGIN_ROOT}", AgentPluginCwdRoot::Package),
+        ("${PLUGIN_DATA}", AgentPluginCwdRoot::Data),
+    ] {
+        if value == placeholder {
+            return Some(root);
+        }
+        if let Some(relative) = value.strip_prefix(&format!("{placeholder}/"))
+            && (relative.is_empty() || is_portable_path_suffix(relative))
+        {
+            return Some(root);
+        }
+    }
+    None
+}
+
+fn expand_agent_plugin_placeholders(value: &str, plugin_root: &str, plugin_data: &str) -> String {
+    const ROOT: &str = "${PLUGIN_ROOT}";
+    const DATA: &str = "${PLUGIN_DATA}";
+    let mut output = String::with_capacity(value.len());
+    let mut remaining = value;
+    loop {
+        let next = match (remaining.find(ROOT), remaining.find(DATA)) {
+            (Some(root), Some(data)) if root <= data => Some((root, ROOT, plugin_root)),
+            (Some(_), Some(data)) => Some((data, DATA, plugin_data)),
+            (Some(root), None) => Some((root, ROOT, plugin_root)),
+            (None, Some(data)) => Some((data, DATA, plugin_data)),
+            (None, None) => None,
+        };
+        let Some((index, placeholder, replacement)) = next else {
+            output.push_str(remaining);
+            break;
+        };
+        output.push_str(&remaining[..index]);
+        output.push_str(replacement);
+        remaining = &remaining[index + placeholder.len()..];
+    }
+    output
+}
+
+fn absolute_plugin_path(path: &Path) -> Result<PathBuf, String> {
+    let absolute = if path.is_absolute() {
+        Ok(path.to_path_buf())
+    } else {
+        std::env::current_dir()
+            .map(|cwd| cwd.join(path))
+            .map_err(|err| format!("failed to resolve plugin path: {err}"))
+    }?;
+    resolve_existing_path_prefix(&absolute)
+}
+
+fn resolve_contained_host_path(
+    value: &str,
+    root: &Path,
+    allowed_root: &Path,
+) -> Result<PathBuf, String> {
+    let value = Path::new(value);
+    let path = if value.is_absolute() {
+        value.to_path_buf()
+    } else {
+        root.join(value)
+    };
+    let path = resolve_existing_path_prefix(&path)?;
+    if !path.starts_with(allowed_root) {
+        return Err(format!(
+            "expanded path `{}` must remain within `{}`",
+            value.display(),
+            allowed_root.display()
+        ));
+    }
+    Ok(path)
+}
+
+fn resolve_existing_path_prefix(path: &Path) -> Result<PathBuf, String> {
+    let mut existing = path.to_path_buf();
+    let mut missing_components = Vec::<OsString>::new();
+    loop {
+        match std::fs::canonicalize(&existing) {
+            Ok(mut resolved) => {
+                for component in missing_components.iter().rev() {
+                    resolved.push(component);
+                }
+                return Ok(lexical_normalize(&resolved));
+            }
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+                if std::fs::symlink_metadata(&existing)
+                    .is_ok_and(|metadata| metadata.file_type().is_symlink())
+                {
+                    return Err(format!(
+                        "failed to resolve symlinked path `{}`",
+                        path.display()
+                    ));
+                }
+                let Some(component) = existing.components().next_back() else {
+                    return Err(format!(
+                        "failed to resolve path `{}`: {err}",
+                        path.display()
+                    ));
+                };
+                if matches!(
+                    component,
+                    std::path::Component::Prefix(_) | std::path::Component::RootDir
+                ) {
+                    return Err(format!(
+                        "failed to resolve path `{}`: {err}",
+                        path.display()
+                    ));
+                }
+                missing_components.push(component.as_os_str().to_os_string());
+                if !existing.pop() {
+                    return Err(format!(
+                        "failed to resolve path `{}`: {err}",
+                        path.display()
+                    ));
+                }
+            }
+            Err(err) => {
+                return Err(format!(
+                    "failed to resolve path `{}`: {err}",
+                    path.display()
+                ));
+            }
+        }
+    }
+}
+
+fn host_path_string(path: &Path) -> String {
+    let rendered = path.to_string_lossy();
+    #[cfg(windows)]
+    if let Some(path) = rendered.strip_prefix(r"\\?\") {
+        return path
+            .strip_prefix(r"UNC\")
+            .map(|path| format!(r"\\{path}"))
+            .unwrap_or_else(|| path.to_string());
+    }
+    rendered.into_owned()
+}
+
+fn is_portable_relative_path(value: &str) -> bool {
+    value
+        .strip_prefix("./")
+        .is_some_and(is_portable_path_suffix)
+}
+
+fn is_portable_path_suffix(value: &str) -> bool {
+    !value.is_empty() && !value.contains('\\')
+}
+
+fn is_valid_http_header_name(name: &str) -> bool {
+    !name.is_empty()
+        && name
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || b"!#$%&'*+-.^_`|~".contains(&byte))
+}
+
+fn lexical_normalize(path: &Path) -> PathBuf {
+    let mut normalized = PathBuf::new();
+    for component in path.components() {
+        match component {
+            std::path::Component::CurDir => {}
+            std::path::Component::ParentDir => {
+                normalized.pop();
+            }
+            component => normalized.push(component.as_os_str()),
+        }
+    }
+    normalized
+}
+
+fn plugin_mcp_json_error(message: impl Into<String>) -> serde_json::Error {
+    serde_json::Error::io(std::io::Error::new(
+        std::io::ErrorKind::InvalidData,
+        message.into(),
+    ))
+}

codex-rs/codex-mcp/src/auth_changes.rs

@@ -0,0 +1,62 @@
+//! Forwards auth invalidations without credentials. The managed client owns the watcher.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use anyhow::Result;
+use codex_login::AuthChangeState;
+use codex_rmcp_client::RmcpClient;
+use rmcp::model::ServerCapabilities;
+use serde_json::json;
+use tokio::sync::watch;
+use tokio_util::task::AbortOnDropHandle;
+
+pub(crate) const CAPABILITY: &str = "codex/auth-change";
+const NOTIFICATION: &str = "notifications/codex/authChanged";
+const SEND_TIMEOUT: Duration = Duration::from_secs(5);
+
+pub(crate) async fn start(
+    client: Arc<RmcpClient>,
+    capabilities: &ServerCapabilities,
+    changes: Option<watch::Receiver<AuthChangeState>>,
+) -> Result<Option<Arc<AbortOnDropHandle<()>>>> {
+    let Some(mut changes) = changes.filter(|_| {
+        capabilities
+            .experimental
+            .as_ref()
+            .is_some_and(|capabilities| capabilities.contains_key(CAPABILITY))
+    }) else {
+        return Ok(None);
+    };
+
+    notify(&client, &mut changes).await?;
+    let task = tokio::spawn(async move {
+        while changes.changed().await.is_ok() {
+            if notify(&client, &mut changes).await.is_err() {
+                tracing::warn!("MCP auth invalidation delivery failed; closing connection");
+                client.shutdown().await;
+                break;
+            }
+        }
+    });
+    Ok(Some(Arc::new(AbortOnDropHandle::new(task))))
+}
+
+async fn notify(client: &RmcpClient, changes: &mut watch::Receiver<AuthChangeState>) -> Result<()> {
+    let state = *changes.borrow_and_update();
+    tokio::time::timeout(
+        SEND_TIMEOUT,
+        client.send_custom_notification(
+            NOTIFICATION,
+            Some(json!({
+                "generation": state.generation,
+                "ownerGeneration": state.owner_generation,
+            })),
+        ),
+    )
+    .await?
+}
+
+#[cfg(test)]
+#[path = "auth_changes_tests.rs"]
+mod tests;

codex-rs/codex-mcp/src/auth_changes_tests.rs

@@ -0,0 +1,104 @@
+use super::*;
+use codex_rmcp_client::InProcessTransportFactory;
+use futures::FutureExt;
+use futures::future::BoxFuture;
+use pretty_assertions::assert_eq;
+use rmcp::ServiceExt;
+use rmcp::model::ClientCapabilities;
+use rmcp::model::CustomNotification;
+use rmcp::model::Implementation;
+use rmcp::model::InitializeRequestParams;
+use tokio::sync::mpsc;
+use tokio::time::timeout;
+
+#[derive(Clone)]
+struct NotificationServer(mpsc::Sender<serde_json::Value>);
+
+impl rmcp::ServerHandler for NotificationServer {
+    async fn on_custom_notification(
+        &self,
+        notification: CustomNotification,
+        _context: rmcp::service::NotificationContext<rmcp::RoleServer>,
+    ) {
+        self.0.send(json!(notification)).await.unwrap();
+    }
+}
+
+impl InProcessTransportFactory for NotificationServer {
+    fn open(&self) -> BoxFuture<'static, std::io::Result<tokio::io::DuplexStream>> {
+        let server = self.clone();
+        async move {
+            let (client, transport) = tokio::io::duplex(/*max_buf_size*/ 4096);
+            tokio::spawn(async move {
+                let service = server.serve(transport).await.unwrap();
+                service.waiting().await.unwrap();
+            });
+            Ok(client)
+        }
+        .boxed()
+    }
+}
+
+#[tokio::test]
+async fn auth_notifications_require_opt_in_and_follow_client_lifetime() -> Result<()> {
+    let (notifications, mut received) = mpsc::channel(/*buffer*/ 8);
+    let client = Arc::new(
+        RmcpClient::new_in_process_client(Arc::new(NotificationServer(notifications))).await?,
+    );
+    client
+        .initialize(
+            InitializeRequestParams::new(
+                ClientCapabilities::default(),
+                Implementation::new("test", "1"),
+            ),
+            Some(SEND_TIMEOUT),
+            Box::new(|_, _| async { anyhow::bail!("unexpected elicitation") }.boxed()),
+        )
+        .await?;
+    let (changes, receiver) = watch::channel(AuthChangeState::default());
+    let mut capabilities = ServerCapabilities::default();
+    assert!(
+        start(Arc::clone(&client), &capabilities, Some(receiver.clone()))
+            .await?
+            .is_none()
+    );
+    capabilities.experimental = Some([(CAPABILITY.to_string(), Default::default())].into());
+    assert!(
+        start(Arc::clone(&client), &capabilities, /*changes*/ None)
+            .await?
+            .is_none()
+    );
+    assert_eq!(received.try_recv(), Err(mpsc::error::TryRecvError::Empty));
+    let watcher = start(Arc::clone(&client), &capabilities, Some(receiver))
+        .await?
+        .unwrap();
+    assert_eq!(
+        timeout(SEND_TIMEOUT, received.recv()).await?,
+        Some(
+            json!({"method": NOTIFICATION, "params": {"_meta": {}, "generation": 0, "ownerGeneration": 0}})
+        ),
+    );
+    changes.send_modify(|state| state.generation += 1);
+    assert_eq!(
+        timeout(SEND_TIMEOUT, received.recv()).await?,
+        Some(
+            json!({"method": NOTIFICATION, "params": {"_meta": {}, "generation": 1, "ownerGeneration": 0}})
+        ),
+    );
+    for _ in 0..2 {
+        changes.send_modify(|state| {
+            state.generation += 1;
+            state.owner_generation += 1;
+        });
+    }
+    assert_eq!(
+        timeout(SEND_TIMEOUT, received.recv()).await?,
+        Some(
+            json!({"method": NOTIFICATION, "params": {"_meta": {}, "generation": 3, "ownerGeneration": 2}})
+        ),
+    );
+    drop(watcher);
+    timeout(SEND_TIMEOUT, changes.closed()).await?;
+    client.shutdown().await;
+    Ok(())
+}

codex-rs/codex-mcp/src/auth_elicitation.rs

@@ -0,0 +1,435 @@
+//! Auth elicitation helpers.
+//!
+//! This module owns protocol-neutral auth elicitation parsing and payload shaping.
+//! Session orchestration stays in `codex-core`.
+
+use codex_protocol::mcp::CallToolResult;
+use serde::Serialize;
+
+pub const MCP_TOOL_CODEX_APPS_META_KEY: &str = "_codex_apps";
+pub const CONNECTOR_AUTH_FAILURE_META_KEY: &str = "connector_auth_failure";
+pub const CONNECTOR_AUTH_FAILURE_IS_AUTH_FAILURE_KEY: &str = "is_auth_failure";
+pub const CONNECTOR_AUTH_FAILURE_AUTH_REASON_KEY: &str = "auth_reason";
+pub const CONNECTOR_AUTH_FAILURE_CONNECTOR_ID_KEY: &str = "connector_id";
+pub const CONNECTOR_AUTH_FAILURE_LINK_ID_KEY: &str = "link_id";
+pub const CONNECTOR_AUTH_FAILURE_ERROR_CODE_KEY: &str = "error_code";
+pub const CONNECTOR_AUTH_FAILURE_ERROR_HTTP_STATUS_CODE_KEY: &str = "error_http_status_code";
+pub const CONNECTOR_AUTH_FAILURE_ERROR_ACTION_KEY: &str = "error_action";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CodexAppsConnectorAuthFailure {
+    pub connector_id: String,
+    pub connector_name: String,
+    pub install_url: String,
+    pub auth_reason: Option<String>,
+    pub link_id: Option<String>,
+    pub error_code: Option<String>,
+    pub error_http_status_code: Option<i64>,
+    pub error_action: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct CodexAppsAuthElicitation {
+    pub meta: serde_json::Value,
+    pub message: String,
+    pub url: String,
+    pub elicitation_id: String,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct CodexAppsAuthElicitationPlan {
+    pub auth_failure: CodexAppsConnectorAuthFailure,
+    pub elicitation: CodexAppsAuthElicitation,
+}
+
+#[derive(Serialize)]
+struct CodexAppsConnectorAuthFailureMeta<'a> {
+    is_auth_failure: bool,
+    connector_id: &'a str,
+    connector_name: &'a str,
+    install_url: &'a str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    auth_reason: Option<&'a str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    link_id: Option<&'a str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    error_code: Option<&'a str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    error_http_status_code: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    error_action: Option<&'a str>,
+}
+
+pub fn connector_auth_failure_from_tool_result(
+    result: &CallToolResult,
+    connector_id: Option<&str>,
+    connector_name: Option<&str>,
+    install_url: Option<String>,
+) -> Option<CodexAppsConnectorAuthFailure> {
+    let connector_id = connector_id
+        .map(str::trim)
+        .filter(|connector_id| !connector_id.is_empty())?;
+    let auth_failure = connector_auth_failure_metadata(result, connector_id)?;
+    let connector_name = connector_name
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .unwrap_or(connector_id)
+        .to_string();
+
+    Some(CodexAppsConnectorAuthFailure {
+        connector_id: connector_id.to_string(),
+        connector_name,
+        install_url: install_url?,
+        auth_reason: string_auth_failure_field(
+            auth_failure,
+            CONNECTOR_AUTH_FAILURE_AUTH_REASON_KEY,
+        ),
+        link_id: string_auth_failure_field(auth_failure, CONNECTOR_AUTH_FAILURE_LINK_ID_KEY),
+        error_code: string_auth_failure_field(auth_failure, CONNECTOR_AUTH_FAILURE_ERROR_CODE_KEY),
+        error_http_status_code: auth_failure
+            .get(CONNECTOR_AUTH_FAILURE_ERROR_HTTP_STATUS_CODE_KEY)
+            .and_then(serde_json::Value::as_i64),
+        error_action: string_auth_failure_field(
+            auth_failure,
+            CONNECTOR_AUTH_FAILURE_ERROR_ACTION_KEY,
+        ),
+    })
+}
+
+pub fn is_connector_auth_failure_from_tool_result(
+    result: &CallToolResult,
+    connector_id: Option<&str>,
+) -> bool {
+    connector_id
+        .map(str::trim)
+        .filter(|connector_id| !connector_id.is_empty())
+        .is_some_and(|connector_id| connector_auth_failure_metadata(result, connector_id).is_some())
+}
+
+fn connector_auth_failure_metadata<'a>(
+    result: &'a CallToolResult,
+    connector_id: &str,
+) -> Option<&'a serde_json::Map<String, serde_json::Value>> {
+    if result.is_error != Some(true) {
+        return None;
+    }
+
+    let auth_failure = result
+        .meta
+        .as_ref()?
+        .as_object()?
+        .get(MCP_TOOL_CODEX_APPS_META_KEY)?
+        .as_object()?
+        .get(CONNECTOR_AUTH_FAILURE_META_KEY)?
+        .as_object()?;
+    if auth_failure
+        .get(CONNECTOR_AUTH_FAILURE_IS_AUTH_FAILURE_KEY)
+        .and_then(serde_json::Value::as_bool)
+        != Some(true)
+    {
+        return None;
+    }
+    if let Some(auth_failure_connector_id) =
+        string_auth_failure_field(auth_failure, CONNECTOR_AUTH_FAILURE_CONNECTOR_ID_KEY)
+        && auth_failure_connector_id != connector_id
+    {
+        return None;
+    }
+
+    Some(auth_failure)
+}
+
+pub fn build_auth_elicitation_plan(
+    call_id: &str,
+    result: &CallToolResult,
+    connector_id: Option<&str>,
+    connector_name: Option<&str>,
+    install_url: Option<String>,
+) -> Option<CodexAppsAuthElicitationPlan> {
+    let auth_failure =
+        connector_auth_failure_from_tool_result(result, connector_id, connector_name, install_url)?;
+    let elicitation = build_auth_elicitation(call_id, &auth_failure);
+    Some(CodexAppsAuthElicitationPlan {
+        auth_failure,
+        elicitation,
+    })
+}
+
+pub fn build_auth_elicitation(
+    call_id: &str,
+    auth_failure: &CodexAppsConnectorAuthFailure,
+) -> CodexAppsAuthElicitation {
+    CodexAppsAuthElicitation {
+        meta: serde_json::json!({
+            MCP_TOOL_CODEX_APPS_META_KEY: {
+                CONNECTOR_AUTH_FAILURE_META_KEY: CodexAppsConnectorAuthFailureMeta {
+                    is_auth_failure: true,
+                    connector_id: &auth_failure.connector_id,
+                    connector_name: &auth_failure.connector_name,
+                    install_url: &auth_failure.install_url,
+                    auth_reason: auth_failure.auth_reason.as_deref(),
+                    link_id: auth_failure.link_id.as_deref(),
+                    error_code: auth_failure.error_code.as_deref(),
+                    error_http_status_code: auth_failure.error_http_status_code,
+                    error_action: auth_failure.error_action.as_deref(),
+                },
+            },
+        }),
+        message: auth_elicitation_message(auth_failure),
+        url: auth_failure.install_url.clone(),
+        elicitation_id: auth_elicitation_id(call_id),
+    }
+}
+
+pub fn auth_elicitation_completed_result(
+    auth_failure: &CodexAppsConnectorAuthFailure,
+    meta: Option<serde_json::Value>,
+) -> CallToolResult {
+    CallToolResult {
+        content: vec![serde_json::json!({
+            "type": "text",
+            "text": format!(
+                "Authentication for {} was requested and accepted. Retry this tool call now.",
+                auth_failure.connector_name
+            ),
+        })],
+        structured_content: None,
+        is_error: Some(true),
+        meta,
+    }
+}
+
+pub fn auth_elicitation_id(call_id: &str) -> String {
+    format!("codex_apps_auth_{call_id}")
+}
+
+fn string_auth_failure_field(
+    auth_failure: &serde_json::Map<String, serde_json::Value>,
+    key: &str,
+) -> Option<String> {
+    auth_failure
+        .get(key)
+        .and_then(serde_json::Value::as_str)
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToString::to_string)
+}
+
+fn auth_elicitation_message(auth_failure: &CodexAppsConnectorAuthFailure) -> String {
+    match auth_failure.auth_reason.as_deref() {
+        Some("oauth_upgrade_required") => format!(
+            "Reconnect {} on ChatGPT to grant the permissions needed for this request.",
+            auth_failure.connector_name
+        ),
+        Some("reauthentication_required") => format!(
+            "Reconnect {} on ChatGPT to restore access for this request.",
+            auth_failure.connector_name
+        ),
+        Some("missing_link") => format!(
+            "Sign in to {} on ChatGPT to use it in Codex.",
+            auth_failure.connector_name
+        ),
+        _ => format!(
+            "Sign in to {} on ChatGPT to continue.",
+            auth_failure.connector_name
+        ),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    fn auth_failure_result() -> CallToolResult {
+        CallToolResult {
+            content: vec![serde_json::json!({
+                "type": "text",
+                "text": "Connector reauthentication required",
+            })],
+            structured_content: None,
+            is_error: Some(true),
+            meta: Some(serde_json::json!({
+                MCP_TOOL_CODEX_APPS_META_KEY: {
+                    CONNECTOR_AUTH_FAILURE_META_KEY: {
+                        CONNECTOR_AUTH_FAILURE_IS_AUTH_FAILURE_KEY: true,
+                        CONNECTOR_AUTH_FAILURE_AUTH_REASON_KEY: "reauthentication_required",
+                        CONNECTOR_AUTH_FAILURE_CONNECTOR_ID_KEY: "connector_calendar",
+                        "connector_name": "Untrusted Calendar",
+                        CONNECTOR_AUTH_FAILURE_LINK_ID_KEY: "link_123",
+                        CONNECTOR_AUTH_FAILURE_ERROR_CODE_KEY: "UNAUTHORIZED",
+                        CONNECTOR_AUTH_FAILURE_ERROR_HTTP_STATUS_CODE_KEY: 401,
+                        CONNECTOR_AUTH_FAILURE_ERROR_ACTION_KEY: "TRIGGER_REAUTHENTICATION",
+                    },
+                },
+            })),
+        }
+    }
+
+    #[test]
+    fn parses_auth_failure_from_trusted_connector_metadata() {
+        assert_eq!(
+            connector_auth_failure_from_tool_result(
+                &auth_failure_result(),
+                Some("connector_calendar"),
+                Some("Google Calendar"),
+                Some("https://chatgpt.com/apps/google-calendar/connector_calendar".to_string()),
+            ),
+            Some(CodexAppsConnectorAuthFailure {
+                connector_id: "connector_calendar".to_string(),
+                connector_name: "Google Calendar".to_string(),
+                install_url: "https://chatgpt.com/apps/google-calendar/connector_calendar"
+                    .to_string(),
+                auth_reason: Some("reauthentication_required".to_string()),
+                link_id: Some("link_123".to_string()),
+                error_code: Some("UNAUTHORIZED".to_string()),
+                error_http_status_code: Some(401),
+                error_action: Some("TRIGGER_REAUTHENTICATION".to_string()),
+            })
+        );
+    }
+
+    #[test]
+    fn rejects_missing_or_mismatched_connector_ids() {
+        assert_eq!(
+            connector_auth_failure_from_tool_result(
+                &auth_failure_result(),
+                /*connector_id*/ None,
+                Some("Google Calendar"),
+                Some("https://chatgpt.com/apps/google-calendar/connector_calendar".to_string()),
+            ),
+            None
+        );
+        assert_eq!(
+            connector_auth_failure_from_tool_result(
+                &auth_failure_result(),
+                Some("connector_drive"),
+                Some("Google Drive"),
+                Some("https://chatgpt.com/apps/google-drive/connector_drive".to_string()),
+            ),
+            None
+        );
+    }
+
+    #[test]
+    fn detects_auth_failure_without_an_install_url() {
+        let result = auth_failure_result();
+
+        assert_eq!(
+            is_connector_auth_failure_from_tool_result(&result, Some("connector_calendar")),
+            true
+        );
+        assert_eq!(
+            connector_auth_failure_from_tool_result(
+                &result,
+                Some("connector_calendar"),
+                Some("Google Calendar"),
+                /*install_url*/ None,
+            ),
+            None
+        );
+    }
+
+    #[test]
+    fn auth_failure_detection_requires_trusted_connector_identity_and_auth_flag() {
+        let result = auth_failure_result();
+        assert_eq!(
+            is_connector_auth_failure_from_tool_result(&result, /*connector_id*/ None),
+            false
+        );
+        assert_eq!(
+            is_connector_auth_failure_from_tool_result(&result, Some("connector_drive")),
+            false
+        );
+
+        let mut ordinary_error = result.clone();
+        ordinary_error.meta.as_mut().expect("auth metadata")[MCP_TOOL_CODEX_APPS_META_KEY]
+            [CONNECTOR_AUTH_FAILURE_META_KEY][CONNECTOR_AUTH_FAILURE_IS_AUTH_FAILURE_KEY] =
+            serde_json::Value::Bool(false);
+        assert_eq!(
+            is_connector_auth_failure_from_tool_result(&ordinary_error, Some("connector_calendar"),),
+            false
+        );
+
+        let mut successful_result = result;
+        successful_result.is_error = Some(false);
+        assert_eq!(
+            is_connector_auth_failure_from_tool_result(
+                &successful_result,
+                Some("connector_calendar"),
+            ),
+            false
+        );
+    }
+
+    #[test]
+    fn detects_each_supported_connector_auth_reason() {
+        for auth_reason in [
+            "missing_link",
+            "oauth_upgrade_required",
+            "reauthentication_required",
+        ] {
+            let mut result = auth_failure_result();
+            result.meta.as_mut().expect("auth metadata")[MCP_TOOL_CODEX_APPS_META_KEY]
+                [CONNECTOR_AUTH_FAILURE_META_KEY][CONNECTOR_AUTH_FAILURE_AUTH_REASON_KEY] =
+                serde_json::Value::String(auth_reason.to_string());
+
+            assert_eq!(
+                is_connector_auth_failure_from_tool_result(&result, Some("connector_calendar")),
+                true
+            );
+        }
+    }
+
+    #[test]
+    fn builds_url_elicitation_payload() {
+        let auth_failure = connector_auth_failure_from_tool_result(
+            &auth_failure_result(),
+            Some("connector_calendar"),
+            Some("Google Calendar"),
+            Some("https://chatgpt.com/apps/google-calendar/connector_calendar".to_string()),
+        )
+        .expect("auth failure");
+
+        assert_eq!(
+            build_auth_elicitation("call_123", &auth_failure),
+            CodexAppsAuthElicitation {
+                meta: serde_json::json!({
+                    MCP_TOOL_CODEX_APPS_META_KEY: {
+                        CONNECTOR_AUTH_FAILURE_META_KEY: {
+                            CONNECTOR_AUTH_FAILURE_IS_AUTH_FAILURE_KEY: true,
+                            CONNECTOR_AUTH_FAILURE_CONNECTOR_ID_KEY: "connector_calendar",
+                            "connector_name": "Google Calendar",
+                            "install_url":
+                                "https://chatgpt.com/apps/google-calendar/connector_calendar",
+                            CONNECTOR_AUTH_FAILURE_AUTH_REASON_KEY: "reauthentication_required",
+                            CONNECTOR_AUTH_FAILURE_LINK_ID_KEY: "link_123",
+                            CONNECTOR_AUTH_FAILURE_ERROR_CODE_KEY: "UNAUTHORIZED",
+                            CONNECTOR_AUTH_FAILURE_ERROR_HTTP_STATUS_CODE_KEY: 401,
+                            CONNECTOR_AUTH_FAILURE_ERROR_ACTION_KEY: "TRIGGER_REAUTHENTICATION",
+                        },
+                    },
+                }),
+                message: "Reconnect Google Calendar on ChatGPT to restore access for this request."
+                    .to_string(),
+                url: "https://chatgpt.com/apps/google-calendar/connector_calendar".to_string(),
+                elicitation_id: "codex_apps_auth_call_123".to_string(),
+            }
+        );
+    }
+
+    #[test]
+    fn builds_auth_elicitation_plan() {
+        let plan = build_auth_elicitation_plan(
+            "call_123",
+            &auth_failure_result(),
+            Some("connector_calendar"),
+            Some("Google Calendar"),
+            Some("https://chatgpt.com/apps/google-calendar/connector_calendar".to_string()),
+        )
+        .expect("auth elicitation plan");
+
+        assert_eq!(plan.auth_failure.connector_name, "Google Calendar");
+        assert_eq!(plan.elicitation.elicitation_id, "codex_apps_auth_call_123");
+    }
+}