From aa88bd847ee4f842d2cbb6589a2bccec14a89b82 Mon Sep 17 00:00:00 2001 From: John Myers Date: Thu, 9 Jul 2026 11:21:32 -0700 Subject: [PATCH 1/5] docs(agents): add gator launch skill Signed-off-by: John Myers --- .../skills/launch-openshell-gator/SKILL.md | 316 ++++++++++++++++++ CONTRIBUTING.md | 1 + 2 files changed, 317 insertions(+) create mode 100644 .agents/skills/launch-openshell-gator/SKILL.md diff --git a/.agents/skills/launch-openshell-gator/SKILL.md b/.agents/skills/launch-openshell-gator/SKILL.md new file mode 100644 index 0000000000..00c3ea9db0 --- /dev/null +++ b/.agents/skills/launch-openshell-gator/SKILL.md @@ -0,0 +1,316 @@ +--- +name: launch-openshell-gator +description: Launch and supervise OpenShell gator agents via scripts/agents/run.sh. Use when starting gator on issues or PRs, checking gator sandboxes, validating gateway readiness, building the gator sandbox image, restarting stuck gators, or experimenting with gator harness/model overrides. Trigger keywords - launch gator, start gator, run gator, gator sandbox, supervised gator, gator logs, restart gator, gpt-5.6-sol 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. + +## When To Use + +Use this skill when the user wants to: + +- Start gator on a GitHub issue or PR. +- Keep a PR under supervised gator watch. +- Verify the OpenShell gateway and local prerequisites before launching gator. +- Build or rebuild the gator sandbox image through the launcher. +- Inspect gator logs, active gator sandboxes, or stuck supervised cycles. +- Restart a gator with an updated payload after changing gator prompt, skill, policy, wrapper, runtime, or Dockerfile files. +- Launch a model experiment with `CODEX_MODEL=...` without changing `scripts/agents/gator/agent.yaml`. + +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 --background` 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 use `--keep` for normal supervised gators. The launcher already keeps watch-mode sandboxes alive through the supervisor. +- 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. +- Treat `/etc/openshell/agent-payload` as immutable once a sandbox is created. After prompt/skill/runtime/image changes, delete and relaunch the affected gator instead of trying to patch files in-place. +- 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: default gateway, harness, providers, runtime, skills, and subagents. | +| `scripts/agents/gator/Dockerfile` | Gator sandbox image source. Local launches build this image through OpenShell. | +| `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/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. | +| `scripts/agents/gator/logs/` | Background launch and supervisor logs. | + +## 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, usually `docker-dev` for local gators. + +```bash +openshell --gateway docker-dev status +openshell --gateway docker-dev 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 +openshell --gateway docker-dev sandbox list +``` + +Look for names like `gator-pr--supervised`. If one exists, inspect its log before deleting or relaunching. + +## Standard Launches + +### Launch A PR Watcher + +Use a stable, scoped name and a prompt that names exactly what gator should do. + +```bash +./scripts/agents/run.sh \ + --agent gator \ + --gateway docker-dev \ + --name gator-pr--supervised \ + --watch \ + --background \ + "Review and monitor PR # through the gator-gate workflow. Scope this invocation only to PR #." +``` + +The launcher builds the gator sandbox image when needed, stages the immutable payload, imports provider profiles, configures provider credentials and refresh, creates the sandbox, and writes a background log under `scripts/agents/gator/logs/`. + +### Launch An Issue Or Issue/PR Pair + +```bash +./scripts/agents/run.sh \ + --agent gator \ + --gateway docker-dev \ + --name gator-issue--supervised \ + --watch \ + --background \ + "Run gator on issue #. Scope this invocation only to issue #." +``` + +For a linked pair: + +```bash +./scripts/agents/run.sh \ + --agent gator \ + --gateway docker-dev \ + --name gator-pr--supervised \ + --watch \ + --background \ + "Review and monitor PR # with linked issue # through the gator-gate workflow. Scope this invocation only to PR # and issue #." +``` + +### Launch With Explicit Maintainer Authorization + +Only include authorization in the prompt when the operator explicitly gave it. + +```bash +./scripts/agents/run.sh \ + --agent gator \ + --gateway docker-dev \ + --name gator-pr--supervised \ + --watch \ + --background \ + "Review and monitor PR # through the gator-gate workflow. Scope this invocation only to PR #. The operator explicitly authorizes applying the test:e2e label and posting /ok to test for the current head SHA if gator determines that is required." +``` + +## Model Or Image Experiments + +Use environment overrides. Do not edit `agent.yaml` for temporary experiments. + +```bash +CODEX_MODEL=gpt-5.6-sol \ +./scripts/agents/run.sh \ + --agent gator \ + --gateway docker-dev \ + --name gator-pr--gpt56sol-supervised \ + --watch \ + --background \ + "Review and monitor PR # through the gator-gate workflow. Scope this invocation only to PR #. 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/` under `/var/folders/52/ygrbs0zn7pxgfcppwggvgklm0000gp/T/opencode` or another approved temp directory, adjust only that temporary Dockerfile, and launch with `--from `. Keep the repo Dockerfile unchanged unless the version bump is the intended code change. + +Example shape: + +```bash +CODEX_MODEL=gpt-5.6-sol \ +./scripts/agents/run.sh \ + --agent gator \ + --gateway docker-dev \ + --name gator-pr--gpt56sol-supervised \ + --from /var/folders/52/ygrbs0zn7pxgfcppwggvgklm0000gp/T/opencode/gator-codex- \ + --watch \ + --background \ + "Review and monitor PR # through the gator-gate workflow. Scope this invocation only to PR #." +``` + +## Monitoring + +### Read The Launch Result + +The launcher prints the log path when `--background` is used: + +```text +Started in background. Log: scripts/agents/gator/logs/.log +``` + +Read that file directly. Important markers: + +- `Built image ...` means the local image build completed. +- `Created sandbox: ` means OpenShell accepted the sandbox. +- `openshell-agent: starting watch cycle` means the in-sandbox supervisor began a bounded cycle. +- `OpenAI Codex v...` plus `model: ...` confirms the Codex CLI and model actually used. +- `OPENSHELL_AGENT_RESULT {...}` is the bounded-cycle sentinel. In watch mode, the supervisor sleeps and relaunches after this line. +- `openshell-agent: still running watch cycle ...` is a heartbeat during long active model cycles. + +### Inspect Active Sandboxes + +```bash +openshell --gateway docker-dev sandbox list +openshell --gateway docker-dev sandbox get +``` + +If `sandbox get` is not supported by the local CLI shape, use `openshell sandbox --help` and follow the current command help. + +### Interpret Common Sentinels + +| Sentinel | Meaning | Operator action | +|---|---|---| +| `status=waiting` | Normal watch wait. | Leave sandbox running. | +| `status=blocked` | Human/process blocker. | Read reason; decide whether a human action is needed. | +| `status=transient_failure` | Retryable infrastructure/auth/transport issue. | Let supervisor retry unless repeated failures hit the configured cap. | +| `status=terminal_failure` | Unrecoverable agent failure. | Inspect log and fix/relaunch. | +| `status=complete` | Target closed, merged, or one-shot complete. | Delete sandbox if no longer needed. | + +## Restarting A Gator + +Restart when the payload must change, the sandbox is wedged without a sentinel, the model/tooling version changed, or a transient failure repeats past the useful retry point. + +Before deleting, check that the sandbox is truly stale or that the operator asked for a restart. If a bounded review cycle is actively running and still producing useful output, prefer leaving it alone. + +```bash +openshell --gateway docker-dev sandbox delete +./scripts/agents/run.sh \ + --agent gator \ + --gateway docker-dev \ + --name \ + --watch \ + --background \ + "" +``` + +When relaunching after a same-SHA infrastructure failure, say that the prior attempt failed before producing a valid review disposition. When relaunching after a draft-only blocker cleared, say that the prior same-SHA disposition was only a draft blocker and the PR is now ready for review. + +## Troubleshooting + +### Gateway Unreachable + +Symptoms: `openshell status` fails, `sandbox list` fails, sandbox remains pending, image build never starts. + +Action: load `debug-openshell-cluster` and diagnose the gateway/driver. Do not keep retrying gator launches against a dead gateway. + +### Image Build Failure + +Symptoms: Dockerfile step failure, missing package, incompatible Codex CLI, registry pull failure. + +Actions: + +- Confirm the build context is `scripts/agents/gator/` or the intended temporary `--from` context. +- Confirm Docker or the selected gateway runtime can pull `nvcr.io/nvidia/base/ubuntu:noble-20251013`. +- For Codex CLI version experiments, adjust a temporary Docker context first. +- Do not commit Dockerfile version changes unless the repo should permanently use that version. + +### Provider Or Credential Failure + +Symptoms: host `gh` auth fails, Codex refresh fails, in-sandbox GitHub calls report auth failures, `reviewer_subagent_failed` repeats due Codex auth. + +Actions: + +- Re-run the GitHub and Codex preflight checks. +- If host Codex auth changed, relaunch with `--reset-refresh` once. +- If Entra or Microsoft auth is involved in a future provider, use the relevant auth skill. Gator's default providers are GitHub and Codex. + +### Unsupported `gh pr view --json` Field + +Gator may recover by using supported `gh pr view` fields plus REST calls. If it does not, patch the gator prompt or skill to avoid the unsupported field, validate, commit, and relaunch with the updated payload. + +### Same-SHA Duplicate Guard Blocks A Needed Comment + +The wrapper intentionally blocks duplicate same-head-SHA gator dispositions. A relaunch should not post again for the same SHA unless one of these applies: + +- Maintainer explicitly requests a same-SHA public response. +- The PR is merged or closed and needs terminal cleanup. +- The earlier attempt failed before posting. +- The prior marked disposition was only a reviewer infrastructure failure. +- The prior marked disposition was only a draft blocker and the PR is now ready for review. + +Do not bypass with `OPENSHELL_GATOR_ALLOW_SAME_SHA_COMMENT=1` unless the operator explicitly confirms a maintainer override. + +## Reporting Back + +When you launch or inspect gator, report: + +- Sandbox name. +- Gateway name. +- Log path. +- Target issue/PR scope. +- Harness and model when relevant. +- Whether image build and sandbox creation succeeded. +- Latest sentinel or heartbeat status. +- Any human action needed. + +Keep the report concise. Include exact commands only when they help the operator reproduce or continue the workflow. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b78f36522f..2082a6d8a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,6 +76,7 @@ Skills live in `.agents/skills/`. Your agent's harness can discover and load the | Reviewing | `review-github-pr` | Summarize PR diffs and key design decisions | | Reviewing | `review-security-issue` | Assess security issues for severity and remediation | | Reviewing | `watch-github-actions` | Monitor CI pipeline status and logs | +| Reviewing | `launch-openshell-gator` | Launch and supervise OpenShell gator agents for issue and PR monitoring | | Reviewing | `test-release-canary` | Dispatch and iterate on the Release Canary workflow that smoke-tests published artifacts | | Triage | `triage-issue` | Assess, classify, and route community-filed issues | | Platform | `generate-sandbox-policy` | Generate YAML sandbox policies from requirements or API docs | From 2c303e0f485d9e126374c7e1a410c60a0118b3ab Mon Sep 17 00:00:00 2001 From: John Myers Date: Thu, 9 Jul 2026 14:38:37 -0700 Subject: [PATCH 2/5] docs(agents): narrow gator launch trigger Signed-off-by: John Myers --- .agents/skills/launch-openshell-gator/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/launch-openshell-gator/SKILL.md b/.agents/skills/launch-openshell-gator/SKILL.md index 00c3ea9db0..1097b4b231 100644 --- a/.agents/skills/launch-openshell-gator/SKILL.md +++ b/.agents/skills/launch-openshell-gator/SKILL.md @@ -1,6 +1,6 @@ --- name: launch-openshell-gator -description: Launch and supervise OpenShell gator agents via scripts/agents/run.sh. Use when starting gator on issues or PRs, checking gator sandboxes, validating gateway readiness, building the gator sandbox image, restarting stuck gators, or experimenting with gator harness/model overrides. Trigger keywords - launch gator, start gator, run gator, gator sandbox, supervised gator, gator logs, restart gator, gpt-5.6-sol gator. +description: Launch and supervise OpenShell gator agents. Use when starting gator on issues or PRs, checking gator sandboxes, building the gator sandbox image, restarting stuck gators, inspecting gator logs, or experimenting with gator harness/model overrides. Trigger keywords - launch gator, start gator, run gator, gator sandbox, supervised gator, gator logs, restart gator. --- # Launch OpenShell Gator From 5427f87a50ed877049a44e6b28d24936dd107925 Mon Sep 17 00:00:00 2001 From: John Myers Date: Thu, 9 Jul 2026 17:16:43 -0700 Subject: [PATCH 3/5] docs(agents): trim gator launch skill intro Signed-off-by: John Myers --- .agents/skills/launch-openshell-gator/SKILL.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/.agents/skills/launch-openshell-gator/SKILL.md b/.agents/skills/launch-openshell-gator/SKILL.md index 1097b4b231..d029fb80e5 100644 --- a/.agents/skills/launch-openshell-gator/SKILL.md +++ b/.agents/skills/launch-openshell-gator/SKILL.md @@ -7,18 +7,6 @@ description: Launch and supervise OpenShell gator agents. Use when starting gato 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. -## When To Use - -Use this skill when the user wants to: - -- Start gator on a GitHub issue or PR. -- Keep a PR under supervised gator watch. -- Verify the OpenShell gateway and local prerequisites before launching gator. -- Build or rebuild the gator sandbox image through the launcher. -- Inspect gator logs, active gator sandboxes, or stuck supervised cycles. -- Restart a gator with an updated payload after changing gator prompt, skill, policy, wrapper, runtime, or Dockerfile files. -- Launch a model experiment with `CODEX_MODEL=...` without changing `scripts/agents/gator/agent.yaml`. - 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 From 12ecf3889f698bcd2fc0e3be4bb9f57740074910 Mon Sep 17 00:00:00 2001 From: John Myers Date: Fri, 10 Jul 2026 08:46:42 -0700 Subject: [PATCH 4/5] docs(agents): harden gator launch examples Signed-off-by: John Myers --- .../skills/launch-openshell-gator/SKILL.md | 89 +++++++++++++++---- 1 file changed, 73 insertions(+), 16 deletions(-) diff --git a/.agents/skills/launch-openshell-gator/SKILL.md b/.agents/skills/launch-openshell-gator/SKILL.md index d029fb80e5..939c3a05cd 100644 --- a/.agents/skills/launch-openshell-gator/SKILL.md +++ b/.agents/skills/launch-openshell-gator/SKILL.md @@ -99,6 +99,26 @@ openshell --gateway docker-dev sandbox list Look for names like `gator-pr--supervised`. If one exists, inspect its log before deleting or relaunching. +## Input Normalization + +Never paste raw operator text into shell arguments such as `--name`, `--from`, issue numbers, or PR numbers. Normalize values before constructing launch commands. + +Use digits only for issue and PR numbers: + +```bash +pr_number="" +[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } +``` + +Use a restricted sandbox-name character set: + +```bash +sandbox_name="gator-pr-${pr_number}-supervised" +[[ "$sandbox_name" =~ ^[A-Za-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 @@ -106,13 +126,18 @@ Look for names like `gator-pr--supervised`. If one exists, inspect its l Use a stable, scoped name and a prompt that names exactly what gator should do. ```bash +pr_number="" +[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } +sandbox_name="gator-pr-${pr_number}-supervised" +[[ "$sandbox_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } + ./scripts/agents/run.sh \ --agent gator \ --gateway docker-dev \ - --name gator-pr--supervised \ + --name "$sandbox_name" \ --watch \ --background \ - "Review and monitor PR # through the gator-gate workflow. Scope this invocation only to PR #." + "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}." ``` The launcher builds the gator sandbox image when needed, stages the immutable payload, imports provider profiles, configures provider credentials and refresh, creates the sandbox, and writes a background log under `scripts/agents/gator/logs/`. @@ -120,25 +145,37 @@ The launcher builds the gator sandbox image when needed, stages the immutable pa ### Launch An Issue Or Issue/PR Pair ```bash +issue_number="" +[[ "$issue_number" =~ ^[0-9]+$ ]] || { echo "invalid issue number" >&2; exit 1; } +sandbox_name="gator-issue-${issue_number}-supervised" +[[ "$sandbox_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } + ./scripts/agents/run.sh \ --agent gator \ --gateway docker-dev \ - --name gator-issue--supervised \ + --name "$sandbox_name" \ --watch \ --background \ - "Run gator on issue #. Scope this invocation only to issue #." + "Run gator on issue #${issue_number}. Scope this invocation only to issue #${issue_number}." ``` For a linked pair: ```bash +pr_number="" +issue_number="" +[[ "$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-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } + ./scripts/agents/run.sh \ --agent gator \ --gateway docker-dev \ - --name gator-pr--supervised \ + --name "$sandbox_name" \ --watch \ --background \ - "Review and monitor PR # with linked issue # through the gator-gate workflow. Scope this invocation only to PR # and issue #." + "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 @@ -146,13 +183,18 @@ For a linked pair: Only include authorization in the prompt when the operator explicitly gave it. ```bash +pr_number="" +[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } +sandbox_name="gator-pr-${pr_number}-supervised" +[[ "$sandbox_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } + ./scripts/agents/run.sh \ --agent gator \ --gateway docker-dev \ - --name gator-pr--supervised \ + --name "$sandbox_name" \ --watch \ --background \ - "Review and monitor PR # through the gator-gate workflow. Scope this invocation only to PR #. The operator explicitly authorizes applying the test:e2e label and posting /ok to test for the current head SHA if gator determines that is required." + "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 and posting /ok to test for the current head SHA if gator determines that is required." ``` ## Model Or Image Experiments @@ -160,30 +202,42 @@ Only include authorization in the prompt when the operator explicitly gave it. Use environment overrides. Do not edit `agent.yaml` for temporary experiments. ```bash +pr_number="" +[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } +sandbox_name="gator-pr-${pr_number}-gpt56sol-supervised" +[[ "$sandbox_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } + CODEX_MODEL=gpt-5.6-sol \ ./scripts/agents/run.sh \ --agent gator \ --gateway docker-dev \ - --name gator-pr--gpt56sol-supervised \ + --name "$sandbox_name" \ --watch \ --background \ - "Review and monitor PR # through the gator-gate workflow. Scope this invocation only to PR #. This launch is intentionally testing Codex model gpt-5.6-sol via the CLI launcher." + "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/` under `/var/folders/52/ygrbs0zn7pxgfcppwggvgklm0000gp/T/opencode` or another approved temp directory, adjust only that temporary Dockerfile, and launch with `--from `. Keep the repo Dockerfile unchanged unless the version bump is the intended code change. +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 +pr_number="" +[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; } +sandbox_name="gator-pr-${pr_number}-gpt56sol-supervised" +[[ "$sandbox_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } +tmp_context="$(mktemp -d "${TMPDIR:-/tmp}/gator-codex-XXXXXX")" +cp -R scripts/agents/gator/. "$tmp_context"/ + CODEX_MODEL=gpt-5.6-sol \ ./scripts/agents/run.sh \ --agent gator \ --gateway docker-dev \ - --name gator-pr--gpt56sol-supervised \ - --from /var/folders/52/ygrbs0zn7pxgfcppwggvgklm0000gp/T/opencode/gator-codex- \ + --name "$sandbox_name" \ + --from "$tmp_context" \ --watch \ --background \ - "Review and monitor PR # through the gator-gate workflow. Scope this invocation only to PR #." + "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}." ``` ## Monitoring @@ -231,11 +285,14 @@ Restart when the payload must change, the sandbox is wedged without a sentinel, Before deleting, check that the sandbox is truly stale or that the operator asked for a restart. If a bounded review cycle is actively running and still producing useful output, prefer leaving it alone. ```bash -openshell --gateway docker-dev sandbox delete +sandbox_name="" +[[ "$sandbox_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } + +openshell --gateway docker-dev sandbox delete "$sandbox_name" ./scripts/agents/run.sh \ --agent gator \ --gateway docker-dev \ - --name \ + --name "$sandbox_name" \ --watch \ --background \ "" From 3475f24e8314573507feba7949c7067fe5ad0955 Mon Sep 17 00:00:00 2001 From: John Myers Date: Fri, 10 Jul 2026 09:27:56 -0700 Subject: [PATCH 5/5] docs(agents): avoid assuming gator gateway Signed-off-by: John Myers --- .../skills/launch-openshell-gator/SKILL.md | 64 ++++++++++++++----- 1 file changed, 49 insertions(+), 15 deletions(-) diff --git a/.agents/skills/launch-openshell-gator/SKILL.md b/.agents/skills/launch-openshell-gator/SKILL.md index 939c3a05cd..b903b5840b 100644 --- a/.agents/skills/launch-openshell-gator/SKILL.md +++ b/.agents/skills/launch-openshell-gator/SKILL.md @@ -80,11 +80,16 @@ If this fails, run the local Codex login flow outside the gator launch. If Codex ### Step 5: Verify Gateway Is Registered And Alive -Use the target gateway, usually `docker-dev` for local gators. +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 docker-dev status -openshell --gateway docker-dev sandbox list +openshell gateway list + +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. @@ -94,14 +99,24 @@ Expected result: status returns successfully and sandbox listing completes. If t Avoid duplicate gators for the same PR unless intentionally replacing a stuck or stale one. ```bash -openshell --gateway docker-dev sandbox list +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--supervised`. If one exists, inspect its log before deleting or relaunching. ## Input Normalization -Never paste raw operator text into shell arguments such as `--name`, `--from`, issue numbers, or PR numbers. Normalize values before constructing launch commands. +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="" +[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } +``` Use digits only for issue and PR numbers: @@ -126,14 +141,16 @@ For local image contexts passed to `--from`, use an agent-created path such as ` Use a stable, scoped name and a prompt that names exactly what gator should do. ```bash +gateway_name="" pr_number="" +[[ "$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-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } ./scripts/agents/run.sh \ --agent gator \ - --gateway docker-dev \ + --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ --background \ @@ -145,14 +162,16 @@ The launcher builds the gator sandbox image when needed, stages the immutable pa ### Launch An Issue Or Issue/PR Pair ```bash +gateway_name="" issue_number="" +[[ "$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-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } ./scripts/agents/run.sh \ --agent gator \ - --gateway docker-dev \ + --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ --background \ @@ -162,8 +181,10 @@ sandbox_name="gator-issue-${issue_number}-supervised" For a linked pair: ```bash +gateway_name="" pr_number="" issue_number="" +[[ "$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" @@ -171,7 +192,7 @@ sandbox_name="gator-pr-${pr_number}-supervised" ./scripts/agents/run.sh \ --agent gator \ - --gateway docker-dev \ + --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ --background \ @@ -183,14 +204,16 @@ sandbox_name="gator-pr-${pr_number}-supervised" Only include authorization in the prompt when the operator explicitly gave it. ```bash +gateway_name="" pr_number="" +[[ "$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-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } ./scripts/agents/run.sh \ --agent gator \ - --gateway docker-dev \ + --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ --background \ @@ -202,7 +225,9 @@ sandbox_name="gator-pr-${pr_number}-supervised" Use environment overrides. Do not edit `agent.yaml` for temporary experiments. ```bash +gateway_name="" pr_number="" +[[ "$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-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } @@ -210,7 +235,7 @@ sandbox_name="gator-pr-${pr_number}-gpt56sol-supervised" CODEX_MODEL=gpt-5.6-sol \ ./scripts/agents/run.sh \ --agent gator \ - --gateway docker-dev \ + --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ --background \ @@ -222,7 +247,9 @@ If the installed Codex CLI is too old for a model, create a temporary copy of `s Example shape: ```bash +gateway_name="" pr_number="" +[[ "$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-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } @@ -232,7 +259,7 @@ cp -R scripts/agents/gator/. "$tmp_context"/ CODEX_MODEL=gpt-5.6-sol \ ./scripts/agents/run.sh \ --agent gator \ - --gateway docker-dev \ + --gateway "$gateway_name" \ --name "$sandbox_name" \ --from "$tmp_context" \ --watch \ @@ -262,8 +289,13 @@ Read that file directly. Important markers: ### Inspect Active Sandboxes ```bash -openshell --gateway docker-dev sandbox list -openshell --gateway docker-dev sandbox get +gateway_name="" +sandbox_name="" +[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } +[[ "$sandbox_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } + +openshell --gateway "$gateway_name" sandbox list +openshell --gateway "$gateway_name" sandbox get "$sandbox_name" ``` If `sandbox get` is not supported by the local CLI shape, use `openshell sandbox --help` and follow the current command help. @@ -285,13 +317,15 @@ Restart when the payload must change, the sandbox is wedged without a sentinel, Before deleting, check that the sandbox is truly stale or that the operator asked for a restart. If a bounded review cycle is actively running and still producing useful output, prefer leaving it alone. ```bash +gateway_name="" sandbox_name="" +[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; } [[ "$sandbox_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid sandbox name" >&2; exit 1; } -openshell --gateway docker-dev sandbox delete "$sandbox_name" +openshell --gateway "$gateway_name" sandbox delete "$sandbox_name" ./scripts/agents/run.sh \ --agent gator \ - --gateway docker-dev \ + --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ --background \