fix(miner): guard repo-clone across sibling processes with a cross-process lockfile

[bitfathers94]

fix(miner): guard repo-clone across sibling processes with a cross-process lockfile

ensureRepoCloned's per-repo serialization (#6762) was an in-process Map, so
two fleet-mode containers sharing the same clone volume each started with an
empty Map and could run git checkout/reset --hard on the same base clone at
once, corrupting the working tree or tripping .git/index.lock.

Take an OS-level exclusive lockfile (open(path, 'wx')) on a deterministic path
beside the clone before any git mutation, held for the whole clone/fetch/
checkout/reset sequence and released on error. A losing process waits, bounded
by a timeout that fails closed with repo_clone_lock_timeout; a lock left by a
crashed process self-expires after a stale window (age-based reclaim, mirroring
worktree-allocator.js) and is registered as a process-lifecycle cleanup
resource so SIGINT/SIGTERM drops it on a clean exit (mirroring local-store.js).
The in-process Map is retained, so same-process calls stay at least as safe.

Closes #7084

[superagent-security]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.76%. Comparing base (a624234) to head (09097be).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7139   +/-   ##
=======================================
  Coverage   93.75%   93.76%           
=======================================
  Files         692      692           
  Lines       68853    68913   +60     
  Branches    18781    18781           
=======================================
+ Hits        64556    64616   +60     
  Misses       3302     3302           
  Partials      995      995           

Flag	Coverage Δ
shard-1	43.31% <6.55%> (-0.46%)	⬇️
shard-2	36.84% <6.55%> (-0.09%)	⬇️
shard-3	33.16% <6.55%> (+0.03%)	⬆️
shard-4	34.46% <100.00%> (-0.01%)	⬇️
shard-5	31.72% <6.55%> (-0.58%)	⬇️
shard-6	46.14% <6.55%> (+0.22%)	⬆️

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

Files with missing lines	Coverage Δ
packages/loopover-miner/lib/repo-clone.js	100.00% <100.00%> (ø)

[loopover-orb]

Caution

🛑 LoopOver review result - reject/close recommended

_{Review updated: 2026-07-18 00:19:30 UTC}

3 files · 1 AI reviewer · 1 blocker · CI green · clean

🛑 Suggested Action - Reject/Close

Review summary
This adds a real OS-level exclusive lockfile (open with 'wx') to serialize ensureRepoCloned across sibling fleet-mode processes, layered on top of the existing in-process Map guard, with stale-lock reclaim, a bounded timeout that fails closed, and cleanup-on-signal registration. The mechanism is well-tested for the single-acquirer paths (fresh acquire, timeout, TOCTOU on read, non-Error stringification), but the stale-lock reclaim path itself has a TOCTOU race that can let two processes both 'win' the lock simultaneously — the exact failure mode this PR exists to prevent.

Blockers

• packages/loopover-miner/lib/repo-clone.js forceUnlinkLock/acquireRepoCloneLock: when a lock is judged stale, forceUnlinkLock unconditionally unlinks the path without re-verifying the content still matches what was read as stale, so if two waiters both read the same stale lock and race to reclaim, the second unlink can delete the FIRST winner's freshly-written live lock (written moments earlier in the same loop iteration by the first winner), after which the second waiter's next `open` also succeeds — both processes end up believing they hold the exclusive lock, defeating the cross-process guarantee this PR is meant to provide; the added tests only exercise a single acquirer reclaiming a stale lock, never two concurrent reclaimers, so this race is untested.

Nits — 5 non-blocking

