fix(miner): validate commit SHA is a safe path segment in replay-snapshot planner (#7796)

[RealDiligent]

Fixes #7796.

Root cause

normalizeCommitSha in packages/loopover-miner/lib/replay-snapshot.ts only trimmed its
input and checked it was non-empty — it applied no format validation. The value then flows
into planReplaySnapshotPath:

return join(input.repoPath, REPLAY_SNAPSHOT_SUBDIR, commitSha);

Because path.join resolves .. segments, a crafted commitSha such as "../../etc" (or any
value containing a path separator) escapes the intended REPLAY_SNAPSHOT_SUBDIR — a real
path-traversal finding. The same unchecked value is also handed to git as a bare revision argument.

Fix approach

Constrain the commit SHA to a single safe path segment, reusing the exact pattern the repo
already established for owner/repo names in repo-clone.ts's isValidRepoSegment (#5831): the
restricted [A-Za-z0-9._-] charset plus an explicit "."/".." rejection. A genuine commit SHA
is hexadecimal and always satisfies this, so no legitimate caller regresses.

The guard is defined locally rather than imported from repo-clone.ts to avoid pulling that
module's heavier dependency graph (process-lifecycle, worktree-allocator) into the snapshot
path for a two-line check; a comment cross-references the canonical definition.

Impact

• Closes the directory-escape vector in the replay-snapshot planner and store.
• Added regression tests assert every traversal payload (../../etc, .., ., a/b, a\b, …)
  throws invalid_commit_sha, and that a real 40-char hex SHA is confined under
  REPLAY_SNAPSHOT_SUBDIR.

Risk / tradeoffs

Minimal and backward-compatible. The charset intentionally matches the existing repo-segment guard
(rather than strict hex) so the change is purely additive safety — it rejects only path-unsafe
values, never any string a real SHA could take. Scope is limited to the two files.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.75%. Comparing base (6a55b8d) to head (0624a03).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/loopover-miner/lib/replay-snapshot.ts	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7992      +/-   ##
==========================================
- Coverage   91.91%   88.75%   -3.16%     
==========================================
  Files         739       95     -644     
  Lines       75850    21958   -53892     
  Branches    23019     3784   -19235     
==========================================
- Hits        69717    19489   -50228     
+ Misses       5041     2291    -2750     
+ Partials     1092      178     -914     

Flag	Coverage Δ
shard-1	0.00% <0.00%> (-58.84%)	⬇️
shard-2	0.00% <0.00%> (-46.84%)	⬇️
shard-3	0.00% <0.00%> (-56.29%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/loopover-miner/lib/replay-snapshot.ts	0.00% <0.00%> (-100.00%)	⬇️

... and 644 files with indirect coverage changes

[loopover-orb]

Caution

🛑 LoopOver review result - fixes required

_{Review updated: 2026-07-22 02:06:13 UTC}

2 files · 1 AI reviewer · no blockers · CI failing · unstable

🛑 Suggested Action - Fix Blockers

Review summary
This PR adds format validation to `normalizeCommitSha` in replay-snapshot.ts, closing a real path-traversal gap where `path.join` would resolve `..` segments in a crafted commitSha, letting the resulting worktree/export path escape `REPLAY_SNAPSHOT_SUBDIR`. The regex `^[A-Za-z0-9._-]+$` plus explicit `.`/`..` rejection correctly blocks all listed traversal payloads while a real hex SHA still passes, and the new tests directly exercise `planReplaySnapshotPath` (the real call site, not a fabricated stand-in) with both malicious and legitimate inputs. The fix is applied at the correct source layer (the shared normalizer used by both the path planner and the store lookups), so downstream `getSnapshot`/`saveSnapshot` calls are protected too.

Nits — 3 non-blocking

• The codecov/patch check failed at 0% reported diff coverage despite the PR adding three new passing tests that exercise every changed line — likely a coverage-tool artifact rather than a real gap, but worth confirming the coverage report picked up the new test file.
• normalizeCommitSha is duplicated from repo-clone.ts's isValidRepoSegment rather than imported; the comment justifies this as avoiding a heavier dependency graph, which is a reasonable but debatable tradeoff worth a maintainer nod rather than silent duplication.
• Consider extracting just the regex/validation constant (not the whole repo-clone module) into a small shared utils file if this pattern gets reused a third time, to avoid drift between the two copies.

CI checks failing

• codecov/patch — 0.00% of diff hit (target 99.00%)

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#7796
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 402 registered-repo PR(s), 170 merged, 36 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 402 PR(s), 36 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The diff adds format validation to normalizeCommitSha that rejects path-traversal-shaped values (charset restriction plus explicit "."/".." rejection) before they reach path.join, and adds regression tests covering traversal payloads as well as valid hex SHAs, directly satisfying the issue's deliverables.

Review context

• Author: RealDiligent
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, Ruby, Svelte, TypeScript, Markdown, MDX
• Official Gittensor activity: 402 PR(s), 36 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver is closing this pull request on the maintainer's behalf (CI is failing (codecov/patch)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.