feat(miner-hands): doctor preflight for claude/codex CLI presence + auth

[jeffrey701]

What

gittensory-miner doctor (offline-only) checks node/engine/state-dir/sqlite/docker today, but has no visibility into the coding-agent CLIs a driver will need. This adds two advisory checks — claude-cli-present and codex-cli-present — so an operator can see, before running a real attempt, whether the claude/codex binaries are on PATH and authenticated.

• Binary detection reuses findExecutableOnPath (the same helper checkDockerPresent uses) — no new PATH search.
• Auth detection is read-only and never spawns the CLI. It surfaces, proactively, the SAME condition each provider checks at call time: CLAUDE_CODE_OAUTH_TOKEN for claude (per createClaudeCodeAi), and a readable auth.json at $CODEX_HOME/auth.json (else $HOME/.codex/auth.json) for codex (per assertCodexAuthConfigured).
• Tone: advisory (ok: true even when absent/unauthenticated), matching checkDockerPresent. A coding-agent CLI is only strictly required once a driver provider is configured (feat(miner-hands): CodingAgentDriver factory + provider-style config resolution #4289, not yet wired), so a missing/unauthenticated CLI is informational — the detail string tells the operator exactly what to fix (set CLAUDE_CODE_OAUTH_TOKEN / run codex auth).

Deliverables

• checkClaudeCliPresent / checkCodexCliPresent added to the array runDoctorChecks returns, each in the exact { name, ok, detail } shape.
• Binary detection reuses findExecutableOnPath (laptop-init.js).
• Auth detection mirrors the providers' own read-only checks (CLAUDE_CODE_OAUTH_TOKEN; codex auth.json readability) — no network, no subprocess.
• Advisory tone chosen and documented (optional until a driver provider is configured, feat(miner-hands): CodingAgentDriver factory + provider-style config resolution #4289) rather than copying Docker's tone blindly.
• Tests: binary present+authed, present+not-authed, and absent, for both claude and codex, plus the runDoctorChecks wiring.

Closes #4304

[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 93.95%. Comparing base (084cb38) to head (f4d1559).
⚠️ Report is 42 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4376   +/-   ##
=======================================
  Coverage   93.95%   93.95%           
=======================================
  Files         400      400           
  Lines       36820    36820           
  Branches    13452    13452           
=======================================
  Hits        34595    34595           
  Misses       1569     1569           
  Partials      656      656           

🚀 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-09 17:17:08 UTC}

5 files · 1 AI reviewer · no blockers · readiness 82/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds two purely advisory doctor checks (checkClaudeCliPresent/checkCodexCliPresent) that detect the claude/codex CLI binaries via the existing findExecutableOnPath helper and probe auth state read-only (CLAUDE_CODE_OAUTH_TOKEN env var; codex auth.json readability), wiring them into runDoctorChecks alongside solid DI-based tests covering present/authed, present/not-authed, and absent for both CLIs plus the wiring itself. The implementation is correct and matches checkDockerPresent's advisory tone (always ok:true), but the codex auth probe only checks that auth.json is readable (accessSync R_OK) while the production readiness check in src/selfhost/health.ts's defaultCodexAuthFileCheck also requires info.size > 0 — an empty auth.json would report 'authenticated' here despite being treated as unauthenticated by the real preflight check it claims to mirror.

Nits — 5 non-blocking

• packages/gittensory-miner/lib/laptop-init.js: checkCodexCliPresent only checks auth.json is readable (accessSync R_OK) but doesn't check it's non-empty, unlike src/selfhost/health.ts's defaultCodexAuthFileCheck which also requires `info.size > 0` — an empty/zero-byte auth.json will be reported as 'authenticated' here, diverging from the behavior it claims to mirror per the PR description.
• test/unit/miner-cli-doctor-checks.test.ts: the 'not authenticated' claude test only covers CLAUDE_CODE_OAUTH_TOKEN being absent (undefined), not present-but-empty (`CLAUDE_CODE_OAUTH_TOKEN: ""`), leaving the `.length > 0` half of that branch unexercised.
• packages/gittensory-miner/lib/laptop-init.js: the JSDoc blocks on checkClaudeCliPresent/checkCodexCliPresent are quite long for advisory helper functions; could be trimmed to the non-obvious rationale (advisory tone + no-subprocess guarantee) without restating the whole design.
• Align checkCodexCliPresent's auth check with defaultCodexAuthFileCheck in src/selfhost/health.ts by also verifying non-zero file size, so the doctor's 'authenticated' claim can't diverge from the actual readiness/call-time check it's meant to preview.
• Add a test case for CLAUDE_CODE_OAUTH_TOKEN set to an empty string to close out branch coverage on the `typeof ... === "string" && ...length > 0` condition.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4304
Related work	⚠️ 1 scoped overlap	Top overlaps are listed below; lower-confidence bulk is hidden.
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: 96 registered-repo PR(s), 36 merged, 4 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jeffrey701; Gittensor profile; 96 PR(s), 4 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds checkClaudeCliPresent/checkCodexCliPresent to runDoctorChecks with the exact {name, ok, detail} shape, reuses findExecutableOnPath for binary detection, mirrors the CLAUDE_CODE_OAUTH_TOKEN and codex auth.json checks read-only, documents the advisory tone rationale, and includes tests covering present+authed, present+not-authed, and absent for both CLIs plus runDoctorChecks wiring.

Review context

• Author: jeffrey701
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, Clojure, JavaScript
• Official Gittensor activity: 96 PR(s), 4 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (issue #4307, issue #4266)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Check active issues and PRs before submitting.

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.

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