docs(pegboard-runner): explain alloc idx eviction invariant

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(sqlite-native): replace stderr sql trace logging #4629
• fix(pegboard): repair follow-up build errors #4628
• docs(pegboard-runner): explain alloc idx eviction invariant #4626 👈 (View in Graphite)
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4630 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: docs(pegboard-runner): explain alloc idx eviction invariant

This is a documentation-only change adding two comment lines to clarify a subtle synchronization invariant in the pegboard-runner disconnect logic.

Summary

The added comment explains why alloc idx is intentionally not cleared when a runner disconnects via eviction: the replacement connection (which reuses the same runner_id) would have already rewritten the alloc idx, so clearing it here would introduce a race condition against the new connection.

Feedback

Correctness: The explanation is accurate and helpful. The comment correctly describes the invariant that needs to hold to avoid a race between the outgoing and incoming connections sharing a runner_id.

Comment style: Per CLAUDE.md conventions, comments should be written as normal, complete sentences and should avoid dashes (hyphens are OK). The added comment uses a comma to join two related ideas, which reads naturally. No issues here.

Comment placement: The comment is placed at the top of the else block (the non-evicted path), which is the right location — it explains why the block only runs in the non-evicted case, complementing the if condition on line 238.

Minor suggestion: The comment could lead with the condition to mirror the symmetric if branch above more clearly. For example:

// If evicted, the replacement connection already rewrote the alloc idx under the same
// runner_id. Clearing it here would race the new connection.

This is purely optional — the current wording is clear.

No functional, performance, or security concerns. This is a pure documentation change with no behavioral impact.

Overall: looks good to merge once out of draft.