feat: add cleanroom agent codex shortcut

[lox]

Summary

This adds a first-class cleanroom agent command for running coding agents inside a Cleanroom sandbox.

Agent sessions use the repository's normal Cleanroom environment: the cleanroom.yaml sandbox image, backend, repository bootstrap, network policy, and interactive console transport. The command keeps newly created sandboxes by default so agents can retain workspace state after the session.

This also adds runtime-configured agent commands and credential copying.

How to use it

Run a built-in agent in a new sandbox from the current repository policy:

cleanroom agent codex -- exec --yolo "fix the failing tests"
cleanroom agent claude
cleanroom agent gemini
cleanroom agent opencode
cleanroom agent --dangerously-allow-all codex -- exec "summarize the repo"

Pass agent arguments after the agent name. A leading -- is stripped when present, so both of these are valid:

cleanroom agent codex -- exec "summarize the repo"
cleanroom agent codex exec "summarize the repo"

Run an agent in an existing sandbox:

cleanroom agent --sandbox-id cr_123 codex -- exec "inspect the current tree"

Configured custom agents are added to the cleanroom agent <agent> enum alongside the built-ins.

What it does

cleanroom agent:

• resolves or creates a sandbox using the same policy path as cleanroom console
• runs the selected agent through the interactive console path
• can disable egress filtering for newly created sandboxes with --dangerously-allow-all
• keeps newly created sandboxes after the agent exits
• copies configured credential paths into the sandbox before attaching the agent
• passes through agent arguments safely by shell-quoting them before appending to the configured command

The built-in agent commands first use an agent binary already present in the sandbox image. If the binary is missing, they fall back to mise-managed Node.js plus the npm package, for example:

mise --no-config exec -y nodejs@lts -- npm exec --yes --package @openai/codex@latest -- codex

That means plain Debian-based Cleanroom images can run agents once they contain the required runtime libraries and the policy allows the package manager/network hosts needed by mise, Node.js, npm, and the agent itself. Images that already include agent binaries skip the fallback path.

Runtime config

cleanroom config init emits agent configuration with default commands and credential mappings. The generated commands are shell snippets; the Codex default is representative:

agents:
  codex:
    command: sh -lc 'if command -v codex >/dev/null 2>&1; then exec codex "$@"; fi; exec env MISE_YES=1 MISE_TRUSTED_CONFIG_PATHS=/workspace mise --no-config exec -y nodejs@lts -- npm exec --yes --package @openai/codex@latest -- codex "$@"' sh
    test: command -v codex >/dev/null 2>&1 || command -v mise >/dev/null 2>&1
    credentials:
      - source: ~/.codex/auth.json
        target: ~/.codex/auth.json
      - source: ~/.codex/config.toml
        target: ~/.codex/config.toml

command, test, and optional install are shell snippets. If install is configured, Cleanroom runs it only when test fails. Built-in defaults do not need install because they either use an existing binary or run the mise fallback.

Credential behavior

Credential entries are explicit runtime config mappings. Each source is read from the host, packaged into a tar archive, copied into the sandbox with the sandbox archive extraction API, and extracted at target before the agent starts.

When copying Codex config, Cleanroom preserves the host config.toml content and adds /workspace as a trusted project in the sandbox copy.

Missing credential paths are skipped. Copied credentials remain in a kept sandbox until that sandbox is terminated.

Testing

• mise exec -- go test ./internal/cli
• mise exec -- go test ./...
• mise exec -- go run ./cmd/cleanroom agent --help

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 685a17d4bb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[lox]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Swish!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[lox]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fedf12d66e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Dereference symlinked credentials before archiving

This path preserves symlinks instead of copying their contents, so a credential source that is a symlink (common with dotfile managers) is extracted into the sandbox as the same link target rather than usable file bytes. If that link points outside the copied tree (for example an absolute host path), the sandbox gets a dangling credential path and agent auth fails even though the source existed on the host.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Base default command check on configured command

When an agent defines command but omits test, the fallback check still hardcodes command -v <agent name>. That makes valid custom commands fail the preflight check (for example absolute paths or wrapper invocations where <agent name> is not on PATH), causing an unnecessary exit 127 before exec would have worked.

Useful? React with 👍 / 👎.