feat(miner): add queue release/requeue escape-hatch subcommands (#4828)

[carlh7777]

Summary

The portfolio-queue CLI exposed only list / next / done / claim-batch, so an operator had no manual way to return an item to the queue outside the automated stuck-lease sweep (#4827/#5202). This adds the two escape-hatch subcommands #4828 asks for:

• queue release <owner/repo> <identifier> — give up a CLAIMED (in_progress) item, returning it to queued. The manual counterpart to the automated reclaim sweep; reuses the store's existing reclaimStuckItem.
• queue requeue <owner/repo> <identifier> — put a COMPLETED (done) item back on the queue so it is picked up again, keeping its original FIFO position (rowid/enqueued_at unchanged). Backed by a new requeueItem store method.

The two target distinct source states (in_progress vs done), so a manual op can never disturb an active claim; anything else (already queued, wrong state, or absent) is a no-op that exits non-zero with a specific code.

Both follow the existing queue done shape exactly — same <owner/repo> <identifier> [--json] parsing (refactored into one shared parseRepoIdentifierArgs helper; done's behavior is unchanged), withPortfolioQueue store lifecycle, exit codes (0 success / 2 failure), and machine-readable error codes (queue_entry_not_in_progress, queue_entry_not_requeuable). Both are documented in --help.

Closes #4828

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 Add a manual release/requeue escape hatch to the portfolio-queue CLI #4828).

Validation

• git diff --check
• npm run typecheck (clean, incl. the updated .d.ts declarations)
• node --check on the changed lib files (the miner package's build gate)
• Tests: 10 new cases in miner-portfolio-queue-cli.test.ts covering, for each command, success · not-applicable-state · --json · parse-error · fail-safe (store throws, both Error and non-Error) · dispatch — all pass. packages/gittensory-miner/** sits outside Codecov's src/** include glob, but every new statement and branch is covered to the 100% house standard.
• npm run test:workers · build:mcp · ui:* — N/A (miner-package + test change only; no worker/MCP/UI/OpenAPI surface touched).

If any required check was skipped, explain why:

Change is confined to the packages/gittensory-miner lib (authored JS validated by node --check) + its .d.ts + unit tests. No boundary beyond the lease work's schema is touched (per the issue's boundary) — requeueItem is a new store method, not a schema change.

Safety

• No secrets, wallet details, hotkeys, coldkeys, PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized and low-noise.
• Auth/CORS/session negative-path tests — N/A (local CLI over a local SQLite store).
• API/OpenAPI/MCP behavior updated/tested where needed — N/A.
• UI changes use real states — N/A (no UI).
• Visible UI changes include UI Evidence — N/A.
• Public docs/changelogs updated where needed — N/A (help text updated in-CLI).

UI Evidence

N/A — no UI/frontend/docs changes.

Notes

• requeue deliberately targets only done items and release only in_progress items, so the two escape hatches are unambiguous and never race an active claim; a requeued item keeps its FIFO position rather than jumping to the back.
• Both new subcommands are reflected in queue list immediately (asserted in the tests), satisfying the issue's acceptance criteria.

[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.79%. Comparing base (19b8fe0) to head (8bff9fa).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5520      +/-   ##
==========================================
+ Coverage   94.78%   94.79%   +0.01%     
==========================================
  Files         566      566              
  Lines       45023    45065      +42     
  Branches    14675    14675              
==========================================
+ Hits        42673    42718      +45     
+ Misses       1616     1613       -3     
  Partials      734      734              

Flag	Coverage Δ
shard-1	43.77% <2.22%> (-0.47%)	⬇️
shard-2	35.42% <100.00%> (+0.01%)	⬆️
shard-3	31.66% <2.22%> (-0.31%)	⬇️
shard-4	31.59% <2.22%> (-0.37%)	⬇️
shard-5	33.06% <2.22%> (+0.16%)	⬆️
shard-6	44.09% <6.66%> (+0.54%)	⬆️

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

Files with missing lines	Coverage Δ
packages/gittensory-miner/lib/cli.js	100.00% <ø> (ø)
...ckages/gittensory-miner/lib/portfolio-queue-cli.js	90.95% <100.00%> (+4.38%)	⬆️
packages/gittensory-miner/lib/portfolio-queue.js	95.74% <100.00%> (+0.14%)	⬆️

🚀 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-13 00:56:40 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds `queue release` and `queue requeue` escape-hatch subcommands to the portfolio-queue CLI, backed by a new `requeueItem` store method and a shared `parseRepoIdentifierArgs` helper that both refactors `parseQueueDoneArgs` and adds the two new parsers. The implementation follows the existing `queue done` pattern exactly (same store lifecycle, exit codes, JSON shape), the SQL statements correctly target disjoint source states (`in_progress` for release, `done` for requeue) so an active claim can never be disturbed, and the refactor of `parseQueueDoneArgs` preserves its original behavior. Tests are thorough, covering both success paths, both no-op/failure paths, parse errors, and thrown-error fallback branches for both Error and non-Error throws.

Nits — 5 non-blocking

• The 'debug leftovers' flagged in the external brief (packages/gittensory-miner/lib/portfolio-queue-cli.js console.log/console.error calls) are the CLI's actual output mechanism, consistent with every other subcommand in this file (e.g. runQueueDone, runQueueList) — not leftover debugging, so no action needed.
• packages/gittensory-miner/lib/portfolio-queue-cli.js: runQueueRelease and runQueueRequeue duplicate the try/withPortfolioQueue/JSON-or-status-print/catch shape almost verbatim from runQueueDone; consider a small shared runner if a fourth item-targeting subcommand shows up, though at two call sites this is fine as-is.
• The PR description says this closes Add a manual release/requeue escape hatch to the portfolio-queue CLI #4828, but I can't independently verify Add a manual release/requeue escape hatch to the portfolio-queue CLI #4828 is an open, maintainer-authorized issue from the diff alone — confirm the issue link is accurate before merging per the repo's issue-scope policy.
• packages/gittensory-miner/lib/portfolio-queue.js: the new `requeueStatement` comment nicely documents why release/requeue can't collide — consider adding a one-line pointer to this invariant in the .d.ts JSDoc for `requeueItem` too, since that's the first place a consumer will look.
• Given `release` and `requeue` are exact structural twins of `done`, a future third addition might warrant extracting the print/error shape into a small `runItemTargetingCommand(parse, storeMethod, notFoundCode)` helper.

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4828
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: 181 registered-repo PR(s), 117 merged, 17 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	carlh7777; Gittensor profile; 181 PR(s), 17 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: carlh7777
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, TypeScript, Cuda, HTML, MDX, Rust
• Official Gittensor activity: 181 PR(s), 17 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]

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