fix(update): actionable EACCES + suppress stale nudge

[bradfair]

Summary

Two papercuts from the first post-release ana update run (issue #28):

• Hostile EACCES. atomicReplace wrapped os.Rename with bare %w, so a perm-denied write to /usr/local/bin/ana surfaced as raw permission denied + tempdir path. New formatReplaceErr detects fs.ErrPermission and returns platform-aware guidance (sudo on Unix, Administrator / %LOCALAPPDATA% on Windows). Routed through all three rename error sites in atomicReplace. The Windows rollback-also-fails branch also skips the misleading "recover from <.old>" wording when the root cause is EACCES — .old sits in the same admin-only directory.
• Stale nudge after ana update. The passive update-check goroutine captures the pre-swap build-time version, so it still emitted "new version available" after a successful self-update. Suppressed at drainNudge via a new verb parameter: only when verb == "update" && verbErr == nil. Failed updates (EACCES etc.) still nudge so the user gets the retry hint.

Test plan

• make test (race)
• make cover — ./internal/... still 100%
• make lint clean
• Smoke: go build -o /tmp/ana ./cmd/ana && /tmp/ana update → no trailing nudge on "already at version" path
• Manual smoke on a perm-denied path (sudo install -m 0755 /tmp/ana /usr/local/bin/ana && ana update) — to be done by reviewer on release build

Closes #28

Summary by CodeRabbit

Release Notes

Bug Fixes

• Enhanced error messages for failed updates due to insufficient permissions, with clear OS-specific remediation steps (elevated privileges guidance)
• Suppressed unnecessary update-check output following successful ana update execution

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 49845847-9765-43ed-9816-88b3f0022d31

📥 Commits

Reviewing files that changed from the base of the PR and between f9e094d and 24537c5.

⛔ Files ignored due to path filters (1)

• internal/update/CLAUDE.md is excluded by !**/*.md

📒 Files selected for processing (4)

• cmd/ana/main.go
• cmd/ana/main_test.go
• internal/update/selfupdate.go
• internal/update/selfupdate_test.go

---

📝 Walkthrough

Walkthrough

Updates to CLI verb handling and update-related error messages: run now captures the verb argument and passes it to drainNudge, which suppresses the update nudge after a successful ana update. Permission-denied errors in the update process are detected and routed through a new helper that provides OS-specific elevation guidance.

Changes

Cohort / File(s)	Summary
CLI Verb Handling cmd/ana/main.go, cmd/ana/main_test.go	Adds firstVerb helper to extract the leading verb from positional arguments and threads it through drainNudge to conditionally suppress nudge output on successful ana update invocations. New test cases verify both branches (suppressed on success, printed on error).
Update Error Handling internal/update/selfupdate.go, internal/update/selfupdate_test.go	Introduces formatReplaceErr to detect fs.ErrPermission during the rename phase and emit user-actionable messages: sudo on Unix, elevated Administrator shell guidance on Windows. All other rename errors retain wrapped error text. Comprehensive test suite covers both OS-specific permission scenarios and success paths.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat(update): update-check nudge + ana update self-update verb #23: Directly extends the nudge-suppression logic introduced here by threading the verb parameter through drainNudge and adjusting conditional behavior.
• fix(cli): global flags visible, position-tolerant, and surface usage errors #10: Modifies cmd/ana/main.go to use cli.StripGlobals for verb extraction, establishing the foundation for the firstVerb helper added in this PR.

Poem

🐰 A hop and a bound through error and nudge,
No pesky reminders when updates do budge.
Permission denied? We'll tell you to sudo,
Each rabbit's delight—a message that's true. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(update): actionable EACCES + suppress stale nudge' directly summarizes the two main changes: fixing EACCES error handling and suppressing the stale nudge post-update.
Description check	✅ Passed	The PR description comprehensively covers both issues, implementation details, and test validation. It follows the template structure with summary and explicit test completion status.
Linked Issues check	✅ Passed	The PR implementation fully satisfies issue #28 objectives: actionable EACCES messages via formatReplaceErr on Unix/Windows, suppression of stale nudge via verb parameter in drainNudge, and comprehensive test coverage.
Out of Scope Changes check	✅ Passed	All changes (refactored atomicReplace error handling, added drainNudge verb parameter, new firstVerb helper, and comprehensive tests) are directly scoped to fixing issue #28 with no extraneous modifications.
Docstring Coverage	✅ Passed	Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%.

_{✏️ 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/update-eacces-stale-nudge

---

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