AGENTS.md git:20261004.56c6cdeA

Immutable. This exact content never changes and is served at /api/v1/blob/3186c0379f5d8c59.

# Agent notes

## GitHub access from a managed Codex worktree

`gh` and HTTPS GitHub access are already authenticated in this environment. Do not print, copy, or
attempt to recover credentials. Read-only commands such as `gh pr view`, `gh api`, `git status`, and
`git log` should work directly.

The recurring Git failure in Codex-managed worktrees is usually **not an authentication failure**.
The worktree's `.git` file points at shared metadata under the original checkout, for example:

```text
/Users/.../git/context-guru/.git/worktrees/...
```

That location is outside the worktree's writable sandbox. Commands that update Git metadata
(`git switch`, `git add`, `git commit`) therefore request escalation. If
`approvals_reviewer = "auto_review"` is configured while the gateway cannot serve the exact
`codex-auto-review` model, escalation fails with HTTP 403 before the command runs.

The user-level fix is to remove that setting from `~/.codex/config.toml`, or set:

```toml
approvals_reviewer = "user"
```

Then restart Codex. Do not modify user configuration unless the user explicitly asks.

### Safe fallback for creating or updating a PR

When the shared Git metadata remains unwritable, use a clean temporary clone. This stays within the
writable `/tmp` root and uses the existing GitHub authentication:

```sh
pr_tmp=$(mktemp -d /tmp/context-guru-pr.XXXXXX)
git clone https://github.com/rossoctl/context-guru.git "$pr_tmp"
git -C "$pr_tmp" switch -c feat/<topic>
```

Copy only the reviewed task files from the Codex worktree into the clone. Preserve paths and modes,
and exclude generated files such as `__pycache__`; do not blindly copy the whole dirty worktree.
Run the relevant tests and `git diff --check` in the clone, then commit with DCO sign-off:

```sh
git -C "$pr_tmp" add <explicit-paths>
git -C "$pr_tmp" commit --signoff -m '<message>'
git -C "$pr_tmp" push -u origin feat/<topic>
gh pr create --repo rossoctl/context-guru --base main --head feat/<topic> \
  --title '<title>' --body '<body>'
```

For later PR updates, reuse the same temporary clone, copy only the changed files, test, commit with
`--signoff`, and run `git -C "$pr_tmp" push`. If commits must be rewritten solely to add DCO
trailers, use `git rebase --signoff` and `git push --force-with-lease`, never an unrestricted force
push.

The local credential helper may print warnings that its configured binary is missing. A push that
ends with a successful `To https://github.com/rossoctl/context-guru.git` ref update still succeeded;
verify with `gh pr view` rather than treating the helper warning alone as failure.

This fallback does not broaden authorization: only create branches, push commits, open issues/PRs,
or post review replies when the user has requested those GitHub mutations.

### Interpret command failures before retrying GitHub mutations

Some nonzero exits are local reporting errors, not failed GitHub operations:

- `gh pr checks` exits 8 while any check is **pending**. Read the per-check status or use
  `gh run view`; do not report a test failure unless a check concludes `failure`.
- A `gh api -X POST` can succeed on GitHub and then fail locally while formatting its reply.
  For example, `--jq id` is invalid; use `--jq '.id'`. Before retrying a comment or reply,
  list PR comments and check `in_reply_to_id` and body so a formatting error does not create
  duplicate posts.
- The credential-helper warnings described above do not reverse a successful Git ref update.
  Verify the remote commit or PR head before attempting another push.

## Eval-box access from a managed Codex sandbox

The `cgssh2` wrapper reaches the eval box (`contextguru2.vpc.cloud9.ibm.com`) only when the
command runs **outside** the local filesystem/network sandbox. Inside the sandbox, SSH can fail
with `Could not resolve hostname ...`; this is a sandbox DNS restriction, not an SSH or API-key
failure. Do not repeatedly retry the same sandboxed command or change credentials to fix it.

For an authorized eval-box task, invoke `/Users/davidamid/cgssh2 '<remote command>'` with
`sandbox_permissions: "require_escalated"` on the command tool, and briefly explain that the
escalation permits the known eval-box SSH connection. Request approval if prompted. Use the same
pattern when piping only explicitly selected files to the remote worktree for testing. On that
box, Go is available at `/usr/local/go/bin/go`. Never print or copy credentials as a workaround.

The eval box may not have `rg`; use `grep` there when needed. A selected-file copy under `/tmp`
has no Git metadata, so Go commands that inspect VCS state can fail with `error obtaining VCS
status` even though the source compiles. Pass `-buildvcs=false` to both `go list` and `go test`
in that test copy. If a pipeline produces no package names, `xargs` may otherwise invoke `go
test` in the repository root and print a misleading `no Go files` error. Check the upstream
command's exit status before treating that as a package-test failure.