Add files using upload-large-folder tool

.github/CODEOWNERS

@@ -0,0 +1,17 @@
+# Core crate ownership.
+/codex-rs/arg0/ @openai/codex-core-agent-team
+/codex-rs/codex-mcp/ @openai/codex-core-agent-team
+/codex-rs/core/ @openai/codex-core-agent-team
+/codex-rs/exec-server/ @openai/codex-core-agent-team
+/codex-rs/exec-server-protocol/ @openai/codex-core-agent-team
+/codex-rs/ext/extension-api/ @openai/codex-core-agent-team
+/codex-rs/prompts/ @openai/codex-core-agent-team
+/codex-rs/utils/path-uri/ @openai/codex-core-agent-team
+
+# Keep macOS AKV signing changes reviewed by Codex maintainers.
+/.github/actions/setup-akv-pkcs11-codesigning/ @openai/codex-core-agent-team
+/.github/scripts/macos-signing/ @openai/codex-core-agent-team
+/.github/workflows/rust-release.yml @openai/codex-core-agent-team
+
+# Keep ownership changes reviewed by the same team.
+/.github/CODEOWNERS @openai/codex-core-agent-team

.github/blob-size-allowlist.txt

@@ -0,0 +1,11 @@
+# Paths are matched exactly, relative to the repository root.
+# Keep this list short and limited to intentional large checked-in assets.
+
+.github/codex-cli-splash.png
+MODULE.bazel.lock
+codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json
+codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json
+codex-rs/models-manager/models.json
+codex-rs/tui/tests/fixtures/oss-story.jsonl
+codex-rs/tui_app_server/tests/fixtures/oss-story.jsonl
+codex-rs/tui/src/app.rs

.github/codex/home/config.toml

@@ -0,0 +1,3 @@
+model = "gpt-5.1"
+
+# Consider setting [mcp_servers] here!

.github/codex/labels/codex-attempt.md

@@ -0,0 +1,9 @@
+Attempt to solve the reported issue.
+
+If a code change is required, create a new branch, commit the fix, and open a pull request that resolves the problem.
+
+Here is the original GitHub issue that triggered this run:
+
+### {CODEX_ACTION_ISSUE_TITLE}
+
+{CODEX_ACTION_ISSUE_BODY}

.github/codex/labels/codex-review.md

@@ -0,0 +1,7 @@
+Review this PR and respond with a very concise final message, formatted in Markdown.
+
+There should be a summary of the changes (1-2 sentences) and a few bullet points if necessary.
+
+Then provide the **review** (1-2 sentences plus bullet points, friendly tone).
+
+{CODEX_ACTION_GITHUB_EVENT_PATH} contains the JSON that triggered this GitHub workflow. It contains the `base` and `head` refs that define this PR. Both refs are available locally.

.github/codex/labels/codex-rust-review.md

@@ -0,0 +1,139 @@
+Review this PR and respond with a very concise final message, formatted in Markdown.
+
+There should be a summary of the changes (1-2 sentences) and a few bullet points if necessary.
+
+Then provide the **review** (1-2 sentences plus bullet points, friendly tone).
+
+Things to look out for when doing the review:
+
+## General Principles
+
+- **Make sure the pull request body explains the motivation behind the change.** If the author has failed to do this, call it out, and if you think you can deduce the motivation behind the change, propose copy.
+- Ideally, the PR body also contains a small summary of the change. For small changes, the PR title may be sufficient.
+- Each PR should ideally do one conceptual thing. For example, if a PR does a refactoring as well as introducing a new feature, push back and suggest the refactoring be done in a separate PR. This makes things easier for the reviewer, as refactoring changes can often be far-reaching, yet quick to review.
+- When introducing new code, be on the lookout for code that duplicates existing code. When found, propose a way to refactor the existing code such that it should be reused.
+
+## Code Organization
+
+- Each crate in the Cargo workspace in `codex-rs` has a specific purpose: make a note if you believe new code is not introduced in the correct crate.
+- When possible, try to keep the `core` crate as small as possible. Non-core but shared logic is often a good candidate for `codex-rs/common`.
+- Be wary of large files and offer suggestions for how to break things into more reasonably-sized files.
+- Rust files should generally be organized such that the public parts of the API appear near the top of the file and helper functions go below. This is analogous to the "inverted pyramid" structure that is favored in journalism.
+
+## Assertions in Tests
+
+Assert the equality of the entire objects instead of doing "piecemeal comparisons," performing `assert_eq!()` on individual fields.
+
+Note that unit tests also function as "executable documentation." As shown in the following example, "piecemeal comparisons" are often more verbose, provide less coverage, and are not as useful as executable documentation.
+
+For example, suppose you have the following enum:
+
+```rust
+#[derive(Debug, PartialEq)]
+enum Message {
+    Request {
+        id: String,
+        method: String,
+        params: Option<serde_json::Value>,
+    },
+    Notification {
+        method: String,
+        params: Option<serde_json::Value>,
+    },
+}
+```
+
+This is an example of a _piecemeal_ comparison:
+
+```rust
+// BAD: Piecemeal Comparison
+
+#[test]
+fn test_get_latest_messages() {
+    let messages = get_latest_messages();
+    assert_eq!(messages.len(), 2);
+
+    let m0 = &messages[0];
+    match m0 {
+        Message::Request { id, method, params } => {
+            assert_eq!(id, "123");
+            assert_eq!(method, "subscribe");
+            assert_eq!(
+                *params,
+                Some(json!({
+                    "conversation_id": "x42z86"
+                }))
+            )
+        }
+        Message::Notification { .. } => {
+            panic!("expected Request");
+        }
+    }
+
+    let m1 = &messages[1];
+    match m1 {
+        Message::Request { .. } => {
+            panic!("expected Notification");
+        }
+        Message::Notification { method, params } => {
+            assert_eq!(method, "log");
+            assert_eq!(
+                *params,
+                Some(json!({
+                    "level": "info",
+                    "message": "subscribed"
+                }))
+            )
+        }
+    }
+}
+```
+
+This is a _deep_ comparison:
+
+```rust
+// GOOD: Verify the entire structure with a single assert_eq!().
+
+use pretty_assertions::assert_eq;
+
+#[test]
+fn test_get_latest_messages() {
+    let messages = get_latest_messages();
+
+    assert_eq!(
+        vec![
+            Message::Request {
+                id: "123".to_string(),
+                method: "subscribe".to_string(),
+                params: Some(json!({
+                    "conversation_id": "x42z86"
+                })),
+            },
+            Message::Notification {
+                method: "log".to_string(),
+                params: Some(json!({
+                    "level": "info",
+                    "message": "subscribed"
+                })),
+            },
+        ],
+        messages,
+    );
+}
+```
+
+## More Tactical Rust Things To Look Out For
+
+- Do not use `unsafe` (unless you have a really, really good reason like using an operating system API directly and no safe wrapper exists). For example, there are cases where it is tempting to use `unsafe` in order to use `std::env::set_var()`, but this indeed `unsafe` and has led to race conditions on multiple occasions. (When this happens, find a mechanism other than environment variables to use for configuration.)
+- Encourage the use of small enums or the newtype pattern in Rust if it helps readability without adding significant cognitive load or lines of code.
+- If you see opportunities for the changes in a diff to use more idiomatic Rust, please make specific recommendations. For example, favor the use of expressions over `return`.
+- When modifying a `Cargo.toml` file, make sure that dependency lists stay alphabetically sorted. Also consider whether a new dependency is added to the appropriate place (e.g., `[dependencies]` versus `[dev-dependencies]`)
+
+## Pull Request Body
+
+- If the nature of the change seems to have a visual component (which is often the case for changes to `codex-rs/tui`), recommend including a screenshot or video to demonstrate the change, if appropriate.
+- References to existing GitHub issues and PRs are encouraged, where appropriate, though you likely do not have network access, so may not be able to help here.
+
+# PR Information
+
+{CODEX_ACTION_GITHUB_EVENT_PATH} contains the JSON that triggered this GitHub workflow. It contains the `base` and `head` refs that define this PR. Both refs are available locally.

.github/dependabot.yaml

