test: AppRouterTests の CI flaky を withMainSerialExecutor で決定化する

[GeneralD]

AppRouterTests の 2 本が で不定期に落ちる。 #346（docs 1 行のみの変更）で発生し、同一コミットのまま再実行したら緑になった。

✘ "start forwards layout changes and player attachment to the window"
    (window.attachedPlayers.count → 0) == 1
    (window.appliedWallpaperScales → [1.0]).contains(1.4)
✘ "config reload that removes the wallpaper detaches the player from the window"
    (window.attachedPlayers.count → 0) == 1

手元では 0.34 秒で通る。 では 3 秒のポーリング期限を使い切って count が 0 のまま。10 倍の余裕があって落ちているので「わずかに遅い」ではない。

原因 — 化されているのは「時間」であって「実行順序」ではない

AppLaunchEnvironmentTests はどおり ImmediateClock() を注入しており、待機経路に Date() も Task.sleep も無い。それでも落ちるのは、待っているが時間ではないため。

router.start() → プレイヤー添付までの実際の経路（Sources/Presenters/Wallpaper/WallpaperPresenter.swift:69-94）:

configInteractor.appStyleChanges
    .receive(on: DispatchQueue.main)      // 実物の GCD ホップ
    .sink { ... }
loadWallpapers(source: interactor.wallpaperSource)

// loadWallpapers()
let stream = interactor.resolvedWallpapers()   // AsyncStream
loadTask = Task { @MainActor [weak self] in    // 非構造化 Task、ハンドルは private
    ...                                         // 最終的に onPlayerAvailable → attachPlayerLayer
}

ImmediateClock が早送りできるのは clock.sleep だけで、上の 3 つ（非化 Task のディスパッチ / AsyncStream の要素配送 / DispatchQueue.main ホップ）はすべて協調スレッドプールと GCD の管轄にあり、注入可能な継ぎ目が無い。

として waitUntil（AppLaunchEnvironmentTests.swift:14-22）は、

while !condition(), ContinuousClock.now < deadline {   // 実時計
    try? await Task.sleep(for: .milliseconds(10))
}

意味論的な問い（「その仕事はもう起きたか」）をマシンのスループットへの賭け（「3 秒以内にディスパッチされるか」）に変換している。負荷の高い runner では賭けが負ける。

waitUntil 自体は CLAUDE.md がする「固定 sleep ではなくポーリング」の正しい書き方であり、固定 sleep より確実に良い。ただし flake 確率を下げるだけで消しはしない — 待つ先が実時計である限り賭けは賭けのまま。

案 — withMainSerialExecutor

swift-concurrency-extras の withMainSerialExecutor で中グローバル executor を単一シリアル実行に固定し、Task の割り込み順を決定的にする。ポーリングは await Task.yield() にできる。

@Test("start forwards layout changes and player attachment to the window")
func startForwardsLayout() async {
    await withMainSerialExecutor {
        // …router.start() の後、ポーリングではなく yield で駆動
    }
}

• 本番コードに触らないのが最大の。Presenter に専用の継ぎ目を足す案（loadTask を await 可能にする）と比べ、production の API 面が増えない
• swift-concurrency-extras は swift-dependencies 経由で既に推移的に入っている（ビルドで確認済み）。Package.swift への明示的なが必要かは実装時に確認
• 現状このリポジトリで withMainSerialExecutor は一度も使われていない

該当箇所

• Tests/AppRouterTests/AppLaunchEnvironmentTests.swift:14-22 — waitUntil ヘルパー
• 同 :553, :603 — 落ちた 2 本のアサーション
• Sources/Presenters/Wallpaper/WallpaperPresenter.swift:69-94 — 待機の非決定性の出どころ（変更対象ではない、原因の所在として）

外

• waitUntil の期限延長 — 賭けの掛けを上げるだけで、賭けであることは変わらない
• 本番コードの変更 — Task + AsyncStream + Combine の設計自体は妥当。側で決定性を取り戻すのが筋
• リトライによる隠蔽 — で落ちたら再実行、を常態化させない

条件

• 落ちた 2 本が withMainSerialExecutor 配下で的に動く
• 実時計へのポーリング（waitUntil）がこの 2 本の経路から消えている
• 本番コードにが無い
• の待ち方をしている他のテストを洗い出し、範囲を明記（一括で直すか別対応かは実装時に判断）

同種の 負荷由来 flake は前歴がある（main の 9f7907f、ScopedAPISession の timing とサブプロセスの timing）。は別だが性質は同一なので、withMainSerialExecutor の適用範囲を検討する際の参考になる。

[GeneralD]

#348 を出しました。1 点、この issue の案から 意図的に外れた ので記録します。

withMainSerialExecutor はしたうえで却下

案 A のとおり ConcurrencyExtras の executor hook を TestScoping トレイトとしてし、AppRouterTests 単体では負荷下 20/20 pass でした。ところが 並列の swift test で無関係な 6 ターゲット 12 が落ちた（DarwinGateway.runProcess は 160 秒停滞）。

原因は hook の性質そのもの: uncheckedUseMainSerialExecutor は swift_task_enqueueGlobal_hook をる プロセス全域 の仕掛けで、トレイト付きテストが走っている間、プロセス内の全 thread-pool タスクが main に直列化される。PointFree のツールは XCTest の直列 invokeTest を提にしていて、数百 suite が同時に走る Swift Testing のプロセスとは相性が悪い。hook を外すとフルスイートが 1435/1435 pass（177 秒 → 3 秒）。

残した

の本体である「期限ポーリング → Task.yield() の drain」はそのまま。drain を no-op にすると と同一シグネチャで決定的に失敗する（順序を待っていた証拠）。ただし契約は「main queue に付きで届く仕事」に限定し、pool 由来の条件は期限ポーリングのまま — この境界を CLAUDE.md / AGENTS.md / docs/ARCHITECTURE.md に書きました。

条件のうち「withMainSerialExecutor 配下で決定的に動く」だけは、文言どおりには満たしていません（決定的には動いているが、hook 配下ではない）。

[GeneralD]

#348 の review 対応で、修正の本体を drain(until:)（Task.yield() のラウンド）から @Published の値を await する settle(_:until:) に差し替えました（dc1e7ef）。

CodeRabbit の指摘どおり、Task.yield() の反復は「serial executor が投入順に走る」という外の前提（Darwin の main queue では真、SE-0392 は保証しない）に依っていました。subject が書く値そのものを待てば、時間にも executor のにも仮定は要りません。SpyWindow の記録を @Published にし、時のハングは suite の .timeLimit(.minutes(1)) で有界にしています。本番コードは引き続き無。