fix(doctor): make engine checks private-install-aware and honor manualOnly

[rohitg00]

Closes #874, closes #875.

The engine-version-mismatch and iii-on-path-not-local-bin checks probed only the PATH-resolved iii binary, while their fixes install the pinned engine to ~/.agentmemory/bin, which is only prepended to PATH in-process. Both checks therefore failed forever and re-prompted on every doctor run, and the offered fixes were no-ops.

Both checks now consult the private install first and pass when it exists at the pinned version, noting a mismatched PATH iii as informational detail since the private install wins at runtime. The version-mismatch fix converges: install then recheck passes. runDoctor consults a new canAutoFix helper in both interactive and --all paths, so manualOnly diagnostics print their manual fix hint and count as skipped instead of prompting or auto-applying.

Tested by new cases in test/cli-doctor-fixes.test.ts including a stateful installer stub proving fix convergence.

Summary by CodeRabbit

• Bug Fixes

  • Improved version mismatch detection between private install and PATH binary locations
  • Refined diagnostic messaging for mismatched or unavailable runtime environments

• New Features

  • Doctor command now identifies which diagnostics can be auto-fixed versus requiring manual intervention
  • Enhanced diagnostic loop to skip prompts for manual-only issues and provide clearer guidance

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentmemory	Ready	Preview, Comment	Jun 10, 2026 10:50pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4ac56019-d629-4631-82d7-e8314b226f1e

📥 Commits

Reviewing files that changed from the base of the PR and between 25e7701 and 18ce604.

📒 Files selected for processing (3)

• src/cli.ts
• src/cli/doctor-diagnostics.ts
• test/cli-doctor-fixes.test.ts

---

📝 Walkthrough

Walkthrough

The PR updates the agentmemory doctor command to fix a diagnostic loop where the iii-on-path-not-local-bin and engine-version-mismatch checks continually reported failures even after fixes were applied. It introduces auto-fix eligibility detection, reorients both checks to prioritize the private ~/.agentmemory/bin/iii install over PATH binaries, and updates the CLI to skip interactive prompts for non-auto-fixable diagnostics.

Changes

Doctor Diagnostics and Auto-Fix Flow

Layer / File(s)	Summary
Auto-fix eligibility helper src/cli/doctor-diagnostics.ts	Adds exported canAutoFix(d) function that returns !d.manualOnly, determining whether a diagnostic is auto-applicable.
CLI auto-fix branching src/cli.ts	Imports canAutoFix and updates the doctor loop to branch on failed diagnostics: if not auto-fixable, logs manual-fix preview and skips the interactive prompt; previous universal prompting and manualOnly annotation logic is replaced.
Engine version diagnostic with private install priority src/cli/doctor-diagnostics.ts, test/cli-doctor-fixes.test.ts	engine-version-mismatch check bases success on private install iii version matching pinned version (not PATH version); PATH mismatch is included in detail only when private install matches; messaging updated to reflect private-install precedence; tests verify pass when private install matches pinned version even if PATH reports different version, and fix results in passing re-check.
Path binary diagnostic with private install validation src/cli/doctor-diagnostics.ts, test/cli-doctor-fixes.test.ts	iii-on-path-not-local-bin message describes private install absence or mismatch; check logic expanded from equality test to multi-step flow: if PATH matches private install path, validates private install version against pin; otherwise fails with PATH reference; marked manualOnly; tests cover missing private install and success when private install matches pin despite PATH mismatch.
Test coverage for auto-fix and diagnostic logic test/cli-doctor-fixes.test.ts	Imports canAutoFix and adds comprehensive coverage: validates canAutoFix returns false for manualOnly diagnostics and true for auto-fixable ones; tests private-install-centric validation for both engine-version-mismatch and iii-on-path-not-local-bin; includes end-to-end fix and re-check scenarios.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• rohitg00/agentmemory#774: Updates doctor diagnostics logic to align with the switch to private ~/.agentmemory/bin/iii vs PATH binary behavior, directly modifying the same diagnostic outcomes and message handling for iii-on-path-not-local-bin and engine-version-mismatch.

Poem

🐰 A doctor's check now sees the truth:
The private path beats PATH in youth!
No looping fixes, just one way—
Skip the dance, let reason play.
thump thump 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main changes: making engine checks private-install-aware and honoring the manualOnly flag for diagnostic fixes.
Linked Issues check	✅ Passed	The changes comprehensively address both issues: #874 and #875 by making both iii-on-path-not-local-bin and engine-version-mismatch check the private install first, implementing canAutoFix to honor manualOnly, and enabling fix convergence through re-checks.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issues: updates to diagnostic logic, introduction of canAutoFix helper, and test coverage for the new behavior.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/doctor-private-install-checks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}