feat(miner-ui): add a systemd unit for running miner-ui as a persistent service

[joaovictor91123]

Summary

• apps/gittensory-miner-ui had no CLI subcommand or process-manager config for running it durably — only a foreground dev server (npm run dev).
• Its vite-ledgers-api.ts/vite-portfolio-queue-api.ts/vite-run-state-api.ts plugins already wire their local-SQLite-backed API routes into both configureServer (dev) and configurePreviewServer (preview), so npm run build && npm run preview already serves the built dashboard and its data routes with no new server code needed.
• Adds systemd/gittensory-miner-ui.service.example, a companion unit to the existing gittensory-miner.service.example (the loop daemon) — mirrors its structure/comment style closely (Type=simple, Restart=on-failure, non-root User=, no --host since the dashboard has no auth of its own — this is separate from and unaffected by the new same-origin cookie auth on /api/* from feat(miner-ui): require a same-origin session cookie on the local API #5605).
• Documents it in apps/gittensory-miner-ui/README.md's new "Running as a persistent service" section, and cross-references it from the main miner's DEPLOYMENT.md bare-host walkthrough.
• No source/runtime code changes — a new example config file plus documentation.

(Re-opening after #5607 was auto-closed by an unrelated, transient CI failure: ui:version-audit caught the repo's hardcoded npm dist-tag lagging one patch behind a real @loopover/mcp publish. That's since been fixed on main by #5609; this branch is rebased on top of it and the audit now passes locally.)

Test plan

• New test/unit/miner-ui-systemd-launcher.test.ts: asserts the unit file has every required systemd directive ([Unit]/[Service]/[Install], Type=simple, ExecStart, WorkingDirectory, User, Restart=on-failure, WantedBy); asserts ExecStart targets the real @loopover/ui-miner workspace name read live from its package.json (not a hardcoded/stale name); asserts no --host flag; asserts the README and DEPLOYMENT.md cross-references exist.
• npm run typecheck passes.
• npm run docs:drift-check passes.
• npm run ui:version-audit passes.
• test/unit/miner-deployment-docs-audit.test.ts (the DEPLOYMENT.md accuracy audit) passes.

Closes #4852

[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 95.01%. Comparing base (1f515de) to head (430d62c).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5610   +/-   ##
=======================================
  Coverage   95.01%   95.01%           
=======================================
  Files         574      574           
  Lines       45684    45684           
  Branches    14661    14661           
=======================================
  Hits        43405    43405           
  Misses       1528     1528           
  Partials      751      751           

Flag	Coverage Δ
shard-1	43.95% <ø> (-0.05%)	⬇️
shard-2	35.78% <ø> (+0.05%)	⬆️
shard-3	32.14% <ø> (-0.10%)	⬇️
shard-4	30.86% <ø> (-1.75%)	⬇️
shard-5	32.65% <ø> (+0.89%)	⬆️
shard-6	44.46% <ø> (+0.38%)	⬆️

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]

Important

🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪

🔍 Gittensory is reviewing…

AI analysis is in progress. This comment will update when the review is complete.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed · 🟪 Reviewing}

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-13 09:27:36 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds a systemd unit example for running the miner-ui dashboard persistently via `vite preview`, documents install steps and cross-references in README/DEPLOYMENT.md, and backs it with a unit test that reads the real workspace name from package.json rather than hardcoding it. This is a docs+example-config change with no src/** modifications, so it carries very little runtime risk, and the test suite verifies the concrete claims (required directives, no forced `--host`, correct workspace name, cross-doc links) rather than fabricating scenarios.

Nits — 5 non-blocking

• The unit file hardcodes `User=gittensory` and `/var/lib/gittensory-miner/src` as if they were defaults, even though the comments correctly mark them REQUIRED placeholders — consider prefixing with `# EXAMPLE:` or similar so a copy-paste-without-reading doesn't silently run as a nonexistent user.
• The test's `--workspace ${packageName} run preview` assertion is coupled to the exact ExecStart formatting (spacing/flag order) in the unit file; a minor stylistic ExecStart change (e.g. `--workspace=name`) would break the test even though the unit is still correct — worth a comment noting the coupling.
• Consider adding a brief note near `ExecStart=` about what happens if the `npm` path resolves to an nvm/asdf shim that isn't available to systemd's PATH at boot (common bare-host gotcha), since the comment already flags the binary-path variability.
• apps/gittensory-miner-ui/README.md:working — could mention what env var (if any) controls the preview port, or link to vite.config.ts, for operators who need to change 4174.
• nit: systemd/gittensory-miner-ui.service.example:35 uses `After=network-online.target` without `Wants=network-online.target`, so it only orders against the target if something else starts it; either drop the line for a loopback-only dashboard or add the matching `Wants=` if you really need the dependency.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#4852
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: 141 registered-repo PR(s), 79 merged, 12 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	joaovictor91123; Gittensor profile; 141 PR(s), 12 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ Insufficient signal	risk: clean · value: insufficient-signal — Nothing measurable for the structural-improvement analyzers on this PR (e.g. no code files changed). LLM value judgment: moderate — It closes a concrete operational gap (no durable way to run the miner-ui dashboard) with a well-tested, low-risk, docs-and-example-only change that mirrors an existing convention (`gittensory-miner.service.example`).

Linked issue satisfaction

Addressed
The PR adds a systemd unit example, README documentation for running the dashboard persistently via build+preview, cross-references from DEPLOYMENT.md, and a test verifying the launcher's correctness, directly fulfilling the issue's ask for a documented persistent-service mechanism.

Review context

• Author: joaovictor91123
• 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: 141 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

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

[loopover-orb]

Important

🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪

🔍 Gittensory is reviewing…

AI analysis is in progress. This comment will update when the review is complete.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed · 🟪 Reviewing}

[loopover-orb]

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

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-13 09:27:45 UTC}

4 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · unknown

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds a systemd unit example for running the miner-ui dashboard persistently via `vite preview`, documents install steps and cross-references in README/DEPLOYMENT.md, and backs it with a unit test that reads the real workspace name from package.json rather than hardcoding it. This is a docs+example-config change with no src/** modifications, so it carries very little runtime risk, and the test suite verifies the concrete claims (required directives, no forced `--host`, correct workspace name, cross-doc links) rather than fabricating scenarios.

Nits — 5 non-blocking

• The unit file hardcodes `User=gittensory` and `/var/lib/gittensory-miner/src` as if they were defaults, even though the comments correctly mark them REQUIRED placeholders — consider prefixing with `# EXAMPLE:` or similar so a copy-paste-without-reading doesn't silently run as a nonexistent user.
• The test's `--workspace ${packageName} run preview` assertion is coupled to the exact ExecStart formatting (spacing/flag order) in the unit file; a minor stylistic ExecStart change (e.g. `--workspace=name`) would break the test even though the unit is still correct — worth a comment noting the coupling.
• Consider adding a brief note near `ExecStart=` about what happens if the `npm` path resolves to an nvm/asdf shim that isn't available to systemd's PATH at boot (common bare-host gotcha), since the comment already flags the binary-path variability.
• apps/gittensory-miner-ui/README.md:working — could mention what env var (if any) controls the preview port, or link to vite.config.ts, for operators who need to change 4174.
• nit: systemd/gittensory-miner-ui.service.example:35 uses `After=network-online.target` without `Wants=network-online.target`, so it only orders against the target if something else starts it; either drop the line for a loopback-only dashboard or add the matching `Wants=` if you really need the dependency.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4852
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: 141 registered-repo PR(s), 79 merged, 12 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	joaovictor91123; Gittensor profile; 141 PR(s), 12 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ Insufficient signal	risk: clean · value: insufficient-signal — Nothing measurable for the structural-improvement analyzers on this PR (e.g. no code files changed).

Review context

• Author: joaovictor91123
• 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: 141 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

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