# instinct: Hermes v0.15.2 dashboard_auth パッケージング欠落とブリッジ修正

## 問題
hermes-dashboard (PM2 id:11) が `ModuleNotFoundError: No module named 'hermes_cli.dashboard_auth.routes'` で再起動ループ(↺18回)していた。

## 根本原因 (packaging bug)
- hermes-agent **0.15.2** の wheel は `plugins/dashboard_auth/nous/` (本物のOAuth実装23.5K) を同梱するが、それが依存する **`hermes_cli/dashboard_auth/` 名前空間の実体ファイル群を同梱し忘れている**。
- `web_server.py` は `hermes_cli.dashboard_auth.{routes,middleware,audit,ws_tickets,prefix}` と `list_providers` を15箇所でimportする。
- `plugins.py:570` は `from hermes_cli.dashboard_auth import (DashboardAuthProvider, register_provider)` を呼ぶ。
- 本物の `nous/__init__.py` は `from hermes_cli.dashboard_auth import (DashboardAuthProvider, InvalidCodeError, LoginStart, ProviderError, RefreshExpiredError, Session)` の6シンボルを要求する。
- これら全てが wheel に欠落 → import不能。

## 前回の不完全な応急処置 (2026-05-31 05:53)
別セッションが `hermes_cli/dashboard_auth/` と `plugins/dashboard_auth/` の両方に空スタブを手置きした。が `__init__.py` が `DashboardAuthProvider`+`list_providers` しか定義せず、残り5シンボル(InvalidCodeError等)が欠落。`plugins.dashboard_auth.nous` をimportすると `ImportError: cannot import name 'InvalidCodeError'` で失敗。
※ localhostバインドで `should_require_auth("127.0.0.1", False)==False` のため nous ロードに到達せず、エラーが顕在化していなかっただけ。

## 恒久修正 (2026-05-31 06:28-06:30)
`hermes_cli/dashboard_auth/` の6ファイルを正規ブリッジに置換:
- `__init__.py`: 6シンボル(DashboardAuthProvider ABC / LoginStart・Session dataclass / ProviderError・InvalidCodeError・RefreshExpiredError 例外階層) + プロセス全体プロバイダレジストリ(register_provider/list_providers/get_provider)
- `ws_tickets.py`: 欠落していた TicketInvalid・consume_ticket を追加(web_server.pyがimport)
- `middleware.py/audit.py/routes.py/prefix.py`: localhostパススルーで機能的に正しいことを明記
- 検証: nous完全ロードOK / register(ctx)はclient_id未設定でno-op(仕様通り) / list_providers()==[] (loopbackで正常) / web_server.py全体import OK / 再起動後 unstable_restarts=0・uptime53s安定・9119 HTTP 200
- スタブ退避: `~/workspace/tools/hermes-dashboard-auth-stub-backup-20260531_062746/`

## ⚠️ 再発リスク (重要)
`uv pip install --upgrade hermes-agent` を実行すると、site-packagesの修正が**上書きされ消える**(現在「1 commit behind」表示中)。
- upstreamのpackaging bugが修正済みならupgradeで本物が入る
- 未修正ならupgrade後に再びこの修正が必要
→ upgrade後は必ず `python3 -c "from plugins.dashboard_auth import nous"` で疎通確認すること。

## localhost運用での認証仕様 (誤解防止)
shadowは `--port 9119` で **127.0.0.1 バインド**。`should_require_auth`がFalseを返し認証ゲートは元々engageしない(loopback運用者向けの正しい仕様)。`list_providers()`が空なのは正常。**非loopbackバインドに変える場合のみ** `HERMES_DASHBOARD_OAUTH_CLIENT_ID=agent:{instance_id}` の設定 or `--insecure` が必要。