@@ -0,0 +1,36 @@
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#package-ecosystem-
+
+version: 2
+updates:
+  - package-ecosystem: bun
+    directory: .github/actions/codex
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+  - package-ecosystem: cargo
+    directories:
+      - codex-rs
+      - codex-rs/*
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+  - package-ecosystem: docker
+    directory: codex-cli
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+  - package-ecosystem: rust-toolchain
+    directory: codex-rs
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7

.github/dotslash-argument-comment-lint-config.json

@@ -0,0 +1,24 @@
+{
+  "outputs": {
+    "argument-comment-lint": {
+      "platforms": {
+        "macos-aarch64": {
+          "regex": "^argument-comment-lint-aarch64-apple-darwin\\.tar\\.gz$",
+          "path": "argument-comment-lint/bin/argument-comment-lint"
+        },
+        "linux-x86_64": {
+          "regex": "^argument-comment-lint-x86_64-unknown-linux-gnu\\.tar\\.gz$",
+          "path": "argument-comment-lint/bin/argument-comment-lint"
+        },
+        "linux-aarch64": {
+          "regex": "^argument-comment-lint-aarch64-unknown-linux-gnu\\.tar\\.gz$",
+          "path": "argument-comment-lint/bin/argument-comment-lint"
+        },
+        "windows-x86_64": {
+          "regex": "^argument-comment-lint-x86_64-pc-windows-msvc\\.zip$",
+          "path": "argument-comment-lint/bin/argument-comment-lint.exe"
+        }
+      }
+    }
+  }
+}

.github/dotslash-config.json

@@ -0,0 +1,136 @@
+{
+  "outputs": {
+    "codex": {
+      "platforms": {
+        "macos-aarch64": {
+          "regex": "^codex-package-aarch64-apple-darwin\\.tar\\.zst$",
+          "path": "bin/codex"
+        },
+        "macos-x86_64": {
+          "regex": "^codex-package-x86_64-apple-darwin\\.tar\\.zst$",
+          "path": "bin/codex"
+        },
+        "linux-x86_64": {
+          "regex": "^codex-package-x86_64-unknown-linux-musl\\.tar\\.zst$",
+          "path": "bin/codex"
+        },
+        "linux-aarch64": {
+          "regex": "^codex-package-aarch64-unknown-linux-musl\\.tar\\.zst$",
+          "path": "bin/codex"
+        },
+        "windows-x86_64": {
+          "regex": "^codex-package-x86_64-pc-windows-msvc\\.tar\\.zst$",
+          "path": "bin/codex.exe"
+        },
+        "windows-aarch64": {
+          "regex": "^codex-package-aarch64-pc-windows-msvc\\.tar\\.zst$",
+          "path": "bin/codex.exe"
+        }
+      }
+    },
+    "codex-app-server": {
+      "platforms": {
+        "macos-aarch64": {
+          "regex": "^codex-app-server-package-aarch64-apple-darwin\\.tar\\.zst$",
+          "path": "bin/codex-app-server"
+        },
+        "macos-x86_64": {
+          "regex": "^codex-app-server-package-x86_64-apple-darwin\\.tar\\.zst$",
+          "path": "bin/codex-app-server"
+        },
+        "linux-x86_64": {
+          "regex": "^codex-app-server-package-x86_64-unknown-linux-musl\\.tar\\.zst$",
+          "path": "bin/codex-app-server"
+        },
+        "linux-aarch64": {
+          "regex": "^codex-app-server-package-aarch64-unknown-linux-musl\\.tar\\.zst$",
+          "path": "bin/codex-app-server"
+        },
+        "windows-x86_64": {
+          "regex": "^codex-app-server-package-x86_64-pc-windows-msvc\\.tar\\.zst$",
+          "path": "bin/codex-app-server.exe"
+        },
+        "windows-aarch64": {
+          "regex": "^codex-app-server-package-aarch64-pc-windows-msvc\\.tar\\.zst$",
+          "path": "bin/codex-app-server.exe"
+        }
+      }
+    },
+    "codex-responses-api-proxy": {
+      "platforms": {
+        "macos-aarch64": {
+          "regex": "^codex-responses-api-proxy-aarch64-apple-darwin\\.zst$",
+          "path": "codex-responses-api-proxy"
+        },
+        "macos-x86_64": {
+          "regex": "^codex-responses-api-proxy-x86_64-apple-darwin\\.zst$",
+          "path": "codex-responses-api-proxy"
+        },
+        "linux-x86_64": {
+          "regex": "^codex-responses-api-proxy-x86_64-unknown-linux-musl\\.zst$",
+          "path": "codex-responses-api-proxy"
+        },
+        "linux-aarch64": {
+          "regex": "^codex-responses-api-proxy-aarch64-unknown-linux-musl\\.zst$",
+          "path": "codex-responses-api-proxy"
+        },
+        "windows-x86_64": {
+          "regex": "^codex-responses-api-proxy-x86_64-pc-windows-msvc\\.exe\\.zst$",
+          "path": "codex-responses-api-proxy.exe"
+        },
+        "windows-aarch64": {
+          "regex": "^codex-responses-api-proxy-aarch64-pc-windows-msvc\\.exe\\.zst$",
+          "path": "codex-responses-api-proxy.exe"
+        }
+      }
+    },
+    "bwrap": {
+      "platforms": {
+        "linux-x86_64": {
+          "regex": "^bwrap-x86_64-unknown-linux-musl\\.zst$",
+          "path": "bwrap"
+        },
+        "linux-aarch64": {
+          "regex": "^bwrap-aarch64-unknown-linux-musl\\.zst$",
+          "path": "bwrap"
+        }
+      }
+    },
+    "codex-command-runner": {
+      "platforms": {
+        "windows-x86_64": {
+          "regex": "^codex-command-runner-x86_64-pc-windows-msvc\\.exe\\.zst$",
+          "path": "codex-command-runner.exe"
+        },
+        "windows-aarch64": {
+          "regex": "^codex-command-runner-aarch64-pc-windows-msvc\\.exe\\.zst$",
+          "path": "codex-command-runner.exe"
+        }
+      }
+    },
+    "codex-windows-sandbox-setup": {
+      "platforms": {
+        "windows-x86_64": {
+          "regex": "^codex-windows-sandbox-setup-x86_64-pc-windows-msvc\\.exe\\.zst$",
+          "path": "codex-windows-sandbox-setup.exe"
+        },
+        "windows-aarch64": {
+          "regex": "^codex-windows-sandbox-setup-aarch64-pc-windows-msvc\\.exe\\.zst$",
+          "path": "codex-windows-sandbox-setup.exe"
+        }
+      }
+    },
+    "codex-windows-sandbox-service": {
+      "platforms": {
+        "windows-x86_64": {
+          "regex": "^codex-windows-sandbox-service-x86_64-pc-windows-msvc\\.exe\\.zst$",
+          "path": "codex-windows-sandbox-service.exe"
+        },
+        "windows-aarch64": {
+          "regex": "^codex-windows-sandbox-service-aarch64-pc-windows-msvc\\.exe\\.zst$",
+          "path": "codex-windows-sandbox-service.exe"
+        }
+      }
+    }
+  }
+}

.github/dotslash-provisioned-config.json

@@ -0,0 +1,16 @@
+{
+  "outputs": {
+    "codex-provisioned": {
+      "platforms": {
+        "macos-aarch64": {
+          "regex": "^codex-provisioned-package-aarch64-apple-darwin\\.tar\\.gz$",
+          "path": "bin/codex"
+        },
+        "macos-x86_64": {
+          "regex": "^codex-provisioned-package-x86_64-apple-darwin\\.tar\\.gz$",
+          "path": "bin/codex"
+        }
+      }
+    }
+  }
+}

.github/dotslash-zsh-config.json

@@ -0,0 +1,32 @@
+{
+  "outputs": {
+    "codex-zsh": {
+      "platforms": {
+        "macos-aarch64": {
+          "name": "codex-zsh-aarch64-apple-darwin.tar.gz",
+          "format": "tar.gz",
+          "hash": "sha256",
+          "path": "codex-zsh/bin/zsh"
+        },
+        "macos-x86_64": {
+          "name": "codex-zsh-x86_64-apple-darwin.tar.gz",
+          "format": "tar.gz",
+          "hash": "sha256",
+          "path": "codex-zsh/bin/zsh"
+        },
+        "linux-x86_64": {
+          "name": "codex-zsh-x86_64-unknown-linux-musl.tar.gz",
+          "format": "tar.gz",
+          "hash": "sha256",
+          "path": "codex-zsh/bin/zsh"
+        },
+        "linux-aarch64": {
+          "name": "codex-zsh-aarch64-unknown-linux-musl.tar.gz",
+          "format": "tar.gz",
+          "hash": "sha256",
+          "path": "codex-zsh/bin/zsh"
+        }
+      }
+    }
+  }
+}

.github/workflows/cargo-deny.yml

@@ -0,0 +1,31 @@
+name: cargo-deny
+
+on:
+  workflow_call:
+
+jobs:
+  cargo-deny:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./codex-rs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-ci
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@e081816240890017053eacbb1bdf337761dc5582 # 1.95.0
+
+      - name: Run cargo-deny
+        uses: EmbarkStudios/cargo-deny-action@82eb9f621fbc699dd0918f3ea06864c14cc84246 # v2
+        with:
+          rust-version: 1.95.0
+          manifest-path: ./codex-rs/Cargo.toml
+
+      - name: Check for a clean worktree
+        if: always() && !cancelled()
+        uses: ./.github/actions/check-clean-worktree

.github/workflows/python-runtime-release.yml

@@ -0,0 +1,63 @@
+name: python-runtime-release
+
+on:
+  workflow_dispatch:
+    inputs:
+      runtime_version:
+        description: "Runtime version to publish before updating the SDK pin, for example 0.136.0, 0.136.0a2, or 0.136.0a2.post1."
+        required: true
+        type: string
+
+concurrency:
+  group: python-runtime-release-${{ inputs.runtime_version }}
+  cancel-in-progress: false
+
+jobs:
+  prepare-python-runtime:
+    name: prepare-python-runtime
+    permissions:
+      contents: read
+    uses: ./.github/workflows/python-runtime-build.yml
+    with:
+      runtime_version: ${{ inputs.runtime_version }}
+
+  # PyPI must trust this top-level workflow for manual runtime publication.
+  publish-python-runtime:
+    if: github.repository == 'openai/codex'
+    name: publish-python-runtime
+    needs: prepare-python-runtime
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write # Required for PyPI trusted publishing.
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Download Python runtime wheels
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-runtime-wheels
+          path: dist/python-runtime
+
+      - name: Publish Python runtime wheels to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/python-runtime
+          skip-existing: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.3"
+
+      - name: Verify Python runtime wheels are available on PyPI
+        env:
+          PYTHON_RUNTIME_VERSION: ${{ needs.prepare-python-runtime.outputs.python_version }}
+        run: |
+          uv run --no-project --with packaging==26.2 python .github/scripts/verify_pypi_release.py \
+            openai-codex-cli-bin "$PYTHON_RUNTIME_VERSION"

.vscode/extensions.json

@@ -0,0 +1,13 @@
+{
+    "recommendations": [
+        "BazelBuild.vscode-bazel",
+        "rust-lang.rust-analyzer",
+        "charliermarsh.ruff",
+        "tamasfe.even-better-toml",
+        "vadimcn.vscode-lldb",
+
+        // Useful if touching files in .github/workflows, though most
+        // contributors will not be doing that?
+        // "github.vscode-github-actions",
+    ]
+}

.vscode/launch.json

@@ -0,0 +1,22 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Cargo launch",
+      "cargo": {
+        "cwd": "${workspaceFolder}/codex-rs",
+        "args": ["build", "--bin=codex-tui"]
+      },
+      "args": []
+    },
+    {
+      "type": "lldb",
+      "request": "attach",
+      "name": "Attach to running codex CLI",
+      "pid": "${command:pickProcess}",
+      "sourceLanguages": ["rust"]
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,27 @@
+{
+    "rust-analyzer.checkOnSave": true,
+    "rust-analyzer.check.command": "clippy",
+    "rust-analyzer.check.extraArgs": ["--tests"],
+    "rust-analyzer.rustfmt.extraArgs": ["--config", "imports_granularity=Item"],
+    "rust-analyzer.cargo.targetDir": "${workspaceFolder}/codex-rs/target/rust-analyzer",
+    "[rust]": {
+        "editor.defaultFormatter": "rust-lang.rust-analyzer",
+        "editor.formatOnSave": true,
+    },
+    "[toml]": {
+        "editor.defaultFormatter": "tamasfe.even-better-toml",
+        "editor.formatOnSave": true,
+    },
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "explicit",
+            "source.organizeImports.ruff": "explicit",
+        },
+    },
+    // Array order for options in ~/.codex/config.toml such as `notify` and the
+    // `args` for an MCP server is significant, so we disable reordering.
+    "evenBetterToml.formatter.reorderArrays": false,
+    "evenBetterToml.formatter.reorderKeys": true,
+}

bazel/build-info/BUILD.bazel

@@ -0,0 +1,12 @@
+load("@bazel_lib//lib:expand_template.bzl", "expand_template")
+
+# Isolate workspace status in a cheap action whose output changes only when
+# the embedded commit changes. Rust compiler actions consume only this file.
+expand_template(
+    name = "build-commit-env",
+    out = "build-commit.env",
+    stamp = 1,
+    stamp_substitutions = {"{BUILD_COMMIT}": "{{STABLE_GIT_COMMIT}}"},
+    template = ["STABLE_GIT_COMMIT={BUILD_COMMIT}"],
+    visibility = ["//codex-rs:__subpackages__"],
+)

bazel/extensions/BUILD.bazel

@@ -0,0 +1,3 @@
+package(default_visibility = ["//visibility:public"])
+
+exports_files(["codex_release_archive.bzl"])

bazel/extensions/codex_release_archive.bzl

@@ -0,0 +1,76 @@
+"""Bazel module extension for pinned Codex release archives."""
+
+_CODEX_RELEASE_BUILD_FILE = """\
+package(default_visibility = ["//visibility:public"])
+
+filegroup(
+    name = "codex",
+    srcs = [{entrypoint}],
+)
+
+filegroup(
+    name = "package",
+    srcs = glob([
+        "codex-package.json",
+        {binaries},
+        {resources},
+        {path},
+    ]),
+)
+"""
+
+def _codex_release_repository_impl(repository_ctx):
+    asset = "codex-package-x86_64-unknown-linux-musl.tar.gz"
+    version = repository_ctx.attr.version
+    repository_ctx.download_and_extract(
+        url = [
+            "https://releases.openai.com/codex/releases/{}/{}".format(version, asset),
+            "https://github.com/openai/codex/releases/download/rust-v{}/{}".format(version, asset),
+        ],
+        sha256 = repository_ctx.attr.sha256,
+    )
+    manifest = json.decode(repository_ctx.read("codex-package.json"))
+    entrypoint = manifest["entrypoint"]
+    binaries = entrypoint.rpartition("/")[0] + "/**"
+    repository_ctx.file(
+        "BUILD.bazel",
+        _CODEX_RELEASE_BUILD_FILE.format(
+            binaries = json.encode(binaries),
+            entrypoint = json.encode(entrypoint),
+            path = json.encode(manifest["pathDir"] + "/**"),
+            resources = json.encode(manifest["resourcesDir"] + "/**"),
+        ),
+        executable = False,
+    )
+    return repository_ctx.repo_metadata(reproducible = True)
+
+_codex_release_repository = repository_rule(
+    implementation = _codex_release_repository_impl,
+    attrs = {
+        "sha256": attr.string(mandatory = True),
+        "version": attr.string(mandatory = True),
+    },
+)
+
+_RELEASE = tag_class(
+    attrs = {
+        "sha256": attr.string(mandatory = True),
+        "version": attr.string(mandatory = True),
+    },
+)
+
+def _codex_release_archive_impl(module_ctx):
+    for module in module_ctx.modules:
+        for release in module.tags.release:
+            _codex_release_repository(
+                name = "codex_release_{}_linux_x86_64".format(release.version),
+                sha256 = release.sha256,
+                version = release.version,
+            )
+
+    return module_ctx.extension_metadata(reproducible = True)
+
+codex_release_archive = module_extension(
+    implementation = _codex_release_archive_impl,
+    tag_classes = {"release": _RELEASE},
+)

bazel/modules/BUILD.bazel

@@ -0,0 +1 @@
+exports_files(["wine.MODULE.bazel"])

bazel/modules/wine.MODULE.bazel

@@ -0,0 +1,26 @@
+http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+# Pin a new-WoW64 build so tests need neither system Wine nor 32-bit host
+# libraries.
+http_archive(
+    name = "wine_linux_x86_64",
+    build_file = "//third_party/wine:BUILD.bazel",
+    sha256 = "39574efa1132c3ca0d5c77dd2eddbe4a49cca0d6cc2c290ff4924493a1c40314",
+    strip_prefix = "wine-11.0-amd64-wow64",
+    urls = [
+        "https://github.com/Kron4ek/Wine-Builds/releases/download/11.0/wine-11.0-amd64-wow64.tar.xz",
+    ],
+)
+
+# Pin the self-contained Windows distribution so Wine tests need neither a
+# system PowerShell installation nor a separate .NET runtime. This intentionally
+# stays on 7.2.24 for the test fixture: 7.4.16 and 7.6.2 currently fail during
+# CLR startup under the pinned Wine 11 runtime, while 7.2.24 runs successfully.
+http_archive(
+    name = "powershell_windows_x86_64",
+    build_file = "//third_party/powershell:BUILD.bazel",
+    sha256 = "a1ccb6d8ad52f917470a136c3752af4465f261bcbe570cf44f52aa69ae6e867e",
+    urls = [
+        "https://github.com/PowerShell/PowerShell/releases/download/v7.2.24/PowerShell-7.2.24-win-x64.zip",
+    ],
+)

bazel/platforms/BUILD.bazel

@@ -0,0 +1 @@
+# Release platform rules live in this package.

bazel/platforms/release_binaries.bzl

@@ -0,0 +1,30 @@
+"""Rules for building release binaries across supported target platforms."""
+
+load("@rules_platform//platform_data:defs.bzl", "platform_data")
+
+_PLATFORM_TRIPLES = {
+    "linux_arm64_musl": "aarch64-unknown-linux-musl",
+    "linux_amd64_musl": "x86_64-unknown-linux-musl",
+    "macos_amd64": "x86_64-apple-darwin",
+    "macos_arm64": "aarch64-apple-darwin",
+    "windows_amd64": "x86_64-pc-windows-msvc",
+    "windows_arm64": "aarch64-pc-windows-msvc",
+}
+
+PLATFORMS = _PLATFORM_TRIPLES.keys()
+
+def multiplatform_binaries(name, platforms = PLATFORMS):
+    """Build a binary for a subset of the declared release platforms."""
+    for platform in platforms:
+        platform_data(
+            name = name + "_" + platform,
+            platform = "@rules_rs//rs/platforms:" + _PLATFORM_TRIPLES[platform],
+            target = name,
+            tags = ["manual"],
+        )
+
+    native.filegroup(
+        name = "release_binaries",
+        srcs = [name + "_" + platform for platform in platforms],
+        tags = ["manual"],
+    )

bazel/rules/BUILD.bazel

@@ -0,0 +1,6 @@
+package(default_visibility = ["//visibility:public"])
+
+exports_files([
+    "e2e_benchmark.bzl",
+    "schema_bundle.bzl",
+])

bazel/rules/e2e_benchmark.bzl

@@ -0,0 +1,56 @@
+load("@crates//:defs.bzl", "all_crate_deps")
+load("@rules_rust//rust:defs.bzl", "rust_binary")
+load("//:defs.bzl", "workspace_root_test")
+
+_WORKSPACE_ROOT_MARKER = "//codex-rs/utils/cargo-bin:repo_root.marker"
+
+def codex_e2e_benchmark(name, binaries = [], data = [], deps = []):
+    """Defines a Bazel-only Divan end-to-end benchmark.
+
+    The benchmark source lives at `e2e_benches/<name>.rs`, with hyphens in
+    `name` replaced by underscores. `binaries` are runtime executables made
+    available through the same `CARGO_BIN_EXE_*` bridge used by Rust tests.
+
+    Args:
+        name: Stem for the generated `<name>-bench` target and benchmark.
+        binaries: Runtime executable labels that the benchmark spawns.
+        data: Additional runtime files needed by the benchmark.
+        deps: Additional Rust dependencies beyond the crate's Cargo deps.
+    """
+    benchmark_name = name.replace("-", "_")
+    source = "e2e_benches/{}.rs".format(benchmark_name)
+    binary_name = name + "-bench-bin"
+    runfile_env = {
+        binary: "CARGO_BIN_EXE_" + native.package_relative_label(binary).name
+        for binary in binaries
+    }
+
+    rust_binary(
+        name = binary_name,
+        testonly = True,
+        srcs = [source],
+        crate_name = benchmark_name + "_bench",
+        crate_root = source,
+        deps = all_crate_deps(
+            normal = True,
+            normal_dev = True,
+        ) + [
+            "@crates//:divan",
+        ] + deps,
+    )
+
+    workspace_root_test(
+        name = name + "-bench",
+        args = [
+            "--bench",
+            benchmark_name,
+        ],
+        data = data,
+        # Keep path resolution inside the wrapper so manifest-only runfiles
+        # work on every supported host platform.
+        runfile_env = runfile_env,
+        tags = ["manual"],
+        test_bin = ":" + binary_name,
+        visibility = ["//codex-rs:__pkg__"],
+        workspace_root_marker = _WORKSPACE_ROOT_MARKER,
+    )

bazel/rules/schema_bundle.bzl

@@ -0,0 +1,39 @@
+"""Cache schema generation from the filtered public Rust test executable."""
+
+def _schema_bundle_impl(ctx):
+    outputs = []
+    for mode in ["stable", "experimental"]:
+        schema = ctx.actions.declare_directory(ctx.label.name + "." + mode)
+        ctx.actions.run(
+            executable = ctx.executable.generator,
+            tools = [ctx.attr.generator[DefaultInfo].files_to_run],
+            arguments = [
+                "--exact",
+                "--ignored",
+                "schema_fixtures_tests::write_schema_fixtures_from_env",
+            ],
+            env = {
+                "CODEX_APP_SERVER_SCHEMA_ROOT": schema.path,
+                "CODEX_APP_SERVER_SCHEMA_EXPERIMENTAL": "1" if mode == "experimental" else "0",
+                "RUST_MIN_STACK": "8388608",
+            },
+            outputs = [schema],
+            mnemonic = "PublicSchema",
+            progress_message = "Generating %s public app-server schemas" % mode,
+        )
+        outputs.append(schema)
+
+    # Expose the pinned compressor alongside the cached directories so callers
+    # can normalize the JSON without a separate `bazel run` invocation.
+    zstd = ctx.actions.declare_file(ctx.label.name + ".zstd")
+    ctx.actions.symlink(output = zstd, target_file = ctx.executable.zstd, is_executable = True)
+    return [DefaultInfo(files = depset(outputs + [zstd]))]
+
+schema_bundle = rule(
+    implementation = _schema_bundle_impl,
+    attrs = {
+        "generator": attr.label(mandatory = True, executable = True, cfg = "exec"),
+        "zstd": attr.label(default = "@zstd//:zstd_cli", executable = True, cfg = "exec"),
+    },
+    doc = "Generates both schema modes as cacheable actions with explicit tool dependencies.",
+)

bazel/rules/testing/BUILD.bazel

@@ -0,0 +1,5 @@
+package(default_visibility = ["//visibility:public"])
+
+exports_files([
+    "foreign_platform_binary.bzl",
+])

bazel/rules/testing/compat/BUILD.bazel

@@ -0,0 +1,31 @@
+load("@rules_rust//rust:defs.bzl", "rust_test")
+
+package(default_visibility = ["//visibility:public"])
+
+exports_files(["exec_server_compat_test.bzl"])
+
+# exec_server_compat_test wraps this shared binary with current or released builds.
+# Keep it manual so only wrapped compatibility tests enter the normal test graph.
+rust_test(
+    name = "exec-server-compat-test-bin",
+    srcs = ["exec_server_compat_test.rs"],
+    crate_name = "exec_server_compat_test",
+    crate_root = "exec_server_compat_test.rs",
+    edition = "2024",
+    tags = ["manual"],
+    target_compatible_with = [
+        "@platforms//cpu:x86_64",
+        "@platforms//os:linux",
+    ],
+    visibility = ["//codex-rs/exec-server:__pkg__"],
+    deps = [
+        "//codex-rs/exec-server",
+        "//codex-rs/exec-server/tests/support",
+        "@crates//:anyhow",
+        "@crates//:pretty_assertions",
+        "@crates//:serde_json",
+        "@crates//:tempfile",
+        "@crates//:tokio",
+        "@crates//:wiremock",
+    ],
+)

bazel/rules/testing/compat/exec_server_compat_test.bzl

@@ -0,0 +1,47 @@
+"""Bazel coverage for app-server and exec-server release compatibility."""
+
+load("//:defs.bzl", "workspace_root_test")
+
+def exec_server_compat_test(
+        name,
+        comparison_binary = None,
+        current_binary = "//codex-rs/cli:codex",
+        release = None):
+    """Tests both executor directions against another Codex build or release.
+
+    Args:
+        name: Name of the generated compatibility test target.
+        comparison_binary: Built Codex executable to compare with the current build.
+        current_binary: Built Codex executable representing the current version.
+        release: External release repository exposing `:codex` and `:package`.
+    """
+    if (comparison_binary == None) == (release == None):
+        fail("exactly one of comparison_binary and release must be set")
+
+    comparison = comparison_binary if release == None else release + "//:codex"
+    data = [] if release == None else [release + "//:package"]
+    comparison_alias = name + "-comparison-binary"
+    native.alias(
+        name = comparison_alias,
+        actual = comparison,
+        tags = ["manual"],
+        visibility = ["//visibility:private"],
+    )
+
+    workspace_root_test(
+        name = name,
+        args = ["--test-threads=1"],
+        data = data,
+        runfile_env = {
+            "//codex-rs/bwrap:bwrap": "CARGO_BIN_EXE_bwrap",
+            current_binary: "CODEX_TEST_CURRENT_CODEX",
+            ":" + comparison_alias: "CODEX_TEST_RELEASED_CODEX",
+        },
+        tags = ["no-sandbox"],
+        target_compatible_with = [
+            "@platforms//cpu:x86_64",
+            "@platforms//os:linux",
+        ],
+        test_bin = "//bazel/rules/testing/compat:exec-server-compat-test-bin",
+        workspace_root_marker = "//codex-rs/utils/cargo-bin:repo_root.marker",
+    )

bazel/rules/testing/compat/exec_server_compat_test.rs

@@ -0,0 +1,379 @@
+use std::path::Path;
+use std::path::PathBuf;
+use std::process::Stdio;
+use std::sync::Arc;
+use std::sync::Mutex;
+
+use anyhow::Context;
+use anyhow::Result;
+use codex_exec_server::CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR;
+use codex_exec_server::CODEX_EXEC_SERVER_NOISE_ENVIRONMENT_ID_ENV_VAR;
+use codex_exec_server::CODEX_EXEC_SERVER_NOISE_REGISTRY_URL_ENV_VAR;
+use codex_exec_server::CODEX_EXEC_SERVER_URL_ENV_VAR;
+use codex_exec_server_test_support::relay::TEST_TIMEOUT as VERSION_SKEW_TIMEOUT;
+use codex_exec_server_test_support::relay::accept_websocket;
+use codex_exec_server_test_support::relay::assert_relay_data_is_encrypted;
+use codex_exec_server_test_support::relay::proxy_relay_frames;
+use codex_exec_server_test_support::relay::registered_executor_public_key;
+use pretty_assertions::assert_eq;
+use serde_json::Value;
+use serde_json::json;
+use tempfile::TempDir;
+use tokio::io::AsyncBufReadExt;
+use tokio::io::AsyncWriteExt;
+use tokio::io::BufReader;
+use tokio::io::Lines;
+use tokio::net::TcpListener;
+use tokio::process::ChildStdin;
+use tokio::process::ChildStdout;
+use tokio::process::Command;
+use tokio::time::timeout;
+use wiremock::Mock;
+use wiremock::MockServer;
+use wiremock::ResponseTemplate;
+use wiremock::matchers::header;
+use wiremock::matchers::method;
+use wiremock::matchers::path;
+
+const ENVIRONMENT_ID: &str = "env-noise-relay-test";
+const EXECUTOR_REGISTRATION_ID: &str = "registration-1";
+const HARNESS_KEY_AUTHORIZATION: &str = "harness-key-authorization";
+const REGISTRY_TOKEN: &str = "registry-token";
+const RELEASED_CODEX_ENV_VAR: &str = "CODEX_TEST_RELEASED_CODEX";
+const CURRENT_CODEX_ENV_VAR: &str = "CODEX_TEST_CURRENT_CODEX";
+const EXECUTOR_MARKER_ENV_VAR: &str = "CODEX_EXECUTOR_VERSION_SKEW_MARKER";
+const EXPECTED_OUTPUT: &str = "executor-version-skew-ok";
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn current_app_server_runs_commands_on_released_exec_server_over_noise() -> Result<()> {
+    let Some((current, released)) = version_skew_binaries()? else {
+        return Ok(());
+    };
+    assert_noise_version_skew(&current, &released).await
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn released_app_server_runs_commands_on_current_exec_server_over_noise() -> Result<()> {
+    let Some((current, released)) = version_skew_binaries()? else {
+        return Ok(());
+    };
+    assert_noise_version_skew(&released, &current).await
+}
+
+fn version_skew_binaries() -> Result<Option<(PathBuf, PathBuf)>> {
+    let Some(released) = std::env::var_os(RELEASED_CODEX_ENV_VAR) else {
+        return Ok(None);
+    };
+    let current = std::env::var_os(CURRENT_CODEX_ENV_VAR)
+        .with_context(|| format!("{CURRENT_CODEX_ENV_VAR} must name the current Codex binary"))?;
+    let current = PathBuf::from(current);
+    let released = PathBuf::from(released);
+    anyhow::ensure!(
+        current.is_file(),
+        "current Codex does not exist: {}",
+        current.display()
+    );
+    anyhow::ensure!(
+        released.is_file(),
+        "released Codex does not exist: {}",
+        released.display()
+    );
+    Ok(Some((current, released)))
+}
+
+async fn assert_noise_version_skew(app_binary: &Path, executor_binary: &Path) -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let model = mock_model(codex_home.path()).await?;
+    let model_url = model.uri();
+    std::fs::write(
+        codex_home.path().join("config.toml"),
+        format!(
+            r#"
+model = "mock-model"
+approval_policy = "never"
+sandbox_mode = "danger-full-access"
+model_provider = "mock_provider"
+
+[model_providers.mock_provider]
+name = "Mock provider"
+base_url = "{model_url}/v1"
+wire_api = "responses"
+request_max_retries = 0
+stream_max_retries = 0
+"#
+        ),
+    )?;
+
+    let listener = TcpListener::bind("127.0.0.1:0").await?;
+    let rendezvous_url = format!("ws://{}", listener.local_addr()?);
+    let registry = MockServer::start().await;
+    let registry_url = registry.uri();
+    Mock::given(method("POST"))
+        .and(path(format!(
+            "/cloud/environment/{ENVIRONMENT_ID}/register"
+        )))
+        .and(header("authorization", format!("Bearer {REGISTRY_TOKEN}")))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "environment_id": ENVIRONMENT_ID,
+            "url": format!("{rendezvous_url}/relay?role=environment"),
+            "security_profile": "noise_hybrid_ik_v1",
+            "executor_registration_id": EXECUTOR_REGISTRATION_ID,
+        })))
+        .expect(1)
+        .mount(&registry)
+        .await;
+    Mock::given(method("POST"))
+        .and(path(format!(
+            "/cloud/environment/{ENVIRONMENT_ID}/validate"
+        )))
+        .and(header("authorization", format!("Bearer {REGISTRY_TOKEN}")))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({"valid": true})))
+        .expect(1)
+        .mount(&registry)
+        .await;
+
+    let mut executor = Command::new(executor_binary)
+        .args([
+            "exec-server",
+            "--remote",
+            registry_url.as_str(),
+            "--environment-id",
+            ENVIRONMENT_ID,
+        ])
+        .current_dir(codex_home.path())
+        .env("CODEX_HOME", codex_home.path())
+        .env("CODEX_API_KEY", REGISTRY_TOKEN)
+        .env(EXECUTOR_MARKER_ENV_VAR, EXPECTED_OUTPUT)
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::inherit())
+        .kill_on_drop(true)
+        .spawn()
+        .with_context(|| format!("start remote executor from {}", executor_binary.display()))?;
+
+    let environment_websocket = accept_websocket(&listener, "environment").await?;
+    let executor_public_key = registered_executor_public_key(&registry).await?;
+    Mock::given(method("POST"))
+        .and(path(format!("/cloud/environment/{ENVIRONMENT_ID}/connect")))
+        .and(header("authorization", format!("Bearer {REGISTRY_TOKEN}")))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "environment_id": ENVIRONMENT_ID,
+            "url": format!("{rendezvous_url}/relay?role=harness"),
+            "security_profile": "noise_hybrid_ik_v1",
+            "executor_registration_id": EXECUTOR_REGISTRATION_ID,
+            "executor_public_key": executor_public_key,
+            "harness_key_authorization": HARNESS_KEY_AUTHORIZATION,
+        })))
+        .expect(1)
+        .mount(&registry)
+        .await;
+
+    let captured_frames = Arc::new(Mutex::new(Vec::new()));
+    let captured_relay_frames = Arc::clone(&captured_frames);
+    let relay = tokio::spawn(async move {
+        let harness_websocket = accept_websocket(&listener, "harness").await?;
+        proxy_relay_frames(
+            environment_websocket,
+            harness_websocket,
+            captured_relay_frames,
+        )
+        .await
+    });
+
+    let mut app_server = Command::new(app_binary)
+        .arg("app-server")
+        .current_dir(codex_home.path())
+        .env("CODEX_HOME", codex_home.path())
+        .env("CODEX_API_KEY", REGISTRY_TOKEN)
+        .env(
+            "CODEX_APP_SERVER_MANAGED_CONFIG_PATH",
+            codex_home.path().join("managed_config.toml"),
+        )
+        .env(CODEX_EXEC_SERVER_NOISE_REGISTRY_URL_ENV_VAR, &registry_url)
+        .env(
+            CODEX_EXEC_SERVER_NOISE_ENVIRONMENT_ID_ENV_VAR,
+            ENVIRONMENT_ID,
+        )
+        .env(CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR, REGISTRY_TOKEN)
+        .env_remove(CODEX_EXEC_SERVER_URL_ENV_VAR)
+        .env_remove(EXECUTOR_MARKER_ENV_VAR)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .kill_on_drop(true)
+        .spawn()
+        .with_context(|| format!("start app-server from {}", app_binary.display()))?;
+    let mut stdin = app_server.stdin.take().context("app-server stdin")?;
+    let stdout = app_server.stdout.take().context("app-server stdout")?;
+    let mut stdout = BufReader::new(stdout).lines();
+    let mut notifications = Vec::new();
+
+    app_server_request(
+        &mut stdin,
+        &mut stdout,
+        &mut notifications,
+        /*id*/ 1,
+        "initialize",
+        json!({
+            "clientInfo": {"name": "noise-version-skew", "version": "0.1.0"},
+            "capabilities": {"experimentalApi": true},
+        }),
+    )
+    .await?;
+    stdin.write_all(b"{\"method\":\"initialized\"}\n").await?;
+
+    let thread = app_server_request(
+        &mut stdin,
+        &mut stdout,
+        &mut notifications,
+        /*id*/ 2,
+        "thread/start",
+        json!({"cwd": codex_home.path()}),
+    )
+    .await?;
+    let thread_id = thread["thread"]["id"]
+        .as_str()
+        .context("thread/start should return a thread id")?;
+    app_server_request(
+        &mut stdin,
+        &mut stdout,
+        &mut notifications,
+        /*id*/ 3,
+        "turn/start",
+        json!({
+            "threadId": thread_id,
+            "input": [{
+                "type": "text",
+                "text": "run the Noise compatibility command",
+                "textElements": [],
+            }],
+        }),
+    )
+    .await?;
+
+    while !notifications
+        .iter()
+        .any(|notification: &Value| notification["method"] == "turn/completed")
+    {
+        let line = timeout(VERSION_SKEW_TIMEOUT, stdout.next_line())
+            .await
+            .context("waiting for turn/completed")??
+            .context("app-server exited before turn/completed")?;
+        notifications.push(serde_json::from_str(&line)?);
+    }
+
+    assert_eq!(
+        std::fs::read_to_string(codex_home.path().join("version-skew-output.txt"))?,
+        EXPECTED_OUTPUT
+    );
+    assert_relay_data_is_encrypted(&captured_frames)?;
+    registry.verify().await;
+    model.verify().await;
+
+    let _ = app_server.start_kill();
+    let _ = executor.start_kill();
+    relay.abort();
+    Ok(())
+}
+
+async fn app_server_request(
+    stdin: &mut ChildStdin,
+    stdout: &mut Lines<BufReader<ChildStdout>>,
+    notifications: &mut Vec<Value>,
+    id: u64,
+    method: &str,
+    params: Value,
+) -> Result<Value> {
+    let request = json!({"id": id, "method": method, "params": params});
+    stdin.write_all(request.to_string().as_bytes()).await?;
+    stdin.write_all(b"\n").await?;
+
+    loop {
+        let line = timeout(VERSION_SKEW_TIMEOUT, stdout.next_line())
+            .await
+            .with_context(|| format!("waiting for {method} response"))??
+            .with_context(|| format!("app-server exited before {method} response"))?;
+        let response: Value = serde_json::from_str(&line)?;
+        if response["id"] == id {
+            anyhow::ensure!(
+                response.get("error").is_none(),
+                "{method} failed: {}",
+                response["error"]
+            );
+            return response.get("result").cloned().context("missing result");
+        }
+        notifications.push(response);
+    }
+}
+
+async fn mock_model(codex_home: &Path) -> Result<MockServer> {
+    let server = MockServer::start().await;
+    let arguments = serde_json::to_string(&json!({
+        "cmd": format!("printf '%s' \"${EXECUTOR_MARKER_ENV_VAR}\" > version-skew-output.txt"),
+        "workdir": codex_home,
+        "yield_time_ms": 5_000,
+    }))?;
+    let completed = |id| {
+        json!({
+            "type": "response.completed",
+            "response": {
+                "id": id,
+                "usage": {
+                    "input_tokens": 0,
+                    "input_tokens_details": null,
+                    "output_tokens": 0,
+                    "output_tokens_details": null,
+                    "total_tokens": 0,
+                },
+            },
+        })
+    };
+    let responses = vec![
+        event_stream(vec![
+            json!({"type": "response.created", "response": {"id": "response-1"}}),
+            json!({
+                "type": "response.output_item.done",
+                "item": {
+                    "type": "function_call",
+                    "call_id": "noise-version-skew-command",
+                    "name": "exec_command",
+                    "arguments": arguments,
+                },
+            }),
+            completed("response-1"),
+        ])?,
+        event_stream(vec![
+            json!({"type": "response.created", "response": {"id": "response-2"}}),
+            json!({
+                "type": "response.output_item.done",
+                "item": {
+                    "type": "message",
+                    "role": "assistant",
+                    "id": "message-1",
+                    "content": [{"type": "output_text", "text": "done"}],
+                },
+            }),
+            completed("response-2"),
+        ])?,
+    ];
+    for response in responses {
+        Mock::given(method("POST"))
+            .and(path("/v1/responses"))
+            .respond_with(ResponseTemplate::new(200).set_body_raw(response, "text/event-stream"))
+            .up_to_n_times(1)
+            .expect(1)
+            .mount(&server)
+            .await;
+    }
+    Ok(server)
+}
+
+fn event_stream(events: Vec<Value>) -> Result<String> {
+    events
+        .into_iter()
+        .map(|event| {
+            let event_type = event["type"].as_str().context("SSE event type")?;
+            Ok(format!("event: {event_type}\ndata: {event}\n\n"))
+        })
+        .collect()
+}

