feat(miner): add lease + expiry sweep to reclaim stuck portfolio-queue items

[nickmopen]

Summary

Portfolio-queue items were flipped to in_progress with no lease and no expiry sweep, so a crashed or killed process left an item stuck in_progress forever with no automated recovery — unlike the sibling stores in the same package (claim-ledger and worktree-allocator), which already solve exactly this for their own tables.

This adds a lease + expiry sweep to the portfolio-queue store, mirroring the existing claim-ledger-expiry pattern:

• leased_at column on miner_portfolio_queue, stamped with the claim time when an item is flipped to in_progress (both dequeueNext and batchClaim) and cleared back to NULL when it leaves in_progress (done / failed / reclaimed). Idempotently migrated onto pre-existing stores (CREATE TABLE IF NOT EXISTS never adds a column, so a guarded ALTER TABLE ... ADD COLUMN).
• store.listInProgress() (lease-annotated rows) and store.reclaimStuckItem() (atomic in_progress → queued, clearing the lease) — the store half of the sweep.
• portfolio-queue-expiry.js — a pure module (findStuckItems + sweepStuckItems), a direct mirror of claim-ledger-expiry.js: reclaim in-flight items whose lease age strictly exceeds a bound (default 30 min), leaving fresh / non-in_progress / unparseable-lease rows untouched.

The base QueueEntry shape every existing caller relies on is unchanged — lease data rides a separate QueueLeaseEntry projection — so no existing consumer or test changes.

Anchored on two existing analogues in the same package: claim-ledger-expiry.js (the sweep shape) and worktree-allocator.js / claim-ledger.js (the store-level expiry the issue cites).

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves — Closes #4827.

Validation

• git diff --check
• npm run build:miner (node --check, incl. the new portfolio-queue-expiry.js)
• npm run test:miner-pack (tarball hygiene — new lib/portfolio-queue-expiry.{js,d.ts} packaged)
• npx vitest run on the changed area — 41 tests pass: the new miner-portfolio-queue-expiry suite (10) plus the existing portfolio-queue store / manager / CLI suites (no regressions)
• typecheck clean on the changed files (.d.ts + test)

If any required check was skipped, explain why:

