fix(#318): 歌詞・メタデータ取得を呼び出し毎のephemeralセッション化し失敗をログ出力 (#320)

GeneralD · web-flow · commit 28239b7b348e · 2026-07-12T13:37:54.000+09:00
![agent](https://img.shields.io/badge/agent-claude-D97757) ![type](https://img.shields.io/badge/type-fix-blue) ![breaking](https://img.shields.io/badge/breaking-no-green) ![scope](https://img.shields.io/badge/scope-network-blue) ![diff](https://img.shields.io/badge/diff-+110%20--35-green) ![files](https://img.shields.io/badge/files-7%20files-yellow) ![tests](https://img.shields.io/badge/tests-added-green) ![review](https://img.shields.io/badge/review-thorough-yellow) ## <img src="https://mojiemoji.jozo.beer/emoji/%E6%A6%82%E8%A6%81?font=toge&amp;color=f43f5e&amp;animation=kage_neon&amp;background=transparent&amp;outline=5ef43f&amp;outline_width=2" alt="概要" height="20" align="absmiddle"> 長時間稼働した daemon で歌詞が<img src="https://mojiemoji.jozo.beer/emoji/%E8%A1%A8%E7%A4%BA?font=gothic&amp;color=a855f7&amp;animation=bure&amp;background=transparent&amp;outline=f7a855&amp;outline_width=2" alt="表示" height="20" align="absmiddle">されなくなり `lyra restart` でのみ復旧する<img src="https://mojiemoji.jozo.beer/emoji/%E3%83%90%E3%82%B0?font=gothic-bold&amp;color=ef4444&amp;animation=gatagata&amp;speed=slow&amp;background=transparent&amp;outline=44ef44&amp;outline_width=2" alt="バグ" height="24" align="absmiddle">の<img src="https://mojiemoji.jozo.beer/emoji/%E4%BF%AE%E6%AD%A3?font=gothic-bold&amp;color=ef4444&amp;animation=kirari&amp;background=transparent&amp;outline=44ef44&amp;outline_width=2" alt="修正" height="20" align="absmiddle">。プロセス寿命の `URLSession.shared` を引き回すのをやめ、<img src="https://mojiemoji.jozo.beer/emoji/API?font=mincho&amp;color=10b981&amp;animation=patapata&amp;background=transparent&amp;outline=8110b9&amp;outline_width=2" alt="API" height="20" align="absmiddle"> 呼び出し毎に ephemeral セッションを<img src="https://mojiemoji.jozo.beer/emoji/%E7%94%9F%E6%88%90?font=maru&amp;color=facc15&amp;animation=tate_scroll&amp;background=transparent&amp;outline=04ca8a&amp;outline_width=2" alt="生成" height="20" align="absmiddle">する。 Closes #318 ## <img src="https://mojiemoji.jozo.beer/emoji/%E5%A4%89%E6%9B%B4?font=gothic&amp;color=22d3ee&amp;animation=tate_scroll&amp;background=transparent&amp;outline=b20891&amp;outline_width=2" alt="変更" height="20" align="absmiddle"><img src="https://mojiemoji.jozo.beer/emoji/%E5%86%85%E5%AE%B9?font=gothic&amp;color=fdba74&amp;animation=kira&amp;background=transparent&amp;outline_width=0" alt="内容" height="20" align="absmiddle"> - `LyricsDataSourceImpl` / `MusicBrainzMetadataDataSourceImpl`: `apiFactory` 化し、呼び出し毎に `URLSessionConfiguration.ephemeral` + request timeout 10 秒のセッションを<img src="https://mojiemoji.jozo.beer/emoji/%E7%94%9F%E6%88%90?font=maru&amp;color=facc15&amp;animation=tate_scroll&amp;background=transparent&amp;outline=04ca8a&amp;outline_width=2" alt="生成" height="20" align="absmiddle">（`LRCLibHealthCheck` と<img src="https://mojiemoji.jozo.beer/emoji/%E5%90%8C%E3%81%98?font=dela&amp;color=60a5fa&amp;animation=mochimochi&amp;background=transparent&amp;outline=fa60a5&amp;outline_width=2" alt="同じ" height="20" align="absmiddle"><img src="https://mojiemoji.jozo.beer/emoji/%E6%A7%8B%E6%88%90?font=zero&amp;color=a855f7&amp;animation=kage_bokashi&amp;background=transparent&amp;outline=f7a855&amp;outline_width=2" alt="構成" height="20" align="absmiddle">）。`init(api:)` の<img src="https://mojiemoji.jozo.beer/emoji/%E3%83%86%E3%82%B9%E3%83%88?font=maru-bold&amp;color=fbbf24&amp;animation=yokomoya&amp;background=transparent&amp;outline=06d977&amp;outline_width=2" alt="テスト" height="20" align="absmiddle">シームは<img src="https://mojiemoji.jozo.beer/emoji/%E7%B6%AD%E6%8C%81?font=maru-bold&amp;color=60a5fa&amp;animation=yurayura&amp;speed=slow&amp;background=transparent&amp;outline=fa60a5&amp;outline_width=2" alt="維持" height="24" align="absmiddle"> - `OpenAICompatibleAPI.provider(for:)`: <img src="https://mojiemoji.jozo.beer/emoji/%E5%90%8C%E6%A7%98%E3%81%AB?font=maru&amp;color=a78bfa&amp;animation=neruneru&amp;speed=slow&amp;background=transparent&amp;outline=faa78b&amp;outline_width=2" alt="同様に" height="24" align="absmiddle"> ephemeral セッション化。タイムアウトは従来の `URLSession.shared` デフォルトと同値の 60 秒を明示（ローカル LLM の長い推論を<img src="https://mojiemoji.jozo.beer/emoji/%E8%80%83%E6%85%AE?font=mincho&amp;color=fbbf24&amp;animation=patapata&amp;speed=slow&amp;background=transparent&amp;outline=24fbbf&amp;outline_width=2" alt="考慮" height="24" align="absmiddle">） - `try?` によるエラー握りつぶしを<img src="https://mojiemoji.jozo.beer/emoji/%E5%BB%83%E6%AD%A2?font=gothic-bold&amp;color=fb923c&amp;animation=zanzo&amp;speed=slow&amp;background=transparent&amp;outline=3cfb92&amp;outline_width=2" alt="廃止" height="24" align="absmiddle">し、取得<img src="https://mojiemoji.jozo.beer/emoji/%E5%A4%B1%E6%95%97?font=hachimaru&amp;color=f472b6&amp;animation=mozaiku&amp;background=transparent&amp;outline=b6f472&amp;outline_width=2" alt="失敗" height="20" align="absmiddle">を stderr に<img src="https://mojiemoji.jozo.beer/emoji/%E3%83%AD%E3%82%B0?font=maru-bold&amp;color=10b981&amp;animation=tatemoya&amp;background=transparent&amp;outline=8110b9&amp;outline_width=2" alt="ログ" height="20" align="absmiddle"><img src="https://mojiemoji.jozo.beer/emoji/%E5%87%BA%E5%8A%9B?font=gothic-bold&amp;color=fb7185&amp;animation=yokomoya&amp;background=transparent&amp;outline=85fb71&amp;outline_width=2" alt="出力" height="20" align="absmiddle">。LRCLIB の 404（歌詞なしの<img src="https://mojiemoji.jozo.beer/emoji/%E6%AD%A3%E5%B8%B8?font=gothic&amp;color=34d399&amp;animation=zanzo&amp;background=transparent&amp;outline=9934d3&amp;outline_width=2" alt="正常" height="20" align="absmiddle"><img src="https://mojiemoji.jozo.beer/emoji/%E5%BF%9C%E7%AD%94?font=gothic-bold&amp;color=c084fc&amp;animation=ekken&amp;background=transparent&amp;outline=fcc084&amp;outline_width=2" alt="応答" height="20" align="absmiddle">）のみ<img src="https://mojiemoji.jozo.beer/emoji/%E3%83%AD%E3%82%B0?font=akzk&amp;color=60a5fa&amp;animation=bure&amp;background=transparent&amp;outline=fa60a5&amp;outline_width=2" alt="ログ" height="20" align="absmiddle"><img src="https://mojiemoji.jozo.beer/emoji/%E5%AF%BE%E8%B1%A1?font=akzk&amp;color=facc15&amp;animation=disco&amp;background=transparent&amp;outline_width=0" alt="対象" height="20" align="absmiddle">外とし、「歌詞なし」と「取得<img src="https://mojiemoji.jozo.beer/emoji/%E5%A4%B1%E6%95%97?font=maru-bold&amp;color=3b82f6&amp;animation=yokomoya&amp;background=transparent&amp;outline=f63b82&amp;outline_width=2" alt="失敗" height="20" align="absmiddle">」を<img src="https://mojiemoji.jozo.beer/emoji/%E5%8C%BA%E5%88%A5?font=maru-bold&amp;color=34d399&amp;animation=kirari&amp;speed=slow&amp;background=transparent&amp;outline=9934d3&amp;outline_width=2" alt="区別" height="24" align="absmiddle"><img src="https://mojiemoji.jozo.beer/emoji/%E5%8F%AF%E8%83%BD?font=kurobara&amp;color=a78bfa&amp;animation=kira&amp;background=transparent&amp;outline_width=0" alt="可能" height="20" align="absmiddle">に - <img src="https://mojiemoji.jozo.beer/emoji/%E3%83%86%E3%82%B9%E3%83%88?font=zero&amp;color=a78bfa&amp;animation=chirichiri&amp;background=transparent&amp;outline=ed7c3a&amp;outline_width=2" alt="テスト" height="20" align="absmiddle">: 404 サイレント分岐の<img src="https://mojiemoji.jozo.beer/emoji/%E3%83%86%E3%82%B9%E3%83%88?font=maru-bold&amp;color=fbbf24&amp;animation=yokomoya&amp;background=transparent&amp;outline=06d977&amp;outline_width=2" alt="テスト" height="20" align="absmiddle">を<img src="https://mojiemoji.jozo.beer/emoji/%E8%BF%BD%E5%8A%A0?font=pixel&amp;color=22d3ee&amp;animation=yatta&amp;speed=normal&amp;background=transparent&amp;outline=ee22d3&amp;outline_width=2" alt="追加" height="24" align="absmiddle">。LLM のプロダクション配線<img src="https://mojiemoji.jozo.beer/emoji/%E3%83%86%E3%82%B9%E3%83%88?font=zero&amp;color=a78bfa&amp;animation=chirichiri&amp;background=transparent&amp;outline=ed7c3a&amp;outline_width=2" alt="テスト" height="20" align="absmiddle">は、ephemeral セッションがグローバル `URLProtocol.registerClass` を経由しなくなったため、refused port (`http://127.0.0.1:1`) での graceful degradation <img src="https://mojiemoji.jozo.beer/emoji/%E6%A4%9C%E8%A8%BC?font=gothic&amp;color=22c55e&amp;animation=nami&amp;background=transparent&amp;outline=5e22c5&amp;outline_width=2" alt="検証" height="20" align="absmiddle">に<img src="https://mojiemoji.jozo.beer/emoji/%E5%A4%89%E6%9B%B4?font=pixel&amp;color=c084fc&amp;animation=disco&amp;background=transparent&amp;outline_width=0" alt="変更" height="20" align="absmiddle">（`OpenAICompatibleHealthCheckDefaultBackendTests` の<img src="https://mojiemoji.jozo.beer/emoji/%E6%97%A2%E5%AD%98?font=maru-bold&amp;color=c084fc&amp;animation=ekken&amp;background=transparent&amp;outline=fcc084&amp;outline_width=2" alt="既存" height="20" align="absmiddle">パターンを<img src="https://mojiemoji.jozo.beer/emoji/%E8%B8%8F%E8%A5%B2?font=mincho&amp;color=c084fc&amp;animation=tatemoya&amp;speed=slow&amp;background=transparent&amp;outline=fcc084&amp;outline_width=2" alt="踏襲" height="24" align="absmiddle">） - CLAUDE.md: Key Design Decisions に「Network session strategy」を<img src="https://mojiemoji.jozo.beer/emoji/%E8%BF%BD%E8%A8%98?font=gothic-bold&amp;color=67e8f9&amp;animation=ekken&amp;speed=slow&amp;background=transparent&amp;outline=f967e8&amp;outline_width=2" alt="追記" height="24" align="absmiddle"> - version 2.21.0 → 2.21.1 ## 背景・<img src="https://mojiemoji.jozo.beer/emoji/%E5%8B%95%E6%A9%9F?font=tamanegi&amp;color=3b82f6&amp;animation=ekken&amp;background=transparent&amp;outline=f63b82&amp;outline_width=2" alt="動機" height="20" align="absmiddle"> 症状は「<img src="https://mojiemoji.jozo.beer/emoji/%E5%90%8C%E3%81%98?font=mincho&amp;color=a78bfa&amp;animation=yatta&amp;background=transparent&amp;outline=ed7c3a&amp;outline_width=2" alt="同じ" height="20" align="absmiddle">メタデータなのに再起動<img src="https://mojiemoji.jozo.beer/emoji/%E7%9B%B4%E5%BE%8C?font=gothic-bold&amp;color=f472b6&amp;animation=shuchusen&amp;background=transparent&amp;outline=77db27&amp;outline_width=2" alt="直後" height="20" align="absmiddle">だけ歌詞がヒットする」＝プロセス内に時間経過で腐る状態がある、を示唆していた。<img src="https://mojiemoji.jozo.beer/emoji/%E8%AA%BF%E6%9F%BB?font=chikara&amp;color=f43f5e&amp;animation=bane&amp;background=transparent&amp;outline=5ef43f&amp;outline_width=2" alt="調査" height="20" align="absmiddle">の<img src="https://mojiemoji.jozo.beer/emoji/%E7%B5%90%E6%9E%9C?font=zero&amp;color=c084fc&amp;animation=mozaiku&amp;background=transparent&amp;outline=fcc084&amp;outline_width=2" alt="結果" height="20" align="absmiddle">、LRCLIB 呼び出しが `static let liveValue` シングルトン + `URLSession.shared` + `try?` 全握りつぶしという<img src="https://mojiemoji.jozo.beer/emoji/%E6%A7%8B%E6%88%90?font=kurobara&amp;color=34d399&amp;animation=tatemoya&amp;background=transparent&amp;outline=9934d3&amp;outline_width=2" alt="構成" height="20" align="absmiddle">で、スリープ復帰やネットワーク<img src="https://mojiemoji.jozo.beer/emoji/%E5%88%87%E6%9B%BF?font=hachimaru&amp;color=fb923c&amp;animation=mabataki&amp;background=transparent&amp;outline=0cea58&amp;outline_width=2" alt="切替" height="20" align="absmiddle">でコネクションプールが死んでも<img src="https://mojiemoji.jozo.beer/emoji/%E6%A4%9C%E7%9F%A5?font=pixel&amp;color=ef4444&amp;animation=bure&amp;background=transparent&amp;outline=44ef44&amp;outline_width=2" alt="検知" height="20" align="absmiddle">も張り替えも<img src="https://mojiemoji.jozo.beer/emoji/%E3%83%AD%E3%82%B0?font=dela&amp;color=facc15&amp;animation=mabataki&amp;background=transparent&amp;outline=04ca8a&amp;outline_width=2" alt="ログ" height="20" align="absmiddle">もされないことが<img src="https://mojiemoji.jozo.beer/emoji/%E5%88%A4%E6%98%8E?font=mincho&amp;color=fde047&amp;animation=mabataki&amp;speed=slow&amp;background=transparent&amp;outline=47fde0&amp;outline_width=2" alt="判明" height="24" align="absmiddle">（<img src="https://mojiemoji.jozo.beer/emoji/%E8%A9%B3%E7%B4%B0?font=chikara&amp;color=a855f7&amp;animation=kira&amp;background=transparent&amp;outline_width=0" alt="詳細" height="20" align="absmiddle">は #318 の仮説 1）。ヘルスチェック (`LRCLibHealthCheck`) だけが ephemeral + 10 秒タイムアウトの<img src="https://mojiemoji.jozo.beer/emoji/%E5%A0%85%E7%89%A2?font=gothic-bold&amp;color=f9a8d4&amp;animation=zairu&amp;speed=slow&amp;background=transparent&amp;outline=d4f9a8&amp;outline_width=2" alt="堅牢" height="24" align="absmiddle">な<img src="https://mojiemoji.jozo.beer/emoji/%E6%A7%8B%E6%88%90?font=kurobara&amp;color=34d399&amp;animation=tatemoya&amp;background=transparent&amp;outline=9934d3&amp;outline_width=2" alt="構成" height="20" align="absmiddle">だったため、本番経路をこれに揃えた。 ## <img src="https://mojiemoji.jozo.beer/emoji/%E3%83%86%E3%82%B9%E3%83%88?font=zero&amp;color=a78bfa&amp;animation=chirichiri&amp;background=transparent&amp;outline=ed7c3a&amp;outline_width=2" alt="テスト" height="20" align="absmiddle">計画 - [x] `swift test` 全 1205 <img src="https://mojiemoji.jozo.beer/emoji/%E3%83%86%E3%82%B9%E3%83%88?font=hachimaru&amp;color=f43f5e&amp;animation=yoko_scroll&amp;background=transparent&amp;outline=5ef43f&amp;outline_width=2" alt="テスト" height="20" align="absmiddle"> pass - [x] `make lint` クリーン - [ ] 実機で daemon を長時間稼働させ、スリープ復帰・ネットワーク<img src="https://mojiemoji.jozo.beer/emoji/%E5%88%87%E6%9B%BF?font=tamanegi&amp;color=f87171&amp;animation=patapata&amp;background=transparent&amp;outline=26dc26&amp;outline_width=2" alt="切替" height="20" align="absmiddle">後も歌詞が取得され続けることを<img src="https://mojiemoji.jozo.beer/emoji/%E7%A2%BA%E8%AA%8D?font=gothic-bold&amp;color=d946ef&amp;animation=zairu&amp;background=transparent&amp;outline=efd946&amp;outline_width=2" alt="確認" height="20" align="absmiddle">（<img src="https://mojiemoji.jozo.beer/emoji/%E7%99%BA%E7%94%9F?font=mincho&amp;color=ec4899&amp;animation=gatagata&amp;background=transparent&amp;outline=99ec48&amp;outline_width=2" alt="発生" height="20" align="absmiddle">条件が長時間のため、リリース<img src="https://mojiemoji.jozo.beer/emoji/%E5%BE%8C?font=chikara&amp;color=10b981&amp;animation=mozaiku&amp;background=transparent&amp;outline=8110b9&amp;outline_width=2" alt="後" height="20" align="absmiddle">の<img src="https://mojiemoji.jozo.beer/emoji/%E7%B5%8C%E9%81%8E?font=maru-bold&amp;color=93c5fd&amp;animation=yoko_scroll&amp;speed=slow&amp;background=transparent&amp;outline=fd93c5&amp;outline_width=2" alt="経過" height="24" align="absmiddle"><img src="https://mojiemoji.jozo.beer/emoji/%E8%A6%B3%E5%AF%9F?font=maru&amp;color=86efac&amp;animation=chirichiri&amp;speed=slow&amp;background=transparent&amp;outline=ac86ef&amp;outline_width=2" alt="観察" height="24" align="absmiddle">） ## 備考 - 呼び出し毎のセッション<img src="https://mojiemoji.jozo.beer/emoji/%E7%94%9F%E6%88%90?font=dela&amp;color=fb923c&amp;animation=ekken&amp;background=transparent&amp;outline=0cea58&amp;outline_width=2" alt="生成" height="20" align="absmiddle">は TLS ハンドシェイクが毎回走るが、歌詞・メタデータ取得はトラック変化毎の低頻度なので<img src="https://mojiemoji.jozo.beer/emoji/%E5%AE%9F%E5%AE%B3?font=mincho&amp;color=f87171&amp;animation=tenmetsu&amp;speed=slow&amp;background=transparent&amp;outline=71f871&amp;outline_width=2" alt="実害" height="24" align="absmiddle">はない - ネガティブキャッシュや `NWPathMonitor` 契機のセッション再<img src="https://mojiemoji.jozo.beer/emoji/%E7%94%9F%E6%88%90?font=maru&amp;color=facc15&amp;animation=tate_scroll&amp;background=transparent&amp;outline=04ca8a&amp;outline_width=2" alt="生成" height="20" align="absmiddle">（#318 <img src="https://mojiemoji.jozo.beer/emoji/%E5%AF%BE%E5%BF%9C?font=maru&amp;color=fdba74&amp;animation=chirichiri&amp;background=transparent&amp;outline=74fdba&amp;outline_width=2" alt="対応" height="20" align="absmiddle">案の残り）は、本<img src="https://mojiemoji.jozo.beer/emoji/%E4%BF%AE%E6%AD%A3?font=gothic-bold&amp;color=ef4444&amp;animation=kirari&amp;background=transparent&amp;outline=44ef44&amp;outline_width=2" alt="修正" height="20" align="absmiddle">で症状が解消するかの経過観察後に<img src="https://mojiemoji.jozo.beer/emoji/%E5%BF%85%E8%A6%81?font=chikara&amp;color=facc15&amp;animation=tate_scroll&amp;background=transparent&amp;outline=04ca8a&amp;outline_width=2" alt="必要" height="20" align="absmiddle">なら別 issue で<img src="https://mojiemoji.jozo.beer/emoji/%E5%AF%BE%E5%BF%9C?font=zero&amp;color=a78bfa&amp;animation=yatta&amp;background=transparent&amp;outline=ed7c3a&amp;outline_width=2" alt="対応" height="20" align="absmiddle">する
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -349,6 +349,8 @@ Cache is Repository's responsibility, not DataSource's. DataSources are pure API
 
 **MetadataRepository cache strategy**: Priority order: LLM cache → LLM DataSource → MusicBrainz cache → MusicBrainz DataSource → Regex DataSource. LLM/MusicBrainz results are cached on success. Regex results are not cached.
 
+**Network session strategy — ephemeral session per call (#318)**: The API DataSources (LRCLIB lyrics, MusicBrainz, OpenAI-compatible LLM) must NOT hold a process-lifetime `URLSession`. In a long-running daemon, pooled connections go silently stale after sleep/wake or network changes, and with every request error swallowed by `try?` the only visible symptom was "lyrics never appear until `lyra restart`" (#318). The shared mechanism is the generic `ScopedAPISession<API>` (its own `Sources/ScopedAPISession` module, Foundation-only): `withAPI { … }` builds a `URLSessionConfiguration.ephemeral` session (request timeout is a per-service init arg — 10 s for LRCLIB/MusicBrainz, 60 s for the LLM, which matches the old `URLSession.shared` default since local LLMs can take tens of seconds per completion), runs the call, and `finishTasksAndInvalidate()`s the session in a `defer`. The session is deliberately **function-local**, not stored behind a class that invalidates in `deinit`: a stored-session/`deinit` design is ARC-fragile — once the caller copies the wrapped client out, the owner (and its session) can be released *before* the request is issued, killing an in-flight or not-yet-started call. Each DataSource holds a `ScopedAPISession<any XxxAPI>` and keeps its `init(api:)` test seam (which wraps a constant `{ _ in stub }` factory — the throwaway session the stub ignores). Per-API differences (base URL, Bearer auth) live in the `makeAPI` closure, so one generic type replaces the three former per-protocol wrapper classes. `LRCLibHealthCheck` already used this exact ephemeral+timeout construction; the daemon path now matches it. Failures are logged to stderr (`lyra: LRCLIB get failed: …`), except LRCLIB 404 which is the regular "no lyrics for this track" answer — so "no lyrics" and "fetch broken" stay distinguishable in the daemon log. Test gotcha: a per-call ephemeral session ignores `URLProtocol.registerClass` (that hook only applies to `URLSession.shared`), so production-wiring tests assert graceful degradation against a refused local port (`http://127.0.0.1:1`) instead of a global URL-protocol mock.
+
 **ColorStyle**: Domain-level enum (`.solid(hex)`, `.gradient([hex])`) enabling any text style to use either solid colors or gradients. Polymorphic TOML decoding supports both `color = "#FFF"` and `color = ["#AAA", "#BBB"]`.
 
 **DI with swift-dependencies**: Protocol definitions + `TestDependencyKey` in `Domain`, all Domain-facing `liveValue` registrations centralized in `DependencyInjection` module (`InteractorRegistration`, `UseCaseRegistration`, `RepositoryRegistration`, `DataSourceRegistration`, `DataStoreRegistration`, `HealthCheckRegistration`). No direct instantiation — everything through `@Dependency`. AppKit foreground lifecycle is an App-module bootstrap dependency because the live implementation owns `NSApplication` and `AppDelegate` setup. UI-test mode is the other wiring-location exception: `AppRouter` may override a small fixture graph at launch based on environment variables, but feature code still reads dependencies normally through `@Dependency`.
diff --git a/Package.swift b/Package.swift
@@ -380,17 +380,20 @@ let package = Package(
                 .product(name: "TOMLKit", package: "TOMLKit"),
             ]
         ),
+        .target(name: "ScopedAPISession"),
         .target(
             name: "LyricsDataSource",
             dependencies: [
                 "Domain",
+                "ScopedAPISession",
                 .product(name: "Papyrus", package: "papyrus"),
             ]
         ),
         .target(
             name: "MetadataDataSource",
             dependencies: [
                 "Domain",
+                "ScopedAPISession",
                 .product(name: "Papyrus", package: "papyrus"),
                 .product(name: "Dependencies", package: "swift-dependencies"),
             ]
@@ -447,6 +450,12 @@ let package = Package(
 
         // ══ Tests ══
 
+        .testTarget(
+            name: "ScopedAPISessionTests",
+            dependencies: [
+                "ScopedAPISession"
+            ]
+        ),
         .testTarget(
             name: "TrackInteractorTests",
             dependencies: [
diff --git a/Sources/LyricsDataSource/LyricsDataSourceImpl.swift b/Sources/LyricsDataSource/LyricsDataSourceImpl.swift
@@ -1,31 +1,60 @@
 import Domain
 import Foundation
-import Papyrus
+@preconcurrency import Papyrus
+import ScopedAPISession
 
 public struct LyricsDataSourceImpl {
-    private let api: any LRCLib
+    private let apiSession: ScopedAPISession<any LRCLib>
 
     public init() {
-        self.init(api: LRCLibAPI(provider: Provider(baseURL: LRCLibAPI.baseURL)))
+        self.init(
+            apiSession: ScopedAPISession(timeout: 10) {
+                LRCLibAPI(provider: Provider(baseURL: LRCLibAPI.baseURL, urlSession: $0))
+            }
+        )
     }
 
     init(api: any LRCLib) {
-        self.api = api
+        self.init(apiSession: ScopedAPISession(timeout: 10) { _ in api })
+    }
+
+    init(apiSession: ScopedAPISession<any LRCLib>) {
+        self.apiSession = apiSession
     }
 }
 
-// Safe: `api` is set at init and never mutated; Papyrus's Provider is configured during construction only.
-extension LyricsDataSourceImpl: @unchecked Sendable {}
+extension LyricsDataSourceImpl: Sendable {}
 
 extension LyricsDataSourceImpl: LyricsDataSource {
     public func get(title: String, artist: String, duration: TimeInterval?) async -> LyricsResult? {
-        guard let result = try? await api.get(trackName: title, artistName: artist, duration: duration.map(Int.init)),
-            result.plainLyrics != nil || result.syncedLyrics != nil
-        else { return nil }
-        return result
+        do {
+            let result = try await apiSession.withAPI {
+                try await $0.get(trackName: title, artistName: artist, duration: duration.map(Int.init))
+            }
+            guard result.plainLyrics != nil || result.syncedLyrics != nil else { return nil }
+            return result
+        } catch {
+            log(error, operation: "get")
+            return nil
+        }
     }
 
     public func search(query: String) async -> [LyricsResult]? {
-        try? await api.search(q: query)
+        do {
+            return try await apiSession.withAPI { try await $0.search(q: query) }
+        } catch {
+            log(error, operation: "search")
+            return nil
+        }
+    }
+}
+
+extension LyricsDataSourceImpl {
+    // 404 is LRCLIB's regular "no lyrics for this track" answer; only transport
+    // and server failures are worth surfacing so "no lyrics" and "fetch broken"
+    // stay distinguishable in the daemon log (#318).
+    private func log(_ error: some Error, operation: String) {
+        if let papyrusError = error as? PapyrusError, papyrusError.response?.statusCode == 404 { return }
+        fputs("lyra: LRCLIB \(operation) failed: \(error)\n", stderr)
     }
 }
diff --git a/Sources/MetadataDataSource/API/OpenAICompatibleAPI.swift b/Sources/MetadataDataSource/API/OpenAICompatibleAPI.swift
@@ -10,12 +10,16 @@ public protocol OpenAICompatible {
 }
 
 extension OpenAICompatible {
-    public static func provider(for config: AIEndpoint) -> Provider {
+    /// Builds the auth-attaching Provider. The session comes from the caller's
+    /// `ScopedAPISession` in production (#318); the `nil` default gives a
+    /// throwaway ephemeral session for construction-only tests that never make a
+    /// network call.
+    public static func provider(for config: AIEndpoint, urlSession: URLSession? = nil) -> Provider {
         let endpoint =
             config.endpoint.hasSuffix("/")
             ? String(config.endpoint.dropLast())
             : config.endpoint
-        return Provider(baseURL: endpoint).modifyRequests { req in
+        return Provider(baseURL: endpoint, urlSession: urlSession ?? URLSession(configuration: .ephemeral)).modifyRequests { req in
             req.addHeader("Authorization", value: "Bearer \(config.apiKey)")
         }
     }
diff --git a/Sources/MetadataDataSource/LLMMetadataDataSourceImpl.swift b/Sources/MetadataDataSource/LLMMetadataDataSourceImpl.swift
@@ -2,19 +2,31 @@ import Dependencies
 import Domain
 import Foundation
 @preconcurrency import Papyrus
+import ScopedAPISession
 
 public struct LLMMetadataDataSourceImpl {
     @Dependency(\.configDataSource) private var configDataSource
-    private let apiFactory: @Sendable (AIEndpoint) -> any OpenAICompatible
+    private let sessionFactory: @Sendable (AIEndpoint) -> ScopedAPISession<any OpenAICompatible>
 
     public init() {
-        self.init { config in
-            OpenAICompatibleAPI(provider: OpenAICompatibleAPI.provider(for: config))
-        }
+        self.init(sessionFactory: { config in
+            ScopedAPISession(timeout: 60) {
+                OpenAICompatibleAPI(provider: OpenAICompatibleAPI.provider(for: config, urlSession: $0))
+            }
+        })
     }
 
+    // Test seam: inject a plain API factory (a stub). The scoped session it is
+    // wrapped in creates and tears down a throwaway ephemeral session the stub
+    // ignores, so the production call path is exercised without a network call.
     init(apiFactory: @escaping @Sendable (AIEndpoint) -> any OpenAICompatible) {
-        self.apiFactory = apiFactory
+        self.init(sessionFactory: { config in
+            ScopedAPISession(timeout: 60) { _ in apiFactory(config) }
+        })
+    }
+
+    init(sessionFactory: @escaping @Sendable (AIEndpoint) -> ScopedAPISession<any OpenAICompatible>) {
+        self.sessionFactory = sessionFactory
     }
 }
 
@@ -32,13 +44,12 @@ extension LLMMetadataDataSourceImpl: MetadataDataSource {
 
 extension LLMMetadataDataSourceImpl {
     fileprivate func callAPI(config: AIEndpoint, rawTitle: String, rawArtist: String) async -> ExtractedMetadata? {
-        let api = apiFactory(config)
         let request = MetadataExtractionPrompt(rawTitle: rawTitle, rawArtist: rawArtist)
             .request(model: config.model)
 
         let response: ChatCompletionResponse
         do {
-            response = try await api.chatCompletion(request: request)
+            response = try await sessionFactory(config).withAPI { try await $0.chatCompletion(request: request) }
         } catch {
             fputs("lyra: AI extraction failed: \(error)\n", stderr)
             return nil
diff --git a/Sources/MetadataDataSource/MusicBrainzMetadataDataSourceImpl.swift b/Sources/MetadataDataSource/MusicBrainzMetadataDataSourceImpl.swift
@@ -1,21 +1,29 @@
 import Domain
 import Foundation
 @preconcurrency import Papyrus
+import ScopedAPISession
 
 public struct MusicBrainzMetadataDataSourceImpl {
-    private let api: any MusicBrainz
+    private let apiSession: ScopedAPISession<any MusicBrainz>
 
     public init() {
-        self.init(api: MusicBrainzAPI(provider: Provider(baseURL: MusicBrainzAPI.baseURL)))
+        self.init(
+            apiSession: ScopedAPISession(timeout: 10) {
+                MusicBrainzAPI(provider: Provider(baseURL: MusicBrainzAPI.baseURL, urlSession: $0))
+            }
+        )
     }
 
     init(api: any MusicBrainz) {
-        self.api = api
+        self.init(apiSession: ScopedAPISession(timeout: 10) { _ in api })
+    }
+
+    init(apiSession: ScopedAPISession<any MusicBrainz>) {
+        self.apiSession = apiSession
     }
 }
 
-// Safe: `api` is set at init and never mutated; Papyrus's Provider is configured during construction only.
-extension MusicBrainzMetadataDataSourceImpl: @unchecked Sendable {}
+extension MusicBrainzMetadataDataSourceImpl: Sendable {}
 
 extension MusicBrainzMetadataDataSourceImpl: MetadataDataSource {
     public func resolve(track: Track) async -> [MusicBrainzMetadata] {
@@ -26,10 +34,14 @@ extension MusicBrainzMetadataDataSourceImpl: MetadataDataSource {
 
         for (title, artist) in [(normalized, normalizedArtist), (normalized, nil as String?)] {
             let query = MusicBrainzAPI.luceneQuery(title: title, artist: artist, duration: nil)
-            guard let response = try? await api.searchRecording(query: query, fmt: "json", limit: 5) else { continue }
-            let candidates = matchRecordings(from: response, regex: regex)
-            guard !candidates.isEmpty else { continue }
-            return candidates
+            do {
+                let response = try await apiSession.withAPI { try await $0.searchRecording(query: query, fmt: "json", limit: 5) }
+                let candidates = matchRecordings(from: response, regex: regex)
+                guard !candidates.isEmpty else { continue }
+                return candidates
+            } catch {
+                fputs("lyra: MusicBrainz search failed: \(error)\n", stderr)
+            }
         }
 
         return []
diff --git a/Sources/ScopedAPISession/ScopedAPISession.swift b/Sources/ScopedAPISession/ScopedAPISession.swift
@@ -0,0 +1,43 @@
+import Foundation
+
+/// Runs a single API call against a fresh, per-call ephemeral `URLSession` that is
+/// finished and invalidated when the body completes (#318).
+///
+/// A process-lifetime `URLSession` can silently go stale after sleep/wake or
+/// network changes, leaving requests failing until the daemon restarts. Building
+/// an ephemeral session per call sidesteps that, and invalidating it right after
+/// the call releases its resources so per-call sessions don't accumulate in the
+/// long-lived daemon.
+///
+/// The session is kept **function-local** inside ``withAPI(_:)`` — not stored
+/// behind a class that invalidates in `deinit`. A stored-session/`deinit` design
+/// is fragile: once the caller copies the wrapped client out, ARC may release the
+/// owner (and invalidate the session) before the request is even issued. Keeping
+/// the session local to the call, with a `defer`-based invalidation, makes the
+/// lifetime unambiguous and the invalidation point explicit.
+///
+/// `makeAPI` receives the scoped session and builds the (Papyrus) client bound to
+/// it; every per-API difference — base URL, auth headers, request shaping — lives
+/// in that closure, so this type stays API-agnostic. Only the request timeout,
+/// which legitimately varies per service, is a stored parameter.
+public struct ScopedAPISession<API> {
+    private let timeout: TimeInterval
+    private let makeAPI: (URLSession) -> API
+
+    public init(timeout: TimeInterval, makeAPI: @escaping (URLSession) -> API) {
+        self.timeout = timeout
+        self.makeAPI = makeAPI
+    }
+
+    public func withAPI<T>(_ body: (API) async throws -> T) async rethrows -> T {
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.timeoutIntervalForRequest = timeout
+        let session = URLSession(configuration: configuration)
+        defer { session.finishTasksAndInvalidate() }
+        return try await body(makeAPI(session))
+    }
+}
+
+// Safe: value type holding only an immutable timeout and an immutable factory
+// closure; `withAPI` creates and tears down its own session with no shared state.
+extension ScopedAPISession: @unchecked Sendable {}
diff --git a/Sources/VersionHandler/Resources/version.txt b/Sources/VersionHandler/Resources/version.txt
@@ -1 +1 @@
-2.21.0
+2.21.1
diff --git a/Tests/LyricsDataSourceTests/LyricsDataSourceImplTests.swift b/Tests/LyricsDataSourceTests/LyricsDataSourceImplTests.swift
@@ -1,5 +1,6 @@
 import Domain
 import Foundation
+@preconcurrency import Papyrus
 import Testing
 
 @testable import LyricsDataSource
@@ -68,6 +69,27 @@ struct LyricsDataSourceImplTests {
         #expect(result == nil)
     }
 
+    @Test("get returns nil on HTTP 404 — LRCLIB's regular no-lyrics answer")
+    func getReturnsNilOn404() async {
+        let dataSource = LyricsDataSourceImpl(
+            api: LRCLibStub(get: { _, _, _ in
+                throw PapyrusError(
+                    "Unsuccessful status code: 404.",
+                    nil,
+                    TestResponse(
+                        request: URLRequest(url: URL(string: "https://lrclib.net/api/get")!),
+                        statusCode: 404,
+                        body: Data()
+                    )
+                )
+            })
+        )
+
+        let result = await dataSource.get(title: "Song", artist: "Artist", duration: nil)
+
+        #expect(result == nil)
+    }
+
     @Test("get forwards arguments verbatim to the API")
     func getForwardsArguments() async {
         let captured = ArgumentRecorder<(String, String, Int?)>()
diff --git a/Tests/MetadataDataSourceTests/LLMMetadataDataSourceImplTests.swift b/Tests/MetadataDataSourceTests/LLMMetadataDataSourceImplTests.swift
@@ -19,30 +19,24 @@ struct LLMMetadataDataSourceImplTests {
         #expect(result.isEmpty)
     }
 
-    @Test("Default init() wires the production OpenAICompatibleAPI factory")
+    @Test("Default init() wires the production OpenAICompatibleAPI factory (degrades to empty on refused port)")
     func defaultFactoryWiresProductionAPI() async throws {
         // Cover the default `apiFactory` closure body which builds
         // `OpenAICompatibleAPI(provider: OpenAICompatibleAPI.provider(for:))`.
-        // We route URLSession.shared through URLProtocolMock so the production
-        // factory's resulting API hits a stubbed endpoint instead of the network.
-        URLProtocolMock.register(host: "llm.invalid") { _ in
-            let body = #"{"choices":[{"message":{"content":"{\"title\":\"Brave Shine\",\"artist\":\"Aimer\"}"}}]}"#
-            return (
-                HTTPURLResponse(url: URL(string: "http://llm.invalid/")!, statusCode: 200, httpVersion: nil, headerFields: nil)!,
-                Data(body.utf8)
-            )
-        }
-        URLProtocol.registerClass(URLProtocolMock.self)
-        defer { URLProtocolMock.unregister(host: "llm.invalid") }
-
-        let config = try makeLLMConfig(endpoint: "http://llm.invalid")
+        // The provider owns a private ephemeral URLSession (#318), so a globally
+        // registered URLProtocol mock cannot intercept it; point the endpoint at
+        // a refused local port instead — same pattern as
+        // OpenAICompatibleHealthCheckDefaultBackendTests — and assert the
+        // graceful empty fallback. The success path through the API is covered
+        // by the apiFactory-injected resolve tests.
+        let config = try makeLLMConfig(endpoint: "http://127.0.0.1:1")
         let result = await withDependencies {
             $0.configDataSource = StubConfigDataSource(loadResult: config)
         } operation: {
             await LLMMetadataDataSourceImpl().resolve(track: Track(title: "x", artist: "y"))
         }
 
-        #expect(result == [Track(title: "Brave Shine", artist: "Aimer")])
+        #expect(result.isEmpty)
     }
 }
 
diff --git a/Tests/ScopedAPISessionTests/ScopedAPISessionTests.swift b/Tests/ScopedAPISessionTests/ScopedAPISessionTests.swift

Original file line number	Diff line number	Diff line change
`@@ -10,12 +10,16 @@ public protocol OpenAICompatible {`
`10`	`10`	`}`
`11`	`11`
`12`	`12`	`extension OpenAICompatible {`
`13`		`- public static func provider(for config: AIEndpoint) -> Provider {`
	`13`	`+ /// Builds the auth-attaching Provider. The session comes from the caller's`
	`14`	+ /// `ScopedAPISession` in production (#318); the `nil` default gives a
	`15`	`+ /// throwaway ephemeral session for construction-only tests that never make a`
	`16`	`+ /// network call.`
	`17`	`+ public static func provider(for config: AIEndpoint, urlSession: URLSession? = nil) -> Provider {`
`14`	`18`	`let endpoint =`
`15`	`19`	`config.endpoint.hasSuffix("/")`
`16`	`20`	`? String(config.endpoint.dropLast())`
`17`	`21`	`: config.endpoint`
`18`		`- return Provider(baseURL: endpoint).modifyRequests { req in`
	`22`	`+ return Provider(baseURL: endpoint, urlSession: urlSession ?? URLSession(configuration: .ephemeral)).modifyRequests { req in`
`19`	`23`	`req.addHeader("Authorization", value: "Bearer \(config.apiKey)")`
`20`	`24`	`}`
`21`	`25`	`}`