bazel/rules/testing/foreign_platform_binary.bzl

@@ -0,0 +1,53 @@
+"""Makes a binary built for a foreign platform available as test data."""
+
+_EXTRA_RUSTC_FLAGS = "@rules_rust//rust/settings:extra_rustc_flags"
+
+def _foreign_platform_transition_impl(settings, attr):
+    # A transition cannot rewrite a dependency's rule attributes. Use the
+    # rules_rust build setting when every Rust target in the foreign
+    # configuration needs additional compiler or linker flags.
+    return {
+        "//command_line_option:platforms": [attr.platform],
+        _EXTRA_RUSTC_FLAGS: settings[_EXTRA_RUSTC_FLAGS] + attr.extra_rustc_flags,
+    }
+
+_foreign_platform_transition = transition(
+    implementation = _foreign_platform_transition_impl,
+    inputs = [_EXTRA_RUSTC_FLAGS],
+    outputs = [
+        "//command_line_option:platforms",
+        _EXTRA_RUSTC_FLAGS,
+    ],
+)
+
+def _foreign_platform_binary_impl(ctx):
+    if len(ctx.attr.binary) != 1:
+        fail("expected exactly one transitioned binary")
+    binary = ctx.attr.binary[0][DefaultInfo]
+    runfiles = ctx.runfiles(transitive_files = binary.files)
+    runfiles = runfiles.merge(binary.default_runfiles)
+    return [
+        DefaultInfo(
+            files = binary.files,
+            runfiles = runfiles,
+        ),
+    ]
+
+foreign_platform_binary = rule(
+    implementation = _foreign_platform_binary_impl,
+    attrs = {
+        "binary": attr.label(
+            cfg = _foreign_platform_transition,
+            executable = True,
+            mandatory = True,
+        ),
+        "extra_rustc_flags": attr.string_list(
+            doc = "Additional flags applied to every Rust target in the foreign configuration.",
+        ),
+        "platform": attr.string(mandatory = True),
+        "_allowlist_function_transition": attr.label(
+            default = "@bazel_tools//tools/allowlists/function_transition_allowlist",
+        ),
+    },
+    doc = "Builds `binary` for `platform` and exposes its files and runfiles.",
+)