• packages/loopover-miner/lib/repo-clone.js: mkdirSync(..., {mode:0o700}) for the owner dir is now done both in the ensureRepoCloned wrapper (for the lockfile) and again inside ensureRepoClonedUnlocked (for the clone) — harmless but duplicated, consider factoring into one call.
• The default staleMs (15min) vs default timeoutMs (10min) combination means a waiter will time out with repo_clone_lock_timeout before it would ever consider the other side's lock stale on a slow clone/fetch; worth a comment noting these two are intentionally independent knobs.
• readExistingLock treats ANY read failure (not just ENOENT) as 'lock vanished, reclaimable' — a transient EACCES/EIO would also be treated as reclaimable rather than surfaced, which is a looser interpretation than forceUnlinkLock's own error handling a few lines below.
• Make stale-lock reclaim compare-and-delete safe: e.g. re-read the lock immediately before unlinking and only unlink if the content (or acquiredAtMs) is unchanged from the staleness check, or unlink by inode/fd where possible, to close the double-acquire race under concurrent reclaimers.
• Add a test with two concurrent acquireRepoCloneLock calls racing to reclaim the same stale lock, asserting only one ends up holding it — this is the scenario the current single-acquirer stale test doesn't cover.

Why this is blocked

• packages/loopover-miner/lib/repo-clone.js forceUnlinkLock/acquireRepoCloneLock: when a lock is judged stale, forceUnlinkLock unconditionally unlinks the path without re-verifying the content still matches what was read as stale, so if two waiters both read the same stale lock and race to reclaim, the second unlink can delete the FIRST winner's freshly-written live lock (written moments earlier in the same loop iteration by the first winner), after which the second waiter's next `open` also succeeds — both processes end up believing they hold the exclusive lock, defeating the cross-process guarantee this PR is meant to provide; the added tests only exercise a single acquirer reclaiming a stale lock, never two concurrent reclaimers, so this race is untested.

📋 Copy for AI agents — paste into your coding agent

Fix the following blocker(s) from this PR review:

1. packages/loopover-miner/lib/repo-clone.js forceUnlinkLock/acquireRepoCloneLock: when a lock is judged stale, forceUnlinkLock unconditionally unlinks the path without re-verifying the content still matches what was read as stale, so if two waiters both read the same stale lock and race to reclaim, the second unlink can delete the FIRST winner's freshly-written live lock \(written moments earlier in the same loop iteration by the first winner\), after which the second waiter's next \`open\` also succeeds — both processes end up believing they hold the exclusive lock, defeating the cross-process guarantee this PR is meant to provide; the added tests only exercise a single acquirer reclaiming a stale lock, never two concurrent reclaimers, so this race is untested.

Decision drivers

• ❌ Code review — 1 blocker (1 reviewer)
• ❌ Gate result — Blocking (Repo-configured hard blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#7084
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	⚠️ 20/25	Preflight is ready, but the PR body does not name the validation run.
Contributor workload	✅ 10/10	Author activity: 23 registered-repo PR(s), 15 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	bitfathers94; Gittensor profile; 23 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: significant

Linked issue satisfaction

Addressed
The diff adds an OS-level exclusive lockfile (open with 'wx') keyed on the resolved repoPath, acquired before git mutations, with bounded wait/timeout (repo_clone_lock_timeout), stale-lock reclaim, crash-safe cleanup via registerCleanupResource, and retains the existing in-process Map lock as required. It includes a real cross-process regression test proving the second independent acquirer blocks

Review context

• Author: bitfathers94
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 23 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Add validation command/output.

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 (AI reviewers agree on a likely critical defect: packages/loopover-miner/lib/repo-clone.js forceUnlinkLock/acquireRepoCloneLock: when a lock is judged stale, forceUnlinkLock unconditionally unlinks the path without re-verifying the content still matches what was read as stale, so if two waiters both read the same stale lock and race to reclaim, the second unlink can delete the FIRST winner's freshly-written live lock (written moments earlier in the same loop iteration by the first winner), after which the second waiter's next `open` also succeeds — both processes end up believing they hold the exclusive lock, defeating the cross-process guarantee this PR is meant to provide; the added tests only exercise a single acquirer reclaiming a stale lock, never two concurrent reclaimers, so this race is untested.). 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.