launch-openshell-gator

# Launch OpenShell Gator Launch and supervise the repository's headless gator sandbox agent through OpenShell. This skill covers the operator workflow around `scripts/agents/run.sh`; the in-sandbox review and state-machine policy remains the `gator-gate` skill baked into the gator payload. For gator's PR/issue validation policy, load `gator-gate` inside the launched sandbox. For generic sandbox CLI usage, use `openshell-cli`. For unhealthy gateways or sandbox startup failures, use `debug-openshell-cluster` after the launch preflight identifies a gateway/runtime problem. ## Non-Negotiable Rules - Keep normal gator launches supervised: use `--watch` and let the in-sandbox supervisor own sleeping and relaunching bounded cycles. - Do not add passive `sleep` loops in the operator session to watch gator. Check logs or status once, then report the current state or launch a proper watcher outside the model session only when explicitly asked. - Do not change the default gator model in `scripts/agents/gator/agent.yaml` for experiments. Use `CODEX_MODEL=...` and, if needed, a temporary `--from` Docker context or `--codex-bin` override. - Do not push to contributor branches, approve, merge, post `/ok to test`, or broaden gator scope unless the operator explicitly authorized that action. - Scope each launch prompt to the requested issue/PR set. Avoid repo-wide gator scans unless the operator asked for repo-wide processing. - Leave unrelated local files alone, including `.opencode/` artifacts and old gator logs unless the user asks for cleanup. ## Key Paths | Path | Purpose | |---|---| | `scripts/agents/run.sh` | Manifest-driven OpenShell agent launcher. | | `scripts/agents/gator/agent.yaml` | Gator manifest: immutable payload version, default gateway, harness, providers, runtime, skills, and subagents. | | `scripts/agents/gator/Dockerfile` | Gator sandbox image source. Local launches build it in gateway's Docker or Podman image store. | | `scripts/agents/gator/policy.yaml` | Sandbox policy for the gator agent. | | `scripts/agents/gator/bin/gh` | Gator-specific `gh` wrapper and same-SHA duplicate-post guard. | | `scripts/agents/gator/bin/review-feedback-ledger` | Builds tree-aware review scope, durable findings, convergence telemetry, and review-budget state. | | `scripts/agents/gator/bin/resolve-gator-review-threads` | Resolves addressed Gator-owned inline review threads by ledger finding ID. | | `scripts/agents/gator/bin/validate-review-findings` | Enforces the blocker evidence schema and downgrades unsupported hypotheses. | | `scripts/agents/gator/prompts/gator.md` | Rendered top-level prompt template baked into the payload. | | `scripts/agents/gator/skills/gator-gate/SKILL.md` | In-sandbox gator state-machine skill. | ## Preflight Run these checks before launching unless the operator asks for a best-effort launch. ### Step 1: Confirm Repository Root ```bash git rev-parse --show-toplevel git status --short --branch ``` Use the repository root as the working directory for all commands. A dirty worktree is allowed, but do not stage or modify unrelated files. ### Step 2: Verify Required Host Tools ```bash command -v openshell command -v gh command -v jq command -v ruby ``` The local `openshell` wrapper may recompile the CLI. If that fails, fix the local build or ask the operator before changing unrelated source. ### Step 3: Verify GitHub Auth Use `gh api user` as the health check. It works with provider-scoped tokens and matches gator's own auth guidance. ```bash gh api user --jq '.login' gh api repos/NVIDIA/OpenShell --jq '{full_name,default_branch}' ``` If this fails, refresh host `gh` auth before launching. Do not rely on `gh auth status` alone inside provider-backed sandboxes. ### Step 4: Verify Codex Auth For Codex Harness The default gator harness is Codex. Check that the host has usable Codex auth material: ```bash jq -e '.tokens.access_token and .tokens.refresh_token and .tokens.account_id' "$HOME/.codex/auth.json" >/dev/null ``` If this fails, run the local Codex login flow outside the gator launch. If Codex was recently reauthenticated and gateway refresh fails later, relaunch with `--reset-refresh` once. ### Step 5: Verify Gateway Is Registered And Alive Use the target gateway from the operator request or current session context. Do not assume a gateway name. If the operator did not specify one, list registered gateways and ask before launching when the correct target is ambiguous. ```bash openshell gateway list gateway_name="<selected-gateway-name>" [[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } openshell --gateway "$gateway_name" status openshell --gateway "$gateway_name" sandbox list ``` Expected result: status returns successfully and sandbox listing completes. If the gateway is unreachable, the runtime cannot create sandboxes, or sandbox listing hangs, switch to `debug-openshell-cluster` and fix the gateway before launching gator. ### Step 6: Check Existing Gator Sandboxes Avoid duplicate gators for the same PR unless intentionally replacing a stuck or stale one. ```bash gateway_name="<selected-gateway-name>" [[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } openshell --gateway "$gateway_name" sandbox list ``` Look for names like `gator-pr-<number>-supervised`. If one exists, inspect its log before deleting or relaunching. ## Input Normalization Never paste raw operator text into shell arguments such as `--gateway`, `--name`, `--from`, issue numbers, or PR numbers. Normalize values before constructing launch commands. Use the operator-specified gateway or a gateway selected from `openshell gateway list`: ```bash gateway_name="<selected-gateway-name>" [[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } ``` Use digits only for issue and PR numbers: ```bash pr_number="<digits-only>" [[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } ``` Use the portable Kubernetes DNS-1123 sandbox-name format even when the selected gateway currently uses another driver: ```bash sandbox_name="gator-pr-${pr_number}-supervised" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } ``` For local image contexts passed to `--from`, use an agent-created path such as `mktemp -d`; do not pass raw user-supplied paths without validating that they are expected local Dockerfile contexts. ## Standard Launches ### Launch A PR Watcher Use a stable, scoped name and a prompt that names exactly what gator should do. ```bash gateway_name="<selected-gateway-name>" pr_number="<digits-only>" [[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } [[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } sandbox_name="gator-pr-${pr_number}-supervised" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } ./scripts/agents/run.sh \ --agent gator \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}." ``` The launcher queries the gateway's selected compute driver, builds the gator image in the matching Docker or Podman image store, stages the immutable payload, imports provider profiles, configures provider credentials and refresh, and starts the agent supervisor as the sandbox's canonical main process. The detached main process survives loss of the host CLI connection and reconnects to a restarted gateway. Unless `--keep` is set, the sandbox is marked ephemeral so the gateway deletes it after the canonical main process exits and its terminal result is finalized. `CONTAINER_ENGINE`, when set, must match the gateway driver. The launcher streams image-build and provisioning output until the detached workload is ready, then exits. Use `openshell logs <sandbox-name>` or the TUI for runtime output. ### Launch An Issue Or Issue/PR Pair ```bash gateway_name="<selected-gateway-name>" issue_number="<digits-only>" [[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } [[ "$issue_number" =~ ^[0-9]+$ ]] || { echo "invalid issue number" >&2; exit 1; } sandbox_name="gator-issue-${issue_number}-supervised" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } ./scripts/agents/run.sh \ --agent gator \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ "Run gator on issue #${issue_number}. Scope this invocation only to issue #${issue_number}." ``` For a linked pair: ```bash gateway_name="<selected-gateway-name>" pr_number="<digits-only>" issue_number="<digits-only>" [[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } [[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } [[ "$issue_number" =~ ^[0-9]+$ ]] || { echo "invalid issue number" >&2; exit 1; } sandbox_name="gator-pr-${pr_number}-supervised" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } ./scripts/agents/run.sh \ --agent gator \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ "Review and monitor PR #${pr_number} with linked issue #${issue_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number} and issue #${issue_number}." ``` ### Launch With Explicit Maintainer Authorization Only include authorization in the prompt when the operator explicitly gave it. ```bash gateway_name="<selected-gateway-name>" pr_number="<digits-only>" [[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } [[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } sandbox_name="gator-pr-${pr_number}-supervised" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } ./scripts/agents/run.sh \ --agent gator \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}. The operator explicitly authorizes applying the test:e2e label, posting /ok to test with the full 40-character current head SHA, and rerunning the relevant current-head workflow when the E2E Label Help bot says that is required." ``` ## Model Or Image Experiments Use environment overrides. Do not edit `agent.yaml` for temporary experiments. ```bash gateway_name="<selected-gateway-name>" pr_number="<digits-only>" [[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } [[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } sandbox_name="gator-pr-${pr_number}-gpt56sol-supervised" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } CODEX_MODEL=gpt-5.6-sol \ ./scripts/agents/run.sh \ --agent gator \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}. This launch is intentionally testing Codex model gpt-5.6-sol via the CLI launcher." ``` If the installed Codex CLI is too old for a model, create a temporary copy of `scripts/agents/gator/`, adjust only that temporary Dockerfile, and launch with that generated context. Keep the repo Dockerfile unchanged unless the version bump is the intended code change. Example shape: ```bash gateway_name="<selected-gateway-name>" pr_number="<digits-only>" [[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } [[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }