feat(miner-extension): show a last-synced label on the opportunity badge

[galuis116]

Summary

• The miner extension's opportunity badge (apps/gittensory-miner-extension/opportunity-badge.js) previously gave a contributor no signal at all about how stale their pasted discover-run data was — the badge could be showing a ranked candidate synced minutes or days ago with no way to tell which.
• options.js now writes a rankedCandidatesSavedAt timestamp (Date.now()) to chrome.storage.local alongside rankedCandidates on every save, including a re-paste/overwrite of previously-saved data.
• background.js's loadIssueOpportunityContext reads that timestamp back and includes it (as savedAt) in the ready message payload sent to the content script.
• opportunity-badge.js gets a new formatLastSyncedLabel(savedAt, nowMs) helper that reimplements the same relative-time thresholds/format as ORB's shared RefreshMeta component (packages/gittensory-ui-kit/src/utils.ts's relativeTimeFromNow: "just now" / "Xm ago" / "Xh ago" / "Xd ago") — reimplemented locally because this content script ships unbundled and cannot import that package.
• content.js's renderOpportunityBadge now takes an injectable nowMs (defaulting to Date.now()), computes the label, and renders it inside the badge markup as a .gittensory-miner-opportunity-badge__synced line.
• A cache saved before this field existed (or with an invalid/missing savedAt) degrades gracefully: the label is simply omitted, never NaN or a crash.

Fixes #5192

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• 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 (e.g. Closes #123) — a linked open issue is required for every contributor PR.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally — this change lives entirely under apps/gittensory-miner-extension/** and its dedicated test file test/unit/miner-extension-content.test.ts, outside vitest's root coverage.include glob (only root src/** is Codecov-measured), so codecov/patch cannot see this diff.
• 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
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

Ran the full local gate: npm run test:ci (796 test files / 15400+ tests, all green) and npm audit --audit-level=moderate (0 vulnerabilities), both clean on the final rebased commit.

Test coverage added to test/unit/miner-extension-content.test.ts (18 tests total in the file, up from 10): formatLastSyncedLabel across every relative-time bucket (just now / 1m / 59m / 1h / 23h / 1d, plus a small-positive-skew clamp), and an explicit invariant that null/undefined/NaN/a non-numeric string/an empty string all degrade to null rather than being misread as epoch-zero (Number("") coerces to 0, which is finite — this was caught live while writing the test and fixed by requiring typeof savedAt === "number" rather than a bare Number.isFinite coercion); renderOpportunityBadgeMarkup with and without a label, asserting the ranking-derived fields (tier/score) are unaffected either way; content.js's renderOpportunityBadge plumbing savedAt + an injected nowMs through to the rendered label; a regression test for a pre-existing cache with no savedAt field rendering cleanly with no label and no NaN; background.js including savedAt in the ready payload and omitting it when there's no ranked signal; and options.js writing a fresh rankedCandidatesSavedAt on every save, including a second save with a different value to prove it's rewritten on overwrite, not just written once.

This branch was rebased past a concurrent PR (#5511, merged as ec7d4c24) that touched the same two files (options.js and this test file) to add a discoveryIndexUrl legacy-purge feature; the rebase conflict was resolved by keeping both sets of changes/tests, and a real gap the merge exposed (a test's chrome.storage.sync mock missing the remove method now called from refreshSettings()) was fixed in the same commit.

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. — N/A, no auth/session/CORS surface touched (local chrome.storage only).
• API/OpenAPI/MCP behavior is updated and tested where needed. — no public API/OpenAPI/MCP surface touched; the extension's internal message payload shape change (savedAt added) is covered by the tests above.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — the badge continues to render from the real chrome.storage.local cache; the missing-savedAt fallback is a real degrade path, not a mock.
• Visible UI changes include a UI Evidence section below.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. — updated apps/gittensory-miner-extension/README.md's "Local ranked cache" section.

UI Evidence

This is a browser extension content script injected into github.com/*/*/issues/* pages — there is no hosted/public deployment to screenshot from this environment (no browser screenshot tooling available here). Verified functionally instead: npm run test:ci includes the full test/unit/miner-extension-content.test.ts suite (18/18 passing), including a direct assertion that renderOpportunityBadgeMarkup/renderOpportunityBadge produce markup literally containing last synced 5m ago-style text alongside the existing tier/score/why badge content, and that the label is cleanly absent (no NaN) when savedAt is missing.

Notes

• Kept the label as a single extra line inside the existing badge markup (.gittensory-miner-opportunity-badge__synced, styled muted/small to match the existing __read-only treatment) rather than a separate UI element, since the badge is already a compact fixed/sidebar-anchored card.
• Scope was kept to the badge itself per the issue's boundary feat(docs): add analytics and mcp version widget #6 ("do not touch any ranking/scoring logic... only render a relative-time label next to the badge") — the options page itself does not display rankedCandidatesSavedAt, since the issue only asked for it on the GitHub issue-page badge.

[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.77%. Comparing base (d25c60d) to head (2715790).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5518   +/-   ##
=======================================
  Coverage   94.77%   94.77%           
=======================================
  Files         565      565           
  Lines       44964    44964           
  Branches    14675    14675           
=======================================
  Hits        42614    42614           
  Misses       1616     1616           
  Partials      734      734           

Flag	Coverage Δ
shard-1	43.75% <ø> (-0.52%)	⬇️
shard-2	35.54% <ø> (+0.18%)	⬆️
shard-3	32.02% <ø> (+0.06%)	⬆️
shard-4	31.23% <ø> (-0.74%)	⬇️
shard-5	33.36% <ø> (+0.45%)	⬆️
shard-6	43.79% <ø> (+0.20%)	⬆️

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]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-13 00:46:19 UTC}

7 files · 2 AI reviewers · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a small, well-scoped feature: options.js now persists a rankedCandidatesSavedAt timestamp on every save, background.js plumbs it through as savedAt on the ready payload, and opportunity-badge.js/content.js render a relative 'last synced' label with graceful degradation for missing/invalid timestamps. The implementation is correct — formatLastSyncedLabel properly guards non-number/NaN input to null, future timestamps clamp to 'just now' via Math.max(0, ...), and the diff is backed by thorough tests covering the formatting buckets, markup rendering, end-to-end plumbing through content.js, and the options.js save path. The PR closes #5192 and stays tightly focused on that one issue without scope creep.

Nits — 5 non-blocking

• The magic numbers (60, 60, 24) in formatLastSyncedLabel (opportunity-badge.js:54-59) could be named constants (e.g. SECONDS_PER_MINUTE, MINUTES_PER_HOUR, HOURS_PER_DAY) for readability, though the comment above already documents intent.
• toolbar-badge.js's own chrome.storage.local.get('rankedCandidates') read in background.js's refreshToolbarBadge is unaffected by this change, but worth double-checking that the new rankedCandidatesSavedAt key doesn't need similar toolbar-badge treatment (it doesn't, since toolbar badge only cares about count).
• Consider extracting the reimplemented relative-time formatting into a tiny shared constants module if more unbundled content scripts end up needing it, to reduce future drift risk from the ui-kit's relativeTimeFromNow.
• The README update at README.md:21-25 is clear and accurately reflects the new storage key and degrade-gracefully behavior — good practice to keep docs in sync.
• nit: apps/gittensory-miner-extension/opportunity-badge.js:51 should validate `nowMs` as finite too, because direct/test callers can currently produce `last synced NaNd ago` if they pass an invalid clock value.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5192
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: 1871 registered-repo PR(s), 1233 merged, 49 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	galuis116; Gittensor profile; 1871 PR(s), 49 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The change closes a real usability gap (no staleness signal on pasted discover-run data) with a correct, well-tested, narrowly-scoped implementation that mirrors an existing UI convention (RefreshMeta) rather than inventing a new pattern.

Linked issue satisfaction

Addressed
The diff writes rankedCandidatesSavedAt on every save (including re-paste) in options.js, plumbs it through background.js and content.js, and renders a relative-time 'last synced' label in opportunity-badge.js mirroring RefreshMeta's thresholds, with graceful degradation for missing/invalid savedAt plus dedicated tests for buckets, invariants, and the regression case.

Review context

• Author: galuis116
• 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: 1871 PR(s), 49 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

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/	desktop			—
/	mobile			—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

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