CLI talks to out-of-date daemon after upgrade (no version check)

[obj-p]

Problem

The daemon persists across CLI invocations (ADB-style, per AGENTS.md). When the user upgrades previewsmcp (via Homebrew, `brew upgrade` / reinstall; or via `swift build` / source), the new CLI binary starts talking to the old daemon that's still running. The daemon was booted from the previous binary version and stays alive until manually killed, rebooted, or explicitly told to exit.

Symptoms:

• New CLI features that depend on new daemon behaviors silently misbehave.
• Internal protocol tweaks (e.g., the v0.12.0 heartbeat channel and stall detection) can mismatch between versions; the CLI's stall timer may trip on an old daemon that doesn't emit heartbeats.
• Error messages shaped for the new daemon don't match old-daemon responses.

Reproducer

# Install old version
brew install obj-p/tap/previewsmcp  # say, v0.11.3

# Start daemon (any CLI command does this transparently)
previewsmcp status

# Upgrade
brew upgrade obj-p/tap/previewsmcp  # to v0.12.0

# CLI is new, daemon is still old:
previewsmcp --version   # shows 0.12.0
ps aux | grep "previewsmcp serve --daemon"  # shows process started by 0.11.3 binary

# User commands now go to the stale daemon:
previewsmcp logs        # new subcommand — works, since it's CLI-only
previewsmcp run ...     # goes to old daemon — may miss new features or trip stall timer

Options, ranked

1. Version handshake in the daemon's MCP initialize response (recommended)

Daemon embeds its binary version in its MCP `serverInfo.version` (already the case via PreviewsMCPCommand.version). On connect, the CLI compares server.serverInfo.version against its own compile-time version. On mismatch:

• CLI logs to stderr: "upgraded: restarting daemon (was X, now Y)"
• CLI calls `kill-daemon`, polls for shutdown
• CLI spawns a fresh daemon with the new binary
• CLI reconnects

This covers every install path (Homebrew, SPM, source build, IDE).

2. Homebrew post-install hook

Formula runs `previewsmcp kill-daemon` on upgrade. Clean for Homebrew users, but doesn't help anyone else. Useful as a secondary defense even with (1) in place — short-circuits the version check since the daemon is already dead before the new CLI connects.

3. Startup banner / warning only

On version mismatch, print a warning and continue. Low-effort, but requires users to act — most won't.

Why this matters more now

v0.12.0 introduces client-server protocol coupling that v0.11.3 didn't have:

• Daemon emits 2s heartbeat `LogMessageNotification` (new)
• CLI's `DaemonClient.withDaemonClient` has a 30s stall timer that expects those heartbeats
• New CLI talking to old daemon: 30s after connect, stall timer trips and disconnects

So v0.12.0 users who auto-upgrade over a running v0.11.x daemon will hit stall-disconnect errors on every command until they manually `kill-daemon`. That's a regression users will hit by simply doing `brew upgrade`.

Suggested scope for the fix

First PR: (1) alone. Handles every install path and fixes the v0.11→v0.12 upgrade specifically.

Follow-up: (2) as defense-in-depth, once the formula is touched for other reasons.

🤖 Filed from a Claude Code session after noticing the symptom on upgrade.

[obj-p]

Implementation plan (consensus reached with planning subagent)

Handshake

