Lock a Git Worktree Before Gateway Changes Go to Review

Last reviewed: 2026-07-20

Direct answer

Lock the gateway experiment worktree before the review agent starts moving changes into a pull request. Treat the lock as a visible stop sign around that checkout: the experiment branch stays available for inspection, but it is not the place where the next agent should keep editing, moving, or cleaning up files. Then move review-ready changes through a separate worktree and record only gateway checks that are supported by the current public references.

A reliable handoff has three parts: a locked experiment worktree, a separate review worktree, and a small smoke-test record that says what was checked without claiming more than the linked API references support. For the broader isolation pattern, see Use Git Worktrees to Keep Parallel Coding Agents Isolated . For the pull request handoff side, pair this workflow with How to Hand Off Coding Agent Pull Requests for Review .

Start with CometAPI when the agent workflow needs a gateway candidate to verify against the current API references.

Who this is for

This guide is for maintainers running more than one coding agent against the same repository, especially when one agent is experimenting with gateway wiring while another prepares a pull request. It assumes the repository already uses Git branches, linked worktrees, and a pull request workflow for review.

It is also useful when a model gateway change must be inspected without letting cleanup, branch movement, or follow-up edits erase the evidence another reviewer needs. The goal is not to make a locked worktree permanent. The goal is to preserve the experiment long enough for a separate review path to produce a clean, reviewable diff.

Use this pattern when the experiment checkout contains gateway configuration, adapter code, request fixtures, or sanitized logs that explain why a change exists. Do not use it to hide messy work from review. The review branch should still be small, intentional, and easy to inspect.

Key takeaways

• Git worktrees let one repository have more than one working tree, so parallel agents can work without sharing the same checkout.
• A locked worktree is useful when the checkout should not be pruned, moved, or deleted while it still carries evidence.
• Pull request review should happen from a review branch with clean scope, not from a frozen experiment checkout.
• Gateway smoke tests should verify only request construction, expected response shape, and safe error handling that the linked API references support.
• Do not assert model availability, prices, quotas, latency, uptime, billing behavior, or exact account permissions from a local smoke test.
• Keep the handoff boring: paths, branch names, commit identifiers, source URLs, pass/fail fields, and uncertainty notes are more useful than broad claims.

Smoke-test workflow

Setup assumptions:

• The experiment worktree already exists and contains gateway changes worth preserving.
• A separate review worktree or branch is available for pull request preparation.
• The operator has a valid local credential stored outside the repository and represented in examples only as <API_KEY_PLACEHOLDER>.
• The exact endpoint family, credential header format, request fields, and response fields are copied from the current linked CometAPI reference before the test runs.
• The pull request branch is meant to carry only the files needed for review, not every scratch file from the experiment checkout.

Happy-path request plan:

1. In the review worktree, prepare one minimal gateway request using the endpoint family selected from the current CometAPI chat or responses reference.
2. Use a harmless placeholder input, a non-secret credential placeholder in documentation, and the smallest response inspection needed to confirm that the gateway adapter can send a request and parse a returned object.
3. Record the endpoint family, docs URL, branch name, worktree path, commit SHA, and pass/fail result.
4. Compare the review branch diff with the experiment checkout so accidental cleanup, temporary debug files, or unrelated edits do not slide into the pull request.

Error-path check:

1. Run one intentionally invalid credential check in a non-production environment.
2. Confirm that the gateway adapter reports a controlled failure without printing secrets, full prompts, or full response bodies.
3. Record the error category using a sanitized label, not a copied private response.
4. Leave provider-specific assumptions out of the handoff unless the current linked source directly supports them.

Minimum assertions:

• The locked experiment worktree remains present and identifiable.
• The review branch contains only intended files for the pull request.
• The request plan follows the current linked API reference.
• The failure path does not expose credentials or sensitive payloads.
• The handoff identifies which source URL was used for each contract area.

What not to assert:

• Do not claim a specific model is available unless the linked source directly supports that exact claim.
• Do not claim a price, quota, rate limit, latency target, billing outcome, or uptime result.
• Do not treat a single smoke test as production readiness.
• Do not treat a locked worktree as a substitute for a clear pull request description.

Sanitized log-record template:

worktree_path: "../gateway-experiment-placeholder"
worktree_lock_reason: "preserve gateway experiment while review branch is prepared"
review_branch: "review/gateway-change-placeholder"
commit_sha: "<COMMIT_SHA_PLACEHOLDER>"
api_reference_url: "https://apidoc.cometapi.com/api/text/responses"
credential_used: "<API_KEY_PLACEHOLDER>"
happy_path_result: "pass|fail"
error_path_result: "pass|fail"
observed_response_shape: "object-present|not-checked"
secret_exposure_check: "pass|fail"
notes: "sanitized operator note"

Sources checked

• Git worktree documentation - accessed 2026-07-20; purpose: verify parallel worktree isolation commands and constraints.
• GitHub pull requests documentation - accessed 2026-07-20; purpose: verify pull request review and collaboration boundaries.
• CometAPI chat completions reference - accessed 2026-07-20; purpose: verify chat completion contract areas.
• CometAPI responses reference - accessed 2026-07-20; purpose: verify responses endpoint contract areas.

Contract details to verify

Failure modes

• Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
• Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
• Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
• Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
• Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.
• Lock confusion: the team assumes a locked worktree means no one can edit files inside it. The practical purpose here is preservation and review discipline; the team still needs branch naming, ownership notes, and a clean pull request path.
• Source overreach: the smoke-test result is expanded into claims about price, availability, limits, latency, or production reliability. Keep those claims out unless a current public source and a broader verification plan support them.

Reader next step

Before the next review window, choose one gateway experiment worktree and write down its path, branch, commit SHA, and lock reason. Create or update a separate review worktree for the pull request branch, then compare the two checkouts before opening the pull request. The review branch should include the intended gateway changes, a short explanation of why they are needed, and a sanitized smoke-test record that points to the exact public source URLs used for the request contract.

If the review branch needs CometAPI verification, open the current chat or responses reference first, copy only the fields that apply to your adapter, and keep credentials represented as <API_KEY_PLACEHOLDER> in all notes. Use the same UTM-tagged CometAPI entry point from this guide if you are setting up a new gateway path: Start with CometAPI .

For a stronger handoff, add a short scope note before the pull request. The checklist in Write Change Scope Notes Before an Agent Pull Request is a good companion when the reviewer needs to separate preserved experiment evidence from the actual diff under review.

FAQ

Why lock the experiment worktree?

Lock it when the checkout still carries evidence another reviewer may need. The lock helps prevent accidental cleanup, movement, or pruning while review work continues elsewhere.

Should the pull request come from the locked worktree?

Usually no. Keep the locked checkout available for inspection and prepare the pull request from a separate review branch or worktree with a clean diff.

Can the smoke test prove the gateway is production-ready?

No. It can show that a narrow request path and a narrow error path behaved as expected during the check. Production readiness needs broader verification.

Can I include real credentials in the handoff note?

No. Use a placeholder such as <API_KEY_PLACEHOLDER> in examples and keep real credentials outside committed files and review comments.

Which CometAPI endpoint should the workflow use?

Use the endpoint family that matches the current gateway adapter and verify the exact request contract in the linked CometAPI reference before running the test.

What should I do after the review branch is ready?

Open the pull request from the review branch, link the preserved experiment worktree in your private operator notes if your team uses them, and include only sanitized evidence in the pull request description. Keep the experiment checkout locked until the reviewer confirms they no longer need it.