What happened
The code agent vendored pi-xai-vertex v0.1.0 into the sandbox Containerfile as specified by issue #6571. The v0.1.0 release used auth.oauth, which requires interactive credential persistence — incompatible with the ephemeral sandbox where every run starts fresh. The human reviewer (waynesun09) discovered this only by building the sandbox image and running the extension end-to-end, at which point every invocation failed. This was the most expensive rework item: testing v0.1.0, diagnosing the auth failure, finding v0.2.0 as the fix, recomputing the SHA256 hash, and re-verifying. The existing docs/contributing/runtime-implementation.md (created in this PR) embeds ephemeral-environment considerations throughout its text but has no consolidated, scannable checklist for vendored-dependency verification.
What could go better
A dedicated checklist in docs/contributing/runtime-implementation.md would give both agents and humans a quick reference when vendoring new dependencies into the sandbox. The current document is thorough but its guidance is spread across multiple sections — the ephemeral-auth constraint, SHA256 pinning, env-var hygiene, and permission lockdown are all covered but not in a single scannable location. I'm fairly confident this would help because: (1) the code agent reads contributing docs during planning and a checklist is more actionable than embedded prose, (2) the human reviewer's verification steps closely match what such a checklist would contain, and (3) this PR itself demonstrates the failure mode. One uncertainty: the code agent might still skip checklist items if the issue specification contradicts them (as it did with v0.1.0), so this works best in combination with external-repo exploration (Proposal 1).
Proposed change
Add a "Vendored dependency checklist" section to docs/contributing/runtime-implementation.md containing items such as: (1) Verify the dependency's auth model works without persisted credentials or interactive prompts — the sandbox is ephemeral, (2) Verify the pinned version's tarball URL is reachable and the SHA256 matches, (3) Check the dependency's changelog/release notes for breaking changes between the specified version and the latest, (4) Confirm file permissions: extension dirs and parent should be read-only (555 root) to the sandbox user, (5) Verify env-var hygiene: unset any credentials that could leak across providers, set project/region defaults conditionally (not unconditionally), (6) Run the extension end-to-end in a sandbox build before merging. This checklist consolidates guidance already present in the document into a quick-reference format.
Validation criteria
The next PR that vendors a new pi extension or bumps an existing extension version should reference this checklist in its verification steps. The code agent should read the checklist during planning and either follow it or flag items it cannot verify. Measure by checking whether the PR description or agent transcript references the checklist items within the next 2 extension-vendoring PRs.
Generated by retro agent from #6572
What happened
The code agent vendored
pi-xai-vertexv0.1.0 into the sandbox Containerfile as specified by issue #6571. The v0.1.0 release usedauth.oauth, which requires interactive credential persistence — incompatible with the ephemeral sandbox where every run starts fresh. The human reviewer (waynesun09) discovered this only by building the sandbox image and running the extension end-to-end, at which point every invocation failed. This was the most expensive rework item: testing v0.1.0, diagnosing the auth failure, finding v0.2.0 as the fix, recomputing the SHA256 hash, and re-verifying. The existingdocs/contributing/runtime-implementation.md(created in this PR) embeds ephemeral-environment considerations throughout its text but has no consolidated, scannable checklist for vendored-dependency verification.What could go better
A dedicated checklist in
docs/contributing/runtime-implementation.mdwould give both agents and humans a quick reference when vendoring new dependencies into the sandbox. The current document is thorough but its guidance is spread across multiple sections — the ephemeral-auth constraint, SHA256 pinning, env-var hygiene, and permission lockdown are all covered but not in a single scannable location. I'm fairly confident this would help because: (1) the code agent reads contributing docs during planning and a checklist is more actionable than embedded prose, (2) the human reviewer's verification steps closely match what such a checklist would contain, and (3) this PR itself demonstrates the failure mode. One uncertainty: the code agent might still skip checklist items if the issue specification contradicts them (as it did with v0.1.0), so this works best in combination with external-repo exploration (Proposal 1).Proposed change
Add a "Vendored dependency checklist" section to
docs/contributing/runtime-implementation.mdcontaining items such as: (1) Verify the dependency's auth model works without persisted credentials or interactive prompts — the sandbox is ephemeral, (2) Verify the pinned version's tarball URL is reachable and the SHA256 matches, (3) Check the dependency's changelog/release notes for breaking changes between the specified version and the latest, (4) Confirm file permissions: extension dirs and parent should be read-only (555 root) to the sandbox user, (5) Verify env-var hygiene: unset any credentials that could leak across providers, set project/region defaults conditionally (not unconditionally), (6) Run the extension end-to-end in a sandbox build before merging. This checklist consolidates guidance already present in the document into a quick-reference format.Validation criteria
The next PR that vendors a new pi extension or bumps an existing extension version should reference this checklist in its verification steps. The code agent should read the checklist during planning and either follow it or flag items it cannot verify. Measure by checking whether the PR description or agent transcript references the checklist items within the next 2 extension-vendoring PRs.
Generated by retro agent from #6572