[freeqaz]

Problem

Two native prepared Git behaviors that an operator meets in the first dogfood session are not documented:

• One repository session admits at most four concurrent Git requests (exchangesPerSession: 4). A fifth concurrent request answers HTTP 503, and Git prints only The requested URL returned error: 503. Six parallel clones from one Agent fail two of them.
• The one-draft allowance of a git-and-draft-pr grant is shared by every Agent and version holding the grant, and is not restored when the draft is closed or its branch deleted. The registry opt-out draftPullLimit: none (accepted by the registry loader since the Credential Proxy release) appears nowhere in docs/ or deploy/.

Change

docs/reference/repository-credentials/prepared-native-git.md: one paragraph on the four-request session limit, and one on the default draftPullLimit: one-per-grant, the operation_conflict answer for a later create, and the draftPullLimit: none opt-out (which changes the grant identity, so a new version must deploy).

Verification

Observed on a k3d install on a remote dogfood host, main 9d6220d, native prepared Git (Kubernetes Compute, dedicated Codex, no Sandbox) against a real GitHub App and a private scratch repository:

• 6 parallel git clone from one Agent: 4 succeed, 2 get HTTP 503; three rounds of 6 parallel git ls-remote: 1 or 2 get 503 per round; 10 sequential pushes all succeed.
• After the Agent deleted its review branch (closing its draft) and pushed it again, a new version's oce-github pr-create --draft got operation_conflict and GitHub received no request. With draftPullLimit: none published and a new version deployed, the same create opened a new draft.
• Limits read from apps/controller/src/drivers/repo/credentials/configuration.ts and service.ts; accepted values from apps/controller/src/drivers/repo/github/credentials/registry.ts.
• prettier --check on the page. Docs only: no tests.

Risks

Docs only. The page stays under the length budget (about 1,100 words).

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs changes before merge.

What this changes

This PR documents the four-request repository session limit and the draft allowance policy.

Example: An operator runs six concurrent Git requests through one Agent repository session.

• Before: The reference does not explain why excess requests return HTTP 503.
• After: The reference states the four-request limit and recommends groups of four or fewer.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	Useful, narrowly scoped documentation with one source-verifiable incorrect recovery recommendation.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes reference prose only; its reported dogfood observations provide context but do not establish repeated native draft creation.
Patch quality	🦪 silver shellfish (2/6)	1 actionable review finding remain.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Operators encounter unexplained HTTP 503 responses and a draft allowance shared across Agent versions.
Reason: The maintainer-authored clarification belongs in the existing reference and provides useful operating limits once the inaccurate native opt-out claim is corrected.

Merge readiness

⛔ Needs changes before merge - 1 item remains

Keep this PR open: the documentation is useful, but its native draft-limit opt-out guidance contradicts the implementation and existing coverage.

Priority: P3
Reviewed head: 2c8f82f0aa24ff75499d34168041121cda42b4cc

Before merge

• Correct the native draft-limit opt-out guidance (P2) - For native prepared Git, setting draftPullLimit to none does not remove the one-draft allowance. The native worker's use() calls recordUse() without installed material, while its unlimited condition requires installed !== undefined. The existing opt-out test also explicitly expects the second native create to return 409. Changing the policy changes the grant fingerprint, which explains the reported first successful create after deployment; another create under that same grant still conflicts. Describe this native limitation and scope the opt-out to the protected sender path rather than promising native recovery through this setting.

Findings

• [P2] Correct the native draft-limit opt-out guidance — docs/reference/repository-credentials/prepared-native-git.md:56-58

Agent review details

How this fits together

Native Git requests enter the repository broker, which enforces session capacity and asks the worker to authorize prepared credential use before contacting GitHub.

flowchart LR
  A[Agent Git client] --> B[Repository broker]
  B --> C[Session capacity]
  C --> D[Prepared credential worker]
  D --> E[Grant receipt storage]
  D --> F[GitHub]

Loading

Technical review

Best possible solution:

Keep the concurrency guidance and describe native Git’s one-draft allowance accurately, distinguishing it from the protected sender opt-out.

Do we have a high-confidence way to reproduce the issue?

The source shows that a second native draft create under the same grant remains limited even with draftPullLimit none, and an existing PostgreSQL test explicitly asserts HTTP 409; no execution was performed.

Is this the best way to solve the issue?

Documenting the limits is appropriate, but the proposed native opt-out explanation mistakes a fresh grant’s first successful create for removal of its allowance.

Full review comments:

• [P2] Correct the native draft-limit opt-out guidance — docs/reference/repository-credentials/prepared-native-git.md:56-58
  For native prepared Git, setting draftPullLimit to none does not remove the one-draft allowance. The native worker's use() calls recordUse() without installed material, while its unlimited condition requires installed !== undefined. The existing opt-out test also explicitly expects the second native create to return 409. Changing the policy changes the grant fingerprint, which explains the reported first successful create after deployment; another create under that same grant still conflicts. Describe this native limitation and scope the opt-out to the protected sender path rather than promising native recovery through this setting.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against b5710af6c76b.

Provenance checked

• Prepared native Git limits and draft allowance keeps the original intent (3115679: The Credential Proxy implementation separates grant scope, prepared credential ownership, and delivery, retaining finite access and original ownership.)

Security

None.

Evidence

Acceptance criteria:

• git diff --check
• pnpm docs:check
• pnpm docs:check-length
• pnpm format:check

What I checked:

• Introduced documentation: The pinned introduction diff adds only eleven documentation lines, including the native draft opt-out recommendation. (docs/reference/repository-credentials/prepared-native-git.md:57, 2c8f82f0aa24)
• Verified concurrency limit: The default exchangesPerSession is four, and reserve returns HTTP 503 when the session reaches that limit. (apps/controller/src/drivers/repo/credentials/service.ts:369, b5710af6c76b)
• Native opt-out does not bypass the allowance: Native use calls recordUse without installed material; the unlimited condition explicitly requires installed material as well as draftPullLimit none. (apps/controller/src/drivers/repo/github/credentials/prepared-repository-git.ts:940, b5710af6c76b)
• Existing test preserves the native distinction: The opt-out scenario permits repeated OpenShell authorizations but explicitly asserts that a second native create returns HTTP 409. (tests/integration/postgres-prepared-github-git-use.test.mjs:638, b5710af6c76b)
• Policy change explains the reported successful create: draftPullLimit participates in the grant fingerprint, so changing it produces a fresh grant with a fresh native allowance; one successful create after deployment does not prove repeated native creates. (apps/controller/src/drivers/repo/github/credentials/registry.ts:372, b5710af6c76b)
• Feature provenance and discussion: Credential Proxy Implementation #2487 introduced the prepared credential implementation and this reference page. Its recorded direction preserves grant scope and original ownership; the current PR has only bot discussion and no separate approval changing native allowance behavior. (docs/reference/repository-credentials/prepared-native-git.md:28, 31156790238d)

Labels

Label changes:

• add P3: This is a focused documentation correction with no runtime changes.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🌊 off-meta tidepool and patch quality is 🦪 silver shellfish.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.

Label justifications:

• P3: This is a focused documentation correction with no runtime changes.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🌊 off-meta tidepool and patch quality is 🦪 silver shellfish.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 25, 2026, 1:08 AM ET / 05:08 UTC.