fix(selfhost): fail fast when a configured _FILE secret is unreadable

[RealDiligent]

Summary

• Root cause: loadFileSecrets() logged selfhost_secret_file_unreadable when a configured <NAME>_FILE path was missing/unreadable, then continued with the target env var unset — so a broken Docker secret mount could boot ORB without the credential.
• Fix: Match the miner’s loadMinerFileSecrets fail-fast behavior: keep the structured error log, then throw so container startup exits non-zero. Genuinely omitted secrets (no _FILE set) and explicit plain-env overrides are unchanged.
• Impact: Operators catch broken high-privilege secret mounts at boot instead of running with silently missing credentials.

Closes #6284

Test plan

• Unit tests: unreadable _FILE throws + logs; omitted _FILE still starts; COMPOSE reserved vars unchanged
• CI validate-code / selfhost path checks

Risk / tradeoffs

• Breaking for misconfigured deploys that previously “worked” with missing secrets: intentional — those were already insecure/incorrect. Correctly mounted secrets and plain-env-only configs are unaffected.

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-16 02:50:51 UTC}

2 files · 1 AI reviewer · no blockers · readiness 86/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR changes loadFileSecrets() in src/selfhost/load-file-secrets.ts to throw (after logging) when a configured <NAME>_FILE path is unreadable, matching the miner package's loadMinerFileSecrets fail-fast behavior, so a broken Docker secret mount now aborts ORB startup instead of silently proceeding without the credential. The diff is small, well-scoped, correctly preserves the precedence rule (explicit env wins, genuinely omitted _FILE vars are unaffected, Compose-reserved vars are still excluded), and the error message intentionally omits the secret's contents. Tests cover the throw-and-log path, a non-Error thrown value, the omitted-_FILE no-op case, and the default-args path, mirroring the miner's existing test suite.

Nits — 4 non-blocking

• load-file-secrets.ts:37-41 constructs the error message inline with a repeated `error instanceof Error ? error.message : String(error)` ternary that already exists verbatim in the miner's env-file-indirection.js — consider extracting a shared helper if this pattern needs to change again in either place.
• The PR doesn't mention whether callers of loadFileSecrets() in server.ts (or elsewhere) already handle a thrown error appropriately (e.g., letting it propagate to a non-zero exit) — worth confirming the call site doesn't swallow it in a try/catch.
• Consider factoring the shared `<NAME>_FILE` resolution logic (COMPOSE_RESERVED_FILE_VARS check, error formatting) into a common utility used by both src/selfhost/load-file-secrets.ts and packages/loopover-miner/lib/env-file-indirection.js, since they're now byte-for-byte identical in behavior and largely in structure.
• Confirm the top-level caller in server.ts doesn't catch and log-and-continue on this new throw, which would defeat the fail-fast intent.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#6284
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	❌ 8/20	High 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: 348 registered-repo PR(s), 168 merged, 30 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 348 PR(s), 30 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Review context

• Author: RealDiligent
• 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: 348 PR(s), 30 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Add a concise scope and risk note.
• Then work through the remaining 1 step in the Signals table above.

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.

🧪 Chat with LoopOver

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

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover 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/loopover-commands

🧪 Experimental — new and may change.

_{🟩 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 LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[superagent-security]

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

[loopover-orb]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.60%. Comparing base (7ab6071) to head (0cdd19f).
⚠️ Report is 36 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6337   +/-   ##
=======================================
  Coverage   95.60%   95.60%           
=======================================
  Files         596      596           
  Lines       47135    47138    +3     
  Branches    15006    15007    +1     
=======================================
+ Hits        45063    45066    +3     
  Misses       1290     1290           
  Partials      782      782           

Flag	Coverage Δ
shard-1	43.95% <0.00%> (-0.19%)	⬇️
shard-2	36.81% <0.00%> (+0.29%)	⬆️
shard-3	32.45% <0.00%> (+0.04%)	⬆️
shard-4	33.92% <100.00%> (-0.65%)	⬇️
shard-5	31.58% <0.00%> (-0.10%)	⬇️
shard-6	45.18% <0.00%> (+0.40%)	⬆️

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

Files with missing lines	Coverage Δ
src/selfhost/load-file-secrets.ts	100.00% <100.00%> (ø)