feat(miner-concurrency): add git-worktree-per-attempt pool allocator (#4297)

[dhgoal]

Adds the git-worktree pool allocator (Closes #4297) — complementary to the isolation primitive (worktree-allocator.ts, #4269, already merged): that plans/creates/tears down ONE worktree; this manages the POOL of them across concurrent fleet attempts.

New packages/gittensory-engine/src/miner/worktree-pool.ts:

• acquireWorktree(state, config, {attemptId, repoPath}) — allocates a slot under a configurable maxConcurrency cap; fails without mutating on already_allocated (idempotency guard) or at_capacity. Each slot's path/branch comes from the primitive's planWorktree.
• releaseWorktree(state, attemptId) — frees the slot for reuse (idempotent).
• reclaimOrphanedWorktrees(state, liveAttemptIds) — frees + returns allocations whose attempt is no longer live (so a crash can't leak worktree slots forever).
• availableWorktreeSlots / isWorktreeAllocated helpers.

Per #4297's split option, the pure allocation logic lives in gittensory-engine so it's unit-testable without a real filesystem or DB; the SQLite-bookkeeping wrapper that persists WorktreePoolState (the claim-ledger.js/run-state.js pattern) is a thin miner-package layer. No IO here — state in, new state out.

Test

test/unit/miner-worktree-pool.test.ts — acquire (deterministic plan), already_allocated + at_capacity (both no-mutation), release + freed capacity + unknown-attempt no-op, orphan reclamation + all-live no-op, and the slots-clamp-at-0 case. Mirrors the primitive's test (imports engine src via vitest).

• Conventional Commit; focused; Closes feat(miner-concurrency): add git-worktree-per-attempt allocator #4297. No site//CNAME/**/lovable/**; no CHANGELOG.md. New engine module + test + one entrypoint export; no secrets.

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[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 94.13%. Comparing base (63d5a0f) to head (fc177e0).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4598   +/-   ##
=======================================
  Coverage   94.12%   94.13%           
=======================================
  Files         430      431    +1     
  Lines       38181    38198   +17     
  Branches    13922    13927    +5     
=======================================
+ Hits        35939    35956   +17     
  Misses       1585     1585           
  Partials      657      657           

Files with missing lines	Coverage Δ
...kages/gittensory-engine/src/miner/worktree-pool.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-10 07:46:50 UTC}

3 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · unstable

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds a pure, in-memory pool-allocator (acquire/release/reclaim under a maxConcurrency cap) on top of the already-merged single-worktree primitive (worktree-allocator.ts, #4269), exported via a barrel `export *`, closing the linked issue #4297 as described. The logic is correct and side-effect-free: already_allocated and at_capacity both fail without mutating state, release and reclaim are idempotent, and availableWorktreeSlots clamps at 0 including for a non-positive maxConcurrency — all consistent with the primitive's planWorktree naming/collision guarantees. Tests exercise every branch (acquire, both failure reasons with no-mutation checks, release incl. unknown-attempt no-op, reclaim incl. all-live no-op, and the clamp-at-0 case), and the new export names don't collide with anything else in the barrel file shown.

Nits — 4 non-blocking

• worktree-pool.ts has no explicit test for a non-positive `maxConcurrency` (0 or negative) even though the doc comment calls out that behavior — worth one assertion given it's a documented edge case.
• The `export * from "./miner/worktree-pool.js"` in index.ts:213 is a wildcard while every other entry in this barrel is a named export list — for consistency with the rest of the file (and to avoid a future silent name collision as new pool exports are added) consider naming the exports explicitly, matching the `worktree-allocator.js` block right above it.
• Add a case for `acquireWorktree` with `maxConcurrency: 0` to lock in the 'non-positive cap allocates nothing' contract mentioned in the WorktreePoolConfig doc comment.
• Convert the `export *` in packages/gittensory-engine/src/index.ts:213 to an explicit named list mirroring the worktree-allocator.js export block for consistency with the rest of the barrel.

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4297
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: 85 registered-repo PR(s), 52 merged, 7 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	dhgoal; Gittensor profile; 85 PR(s), 7 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Partially addressed
The PR delivers the pure, unit-testable pool-allocation logic (acquire/release/reclaim, cap enforcement, tests) in gittensory-engine, which is an explicitly allowed split per the issue, but the diff shown contains no miner-package SQLite-bookkeeping wrapper (packages/gittensory-miner) implementing the required durable persistence (local SQLite, chmodSync 0o600, busy_timeout pragma) that the issue

Review context

• Author: dhgoal
• 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: 85 PR(s), 7 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.

_{🟩 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 Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.