fix(miner): add optional token verification to init

[taillred]

Summary

Add an opt-in --verify-token flag to gittensory-miner init that makes one authenticated GitHub API call, reports the returned scopes on success, and fails fast on invalid or under-scoped tokens. Default init behavior is unchanged when the flag is omitted.

Closes #5171.

Supersedes #5417.

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 #5171).

Validation

• git diff --check
• npm run build --workspace @jsonbored/gittensory-engine
• npm run typecheck
• npm run test -- test/unit/miner-init-verify-token.test.ts test/unit/miner-laptop-init.test.ts
• npm run actionlint
• npm run test:coverage
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate

If any required check was skipped, explain why:

• The workspace in this environment did not have the repo dev dependencies installed initially, so I installed them locally before rerunning the CI-equivalent checks. The branch now passes the repo typecheck and the targeted miner tests.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.

Notes

• doctor remains untouched and still makes no network calls.
• init only performs a GitHub request when --verify-token is passed.

[superagent-security]

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

[codecov]

Codecov Report

❌ Patch coverage is 97.77778% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 94.45%. Comparing base (b440230) to head (56ed3a5).

Files with missing lines	Patch %	Lines
packages/gittensory-miner/lib/laptop-init.js	97.77%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5419   +/-   ##
=======================================
  Coverage   94.45%   94.45%           
=======================================
  Files         553      553           
  Lines       44357    44400   +43     
  Branches    14659    14659           
=======================================
+ Hits        41898    41940   +42     
- Misses       1784     1785    +1     
  Partials      675      675           

Flag	Coverage Δ
shard-1	43.87% <6.66%> (-0.28%)	⬇️
shard-2	34.75% <22.22%> (+<0.01%)	⬆️
shard-3	31.64% <97.77%> (-0.28%)	⬇️
shard-4	31.41% <6.66%> (+0.13%)	⬆️
shard-5	32.88% <6.66%> (-0.43%)	⬇️
shard-6	43.83% <0.00%> (+0.51%)	⬆️

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% <ø> (ø)
packages/gittensory-miner/lib/laptop-init.js	97.32% <97.77%> (+0.21%)	⬆️

🚀 New features to boost your workflow:

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

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - reject/close recommended

_{Review updated: 2026-07-12 18:14:18 UTC}

8 files · 2 AI reviewers · 1 blocker · readiness 100/100 · CI failing · unstable

🛑 Suggested Action - Reject/Close

• AI reviewers agree on a likely critical defect: packages/gittensory-miner/lib/laptop-init.js:196 treats an explicitly empty `x-oauth-scopes` header as equivalent to an omitted header, so a reachable classic token with no scopes passes `verifyGithubToken`
• preserve whether the header was present and reject present-but-empty or present-without `repo`/`public_repo`, while only allowing the omitted-header path for tokens where GitHub truly does not report classic scopes. — Resolve the flagged defect, or override if the AI reviewers are mistaken, then re-run the gate.

Review summary
This PR adds an opt-in `--verify-token` flag to `gittensory-miner init` that makes a single authenticated call to `GET /user`, checks the `x-oauth-scopes` header for `repo`/`public_repo`, and fails fast with a clear message on invalid or under-scoped tokens; default `init` behavior (no flag) stays synchronous-equivalent and network-free, verified by an explicit test asserting zero fetch calls. The `runInit` signature change to `async`/`Promise<number>` is threaded correctly through both call sites (`bin/gittensory-miner.js` now awaits it) and the `.d.ts` is updated to match. The scope-check logic correctly treats a missing `x-oauth-scopes` header as valid (fine-grained PATs don't set it) rather than rejecting, which is the right call for modern token types, and is directly tested for both branches.

Blockers

• packages/gittensory-miner/lib/laptop-init.js:196 treats an explicitly empty `x-oauth-scopes` header as equivalent to an omitted header, so a reachable classic token with no scopes passes `verifyGithubToken`; preserve whether the header was present and reject present-but-empty or present-without `repo`/`public_repo`, while only allowing the omitted-header path for tokens where GitHub truly does not report classic scopes.

Nits — 5 non-blocking

• packages/gittensory-miner/lib/laptop-init.js:161 hardcodes the 5000ms timeout inline; a named constant (e.g. `defaultVerifyTimeoutMs`) would match the file's existing convention of naming other magic values like `githubApiVersion`.
• packages/gittensory-miner/lib/laptop-init.js:154 `verifyGithubToken` is a fairly dense function (~66 lines, several branches); consider splitting the response-parsing/classification logic from the fetch/timeout plumbing for readability.
• The PR references 'Closes Add an opt-in gittensory-miner init --verify-token flag to validate GITHUB_TOKEN scopes via a single API call #5171' and 'Supersedes fix(miner): add optional token verification to init #5417' — worth confirming fix(miner): add optional token verification to init #5417 is closed/superseded cleanly so there isn't a duplicate open PR for the same issue.
• Consider extracting the timeout constant and possibly the response-classification block (scope check + ok/error shaping) into a small helper for testability independent of `fetch`.
• The codecov/patch check is failing at 97.77% vs a 99% target — worth checking which specific branch is uncovered (likely an edge case in `readGithubErrorMessage` or the apiBaseUrl trimming logic) and adding a targeted test.

Why this is blocked

• packages/gittensory-miner/lib/laptop-init.js:196 treats an explicitly empty `x-oauth-scopes` header as equivalent to an omitted header, so a reachable classic token with no scopes passes `verifyGithubToken`; preserve whether the header was present and reject present-but-empty or present-without `repo`/`public_repo`, while only allowing the omitted-header path for tokens where GitHub truly does not report classic scopes.

CI checks failing

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

Signal	Result	Evidence
Code review	❌ 1 blocker	2 reviewers, synthesized
Linked issue	✅ Linked	#5171
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: 53 registered-repo PR(s), 34 merged, 1 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	luckydicer; Gittensor profile; 53 PR(s), 1 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The change is a small, well-tested, backward-compatible addition (opt-in flag, unchanged default path) that closes a linked issue and is directly useful for reducing wasted miner attempts on invalid tokens.

Linked issue satisfaction

Addressed
The PR adds an opt-in --verify-token flag to init that makes exactly one GET /user call, reports scopes/validity on success, errors and exits before init runs on failure, leaves default init behavior byte-identical (verified by a network-call assertion test), and leaves doctor's dispatch and no-network contract untouched. Tests cover success, insufficient-scope, invalid-token, network-error, and n

Review context

• Author: luckydicer
• 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: 53 PR(s), 1 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 is closing this pull request on the maintainer's behalf (CI is failing (codecov/patch); AI reviewers agree on a likely critical defect: packages/gittensory-miner/lib/laptop-init.js:196 treats an explicitly empty `x-oauth-scopes` header as equivalent to an omitted header, so a reachable classic token with no scopes passes `verifyGithubToken`; preserve whether the header was present and reject present-but-empty or present-without `repo`/`public_repo`, while only allowing the omitted-header path for tokens where GitHub truly does not report classic scopes.). 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.