• Change is confined to packages/gittensory-miner/lib/** (hand-written ESM .js + .d.ts, validated via node --check, not tsc) and test/unit/**. No src/**, UI, MCP, workflow, migration, or dependency changes — Codecov ignores this path (no src/** touched), and the backend/UI/MCP CI jobs are path-skipped.

Safety

• No secrets, wallet details, hotkeys, coldkeys, PATs, private keys, raw trust scores, private rankings, or maintainer evidence are exposed. The store is 100% local SQLite — never uploaded/synced.
• Public GitHub text stays sanitized, low-noise, and implies no compensation guarantees or optimization tactics.
• Auth/cookie/CORS/GitHub App/Cloudflare/session changes include negative-path tests. (N/A — none touched.)
• API/OpenAPI/MCP behavior updated and tested where needed. (N/A — no API/MCP surface changed.)
• No changelog edited.

Notes

• The sweep is wired into PortfolioQueueManager: claimNextBatch() reclaims orphaned leases back to queued before selecting, so a crashed process's stuck item becomes eligible again instead of permanently occupying a WIP slot. Also exposed as manager.reclaimStuckItems(maxLeaseMs?) and configurable via the staleLeaseMs option (default 30 min). The pure sweepStuckItems/findStuckItems module stays IO/Date-free (mirroring claim-ledger-expiry); the manager supplies Date.now() at the boundary.
• Fail-safe boundary: an item exactly at the age bound is treated as still within the window (not reclaimed); a missing/unparseable leasedAt is never swept.

Closes #4827

[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.35%. Comparing base (5f3ebf7) to head (3aae12d).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5202   +/-   ##
=======================================
  Coverage   94.35%   94.35%           
=======================================
  Files         473      473           
  Lines       39977    39977           
  Branches    14574    14574           
=======================================
  Hits        37719    37719           
  Misses       1585     1585           
  Partials      673      673           

Flag	Coverage Δ
shard-1	46.34% <ø> (-0.13%)	⬇️
shard-2	34.43% <ø> (-0.14%)	⬇️
shard-3	30.83% <ø> (-0.15%)	⬇️
shard-4	33.29% <ø> (-0.02%)	⬇️
shard-5	33.52% <ø> (-0.17%)	⬇️
shard-6	45.18% <ø> (+0.30%)	⬆️

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

🚀 New features to boost your workflow:

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

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-12 09:39:47 UTC}

8 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · dirty

⏸️ Suggested Action - Manual Review

Review summary
This adds a leased_at column, a guarded ALTER TABLE migration, listInProgress/reclaimStuckItem store methods, and a pure findStuckItems/sweepStuckItems module mirroring the existing claim-ledger-expiry pattern. The store-level wiring is correct: dequeueNext and batchClaim stamp leased_at, markDone/markFailed/reclaimStuckItem clear it, and the migration is idempotent via PRAGMA table_info. The tests exercise the real store (not fabricated payloads) and cover the boundary condition (age == maxLeaseMs not stuck) correctly. One gap: nothing in this diff actually invokes sweepStuckItems anywhere (no CLI command, no manager wiring, no cron/poll hook), so the sweep exists but is never called in production.

Blockers

• packages/gittensory-miner/lib/portfolio-queue-expiry.js:38 defines sweepStuckItems, but no changed production caller invokes it, so a crashed item can still remain in_progress forever during normal miner execution; wire the sweep into the portfolio-queue processing path before claims, or show the existing production caller that will call sweepStuckItems on an interval/startup.

Nits — 5 non-blocking

• No caller wires sweepStuckItems into anything runnable (portfolio-queue-manager.js, portfolio-queue-cli.js, or a poll loop) — the sweep is built but dormant until something invokes it periodically; confirm that's intentional/deferred to a follow-up.
• portfolio-queue.js:127-130 reclaimStatement duplicates markFailedStatement's SQL (both do status='queued', leased_at=NULL WHERE ... status='in_progress' RETURNING *) — consider consolidating or explain why markFailed can't just be reused for reclaim.
• rowToLeaseEntry (portfolio-queue.js:60) and rowToEntry are near-identical projections differing only in included columns; fine as-is given the stated intent to keep QueueEntry unchanged, but worth a one-line note if a third projection is added later.
• Wire sweepStuckItems into portfolio-queue-manager.js or a CLI subcommand (or link the follow-up issue) so the sweep actually runs somewhere.
• Consider whether reclaimStatement (portfolio-queue.js:127) can just delegate to the same prepared statement as markFailedStatement since the SQL is identical.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4827
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: 137 registered-repo PR(s), 84 merged, 12 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nickmopen; Gittensor profile; 137 PR(s), 12 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence.

Review context

• Author: nickmopen
• 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: 137 PR(s), 12 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.

[BETA] Chat with Gittensory

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

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

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 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]

An AI reviewer flagged a likely defect, but its confidence was below this repository's configured close-confidence floor, so this is held for a maintainer to confirm instead of closing automatically. Resolve the flagged defect (see the review notes), or ask a maintainer to override.

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (conflicts with the base branch — resolve and open a fresh PR). 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.

[JSONbored]

Fix merge conflict, bot merged one of my PRs before yours accidentally

[nickmopen]

Thanks for the heads-up! Rebased onto latest main and resolved the packages/gittensory-miner/package.json build-chain conflict (kept all the newly-added node --check entries and re-inserted portfolio-queue-expiry.js). Now conflict-free and mergeable — 43 tests green, build:miner + test:miner-pack pass, diff still confined to packages/gittensory-miner/lib/** + test/**.