Phase 4 (#135): instrumentation + remove starving 300ms Task.sleep

[obj-p]

Closes issue #135.

Origin and plan change

Opened as Phase 4A — diagnostic-only instrumentation to localize the post-reload wedge that Phases 1-3 caught-but-didn't-fix. The first CI run on this PR (run 72439165932) caught the wedge in action and pinpointed it to one specific line, so Phase 4B (the actual fix) got added to this same PR rather than a follow-up.

What the markers caught

From the CI dump, server `61077F6F`'s stderr after ~8 successful snapshot cycles:

```
[snapshot] enter
[snapshot] pre session-check
[snapshot] post session-check ← last marker before 10-minute silence
```

The ONLY code between `[snapshot] post session-check` and the never-fired `[snapshot] post 300ms sleep` is:

```swift
guard isMacOSSession else { ... } // no await
try await Task.sleep(for: .milliseconds(300)) // ← wedges here
```

`Task.sleep` ultimately depends on Swift's cooperative scheduler to resume. Under rapid snapshot polling (literal-only path has no swiftc breaks to drain the pool), the timer's continuation stays unscheduled — classic cooperative-pool starvation, the same class of failure PR #136 addressed for the test harness.

The fix

Remove the 300ms sleep. It was added in the initial commit (820b0cd) with the generic comment "Wait briefly for SwiftUI to finish layout." It's unnecessary: `Snapshot.capture` calls `NSView.cacheDisplay(in:to:)`, which forces layout synchronously when the view is dirty. The client→server round-trip already gives the UI plenty of time to settle.

All 7 `MacOSMCPTests` pass without the sleep — including both hot-reload tests, which assert image bytes actually change after the reload (would fail if capture returned stale frames).

Diagnostic markers stay

Keeping the `[snapshot]` and `[reload]` markers in place for at least one release cycle. They fire on every snapshot call on the macOS path (test-only visibility — `DaemonClient.registerStderrLogForwarder` doesn't forward raw daemon stderr), and they're the only reason we found the root cause. Tagged with `TODO(#135-4B)` for future cleanup. Follow-up PR can remove them once we're confident no other failure mode lurks in this handler.

Test plan

• `swift build` — clean
• `swift-format lint --strict --recursive Sources/ Tests/ examples/` — clean
• `swift test --filter MacOSMCPTests` — 7/7 pass, 72.5s locally (including `hotReloadLiteralOnly` 4.9s and `hotReloadStructural` 7.2s — both assert byte-diff after reload, so the removed sleep can't be hiding a capture-too-early bug)
• CI `build-and-test` — the critical validation; PR Phase 4 (#135): instrumentation + remove starving 300ms Task.sleep #139's prior CI run hit the wedge at the exact spot the fix targets

Related

Closes #135. Builds on all prior work:

• PR Add watchdog diagnostic for MCP integration test hangs #134 — diagnostic watchdog + post-failure stderr dump infrastructure (this PR's markers travel on it)
• PR Make MCPTestServer.withTimeout starvation-immune via pthread timer #136 — Phase 3 pthread test-harness timeout
• PR Add daemon-global 2s heartbeat notification (Phase 1 of issue #135) #137 — Phase 1 daemon heartbeat
• PR Add client-side stall detection via StallTimer (Phase 2 of issue #135) #138 — Phase 2 client stall detection
• PR Add previewsmcp logs subcommand and promote Debugging section #133 — the original logs subcommand that this whole epic unblocked

🤖 Generated with Claude Code