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]

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.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-1826.docs.buildwithfern.com/openshell

[johntmyers]

@drew @elezar refactored to be under scripts/agents and implemented other suggestions w/ the exception of factoring out Ruby. would like to just merge this so its at least in main and can iterate more later.