Document EXECUTOR_DIR script-flattening constraint in hack/gitlab-runner-vm #7252

What happened

In PR #7244, install_executor (hack/gitlab-runner-vm/setup.sh:660-688) copies job_id.sh/prepare.sh/run.sh/cleanup.sh/gateway.sh into a flat EXECUTOR_DIR with no .github/scripts sibling. The code agent's round-1 security fix (commit a9e29aa) added logic to gateway.sh that located .github/scripts/openshell-version.sh via two BASH_SOURCE-relative guesses (VM source-tree layout and repo-checkout layout), neither of which matches the flattened runtime layout install_executor actually produces. This meant OPENSHELL_VERSION/OPENSHELL_SHA would be unset in production, breaking every version-mismatch job — exactly the scenario #7218 was filed to fix. The review agent caught this in round 2 (finding on commit a9e29aa, ~17 min review), and the fix agent resolved it in commit 81fb8b0 by copying the pin file into the flattened EXECUTOR_DIR/.github/scripts/ and adding a regression test (hack/gitlab-runner-vm/executor/gateway_test.sh:70-103) that sources gateway.sh from an isolated flattened-layout temp dir.

What could go better

This cost one extra review round (~17 min) and one extra fix round (~10 min) — not large in isolation, but it is a repeatable class of mistake: any new script added under hack/gitlab-runner-vm/executor/ that reaches for a file outside its own directory via a guessed relative path can silently break once install_executor flattens it, and this constraint currently exists only as inline comments in gateway.sh and a single regression test — there is no README or docs/contributing/ note that surfaces it to a contributor (human or agent) before they write the code. I verified (via subagent search) that job_id.sh, prepare.sh, run.sh, and cleanup.sh are currently safe because they only reference same-directory siblings, so today's blast radius is limited to gateway.sh specifically — but the underlying trap (guessing a path across a flattening boundary) is not documented anywhere a future contributor would see it before hitting the same review cycle. I am confident this exact gap existed and caused rework in this PR; I have lower confidence about how often new scripts get added to this directory, so the future-recurrence risk is speculative.

Proposed change

Add a short section to hack/gitlab-runner-vm/README.md (create the file if it does not exist, or add a section if it does) titled something like 'Executor script layout' that states: install_executor (setup.sh) copies executor/*.sh into a flat EXECUTOR_DIR at runtime with no preserved parent directories except explicitly-seeded ones (currently only .github/scripts/openshell-version.sh); any script added to executor/ that needs a file outside its own directory must either (a) reference only same-directory siblings, or (b) have install_executor explicitly seed the needed file into EXECUTOR_DIR, mirroring the openshell-version.sh precedent. Cross-link this section from the comment block at the top of gateway.sh (lines ~17-36) so someone reading the code lands on the doc too.

Validation criteria

The README section exists and is linked from gateway.sh's fallback-resolution comment. If a future PR adds a new script under hack/gitlab-runner-vm/executor/ that reads a file outside its own directory via a relative-path guess (rather than an explicit install_executor seed), the review agent or a human reviewer should be able to cite this doc directly instead of re-deriving the flattening constraint from scratch — track this by checking whether the next such PR's review cycle resolves in one round instead of two.

Generated by retro agent from #7244