bazel/rules/testing/wine/BUILD.bazel

@@ -0,0 +1,54 @@
+load("@rules_rust//rust:defs.bzl", "rust_binary", "rust_library")
+load(":wine.bzl", "wine_rust_test")
+
+package(default_visibility = ["//visibility:public"])
+
+exports_files([
+    "wine.bzl",
+    "wine_runtime.bzl",
+])
+
+rust_library(
+    name = "wine_test_support",
+    testonly = True,
+    srcs = [
+        "src/lib.rs",
+        "src/lib_tests.rs",
+    ],
+    crate_name = "wine_test_support",
+    crate_root = "src/lib.rs",
+    edition = "2024",
+    target_compatible_with = ["@platforms//os:linux"],
+    deps = [
+        "//codex-rs/utils/cargo-bin",
+        "//codex-rs/utils/pty",
+        "@crates//:anyhow",
+        "@crates//:tempfile",
+        "@crates//:tokio",
+    ],
+)
+
+rust_binary(
+    name = "windows-smoke",
+    testonly = True,
+    srcs = ["fixtures/windows_smoke.rs"],
+    crate_name = "wine_smoke",
+    crate_root = "fixtures/windows_smoke.rs",
+    edition = "2024",
+    tags = ["manual"],
+    target_compatible_with = ["@platforms//os:windows"],
+    visibility = ["//visibility:private"],
+)
+
+wine_rust_test(
+    name = "wine-test-support-unit-tests",
+    timeout = "short",
+    crate = ":wine_test_support",
+    windows_binaries = {
+        "wine-smoke": ":windows-smoke",
+    },
+    deps = [
+        "@crates//:futures",
+        "@crates//:pretty_assertions",
+    ],
+)

bazel/rules/testing/wine/fixtures/windows_smoke.rs

@@ -0,0 +1,15 @@
+use std::io::Write;
+
+fn main() {
+    println!("WINE_TEST_READY");
+    std::io::stdout().flush().expect("flush readiness marker");
+
+    if std::env::args().any(|arg| arg == "--fail") {
+        std::process::exit(9);
+    }
+    if std::env::args().any(|arg| arg == "--wait") {
+        loop {
+            std::thread::park();
+        }
+    }
+}

bazel/rules/testing/wine/src/lib.rs