DaemonClient.connect captures Initialize.Result.serverInfo.version (currently discarded via _ =). Compares against PreviewsMCPCommand.version using baseVersion(_:), which strips only the git-describe suffix -<N>-g<SHA>$. So 0.12.0 matches 0.12.0-5-gabc123 (dev builds of the same base release don't thrash), but 0.12.0 ≠ 0.13.0 and 0.12.0 ≠ 0.12.0-rc.1.

Mismatch handling

1. Acquire flock(DaemonPaths.restartLock, LOCK_EX) — new file, sibling of pid file — so concurrent CLIs serialize.
2. After acquiring, re-stat pid file. If PID changed during the wait, a sibling CLI already restarted: re-probe the daemon and trust the fresh compare. Otherwise the cached Initialize.Result.serverInfo.version is still authoritative.
3. If still mismatched: write banner to stderr (previewsmcp: daemon was X, CLI is Y — restarting), await client.disconnect(), SIGTERM the old PID, poll DaemonLifecycle.isProcessAlive with ~5s timeout, spawnDaemon(), waitForSocket, open fresh NWConnection + Client, re-run configure, reconnect.
4. Guard with didRestart: Bool so we never loop. If the second handshake still mismatches, error names the env var as the likely culprit: daemon still reports X after restart; check _PREVIEWSMCP_TEST_DAEMON_VERSION in your shell environment.

Env strip in spawnDaemon (unconditional)

Respawned daemon inherits a filtered parent env: _PREVIEWSMCP_TEST_DAEMON_VERSION is removed. Unconditional — not test-gated — so a stray export in a shell rc can't cause a respawn loop regardless of whether tests are involved.

Test-only server-side hook

configureMCPServer reads _PREVIEWSMCP_TEST_DAEMON_VERSION and passes that to Server(version:) if present, else falls back to PreviewsMCPCommand.version. Leading underscore signals "internal, not a supported user knob." The client never reads this variable.

Breadcrumb

The respawning CLI sets _PREVIEWSMCP_DAEMON_RESTART_REASON=prev=X,now=Y,by=pid<Z> in the spawn env of the new daemon (and only the new daemon — this one env var is not stripped on that first spawn, obviously). Daemon startup logs one line to serve.log: daemon: started after version-mismatch restart (prev: X, now: Y, restarted by pid Z). Diagnoses restart loops without any persistent state.

Tests (all under DaemonTestLock.run)

1. happy_path_restart — kill-daemon; manually spawn previewsmcp serve --daemon with _PREVIEWSMCP_TEST_DAEMON_VERSION=0.0.0-stale-test set on the subprocess; capture the stale PID; invoke a fast withDaemonClient command (e.g. simulators --json) via CLIRunner.run without the override; assert: exit 0, stderr contains the banner with the stale version string, stale PID no longer alive, new daemon PID is different, new daemon advertises the real version.
2. no_restart_when_versions_match — daemon at the real version; CLI command; assert no banner on stderr, PID unchanged.
3. concurrent_clients_restart_once — stale daemon; two parallel CLIRunner.run calls via async let; assert exactly one banner is emitted, exactly one new daemon PID exists at the end, both commands exit 0.

Files to touch

• Sources/PreviewsCLI/DaemonClient.swift — capture Initialize.Result, add baseVersion(_:), lock + re-check + restart, env-strip in spawnDaemon, set breadcrumb env on respawn.
• Sources/PreviewsCLI/DaemonPaths.swift — add restartLock URL.
• Sources/PreviewsCLI/MCPServer.swift — honor _PREVIEWSMCP_TEST_DAEMON_VERSION; emit breadcrumb log line when _PREVIEWSMCP_DAEMON_RESTART_REASON is set.
• Tests/CLIIntegrationTests/VersionHandshakeTests.swift — new file, three tests.

Deferred (out of this PR)

• SIGTERM-resistant daemon + SIGKILL escalation — separable kill-daemon hardening. Will file as its own issue.
• Surfacing version in status output — nice-to-have, not needed for the fix.
• Homebrew post-install hook — already listed as follow-up in the issue body.

Key design decisions (from subagent critique)

• Serialization via flock, not accept-the-race. Brew upgrade + N editors each holding a CLI call open is a realistic concurrent-invocation scenario, not theoretical.
• Cache first Initialize.Result; don't re-probe unless pid changed. Avoids a full second connect/initialize round trip on the hot path for zero semantic gain.
• Env strip in spawnDaemon is unconditional, not test-only. Closes the shell-rc footgun regardless of test presence.
• Dev-build tolerance is narrow — strip only -<N>-g<SHA>$, not arbitrary pre-release tags. A 0.13.0-rc.1 daemon should not be considered equivalent to 0.13.0.
• Breadcrumb includes the restarting CLI's PID. Needed for diagnosing repeat-restart scenarios in the wild.

Work will land on branch worktree-issue-142-version-handshake.