macOS: auto-migrate install.sh legacy install on first DMG launch

[sanity]

Problem

Users who previously installed Freenet via the old install.sh path on macOS have:

• Legacy CLI binary at /usr/local/bin/freenet (or ~/.local/bin/freenet)
• Legacy launchd agent ~/Library/LaunchAgents/org.freenet.node.plist that auto-starts the legacy binary on login

If such a user downloads the new signed DMG and installs Freenet.app, the current DMG code (landed in #3928 and follow-ups) only:

1. Detects org.freenet.node.plist via legacy_launchd_agent_present() and logs a warning with manual cleanup instructions
2. Treats "legacy present" as "already enabled" for the Launch-at-Login decision, so it doesn't write a duplicate plist

It does NOT remove the legacy plist, unload its launchd agent, or remove the legacy CLI. Consequences:

• On next login, launchd auto-starts the legacy (old-version) binary, binding port 7509. The new DMG's Freenet.app has to fight for the port if the user manually opens it.
• kill_stale_freenet_processes in the DMG wrapper pkills the legacy backend on startup, triggering a flap where the legacy launchd agent respawns it — then the new wrapper's backend loses the port race and exits 43.

Existing users are largely fine because the legacy install has its own auto-update mechanism and will keep picking up new versions. But anyone who WANTS to switch to the DMG path (e.g., because they want the tray and Launch-at-Login UX, or we promote the DMG as the preferred install) has to manually clean up first, per the warning log line.

Proposed solution

On first launch of DMG-installed Freenet.app (gated on the first-run marker), if legacy_launchd_agent_present() returns true, auto-migrate:

1. launchctl bootout gui/$UID ~/Library/LaunchAgents/org.freenet.node.plist
2. rm ~/Library/LaunchAgents/org.freenet.node.plist
3. rm /usr/local/bin/freenet and/or rm ~/.local/bin/freenet and/or rm ~/bin/freenet (whichever exist and are owned by the user)
4. Log each action clearly in the wrapper log
5. Proceed with the normal DMG-install first-run flow, which then writes the NEW org.freenet.Freenet.plist

Silent is appropriate — this matches what a Windows installer would do on upgrade and avoids a mystery dialog for users who don't understand their own install history. Data directories (~/Library/Application Support/freenet/) are shared between old and new installs, so user state is preserved across the migration.

Alternatives considered:

• AppleScript prompt ([Migrate / Skip]): more respectful of user choice but adds GUI dependency and a confusing dialog for users who don't know they have two installs.
• Documentation only: the current approach plus a quickstart-page note. Relies on users reading. Acceptable for v0.2.49 release but should not be the long-term answer.

Implementation notes

• Pure-function extraction per .claude/rules/deployment.md: legacy_install_migration_plan(exe_exists: bool, plist_exists: bool) -> MigrationAction → exhaustive cases, unit-testable on Linux CI.
• Scope to macOS only.
• Needs to handle sudo permission if the legacy CLI lives at /usr/local/bin/freenet and isn't user-owned. Fall back to logging "please manually remove X" if rm fails, rather than failing the whole migration.
• Write a regression test that reproduces the legacy-install scenario with a temp $HOME and asserts the migration cleans up correctly.

Priority

Medium. New-user DMG install path is unaffected (no legacy present). Existing install.sh users keep working via legacy auto-update. Only actively affects users who try to switch install mechanisms, which is a minority. Worth doing before we promote the DMG as the default install in the quickstart, but not urgent enough to block v0.2.49.

Context

Discussed in the lead-up to v0.2.49 (Freenet.org/quickstart will point at the DMG download once the dup-tray fix from #3939 lands). Ian confirmed existing users don't strictly need to migrate because the legacy install already auto-updates, so this is quality-of-life for deliberate migrators rather than a correctness blocker.

[AI-assisted - Claude]

[github-actions]

🤖 Auto-labeled

Applied labels:

• T-enhancement (95% confidence)
• P-medium (90% confidence)
• E-medium (80% confidence)
• A-developer-xp (85% confidence)

Reasoning: This issue requests an improvement to the macOS DMG installer to auto-migrate legacy install.sh artifacts (plist and CLI) on first launch. It's an enhancement to existing installer behavior rather than a bug or totally new feature (T-enhancement). The reporter marks priority as Medium and the change affects a subset of users switching install paths (P-medium). The implementation requires cross-user/path checks, sudo fallback handling, unit tests and macOS-specific commands, so it's moderate effort (E-medium). The change is primarily about installer/developer/user-experience for deployment on macOS, so A-developer-xp is appropriate.

Previous labels: none

If these labels are incorrect, please update them. This helps improve the auto-labeling system.

[sanity]

Issue Priority Assessment

Generated: 2026-05-26T15:54:33.595978938+00:00
Issue hash: df9bc30f

Value Assessment

The current macos_launch_at_login_startup function (lines 838–893) confirms the issue is still open. The code logs a warning and prevents a duplicate plist, but does not perform the auto-migration described in the issue — it does not call launchctl_bootout, does not remove the legacy plist file, and does not remove the legacy CLI binary.

---

Relevance Check: This issue remains fully relevant. The current code at service.rs:838–893 implements only the "detect and warn" behavior from the issue's problem statement, not the proposed solution. The launchctl_bootout helper exists (lines 647–677) and the legacy plist detection is already in place — the automation step of wiring them together has not been done.

User Impact: The impact is narrow but sharp for the specific users it hits: anyone who deliberately switches from the install.sh path to the DMG installer encounters a port-7509 race condition that causes the new app to fail at startup (exit code 43). This is a confusing, silent failure that requires command-line cleanup knowledge to resolve. For users migrating precisely because they want the tray/GUI experience, this is a particularly poor first impression. The population is small — new users and users who never installed the legacy path are unaffected — but it's likely to grow as the DMG becomes the promoted install method.

Strategic Alignment: The issue aligns directly with the stated goal of making the DMG the default install path on macOS. The issue notes that the quickstart page (freenet.org/quickstart) is planned to point at the DMG download once the dup-tray fix (#3939) lands. Promoting a download path that silently fails for a non-trivial class of existing users undermines adoption. The migration is also self-contained macOS-specific code, and the issue includes a well-specified pure-function extraction (legacy_install_migration_plan) that would keep the logic testable on Linux CI — exactly matching the project's deployment rules.

Blocking Factor and Urgency: This issue softly blocks the DMG-as-default promotion. It doesn't block any active development, but it does create a support tail once the DMG becomes the recommended path. The fix is low-risk (the building blocks — launchctl_bootout, rm with fallback-to-warn, first-run marker gating — are all already in the codebase) and self-contained to macOS tray code. Given the planned quickstart update, addressing this before that promotion would avoid user-reported failures. Medium-priority is appropriate; it's not an emergency, but it has a concrete trigger event (the quickstart redirect) that gives it urgency beyond pure nice-to-have.

Cost Assessment

The issue is well-scoped and still actionable. The relevant code is concentrated in crates/core/src/bin/commands/service.rs, specifically around legacy_launchd_agent_present() (line 812) and macos_launch_at_login_startup() (line 838). The current code already detects the legacy plist and treats it as "already enabled" — the migration logic simply needs to be added where the warning is currently logged (lines 848–856). The issue's proposed legacy_install_migration_plan() pure-function extraction pattern fits naturally into this code, and the existing disable_launch_at_login() / launchctl_bootout() infrastructure (lines 647–688) already implements the launchctl commands that the migration needs to call.

The scope is narrow: one macOS-only function to add, one call site to modify, and a handful of rm calls with graceful fallback for /usr/local/bin/freenet (which may require sudo). The sudo fallback is the main edge case — if the legacy CLI is at /usr/local/bin/freenet and not user-owned, the migration must skip that rm, log a manual-cleanup message, and continue. The uninstall.sh script (lines 202–220) already shows the correct launchctl bootout gui/$UID invocation pattern, so that's directly reusable. The first-run marker path is already established at ~/.local/share/freenet/.first-run-complete, so gating migration on first-run is trivial.

There are no external dependencies — no third-party services, no certificates, no approvals needed. The risk is low: the migration only fires on first launch when a legacy agent is present, the data directory is explicitly preserved (shared between old and new installs), and each step logs on failure rather than aborting. The one real risk is the kill_stale_freenet_processes / legacy-launchd respawn race described in the issue — but the migration running before that function is called would resolve it, or alternatively running migration before the normal flow starts.

Testing effort is moderate but well-defined. The issue itself calls for a regression test using a temp $HOME with a mock legacy plist, which is straightforward since legacy_launchd_agent_present() is a path check and launchctl calls can be stubbed or the whole function extracted as the pure legacy_install_migration_plan() the issue describes. The main test limitation is that CI runs on Linux, so launchctl calls must be behind #[cfg(target_os = "macos")] or mocked, but the pure-function extraction approach handles this cleanly. Overall this is a 1–2 day implementation: one focused Rust function, a few shell-removal calls with graceful fallback, and a regression test. The E-medium label is accurate.

---

Generated by issue-prioritizer