@@ -0,0 +1,402 @@
+#[cfg(not(target_os = "linux"))]
+compile_error!("wine_test_support can only run on Linux");
+
+use std::ffi::OsString;
+use std::fs;
+use std::future::Future;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+use std::process::Command as StdCommand;
+use std::process::Stdio;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use tempfile::TempDir;
+use tokio::process::Child;
+use tokio::process::ChildStdout;
+use tokio::process::Command as TokioCommand;
+
+/// Builds a command that runs a Windows executable in an isolated Wine prefix.
+pub struct WineTestCommand {
+    executable: PathBuf,
+    args: Vec<OsString>,
+    env: Vec<(OsString, OsString)>,
+}
+
+/// Owns a Wine process and its isolated wineserver.
+///
+/// Call [`Self::scope`] or [`Self::shutdown`] on every successful path. A
+/// normal unguarded drop panics, while a drop during unwinding performs
+/// blocking cleanup without introducing a second panic.
+pub struct WineTestProcess {
+    processes: Option<WineProcesses>,
+}
+
+struct WineProcesses {
+    child: Child,
+    cleanup_complete: bool,
+    prefix: TempDir,
+    runtime: WineRuntimePaths,
+}
+
+struct WineRuntimePaths {
+    dll_path: PathBuf,
+    powershell_runtime: PathBuf,
+    wine: PathBuf,
+    wineserver: PathBuf,
+}
+
+impl WineTestCommand {
+    /// Creates a Wine command for `executable`.
+    pub fn new(executable: impl Into<PathBuf>) -> Self {
+        Self {
+            executable: executable.into(),
+            args: Vec::new(),
+            env: Vec::new(),
+        }
+    }
+
+    /// Adds an argument passed to the Windows executable.
+    #[must_use]
+    pub fn arg(mut self, arg: impl Into<OsString>) -> Self {
+        self.args.push(arg.into());
+        self
+    }
+
+    /// Adds or overrides an environment variable for the Wine process.
+    #[must_use]
+    pub fn env(mut self, key: impl Into<OsString>, value: impl Into<OsString>) -> Self {
+        self.env.push((key.into(), value.into()));
+        self
+    }
+
+    /// Starts the Windows executable with a fresh `WINEPREFIX`.
+    pub fn spawn(self) -> Result<WineTestProcess> {
+        let runtime = WineRuntimePaths::from_runfiles()?;
+        let prefix = TempDir::new().context("create isolated Wine prefix")?;
+        install_powershell_runtime(prefix.path(), &runtime.powershell_runtime)?;
+        let mut command = StdCommand::new(&runtime.wine);
+        configure_wine_environment(&mut command, &runtime, prefix.path());
+        command
+            .arg(self.executable)
+            .args(self.args)
+            .envs(self.env)
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::inherit());
+
+        let mut command = TokioCommand::from(command);
+        command.kill_on_drop(true);
+        let child = command
+            .spawn()
+            .context("start Windows process under Wine")?;
+
+        Ok(WineTestProcess {
+            processes: Some(WineProcesses {
+                child,
+                cleanup_complete: false,
+                prefix,
+                runtime,
+            }),
+        })
+    }
+}
+
+impl WineTestProcess {
+    /// Returns the host path to this process's isolated Wine prefix.
+    pub fn prefix_path(&self) -> &Path {
+        let Some(processes) = self.processes.as_ref() else {
+            panic!("Wine process guard is missing");
+        };
+        processes.prefix.path()
+    }
+
+    /// Takes the piped standard output of the Wine process.
+    ///
+    /// This may only be called once for a process created by
+    /// [`WineTestCommand::spawn`].
+    pub fn take_stdout(&mut self) -> ChildStdout {
+        let Some(processes) = self.processes.as_mut() else {
+            panic!("Wine process guard is missing");
+        };
+        let Some(stdout) = processes.child.stdout.take() else {
+            panic!("Wine process stdout has already been taken");
+        };
+        stdout
+    }
+
+    /// Runs `future`, then asynchronously tears down Wine before returning.
+    ///
+    /// If both the scoped operation and teardown fail, the operation error is
+    /// returned with the teardown error attached as context. A panic in the
+    /// scoped operation triggers the blocking unwind-time fallback instead.
+    pub async fn scope<T>(self, future: impl Future<Output = Result<T>>) -> Result<T> {
+        let scope_result = future.await;
+        let shutdown_result = self.shutdown().await;
+        match (scope_result, shutdown_result) {
+            (Ok(value), Ok(())) => Ok(value),
+            (Err(error), Ok(())) => Err(error),
+            (Ok(_), Err(error)) => Err(error),
+            (Err(error), Err(shutdown_error)) => {
+                Err(error.context(format!("Wine teardown also failed: {shutdown_error:#}")))
+            }
+        }
+    }
+
+    /// Kills the Windows process, waits for it, and stops its wineserver.
+    pub async fn shutdown(mut self) -> Result<()> {
+        let Some(processes) = self.processes.as_mut() else {
+            anyhow::bail!("Wine process guard is missing");
+        };
+        let result = processes.shutdown().await;
+        self.processes.take();
+        result
+    }
+}
+
+impl Drop for WineTestProcess {
+    fn drop(&mut self) {
+        // Panicking here starts unwinding, after which WineProcesses performs
+        // the blocking fallback while its field is dropped.
+        if self.processes.is_some() && !std::thread::panicking() {
+            panic!("WineTestProcess dropped without async teardown");
+        }
+    }
+}
+
+impl WineRuntimePaths {
+    fn from_runfiles() -> Result<Self> {
+        let wine = codex_utils_cargo_bin::cargo_bin("wine")?;
+        let runtime_marker = codex_utils_cargo_bin::cargo_bin("wine-runtime-marker")?;
+        let dll_path = runtime_marker
+            .parent()
+            .context("locate Wine runtime directory")?
+            .to_path_buf();
+        let wineserver = codex_utils_cargo_bin::cargo_bin("wineserver")?;
+        let powershell_runtime = codex_utils_cargo_bin::cargo_bin("pwsh-runtime-marker")?
+            .parent()
+            .context("locate PowerShell runtime directory")?
+            .to_path_buf();
+        Ok(Self {
+            dll_path,
+            powershell_runtime,
+            wine,
+            wineserver,
+        })
+    }
+}
+
+impl WineProcesses {
+    async fn shutdown(&mut self) -> Result<()> {
+        let (kill_result, check_exit_status) = match self.child.try_wait() {
+            Ok(Some(_)) => (Ok(()), true),
+            Ok(None) => (
+                self.child
+                    .start_kill()
+                    .context("kill Windows process running under Wine"),
+                false,
+            ),
+            Err(error) => (Err(error).context("check Windows process status"), false),
+        };
+        let wait_result = self
+            .child
+            .wait()
+            .await
+            .context("wait for Windows process running under Wine")
+            .and_then(|status| {
+                anyhow::ensure!(
+                    !check_exit_status || status.success(),
+                    "Windows process exited with {status}"
+                );
+                Ok(())
+            });
+        let wineserver_result = async {
+            let mut command = TokioCommand::from(self.stop_wineserver_command());
+            let status = command.status().await.context("stop isolated wineserver")?;
+            anyhow::ensure!(status.success(), "wineserver exited with {status}");
+            Ok(())
+        }
+        .await;
+
+        // Every cleanup action has been attempted, so an individual error
+        // should not cause the blocking fallback to repeat them.
+        self.cleanup_complete = true;
+        kill_result?;
+        wait_result?;
+        wineserver_result
+    }
+
+    fn stop_wineserver_command(&self) -> StdCommand {
+        let mut command = StdCommand::new(&self.runtime.wineserver);
+        configure_wine_environment(&mut command, &self.runtime, self.prefix.path());
+        command
+            .args(["-k", "-w"])
+            .stdout(Stdio::null())
+            .stderr(Stdio::null());
+        command
+    }
+
+    fn shutdown_blocking(&mut self) {
+        log_panic_cleanup(format_args!(
+            "Wine panic cleanup starting for prefix {}",
+            self.prefix.path().display()
+        ));
+        if let Err(error) = self.child.start_kill() {
+            log_panic_cleanup(format_args!(
+                "Wine panic cleanup could not kill its child: {error}"
+            ));
+        }
+
+        log_panic_cleanup(format_args!("Wine panic cleanup waiting for its child"));
+        loop {
+            match self.child.try_wait() {
+                Ok(Some(status)) => {
+                    log_panic_cleanup(format_args!(
+                        "Wine panic cleanup child exited with {status}"
+                    ));
+                    break;
+                }
+                Ok(None) => std::thread::sleep(Duration::from_millis(10)),
+                Err(error) => {
+                    log_panic_cleanup(format_args!(
+                        "Wine panic cleanup could not wait for its child: {error}"
+                    ));
+                    break;
+                }
+            }
+        }
+
+        log_panic_cleanup(format_args!("Wine panic cleanup stopping its wineserver"));
+        match self.stop_wineserver_command().status() {
+            Ok(status) => log_panic_cleanup(format_args!(
+                "Wine panic cleanup wineserver exited with {status}"
+            )),
+            Err(error) => log_panic_cleanup(format_args!(
+                "Wine panic cleanup could not stop its wineserver: {error}"
+            )),
+        }
+        self.cleanup_complete = true;
+        log_panic_cleanup(format_args!("Wine panic cleanup complete"));
+    }
+}
+
+impl Drop for WineProcesses {
+    fn drop(&mut self) {
+        // Never introduce a second panic while unwinding. Blocking here is
+        // intentional because test failures must not leak Wine children.
+        if !self.cleanup_complete && std::thread::panicking() {
+            self.shutdown_blocking();
+        }
+    }
+}
+
+fn log_panic_cleanup(args: std::fmt::Arguments<'_>) {
+    let _ = writeln!(std::io::stderr().lock(), "{args}");
+}
+
+fn configure_wine_environment(command: &mut StdCommand, runtime: &WineRuntimePaths, prefix: &Path) {
+    command
+        .env_remove("DISPLAY")
+        .env("HOME", prefix)
+        .env("XDG_RUNTIME_DIR", prefix)
+        .env("WINEARCH", "win64")
+        .env("WINEPREFIX", prefix)
+        .env("WINEDLLPATH", &runtime.dll_path)
+        .env("WINESERVER", &runtime.wineserver)
+        .env("WINEDEBUG", "-all")
+        .env("WINEDLLOVERRIDES", "mscoree,mshtml,winegstreamer=")
+        .env("LANG", "C.UTF-8")
+        .env("LC_ALL", "C.UTF-8")
+        .env("LC_CTYPE", "C.UTF-8")
+        .env("TEMP", r"C:\windows\temp")
+        .env("TMP", r"C:\windows\temp");
+}
+
+/// Installs the complete pinned PowerShell distribution where Windows tooling
+/// expects to discover PowerShell 7.
+///
+/// `pwsh.exe` is not a standalone executable: it loads its adjacent .NET host,
+/// managed assemblies, native libraries, modules, and configuration files at
+/// startup. The Bazel archive is exposed through runfiles rather than a normal
+/// Windows installation, while shell detection deliberately probes the
+/// conventional `C:\Program Files\PowerShell\7` fallback. We therefore have to
+/// reproduce the archive's directory tree inside each isolated Wine prefix;
+/// copying only the executable would fail before a command could run.
+fn install_powershell_runtime(prefix: &Path, runtime: &Path) -> Result<()> {
+    let powershell_parent = prefix
+        .join("drive_c")
+        .join("Program Files")
+        .join("PowerShell");
+    fs::create_dir_all(&powershell_parent).context("create PowerShell installation parent")?;
+    let destination = powershell_parent.join("7");
+    materialize_runtime_directory(runtime, &destination)
+}
+
+/// Recursively reproduces a runfiles directory in a writable Wine prefix.
+///
+/// Bazel runfiles may be immutable, represented by a symlink forest, and may
+/// contain the PowerShell distribution on a different filesystem from the
+/// temporary prefix. Hard links avoid repeatedly copying the roughly
+/// hundred-megabyte runtime when both locations share a filesystem; the copy
+/// fallback preserves correctness for sandbox or remote-execution layouts
+/// where cross-device hard links are unavailable.
+fn materialize_runtime_directory(source: &Path, destination: &Path) -> Result<()> {
+    fs::create_dir_all(destination).with_context(|| {
+        format!(
+            "create PowerShell runtime directory {}",
+            destination.display()
+        )
+    })?;
+    for entry in fs::read_dir(source)
+        .with_context(|| format!("read PowerShell runtime directory {}", source.display()))?
+    {
+        let entry = entry.context("read PowerShell runtime entry")?;
+        let source_path = entry.path();
+        let destination_path = destination.join(entry.file_name());
+        // Local Bazel runfiles trees expose external-repository files as
+        // symlinks. Resolve those trusted runfiles entries before inspecting
+        // or linking them so the writable prefix contains ordinary files.
+        let resolved_source_path = fs::canonicalize(&source_path).with_context(|| {
+            format!("resolve PowerShell runtime entry {}", source_path.display())
+        })?;
+        let file_type = fs::metadata(&resolved_source_path)
+            .with_context(|| {
+                format!(
+                    "inspect PowerShell runtime entry {}",
+                    resolved_source_path.display()
+                )
+            })?
+            .file_type();
+        if file_type.is_dir() {
+            // PowerShell resolves assemblies and modules by their relative
+            // locations, so flattening the archive is not an option.
+            materialize_runtime_directory(&resolved_source_path, &destination_path)?;
+        } else if file_type.is_file() {
+            // A hard link gives each prefix the expected installation layout
+            // without duplicating the large runtime in the common local case.
+            if fs::hard_link(&resolved_source_path, &destination_path).is_err() {
+                // Cross-device links are common under Bazel sandboxing and
+                // remote execution, where an ordinary copy is still valid.
+                fs::copy(&resolved_source_path, &destination_path).with_context(|| {
+                    format!(
+                        "copy PowerShell runtime file {} to {}",
+                        resolved_source_path.display(),
+                        destination_path.display()
+                    )
+                })?;
+            }
+        } else {
+            anyhow::bail!(
+                "unsupported PowerShell runtime entry type at {}",
+                source_path.display()
+            );
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "lib_tests.rs"]
+mod tests;

bazel/rules/testing/wine/src/lib_tests.rs

@@ -0,0 +1,451 @@
+use std::any::Any;
+use std::collections::HashMap;
+use std::fs;
+use std::future::Future;
+use std::panic::AssertUnwindSafe;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use codex_utils_pty::SpawnedProcess;
+use codex_utils_pty::TerminalSize;
+use futures::FutureExt;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+use tokio::io::AsyncBufReadExt;
+use tokio::io::BufReader;
+use tokio::process::Command as TokioCommand;
+use tokio::time::timeout;
+
+use super::WineRuntimePaths;
+use super::WineTestCommand;
+use super::WineTestProcess;
+use super::install_powershell_runtime;
+
+async fn waiting_smoke_process() -> Result<WineTestProcess> {
+    let executable = codex_utils_cargo_bin::cargo_bin("wine-smoke")?;
+    let mut process = WineTestCommand::new(executable).arg("--wait").spawn()?;
+    let mut lines = BufReader::new(process.take_stdout()).lines();
+    let ready_line = lines
+        .next_line()
+        .await?
+        .context("Windows smoke process exited before becoming ready")?;
+    assert_eq!(ready_line, "WINE_TEST_READY");
+    Ok(process)
+}
+
+fn prefix_path(process: &WineTestProcess) -> PathBuf {
+    process
+        .processes
+        .as_ref()
+        .expect("Wine process guard")
+        .prefix
+        .path()
+        .to_path_buf()
+}
+
+fn assert_prefix_removed(prefix: &Path) {
+    assert!(
+        !prefix.exists(),
+        "Wine prefix remains: {}",
+        prefix.display()
+    );
+}
+
+fn assert_panic_message(panic: Box<dyn Any + Send>, expected: &str) {
+    assert_eq!(panic.downcast_ref::<&str>(), Some(&expected));
+}
+
+async fn assert_future_panics<T>(future: impl Future<Output = T>, expected: &str) {
+    let panic = match AssertUnwindSafe(future).catch_unwind().await {
+        Ok(_) => panic!("future should panic"),
+        Err(panic) => panic,
+    };
+    assert_panic_message(panic, expected);
+}
+
+async fn process_with_failing_wineserver_stop() -> Result<WineTestProcess> {
+    let mut process = waiting_smoke_process().await?;
+    let processes = process.processes.as_mut().expect("Wine process guard");
+
+    let mut command = TokioCommand::from(processes.stop_wineserver_command());
+    let status = command
+        .status()
+        .await
+        .context("pre-stop isolated wineserver")?;
+    assert!(status.success(), "wineserver exited with {status}");
+
+    processes.runtime.wineserver = processes.prefix.path().join("missing-wineserver");
+    Ok(process)
+}
+
+#[tokio::test]
+async fn dropping_without_teardown_panics() -> Result<()> {
+    let process = waiting_smoke_process().await?;
+    let prefix = prefix_path(&process);
+    assert_future_panics(
+        async move { drop(process) },
+        "WineTestProcess dropped without async teardown",
+    )
+    .await;
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[tokio::test]
+async fn dropping_while_panicking_does_not_panic_again() -> Result<()> {
+    let process = waiting_smoke_process().await?;
+    let prefix = prefix_path(&process);
+    assert_future_panics(
+        async move {
+            let _process = process;
+            panic!("sentinel panic");
+        },
+        "sentinel panic",
+    )
+    .await;
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[tokio::test]
+async fn async_teardown_disarms_drop_bomb() -> Result<()> {
+    let process = waiting_smoke_process().await?;
+    let prefix = prefix_path(&process);
+    process.shutdown().await?;
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[tokio::test]
+async fn take_stdout_panics_when_called_twice() -> Result<()> {
+    let mut process = waiting_smoke_process().await?;
+    let prefix = prefix_path(&process);
+    assert_future_panics(
+        async {
+            process.take_stdout();
+        },
+        "Wine process stdout has already been taken",
+    )
+    .await;
+    process.shutdown().await?;
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[tokio::test]
+async fn scope_returns_value_and_tears_down() -> Result<()> {
+    let process = waiting_smoke_process().await?;
+    let prefix = prefix_path(&process);
+    let value = process
+        .scope(async { Ok::<_, anyhow::Error>("scope value") })
+        .await?;
+    assert_eq!(value, "scope value");
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[tokio::test]
+async fn scope_returns_body_error_and_tears_down() -> Result<()> {
+    let process = waiting_smoke_process().await?;
+    let prefix = prefix_path(&process);
+
+    let error = process
+        .scope(async { Err::<(), _>(anyhow!("scope body failed")) })
+        .await
+        .expect_err("scope body should fail");
+
+    assert_eq!(error.to_string(), "scope body failed");
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[tokio::test]
+async fn scope_panic_preserves_panic_and_tears_down() -> Result<()> {
+    let process = waiting_smoke_process().await?;
+    let prefix = prefix_path(&process);
+
+    assert_future_panics(
+        process.scope::<()>(async { panic!("scope panic") }),
+        "scope panic",
+    )
+    .await;
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[tokio::test]
+async fn shutdown_reports_nonzero_process_exit() -> Result<()> {
+    let executable = codex_utils_cargo_bin::cargo_bin("wine-smoke")?;
+    let mut process = WineTestCommand::new(executable).arg("--fail").spawn()?;
+    let prefix = prefix_path(&process);
+    let status = process
+        .processes
+        .as_mut()
+        .expect("Wine process guard")
+        .child
+        .wait()
+        .await?;
+    assert!(
+        !status.success(),
+        "Windows smoke process unexpectedly passed"
+    );
+
+    let error = process.shutdown().await.expect_err("shutdown should fail");
+
+    assert!(error.to_string().starts_with("Windows process exited with"));
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[tokio::test]
+async fn scope_preserves_body_error_when_teardown_also_fails() -> Result<()> {
+    let process = process_with_failing_wineserver_stop().await?;
+    let prefix = prefix_path(&process);
+
+    let error = process
+        .scope(async { Err::<(), _>(anyhow!("scope body failed")) })
+        .await
+        .expect_err("scope body and teardown should fail");
+
+    assert!(
+        error
+            .to_string()
+            .starts_with("Wine teardown also failed: stop isolated wineserver"),
+        "unexpected error: {error:#}"
+    );
+    assert_eq!(
+        error.chain().last().map(ToString::to_string),
+        Some("scope body failed".to_string())
+    );
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[tokio::test]
+async fn shutdown_returns_teardown_error() -> Result<()> {
+    let process = process_with_failing_wineserver_stop().await?;
+    let prefix = prefix_path(&process);
+
+    let error = process
+        .shutdown()
+        .await
+        .expect_err("shutdown should report a wineserver failure");
+
+    assert_eq!(error.to_string(), "stop isolated wineserver");
+    assert_prefix_removed(&prefix);
+    Ok(())
+}
+
+#[test]
+fn powershell_runtime_is_materialized_at_the_windows_fallback_path() -> Result<()> {
+    let prefix = TempDir::new()?;
+    let runtime = TempDir::new()?;
+    fs::create_dir(runtime.path().join("Modules"))?;
+    fs::write(runtime.path().join("pwsh.exe"), b"pwsh")?;
+    fs::write(runtime.path().join("Modules").join("marker.txt"), b"module")?;
+
+    install_powershell_runtime(prefix.path(), runtime.path())?;
+
+    let installed = prefix
+        .path()
+        .join("drive_c")
+        .join("Program Files")
+        .join("PowerShell")
+        .join("7");
+    assert_eq!(fs::read(installed.join("pwsh.exe"))?, b"pwsh");
+    assert_eq!(
+        fs::read(installed.join("Modules").join("marker.txt"))?,
+        b"module"
+    );
+    Ok(())
+}
+
+#[test]
+fn powershell_runtime_follows_runfiles_symlinks() -> Result<()> {
+    let prefix = TempDir::new()?;
+    let runtime = TempDir::new()?;
+    let backing = TempDir::new()?;
+    let backing_file = backing.path().join("pwsh.exe");
+    fs::write(&backing_file, b"pwsh")?;
+    std::os::unix::fs::symlink(&backing_file, runtime.path().join("pwsh.exe"))?;
+
+    install_powershell_runtime(prefix.path(), runtime.path())?;
+
+    let installed = prefix
+        .path()
+        .join("drive_c")
+        .join("Program Files")
+        .join("PowerShell")
+        .join("7")
+        .join("pwsh.exe");
+    assert_eq!(fs::read(installed)?, b"pwsh");
+    Ok(())
+}
+
+#[tokio::test]
+async fn pinned_powershell_runs_under_wine_with_a_pty() -> Result<()> {
+    // Keep this integration smoke test local to the Wine support crate. The
+    // production-shaped PowerShell launch path belongs to exec-server tests.
+    // The marker makes the assertion resilient to Wine or PTY startup chatter.
+    const POWERSHELL_SMOKE_MARKER: &str = "WINE_PWSH_SMOKE";
+    // Besides proving that the pinned runtime starts, report the properties
+    // that shell detection and command construction rely on: PowerShell 7 Core
+    // running with Windows semantics and a backslash path separator.
+    const POWERSHELL_SMOKE_SCRIPT: &str = concat!(
+        "$ErrorActionPreference = 'Stop'; ",
+        "[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); ",
+        "$separatorCode = [int]([System.IO.Path]::DirectorySeparatorChar); ",
+        "if ($PSVersionTable.PSVersion.Major -ne 7) { throw 'expected PowerShell 7' }; ",
+        "if ($PSVersionTable.PSEdition -ne 'Core') { throw 'expected PowerShell Core' }; ",
+        "if (-not $IsWindows) { throw 'expected Windows semantics' }; ",
+        "if ($separatorCode -ne 92) { throw 'expected backslash path separator' }; ",
+        "Write-Output ('WINE_PWSH_SMOKE|' + ",
+        "$PSVersionTable.PSVersion.ToString() + '|' + ",
+        "$PSVersionTable.PSEdition + '|' + ",
+        "$IsWindows.ToString().ToLowerInvariant() + '|' + $separatorCode)",
+    );
+    let runtime = WineRuntimePaths::from_runfiles()?;
+    let prefix = TempDir::new()?;
+    install_powershell_runtime(prefix.path(), &runtime.powershell_runtime)?;
+    let mut env = std::env::vars().collect::<HashMap<_, _>>();
+    env.remove("DISPLAY");
+    env.extend([
+        (
+            "HOME".to_string(),
+            prefix.path().to_string_lossy().into_owned(),
+        ),
+        (
+            "XDG_RUNTIME_DIR".to_string(),
+            prefix.path().to_string_lossy().into_owned(),
+        ),
+        ("WINEARCH".to_string(), "win64".to_string()),
+        (
+            "WINEPREFIX".to_string(),
+            prefix.path().to_string_lossy().into_owned(),
+        ),
+        (
+            "WINEDLLPATH".to_string(),
+            runtime.dll_path.to_string_lossy().into_owned(),
+        ),
+        (
+            "WINESERVER".to_string(),
+            runtime.wineserver.to_string_lossy().into_owned(),
+        ),
+        ("WINEDEBUG".to_string(), "-all".to_string()),
+        (
+            "WINEDLLOVERRIDES".to_string(),
+            "mscoree,mshtml,winegstreamer=".to_string(),
+        ),
+        ("LANG".to_string(), "C.UTF-8".to_string()),
+        ("LC_ALL".to_string(), "C.UTF-8".to_string()),
+        ("LC_CTYPE".to_string(), "C.UTF-8".to_string()),
+        ("TEMP".to_string(), r"C:\windows\temp".to_string()),
+        ("TMP".to_string(), r"C:\windows\temp".to_string()),
+    ]);
+    let args = [
+        r"C:\Program Files\PowerShell\7\pwsh.exe".to_string(),
+        "-NoLogo".to_string(),
+        "-NoProfile".to_string(),
+        "-NonInteractive".to_string(),
+        "-Command".to_string(),
+        POWERSHELL_SMOKE_SCRIPT.to_string(),
+    ];
+    let wine = runtime.wine.to_string_lossy().into_owned();
+    let SpawnedProcess {
+        session,
+        mut stdout_rx,
+        mut stderr_rx,
+        exit_rx,
+    } = codex_utils_pty::spawn_pty_process(
+        &wine,
+        &args,
+        prefix.path(),
+        &env,
+        /*arg0*/ &None,
+        TerminalSize::default(),
+        /*inherited_fds*/ &[],
+    )
+    .await?;
+    let command_result = timeout(Duration::from_secs(30), async {
+        let stdout = async {
+            let mut output = Vec::new();
+            while let Some(chunk) = stdout_rx.recv().await {
+                output.extend(chunk);
+            }
+            output
+        };
+        let stderr = async {
+            let mut output = Vec::new();
+            while let Some(chunk) = stderr_rx.recv().await {
+                output.extend(chunk);
+            }
+            output
+        };
+        let (stdout, stderr, exit_code) = tokio::join!(stdout, stderr, exit_rx);
+        Ok::<_, anyhow::Error>((stdout, stderr, exit_code.context("wait for PowerShell")?))
+    })
+    .await
+    .context("PowerShell smoke test timed out")
+    .and_then(std::convert::identity);
+    drop(session);
+    let shutdown_result = timeout(Duration::from_secs(10), async {
+        let mut command = TokioCommand::new(&runtime.wineserver);
+        command
+            .args(["-k", "-w"])
+            .env("HOME", prefix.path())
+            .env("WINEPREFIX", prefix.path())
+            .env("XDG_RUNTIME_DIR", prefix.path())
+            .kill_on_drop(true);
+        let status = command.status().await.context("stop isolated wineserver")?;
+        anyhow::ensure!(
+            status.success() || status.code() == Some(1),
+            "wineserver exited with {status}"
+        );
+        Ok::<_, anyhow::Error>(())
+    })
+    .await
+    .context("stop isolated wineserver timed out")
+    .and_then(std::convert::identity);
+    let (stdout, stderr, exit_code) = match (command_result, shutdown_result) {
+        (Ok(output), Ok(())) => output,
+        (Err(error), Ok(())) => return Err(error),
+        (Ok(_), Err(error)) => return Err(error),
+        (Err(error), Err(shutdown_error)) => {
+            return Err(error.context(format!("Wine teardown also failed: {shutdown_error:#}")));
+        }
+    };
+    anyhow::ensure!(
+        exit_code == 0,
+        "PowerShell exited with {}; stderr: {}",
+        exit_code,
+        String::from_utf8_lossy(&stderr),
+    );
+    let output = String::from_utf8(stdout)?;
+    let marker_start = output
+        .find(POWERSHELL_SMOKE_MARKER)
+        .with_context(|| format!("PowerShell smoke marker was missing from {output:?}"))?;
+    let smoke = output[marker_start..]
+        .lines()
+        .next()
+        .context("PowerShell smoke marker line was incomplete")?
+        .trim_end_matches('\r');
+    let fields = smoke.split('|').collect::<Vec<_>>();
+    assert_eq!(
+        fields.len(),
+        5,
+        "unexpected PowerShell smoke output: {smoke}"
+    );
+    assert_eq!(fields[0], POWERSHELL_SMOKE_MARKER);
+    assert_eq!(
+        fields[1].split('.').next(),
+        Some("7"),
+        "expected PowerShell 7.x, got {}",
+        fields[1],
+    );
+    assert_eq!(&fields[2..], &["Core", "true", "92"]);
+    Ok(())
+}

bazel/rules/testing/wine/wine.bzl

@@ -0,0 +1,69 @@
+"""Macros for cross-building Windows Rust binaries and testing them with Wine."""
+
+load("@rules_rust//rust:defs.bzl", "rust_test")
+load("//:defs.bzl", "WINDOWS_GNULLVM_RUSTC_LINK_FLAGS")
+load("//bazel/rules/testing:foreign_platform_binary.bzl", "foreign_platform_binary")
+load(":wine_runtime.bzl", "WINE_TEST_TARGET_COMPATIBLE_WITH", "wine_test_runtime")
+
+def wine_rust_test(
+        name,
+        windows_binaries,
+        host_binaries = {},
+        data = [],
+        target_compatible_with = [],
+        **kwargs):
+    """Defines an x86-64 Linux Rust test with a pinned Wine runtime.
+
+    Each `windows_binaries` executable is transitioned to GNU/LLVM Windows;
+    every Rust dependency receives the repository's Windows linker flags while
+    the test stays on x86-64 Linux. Its environment-variable contract is:
+
+    * Each `host_binaries` and `windows_binaries` entry contributes
+      `CARGO_BIN_EXE_<binary_name>` for its executable.
+    * `CARGO_BIN_EXE_wine` and `CARGO_BIN_EXE_wineserver` identify Wine tools.
+    * `CARGO_BIN_EXE_wine-runtime-marker` identifies a file whose parent is the
+      Wine DLL directory to use as `WINEDLLPATH`.
+    * `CARGO_BIN_EXE_pwsh` identifies the pinned PowerShell executable and
+      `CARGO_BIN_EXE_pwsh-runtime-marker` identifies a file whose parent is the
+      complete PowerShell runtime.
+
+    These are Bazel runfile locations. Resolve binaries with
+    `codex_utils_cargo_bin::cargo_bin`; `:wine_test_support` resolves the fixed
+    runtime names and starts each process in an isolated prefix.
+
+    Args:
+      name: Name of the generated Linux `rust_test`.
+      windows_binaries: Map from `CARGO_BIN_EXE_*` suffixes to Windows targets.
+      host_binaries: Map from `CARGO_BIN_EXE_*` suffixes to Linux host targets.
+      data: Additional runtime data for the Linux test.
+      target_compatible_with: Additional compatibility constraints.
+      **kwargs: Remaining attributes forwarded to `rust_test`.
+    """
+    binaries = dict(host_binaries)
+    for index, binary_name in enumerate(sorted(windows_binaries.keys())):
+        if binary_name in binaries:
+            fail("Windows test binary name collides with host binary: {}".format(binary_name))
+        transitioned_binary = name + "-windows-binary-" + str(index)
+        foreign_platform_binary(
+            name = transitioned_binary,
+            binary = windows_binaries[binary_name],
+            extra_rustc_flags = WINDOWS_GNULLVM_RUSTC_LINK_FLAGS,
+            platform = "//:windows_x86_64_gnullvm",
+            tags = ["manual"],
+            target_compatible_with = [
+                "@platforms//cpu:x86_64",
+                "@platforms//os:linux",
+            ],
+            testonly = True,
+            visibility = ["//visibility:private"],
+        )
+        binaries[binary_name] = ":" + transitioned_binary
+
+    runtime = wine_test_runtime(binaries)
+    rust_test(
+        name = name,
+        data = data + runtime.data,
+        env = runtime.env,
+        target_compatible_with = target_compatible_with + WINE_TEST_TARGET_COMPATIBLE_WITH,
+        **kwargs
+    )

bazel/rules/testing/wine/wine_runtime.bzl

@@ -0,0 +1,40 @@
+"""Runfiles shared by tests that execute Windows binaries through Wine."""
+
+_WINE_RUNTIME_BINARIES = {
+    "pwsh": "@powershell_windows_x86_64//:pwsh",
+    "pwsh-runtime-marker": "@powershell_windows_x86_64//:runtime_marker",
+    "wine": "@wine_linux_x86_64//:wine",
+    "wine-runtime-marker": "@wine_linux_x86_64//:runtime_marker",
+    "wineserver": "@wine_linux_x86_64//:wineserver",
+}
+
+_WINE_RUNTIME_DATA = [
+    "@powershell_windows_x86_64//:runtime",
+    "@wine_linux_x86_64//:runtime",
+]
+
+WINE_TEST_TARGET_COMPATIBLE_WITH = [
+    "@llvm//constraints/libc:gnu.2.28",
+    "@platforms//cpu:x86_64",
+    "@platforms//os:linux",
+]
+
+def wine_test_runtime(test_binaries = {}):
+    """Returns data and environment mappings for a Wine-backed test."""
+    binaries = dict(_WINE_RUNTIME_BINARIES)
+    for binary_name in sorted(test_binaries.keys()):
+        if binary_name in binaries:
+            fail("test binary name collides with Wine runtime: {}".format(binary_name))
+        binaries[binary_name] = test_binaries[binary_name]
+
+    return struct(
+        data = _WINE_RUNTIME_DATA + [binary for binary in binaries.values()],
+        env = {
+            "CARGO_BIN_EXE_{}".format(binary_name): "$(rlocationpath {})".format(binary)
+            for binary_name, binary in binaries.items()
+        },
+        runfile_env = {
+            binary_label: "CARGO_BIN_EXE_" + binary_name
+            for binary_name, binary_label in binaries.items()
+        },
+    )

bazel/schema/BUILD.bazel

@@ -0,0 +1,8 @@
+load("//bazel/rules:schema_bundle.bzl", "schema_bundle")
+
+schema_bundle(
+    name = "public-schema-bundle",
+    testonly = True,
+    generator = "//codex-rs/app-server-protocol:schema-generator",
+    tags = ["manual"],
+)

bazel/toolchains/prost/BUILD.bazel

@@ -0,0 +1,35 @@
+load("@rules_rust//extensions/prost:defs.bzl", "rust_prost_toolchain")
+load("@rules_rust//rust:defs.bzl", "rust_library_group")
+
+package(default_visibility = ["//visibility:public"])
+
+rust_library_group(
+    name = "prost_runtime",
+    deps = ["@crates//:prost"],
+)
+
+rust_library_group(
+    name = "tonic_runtime",
+    deps = [
+        ":prost_runtime",
+        "@crates//:tonic",
+        "@crates//:tonic-prost",
+    ],
+)
+
+rust_prost_toolchain(
+    name = "toolchain_impl",
+    compile_well_known_types = False,
+    prost_plugin = "@rules_rs//rs/private/prost:protoc-gen-prost__protoc-gen-prost",
+    prost_runtime = ":prost_runtime",
+    prost_types = "@crates//:prost-types-0.14.3",
+    tonic_plugin = "@rules_rs//rs/private/prost:protoc-gen-tonic__protoc-gen-tonic",
+    tonic_plugin_flag = "--plugin=protoc-gen-tonic=%s",
+    tonic_runtime = ":tonic_runtime",
+)
+
+toolchain(
+    name = "toolchain",
+    toolchain = ":toolchain_impl",
+    toolchain_type = "@rules_rust//extensions/prost:toolchain_type",
+)

scripts/build_codex_package.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Build a canonical Codex package directory and optional archive."""
+
+from pathlib import Path
+import sys
+
+
+# Some developer environments set PYTHONSAFEPATH=1, which prevents Python from
+# adding the script directory to sys.path. Add it explicitly so the local helper
+# package remains importable when this executable is launched from any cwd.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from codex_package.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/build_winget_package.py

@@ -0,0 +1,37 @@
+"""Adapt an extracted signed Windows package to WinGet's existing root filenames."""
+
+import argparse
+import json
+import shutil
+from pathlib import Path
+
+
+def prepare_winget_package(package: Path) -> None:
+    metadata_path = package / "codex-package.json"
+    metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+    target = metadata["target"]
+    if target not in ("x86_64-pc-windows-msvc", "aarch64-pc-windows-msvc"):
+        raise ValueError("WinGet requires a Windows package")
+    if metadata["entrypoint"] != "bin/codex.exe":
+        raise ValueError("WinGet requires the canonical Codex entrypoint")
+    entrypoint = f"codex-{target}.exe"
+    manifest_path = package / "codex-resources/voice/manifest.json"
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    manifest["sha256"][entrypoint] = manifest["sha256"].pop("bin/codex.exe")
+    (package / "bin/codex.exe").rename(package / entrypoint)
+    (package / "bin/codex-code-mode-host.exe").rename(
+        package / "codex-code-mode-host.exe"
+    )
+    # Keep resources in place for package-aware discovery and provide the root
+    # filenames declared by the existing WinGet portable installer manifest.
+    for helper in ("codex-command-runner.exe", "codex-windows-sandbox-setup.exe"):
+        shutil.copy2(package / "codex-resources" / helper, package / helper)
+    metadata["entrypoint"] = entrypoint
+    for path, value in ((metadata_path, metadata), (manifest_path, manifest)):
+        path.write_text(json.dumps(value, indent=2) + "\n", encoding="utf-8")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("package", type=Path)
+    prepare_winget_package(parser.parse_args().package)

scripts/check-module-bazel-lock.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+if ! "${repo_root}/.github/scripts/run_bazel_with_buildbuddy.py" mod deps --lockfile_mode=error; then
+  echo "MODULE.bazel.lock is out of date."
+  echo "Run 'just bazel-lock-update' and commit the updated lockfile."
+  exit 1
+fi

scripts/codex_package/README.md

@@ -0,0 +1,92 @@
+# Codex package builder
+
+This package contains the implementation behind `scripts/build_codex_package.py`.
+The top-level script is the stable executable entry point; these modules keep the
+package-building logic split by responsibility.
+
+Run the builder through `just`:
+
+```bash
+just assemble-codex-package --help
+just assemble-codex-package --variant codex-app-server
+just assemble-codex-package --target x86_64-unknown-linux-gnu
+```
+
+The builder creates a canonical Codex package directory:
+
+```text
+.
+├── codex-package.json
+├── bin
+│   ├── <entrypoint>[.exe]
+│   └── codex-code-mode-host[.exe]
+├── codex-resources
+│   ├── bwrap                             # Linux only
+│   ├── zsh/bin/zsh                       # supported Unix targets only
+│   ├── codex-command-runner.exe          # Windows only
+│   └── codex-windows-sandbox-setup.exe   # Windows only
+└── codex-path
+    └── rg[.exe]
+```
+
+The package directory is the primary artifact. Archive formats such as
+`.tar.gz`, `.tar.zst`, and `.zip` are serializations of that directory.
+
+If `--target` is omitted, the builder uses the release target for the current
+host platform. On Linux, that default is a musl target to match Codex release
+artifacts; pass a GNU Linux target explicitly for native glibc local builds. If
+`--package-dir` is omitted, the builder creates a new temporary directory and
+prints its path after the package is built.
+
+The `--variant` flag selects the package entrypoint. Supported variants are
+`codex` and `codex-app-server`. The `--package-version` flag sets the version in
+`codex-package.json`; it defaults to `[workspace.package].version` in
+`codex-rs/Cargo.toml`.
+
+## Source-built artifacts
+
+Artifacts built from this repository are built by the package builder in one
+grouped `cargo build` command per package when they are needed and no prebuilt
+override was provided:
+
+- all targets: the selected entrypoint, unless `--entrypoint-bin` is provided
+- all targets: `codex-code-mode-host`, unless `--code-mode-host-bin` is provided
+- Linux targets: `bwrap`, unless `--bwrap-bin` is provided
+- Windows targets: `codex-command-runner` and `codex-windows-sandbox-setup`,
+  unless the corresponding prebuilt helper flags are provided
+
+The default cargo profile is `dev-small` because local iteration should favor
+fast, small builds. Release jobs should pass `--cargo-profile release` and an
+explicit target. Release jobs that already built and signed/notarized the
+entrypoint should pass `--entrypoint-bin` so the package contains that exact
+binary instead of rebuilding it.
+
+Release jobs should likewise pass `--code-mode-host-bin` so the package contains
+the signed host executable beside the signed entrypoint.
+
+Release jobs that already built package resource binaries should also pass the
+corresponding resource flags: `--bwrap-bin` for Linux packages, and
+`--codex-command-runner-bin` plus `--codex-windows-sandbox-setup-bin` for
+Windows packages. This keeps package archive creation as a pure staging step
+after signing instead of rebuilding resources.
+
+When the builder source-builds an entrypoint for a Darwin or Linux target, it
+downloads and verifies the matching Codex-built V8 release pair before invoking
+Cargo and sets `RUSTY_V8_ARCHIVE` plus `RUSTY_V8_SRC_BINDING_PATH` for that
+build. Windows targets keep Cargo's release-build MSVC artifact path. Explicit
+overrides remain authoritative when both variables are already set. Set
+`V8_FROM_SOURCE=1` to leave the build with the `v8` crate source-build path.
+
+`rg` is not built from this repository, so the builder fetches it from the
+DotSlash manifest at `scripts/codex_package/rg`. Downloaded archives are cached
+under `$TMPDIR/codex-package/<target>-rg` and are reused only after the recorded
+size and SHA-256 digest have been verified. Pass `--rg-bin` to use a local
+ripgrep executable instead.
+
+The patched zsh fork used by `shell_zsh_fork` is fetched from the DotSlash
+manifest at `scripts/codex_package/codex-zsh` when the selected target has a
+matching prebuilt artifact. Downloaded archives are cached under
+`$TMPDIR/codex-package/<target>-zsh` and installed at
+`codex-resources/zsh/bin/zsh`. Pass `--zsh-bin` to package a prebuilt, signed
+executable, or `--zsh-manifest` to use a different DotSlash manifest, such as
+the manifest published with a standalone zsh artifact release.

scripts/codex_package/__init__.py

@@ -0,0 +1 @@
+"""Helpers for building canonical Codex package archives."""

scripts/codex_package/archive.py

@@ -0,0 +1,118 @@
+"""Archive writers for canonical Codex package directories."""
+
+import shutil
+import subprocess
+import tarfile
+import tempfile
+import zipfile
+from collections.abc import Callable
+from pathlib import Path
+
+from .targets import REPO_ROOT
+
+
+ZSTD_DOTSLASH = REPO_ROOT / ".github" / "workflows" / "zstd"
+
+
+def write_archive(package_dir: Path, archive_path: Path, *, force: bool) -> None:
+    if is_relative_to(archive_path, package_dir):
+        raise RuntimeError(
+            f"Archive output must be outside the package directory: {archive_path}"
+        )
+
+    archive_path.parent.mkdir(parents=True, exist_ok=True)
+    if archive_path.exists():
+        if not force:
+            raise RuntimeError(f"Archive output already exists: {archive_path}")
+        archive_path.unlink()
+
+    archive_format = archive_format_for_path(archive_path)
+    if archive_format == "tar.gz":
+        write_tar_archive(package_dir, archive_path, mode="w:gz")
+    elif archive_format == "tar.zst":
+        write_tar_zst_archive(package_dir, archive_path)
+    elif archive_format == "zip":
+        write_zip_archive(package_dir, archive_path)
+    else:
+        raise AssertionError(f"unexpected archive format: {archive_format}")
+
+
+def is_relative_to(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+
+
+def archive_format_for_path(path: Path) -> str:
+    suffixes = path.suffixes
+    if suffixes[-2:] == [".tar", ".gz"] or path.suffix == ".tgz":
+        return "tar.gz"
+    if suffixes[-2:] == [".tar", ".zst"]:
+        return "tar.zst"
+    if path.suffix == ".zip":
+        return "zip"
+    raise RuntimeError(
+        f"Unsupported archive suffix for {path}. Use .tar.gz, .tgz, .tar.zst, or .zip."
+    )
+
+
+def write_tar_archive(package_dir: Path, archive_path: Path, *, mode: str) -> None:
+    options = {"compresslevel": 6} if mode == "w:gz" else {}
+    with tarfile.open(archive_path, mode, **options) as archive:
+        for path in package_entries(package_dir):
+            archive.add(
+                path,
+                arcname=path.relative_to(package_dir),
+                recursive=False,
+            )
+
+
+def write_tar_zst_archive(package_dir: Path, archive_path: Path) -> None:
+    zstd_command = resolve_zstd_command()
+
+    with tempfile.TemporaryDirectory(prefix="codex-package-archive-") as temp_dir_str:
+        tar_path = Path(temp_dir_str) / "package.tar"
+        write_tar_archive(package_dir, tar_path, mode="w")
+        subprocess.check_call(
+            [*zstd_command, "-T0", "-19", "-f", str(tar_path), "-o", str(archive_path)]
+        )
+
+
+def resolve_zstd_command(
+    *,
+    dotslash_manifest: Path = ZSTD_DOTSLASH,
+    which: Callable[[str], str | None] = shutil.which,
+) -> list[str]:
+    zstd = which("zstd")
+    if zstd is not None:
+        return [zstd]
+
+    dotslash = which("dotslash")
+    if dotslash is not None and dotslash_manifest.is_file():
+        return [dotslash, str(dotslash_manifest)]
+
+    raise RuntimeError(
+        "zstd is required to write .tar.zst archives. Install zstd, or install "
+        f"DotSlash so the repository wrapper can run: {dotslash_manifest}"
+    )
+
+
+def write_zip_archive(package_dir: Path, archive_path: Path) -> None:
+    with zipfile.ZipFile(
+        archive_path, "w", compression=zipfile.ZIP_DEFLATED
+    ) as archive:
+        for path in package_entries(package_dir):
+            relative_path = path.relative_to(package_dir)
+            if path.is_dir():
+                archive.write(path, f"{relative_path}/")
+            else:
+                archive.write(path, relative_path)
+
+
+def package_entries(package_dir: Path) -> list[Path]:
+    return sorted(
+        package_dir.rglob("*"),
+        key=lambda path: path.relative_to(package_dir).as_posix(),
+    )

scripts/codex_package/cargo.py

@@ -0,0 +1,194 @@
+"""Cargo builds for source-built Codex package artifacts."""
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .targets import REPO_ROOT
+from .targets import PackageVariant
+from .targets import TargetSpec
+from .v8 import resolve_codex_v8_cargo_env
+
+
+CODEX_RS_ROOT = REPO_ROOT / "codex-rs"
+
+
+@dataclass(frozen=True)
+class SourceBuildOutputs:
+    entrypoint_bin: Path
+    code_mode_host_bin: Path
+    bwrap_bin: Path | None
+    codex_command_runner_bin: Path | None
+    codex_windows_sandbox_setup_bin: Path | None
+
+
+def build_source_binaries(
+    spec: TargetSpec,
+    variant: PackageVariant,
+    *,
+    cargo: str,
+    profile: str,
+    entrypoint_bin: Path | None,
+    code_mode_host_bin: Path | None,
+    bwrap_bin: Path | None,
+    codex_command_runner_bin: Path | None,
+    codex_windows_sandbox_setup_bin: Path | None,
+) -> SourceBuildOutputs:
+    validate_prebuilt_resource_inputs(
+        spec,
+        bwrap_bin=bwrap_bin,
+        codex_command_runner_bin=codex_command_runner_bin,
+        codex_windows_sandbox_setup_bin=codex_windows_sandbox_setup_bin,
+    )
+    binaries = source_binaries_for_target(
+        spec,
+        variant,
+        build_entrypoint=entrypoint_bin is None,
+        build_code_mode_host=code_mode_host_bin is None,
+        build_bwrap=spec.is_linux and bwrap_bin is None,
+        build_codex_command_runner=spec.is_windows and codex_command_runner_bin is None,
+        build_codex_windows_sandbox_setup=spec.is_windows
+        and codex_windows_sandbox_setup_bin is None,
+    )
+    if binaries:
+        cmd = [
+            cargo,
+            "build",
+            "--target",
+            spec.target,
+            "--profile",
+            profile,
+        ]
+        for binary in binaries:
+            cmd.extend(["--bin", binary])
+
+        cargo_env = None
+        if entrypoint_bin is None or code_mode_host_bin is None:
+            codex_v8_env = resolve_codex_v8_cargo_env(spec)
+            if codex_v8_env:
+                cargo_env = {**os.environ, **codex_v8_env}
+
+        print("+", " ".join(cmd))
+        subprocess.run(
+            cmd,
+            cwd=CODEX_RS_ROOT,
+            check=True,
+            env=cargo_env,
+        )
+
+    output_dir = cargo_profile_output_dir(spec, profile)
+    outputs = SourceBuildOutputs(
+        entrypoint_bin=resolve_output_path(
+            entrypoint_bin,
+            output_dir / variant.entrypoint_name(spec),
+        ),
+        code_mode_host_bin=(
+            code_mode_host_bin.resolve()
+            if code_mode_host_bin is not None
+            else output_dir / f"codex-code-mode-host{spec.exe_suffix}"
+        ),
+        bwrap_bin=resolve_output_path(
+            bwrap_bin,
+            output_dir / "bwrap" if spec.is_linux else None,
+        ),
+        codex_command_runner_bin=resolve_output_path(
+            codex_command_runner_bin,
+            output_dir / "codex-command-runner.exe" if spec.is_windows else None,
+        ),
+        codex_windows_sandbox_setup_bin=resolve_output_path(
+            codex_windows_sandbox_setup_bin,
+            output_dir / "codex-windows-sandbox-setup.exe" if spec.is_windows else None,
+        ),
+    )
+    validate_source_outputs(outputs)
+    return outputs
+
+
+def source_binaries_for_target(
+    spec: TargetSpec,
+    variant: PackageVariant,
+    *,
+    build_entrypoint: bool,
+    build_code_mode_host: bool,
+    build_bwrap: bool,
+    build_codex_command_runner: bool,
+    build_codex_windows_sandbox_setup: bool,
+) -> list[str]:
+    binaries = []
+    if build_entrypoint:
+        binaries.append(variant.cargo_bin)
+    if build_code_mode_host:
+        binaries.append("codex-code-mode-host")
+    if build_bwrap:
+        binaries.append("bwrap")
+    if build_codex_command_runner:
+        binaries.append("codex-command-runner")
+    if build_codex_windows_sandbox_setup:
+        binaries.append("codex-windows-sandbox-setup")
+    return binaries
+
+
+def validate_prebuilt_resource_inputs(
+    spec: TargetSpec,
+    *,
+    bwrap_bin: Path | None,
+    codex_command_runner_bin: Path | None,
+    codex_windows_sandbox_setup_bin: Path | None,
+) -> None:
+    if bwrap_bin is not None and not spec.is_linux:
+        raise RuntimeError("--bwrap-bin is only supported for Linux targets.")
+    if codex_command_runner_bin is not None and not spec.is_windows:
+        raise RuntimeError(
+            "--codex-command-runner-bin is only supported for Windows targets."
+        )
+    if codex_windows_sandbox_setup_bin is not None and not spec.is_windows:
+        raise RuntimeError(
+            "--codex-windows-sandbox-setup-bin is only supported for Windows targets."
+        )
+
+
+def resolve_output_path(
+    explicit_path: Path | None, default_path: Path | None
+) -> Path | None:
+    if explicit_path is not None:
+        return explicit_path.resolve()
+
+    return default_path
+
+
+def cargo_profile_output_dir(spec: TargetSpec, profile: str) -> Path:
+    target_dir = cargo_target_dir()
+    return target_dir / spec.target / cargo_profile_dirname(profile)
+
+
+def cargo_target_dir() -> Path:
+    target_dir = os.environ.get("CARGO_TARGET_DIR")
+    if target_dir is None:
+        return CODEX_RS_ROOT / "target"
+
+    path = Path(target_dir)
+    if path.is_absolute():
+        return path
+
+    return CODEX_RS_ROOT / path
+
+
+def cargo_profile_dirname(profile: str) -> str:
+    if profile == "dev":
+        return "debug"
+    if profile == "release":
+        return "release"
+    return profile
+
+
+def validate_source_outputs(outputs: SourceBuildOutputs) -> None:
+    for path in [
+        outputs.entrypoint_bin,
+        outputs.code_mode_host_bin,
+        outputs.bwrap_bin,
+        outputs.codex_command_runner_bin,
+        outputs.codex_windows_sandbox_setup_bin,
+    ]:
+        if path is not None and not path.is_file():
+            raise RuntimeError(f"cargo build did not produce expected binary: {path}")

scripts/codex_package/cli.py

@@ -0,0 +1,249 @@
+"""Command-line interface for building Codex package directories."""
+
+import argparse
+import re
+import tempfile
+from pathlib import Path
+
+from .archive import write_archive
+from .cargo import build_source_binaries
+from .layout import build_package_dir
+from .layout import prepare_package_dir
+from .layout import validate_package_dir
+from .ripgrep import resolve_rg_bin
+from .targets import PACKAGE_VARIANTS
+from .targets import TARGET_SPECS
+from .targets import PackageInputs
+from .targets import default_target
+from .targets import resolve_input_path
+from .zsh import resolve_zsh_bin
+from .version import read_workspace_version
+
+
+# Release pipelines run this builder with system Python, so avoid new dependencies.
+SEMVER_PATTERN = re.compile(
+    r"(?P<major>0|[1-9][0-9]*)\."
+    r"(?P<minor>0|[1-9][0-9]*)\."
+    r"(?P<patch>0|[1-9][0-9]*)"
+    r"(?:-(?P<prerelease>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?"
+    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?"
+)
+
+
+def parse_package_version(value: str) -> str:
+    match = SEMVER_PATTERN.fullmatch(value)
+    if match is not None:
+        components = (match.group(name) for name in ("major", "minor", "patch"))
+        prerelease = match.group("prerelease") or ""
+        if all(int(component) <= 2**64 - 1 for component in components) and all(
+            not (part.isdigit() and len(part) > 1 and part.startswith("0"))
+            for part in prerelease.split(".")
+        ):
+            return value
+
+    raise argparse.ArgumentTypeError(f"invalid semantic version: {value!r}")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build a canonical Codex package directory and optional archive.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--target",
+        default=argparse.SUPPRESS,
+        choices=sorted(TARGET_SPECS),
+        help=(
+            "Rust target triple for the package. Defaults to the release target "
+            "for this host platform."
+        ),
+    )
+    parser.add_argument(
+        "--variant",
+        choices=sorted(PACKAGE_VARIANTS),
+        default="codex",
+        help="Package variant to build.",
+    )
+    parser.add_argument(
+        "--package-version",
+        type=parse_package_version,
+        default=read_workspace_version(),
+        help="Semantic version to record in codex-package.json.",
+    )
+    parser.add_argument(
+        "--package-dir",
+        type=Path,
+        default=argparse.SUPPRESS,
+        help=(
+            "Output directory to create as the package root. Defaults to a new temporary directory."
+        ),
+    )
+    parser.add_argument(
+        "--archive-output",
+        type=Path,
+        action="append",
+        default=[],
+        help=(
+            "Optional archive output path. May be repeated. Supported suffixes: "
+            ".tar.gz, .tgz, .tar.zst, .zip."
+        ),
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace an existing package directory or archive output.",
+    )
+    parser.add_argument(
+        "--cargo",
+        default="cargo",
+        help="Cargo executable to use for source-built package artifacts.",
+    )
+    parser.add_argument(
+        "--cargo-profile",
+        default="dev-small",
+        help=(
+            "Cargo profile for source-built package artifacts. Use release for release packages."
+        ),
+    )
+    parser.add_argument(
+        "--entrypoint-bin",
+        type=Path,
+        help=(
+            "Optional prebuilt entrypoint executable for the selected package "
+            "variant. If omitted, the entrypoint is built with Cargo."
+        ),
+    )
+    parser.add_argument(
+        "--code-mode-host-bin",
+        type=Path,
+        help=(
+            "Optional prebuilt codex-code-mode-host executable. If omitted, "
+            "the host is built with Cargo."
+        ),
+    )
+    parser.add_argument(
+        "--bwrap-bin",
+        type=Path,
+        help=(
+            "Optional prebuilt Linux bwrap executable. If omitted for Linux "
+            "targets, bwrap is built with Cargo."
+        ),
+    )
+    zsh_source = parser.add_mutually_exclusive_group()
+    zsh_source.add_argument(
+        "--zsh-manifest",
+        type=Path,
+        help=(
+            "Optional DotSlash manifest for the patched zsh fork instead of "
+            "scripts/codex_package/codex-zsh."
+        ),
+    )
+    zsh_source.add_argument(
+        "--zsh-bin",
+        type=Path,
+        help="Optional prebuilt zsh executable instead of fetching from a manifest.",
+    )
+    parser.add_argument(
+        "--codex-command-runner-bin",
+        type=Path,
+        help=(
+            "Optional prebuilt Windows codex-command-runner.exe executable. "
+            "If omitted for Windows targets, codex-command-runner is built "
+            "with Cargo."
+        ),
+    )
+    parser.add_argument(
+        "--codex-windows-sandbox-setup-bin",
+        type=Path,
+        help=(
+            "Optional prebuilt Windows codex-windows-sandbox-setup.exe "
+            "executable. If omitted for Windows targets, "
+            "codex-windows-sandbox-setup is built with Cargo."
+        ),
+    )
+    parser.add_argument(
+        "--rg-bin",
+        type=Path,
+        help=(
+            "Optional local ripgrep executable override instead of fetching from "
+            "scripts/codex_package/rg."
+        ),
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    spec = TARGET_SPECS[getattr(args, "target", None) or default_target()]
+    variant = PACKAGE_VARIANTS[args.variant]
+    package_dir_arg = getattr(args, "package_dir", None)
+    package_dir = (
+        package_dir_arg.resolve()
+        if package_dir_arg is not None
+        else Path(tempfile.mkdtemp(prefix="codex-package-")).resolve()
+    )
+
+    source_outputs = build_source_binaries(
+        spec,
+        variant,
+        cargo=args.cargo,
+        profile=args.cargo_profile,
+        entrypoint_bin=resolve_optional_input_path(
+            args.entrypoint_bin,
+            "prebuilt entrypoint executable",
+            "--entrypoint-bin",
+        ),
+        code_mode_host_bin=resolve_optional_input_path(
+            args.code_mode_host_bin,
+            "prebuilt code-mode host executable",
+            "--code-mode-host-bin",
+        ),
+        bwrap_bin=resolve_optional_input_path(
+            args.bwrap_bin,
+            "prebuilt Linux bwrap executable",
+            "--bwrap-bin",
+        ),
+        codex_command_runner_bin=resolve_optional_input_path(
+            args.codex_command_runner_bin,
+            "prebuilt Windows codex-command-runner.exe executable",
+            "--codex-command-runner-bin",
+        ),
+        codex_windows_sandbox_setup_bin=resolve_optional_input_path(
+            args.codex_windows_sandbox_setup_bin,
+            "prebuilt Windows codex-windows-sandbox-setup.exe executable",
+            "--codex-windows-sandbox-setup-bin",
+        ),
+    )
+    inputs = PackageInputs(
+        entrypoint_bin=source_outputs.entrypoint_bin,
+        code_mode_host_bin=source_outputs.code_mode_host_bin,
+        rg_bin=resolve_rg_bin(spec, args.rg_bin),
+        zsh_bin=resolve_zsh_bin(spec, args.zsh_manifest, zsh_bin=args.zsh_bin),
+        bwrap_bin=source_outputs.bwrap_bin,
+        codex_command_runner_bin=source_outputs.codex_command_runner_bin,
+        codex_windows_sandbox_setup_bin=source_outputs.codex_windows_sandbox_setup_bin,
+    )
+    prepare_package_dir(package_dir, force=args.force)
+    build_package_dir(package_dir, args.package_version, variant, spec, inputs)
+    validate_package_dir(
+        package_dir, variant, spec, include_zsh=inputs.zsh_bin is not None
+    )
+
+    for archive_output in args.archive_output:
+        archive_path = archive_output.resolve()
+        write_archive(package_dir, archive_path, force=args.force)
+        print(f"Built Codex package archive at {archive_path}")
+
+    print(f"Built Codex package directory at {package_dir}")
+    return 0
+
+
+def resolve_optional_input_path(
+    explicit_path: Path | None,
+    description: str,
+    flag_name: str,
+) -> Path | None:
+    if explicit_path is None:
+        return None
+
+    return resolve_input_path(explicit_path, description, flag_name)

scripts/codex_package/codex-zsh

@@ -0,0 +1,55 @@
+#!/usr/bin/env dotslash
+
+{
+  "name": "codex-zsh",
+  "platforms": {
+    "macos-aarch64": {
+      "size": 358776,
+      "hash": "sha256",
+      "digest": "49dec9832379688c9090666694a3449502ac5ebd4d76b9ffde1d0999cd088205",
+      "format": "tar.gz",
+      "path": "codex-zsh/bin/zsh",
+      "providers": [
+        {
+          "url": "https://github.com/openai/codex/releases/download/rust-v0.134.0-alpha.3/codex-zsh-aarch64-apple-darwin.tar.gz"
+        }
+      ]
+    },
+    "macos-x86_64": {
+      "size": 391161,
+      "hash": "sha256",
+      "digest": "0246fd4703bb540ae74f13ec739ca365ebd607df44a1f21e335eb7a421352923",
+      "format": "tar.gz",
+      "path": "codex-zsh/bin/zsh",
+      "providers": [
+        {
+          "url": "https://github.com/openai/codex/releases/download/rust-v0.134.0-alpha.3/codex-zsh-x86_64-apple-darwin.tar.gz"
+        }
+      ]
+    },
+    "linux-x86_64": {
+      "size": 433412,
+      "hash": "sha256",
+      "digest": "e7f760998c9644448d2cb8a821084a0134d6820c14b284bd7f39d7f32262ad40",
+      "format": "tar.gz",
+      "path": "codex-zsh/bin/zsh",
+      "providers": [
+        {
+          "url": "https://github.com/openai/codex/releases/download/rust-v0.134.0-alpha.3/codex-zsh-x86_64-unknown-linux-musl.tar.gz"
+        }
+      ]
+    },
+    "linux-aarch64": {
+      "size": 411655,
+      "hash": "sha256",
+      "digest": "8d50cff5dfabc97e37e1138513da022d9247a802c2ff996ab91654bf1892c7d5",
+      "format": "tar.gz",
+      "path": "codex-zsh/bin/zsh",
+      "providers": [
+        {
+          "url": "https://github.com/openai/codex/releases/download/rust-v0.134.0-alpha.3/codex-zsh-aarch64-unknown-linux-musl.tar.gz"
+        }
+      ]
+    }
+  }
+}

scripts/codex_package/dotslash.py

@@ -0,0 +1,222 @@
+"""Fetch executable artifacts from checked-in DotSlash manifests."""
+
+import hashlib
+import json
+import shutil
+import stat
+import tarfile
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+from .targets import TargetSpec
+
+
+DOWNLOAD_TIMEOUT_SECS = 60
+
+
+@dataclass(frozen=True)
+class DotSlashArtifact:
+    size: int
+    digest: str
+    archive_format: str
+    archive_member: str
+    url: str
+
+
+def fetch_dotslash_executable(
+    spec: TargetSpec,
+    *,
+    manifest_path: Path,
+    artifact_label: str,
+    cache_key: str,
+    dest_name: str,
+    missing_ok: bool = False,
+) -> Path | None:
+    artifact = artifact_for_target(
+        spec,
+        manifest_path,
+        artifact_label=artifact_label,
+        missing_ok=missing_ok,
+    )
+    if artifact is None:
+        return None
+
+    cache_dir = default_cache_root() / cache_key
+    archive_path = cache_dir / archive_filename(artifact.url)
+
+    if not archive_is_valid(archive_path, artifact, artifact_label):
+        download_archive(artifact.url, archive_path)
+        try:
+            verify_archive(archive_path, artifact, artifact_label)
+        except RuntimeError:
+            archive_path.unlink(missing_ok=True)
+            raise
+
+    dest = cache_dir / dest_name
+    extract_archive_member(archive_path, artifact, dest, artifact_label)
+    if not spec.is_windows:
+        mode = dest.stat().st_mode
+        dest.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return dest
+
+
+def artifact_for_target(
+    spec: TargetSpec,
+    manifest_path: Path,
+    *,
+    artifact_label: str,
+    missing_ok: bool = False,
+) -> DotSlashArtifact | None:
+    manifest = load_manifest(manifest_path)
+    platform_info = manifest.get("platforms", {}).get(spec.dotslash_platform)
+    if platform_info is None:
+        if missing_ok:
+            return None
+        raise RuntimeError(
+            f"{artifact_label} manifest {manifest_path} is missing platform "
+            f"{spec.dotslash_platform!r}"
+        )
+
+    providers = platform_info.get("providers")
+    if not providers:
+        raise RuntimeError(
+            f"{artifact_label} manifest {manifest_path} has no providers for "
+            f"{spec.dotslash_platform!r}"
+        )
+
+    hash_name = platform_info.get("hash")
+    if hash_name != "sha256":
+        raise RuntimeError(
+            f"Unsupported {artifact_label} hash {hash_name!r} for "
+            f"{spec.dotslash_platform!r}; expected sha256"
+        )
+
+    return DotSlashArtifact(
+        size=int(platform_info["size"]),
+        digest=str(platform_info["digest"]),
+        archive_format=str(platform_info["format"]),
+        archive_member=str(platform_info["path"]),
+        url=str(providers[0]["url"]),
+    )
+
+
+def load_manifest(manifest_path: Path) -> dict:
+    text = manifest_path.read_text(encoding="utf-8")
+    if text.startswith("#!"):
+        text = "\n".join(text.splitlines()[1:])
+    return json.loads(text)
+
+
+def default_cache_root() -> Path:
+    return Path(tempfile.gettempdir()) / "codex-package"
+
+
+def archive_filename(url: str) -> str:
+    filename = Path(urlparse(url).path).name
+    if not filename:
+        raise RuntimeError(f"Unable to determine archive filename from {url}")
+    return filename
+
+
+def archive_is_valid(
+    archive_path: Path,
+    artifact: DotSlashArtifact,
+    artifact_label: str,
+) -> bool:
+    if not archive_path.is_file():
+        return False
+    try:
+        verify_archive(archive_path, artifact, artifact_label)
+    except RuntimeError:
+        archive_path.unlink(missing_ok=True)
+        return False
+    return True
+
+
+def verify_archive(
+    archive_path: Path,
+    artifact: DotSlashArtifact,
+    artifact_label: str,
+) -> None:
+    actual_size = archive_path.stat().st_size
+    if actual_size != artifact.size:
+        raise RuntimeError(
+            f"{artifact_label} archive {archive_path} has size {actual_size}, "
+            f"expected {artifact.size}"
+        )
+
+    digest = hashlib.sha256()
+    with open(archive_path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            digest.update(chunk)
+
+    actual_digest = digest.hexdigest()
+    if actual_digest != artifact.digest:
+        raise RuntimeError(
+            f"{artifact_label} archive {archive_path} has sha256 {actual_digest}, "
+            f"expected {artifact.digest}"
+        )
+
+
+def download_archive(url: str, archive_path: Path) -> None:
+    archive_path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path = archive_path.with_suffix(f"{archive_path.suffix}.tmp")
+    temp_path.unlink(missing_ok=True)
+    try:
+        with urlopen(url, timeout=DOWNLOAD_TIMEOUT_SECS) as response:
+            with open(temp_path, "wb") as out:
+                shutil.copyfileobj(response, out)
+        temp_path.replace(archive_path)
+    finally:
+        temp_path.unlink(missing_ok=True)
+
+
+def extract_archive_member(
+    archive_path: Path,
+    artifact: DotSlashArtifact,
+    dest: Path,
+    artifact_label: str,
+) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.unlink(missing_ok=True)
+
+    if artifact.archive_format == "tar.gz":
+        with tarfile.open(archive_path, "r:gz") as archive:
+            try:
+                member = archive.getmember(artifact.archive_member)
+            except KeyError as exc:
+                raise RuntimeError(
+                    f"{artifact_label} archive {archive_path} is missing "
+                    f"{artifact.archive_member!r}"
+                ) from exc
+
+            extracted = archive.extractfile(member)
+            if extracted is None:
+                raise RuntimeError(
+                    f"{artifact_label} archive member {artifact.archive_member!r} is not a file"
+                )
+            with extracted, open(dest, "wb") as out:
+                shutil.copyfileobj(extracted, out)
+        return
+
+    if artifact.archive_format == "zip":
+        with zipfile.ZipFile(archive_path) as archive:
+            try:
+                with archive.open(artifact.archive_member) as extracted:
+                    with open(dest, "wb") as out:
+                        shutil.copyfileobj(extracted, out)
+            except KeyError as exc:
+                raise RuntimeError(
+                    f"{artifact_label} archive {archive_path} is missing "
+                    f"{artifact.archive_member!r}"
+                ) from exc
+        return
+
+    raise RuntimeError(
+        f"Unsupported {artifact_label} archive format {artifact.archive_format!r}; "
+        "expected tar.gz or zip"
+    )

scripts/codex_package/layout.py

@@ -0,0 +1,187 @@
+"""Canonical Codex package directory layout."""
+
+import json
+import shutil
+import stat
+from pathlib import Path
+
+from .targets import PackageInputs
+from .targets import PackageVariant
+from .targets import TargetSpec
+from .zsh import ZSH_RESOURCE_PATH
+
+
+LAYOUT_VERSION = 1
+
+
+def prepare_package_dir(package_dir: Path, *, force: bool) -> None:
+    if package_dir.exists():
+        if not package_dir.is_dir():
+            raise RuntimeError(
+                f"Package output exists and is not a directory: {package_dir}"
+            )
+        if any(package_dir.iterdir()):
+            if not force:
+                raise RuntimeError(
+                    f"Package output directory is not empty: {package_dir}. "
+                    "Pass --force to replace it."
+                )
+            shutil.rmtree(package_dir)
+
+    package_dir.mkdir(parents=True, exist_ok=True)
+
+
+def build_package_dir(
+    package_dir: Path,
+    version: str,
+    variant: PackageVariant,
+    spec: TargetSpec,
+    inputs: PackageInputs,
+) -> None:
+    bin_dir = package_dir / "bin"
+    resources_dir = package_dir / "codex-resources"
+    path_dir = package_dir / "codex-path"
+    bin_dir.mkdir()
+    resources_dir.mkdir()
+    path_dir.mkdir()
+
+    entrypoint_name = variant.entrypoint_name(spec)
+    copy_executable(
+        inputs.entrypoint_bin,
+        bin_dir / entrypoint_name,
+        is_windows=spec.is_windows,
+    )
+    copy_executable(
+        inputs.code_mode_host_bin,
+        bin_dir / f"codex-code-mode-host{spec.exe_suffix}",
+        is_windows=spec.is_windows,
+    )
+    copy_executable(inputs.rg_bin, path_dir / spec.rg_name, is_windows=spec.is_windows)
+
+    if inputs.zsh_bin is not None:
+        copy_executable(
+            inputs.zsh_bin,
+            resources_dir / ZSH_RESOURCE_PATH,
+            is_windows=False,
+        )
+
+    if inputs.bwrap_bin is not None:
+        copy_executable(inputs.bwrap_bin, resources_dir / "bwrap", is_windows=False)
+
+    if inputs.codex_command_runner_bin is not None:
+        copy_executable(
+            inputs.codex_command_runner_bin,
+            resources_dir / "codex-command-runner.exe",
+            is_windows=True,
+        )
+
+    if inputs.codex_windows_sandbox_setup_bin is not None:
+        copy_executable(
+            inputs.codex_windows_sandbox_setup_bin,
+            resources_dir / "codex-windows-sandbox-setup.exe",
+            is_windows=True,
+        )
+
+    metadata = {
+        "layoutVersion": LAYOUT_VERSION,
+        "version": version,
+        "target": spec.target,
+        "variant": variant.name,
+        "entrypoint": f"bin/{entrypoint_name}",
+        "resourcesDir": "codex-resources",
+        "pathDir": "codex-path",
+    }
+    write_json(package_dir / "codex-package.json", metadata)
+
+
+def validate_package_dir(
+    package_dir: Path,
+    variant: PackageVariant,
+    spec: TargetSpec,
+    *,
+    include_zsh: bool,
+) -> None:
+    required_dirs = [
+        Path("bin"),
+        Path("codex-resources"),
+        Path("codex-path"),
+    ]
+    for relative_dir in required_dirs:
+        path = package_dir / relative_dir
+        if not path.is_dir():
+            raise RuntimeError(f"Missing package directory: {relative_dir}")
+
+    metadata_path = package_dir / "codex-package.json"
+    if not metadata_path.is_file():
+        raise RuntimeError("Missing package metadata: codex-package.json")
+
+    with open(metadata_path, encoding="utf-8") as fh:
+        metadata = json.load(fh)
+
+    expected_metadata = {
+        "layoutVersion": LAYOUT_VERSION,
+        "target": spec.target,
+        "variant": variant.name,
+        "entrypoint": f"bin/{variant.entrypoint_name(spec)}",
+        "resourcesDir": "codex-resources",
+        "pathDir": "codex-path",
+    }
+    for key, expected in expected_metadata.items():
+        actual = metadata.get(key)
+        if actual != expected:
+            raise RuntimeError(
+                f"Invalid package metadata field {key!r}: expected {expected!r}, got {actual!r}"
+            )
+
+    required_files = [
+        Path("bin") / variant.entrypoint_name(spec),
+        Path("bin") / f"codex-code-mode-host{spec.exe_suffix}",
+        Path("codex-path") / spec.rg_name,
+    ]
+    executable_files = list(required_files)
+
+    if include_zsh:
+        zsh_path = Path("codex-resources") / ZSH_RESOURCE_PATH
+        required_files.append(zsh_path)
+        executable_files.append(zsh_path)
+
+    if spec.is_linux:
+        required_files.append(Path("codex-resources") / "bwrap")
+        executable_files.append(Path("codex-resources") / "bwrap")
+
+    if spec.is_windows:
+        required_files.extend(
+            [
+                Path("codex-resources") / "codex-command-runner.exe",
+                Path("codex-resources") / "codex-windows-sandbox-setup.exe",
+            ]
+        )
+
+    for relative_file in required_files:
+        path = package_dir / relative_file
+        if not path.is_file():
+            raise RuntimeError(f"Missing package file: {relative_file}")
+
+    if not spec.is_windows:
+        for relative_file in executable_files:
+            path = package_dir / relative_file
+            if not is_executable(path):
+                raise RuntimeError(f"Package file is not executable: {relative_file}")
+
+
+def copy_executable(src: Path, dest: Path, *, is_windows: bool) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(src, dest)
+    if not is_windows:
+        mode = dest.stat().st_mode
+        dest.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def write_json(path: Path, value: object) -> None:
+    with open(path, "w", encoding="utf-8") as out:
+        json.dump(value, out, indent=2)
+        out.write("\n")
+
+
+def is_executable(path: Path) -> bool:
+    return bool(path.stat().st_mode & stat.S_IXUSR)