feat(agents): add manifest-driven gator agent

[johntmyers]

Summary

Add a manifest-driven sandbox agent launcher and the first concrete agent, Gator, for validating and monitoring OpenShell issues and PRs. The launcher packages shared runtime adapters, provider profiles, skills, subagents, and prompts into supervised OpenShell sandboxes so gator can run bounded Codex cycles in watch mode.

Related Issue

None.

Changes

• Add openshell-agents/run.sh, shared runtime entrypoint, supervisor, Codex harness adapter, and subagent dispatch support.
• Add the openshell-agents/gator/ manifest, prompt, README, Dockerfile, scoped GitHub/Codex provider profiles, and sandbox policy.
• Add the gator-gate skill for the gator state machine, validation rules, human-response disposition, reviewer invocation, CI/test gating, and scoped GitHub auth guidance.
• Add gateway-managed Codex access-token refresh handling and preserve/repair behavior for long-running watch sandboxes.
• Harden watch mode so transient transport failures, malformed cycle results, and legacy failure statuses retry without exiting the sandbox.
• Document the agent runtime and provider placeholder behavior in openshell-agents/README.md.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)

Additional checks:

• bash openshell-agents/runtime/supervisor_test.sh
• Live gator sandboxes relaunched and observed Ready on docker-dev
• Verified provider-backed Codex and GitHub placeholder resolution inside gator sandboxes

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (not applicable; agent docs live under openshell-agents/)

[elezar]

Question: Is the expectation that each agent will have it's own Dockerfile? If so, does it make sense to move this to openshell-agents/gator/Dockerfile instead? Alternatively, we may need to update the README.md to show an (optional?) Dockerfile.agent.

[elezar]

On the systems that I have setup, I don't have ruby installed and don't get past this requirement. How can we increase the portability of this script? Would adding a new openshell subcommand be too heavy-weight here?

[elezar]

From Codex:

Why does the openshell-agents/run.sh command require ruby?

openshell-agents/run.sh requires Ruby because the Bash launcher uses embedded Ruby snippets for structured host-side work. It explicitly
  checks for ruby at openshell-agents/run.sh:169.

  Ruby is used to:

  - Parse agent.yaml and emit shell-safe variables with YAML + Shellwords: openshell-agents/run.sh:178
  - Resolve provider profile YAML files and detect duplicate profile IDs: openshell-agents/run.sh:339
  - Read nested values from JSON credential files like ~/.codex/auth.json: openshell-agents/run.sh:399
  - Render the prompt template into agent-prompt.md: openshell-agents/run.sh:545
  - Patch the staged Dockerfile to copy in the immutable agent payload while preserving the final USER: openshell-agents/run.sh:609

  So Ruby is not required by the agent runtime or Codex harness itself. It is a host-side implementation dependency of the launcher. It also
  appears to be undeclared in mise.toml, so right now it is a hidden local prerequisite unless installed by the OS or user environment.

[elezar]

While exercising the gator state machine on #1850, I hit one transition that is worth clarifying in this PR.

When a PR is in gator:approval-needed and a maintainer approval arrives, gator currently re-checks the PR and stays in gator:approval-needed until the PR is merged or closed. Mechanically that is fine, but the label reads as if approval is still missing after approval has already been received.

Can we make this explicit in the gator support added here? Two reasonable options:

• Document/comment-template wording: after approval, gator:approval-needed means "maintainer merge decision pending" for an open PR.
• Add a distinct state such as gator:merge-ready or gator:merge-pending so the post-approval state is not overloaded.

The current behavior is not blocking #1850, but without this clarification users will reasonably ask why an approved PR still says approval-needed.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.