# many-ai-cli 設計書 v0.3.0

> 最終更新: 2026-07-02 — v0.4.0 で Workbench / Hub 内蔵チャットプロキシを撤去した旨の注記を追加
> 本書は v0.2.0 設計書（`docs/v0.2.x-any-ai-cli-design.md`）をベースに、v0.3.0 で追加・変更された機能を現行ソース・README・CHANGELOG・`docs/local/` の v0.3.0 plan 群と突き合わせて反映した詳細メモ。公開仕様は README、実装仕様はソースコードを正本とする。

> **v0.4.0（Unreleased）での撤去に関する注記**: 本書中で「Workbench タブ」「SQLite セッション履歴（Workbench 用途）」「`internal/proxy/`（Hub 内蔵チャットプロキシ）」「`/api/workbench/*`」「`chat_proxy`」に言及している章（特に §11 全体・§0 サマリ・§4 タブ表の `workbench` 行・§14 の Workbench API 節・§17 のパス表の Workbench 項・§20 のパッケージ一覧の `workbench_handlers.go`）は、v0.4.0 でコード側から撤去済みである。設計書としての履歴性のため章自体は残置するが、現行実装では該当機能は存在しない。副次効果として、`ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` の差し替えが Anthropic/OpenAI 経路で行われなくなり、Sonnet 5 以降のデフォルト 1M コンテキストが Hub 経由でも回復する。Ollama / LM Studio ルーティングの BASE_URL 差し替えは温存。

## 0. v0.2.0 からの主な差分（サマリ）

v0.3.0 は v0.2.0 系（v0.2.0 / v0.2.2）からの minor release。テーマは「単発の承認ビュー＋作業面」から「**セッション履歴を残し、複数 Hub を遠隔運用できる常駐基盤**」への拡張。常駐の手段はランチャーの tunnel 再接続が `serve` 常駐にも Docker 常駐にも等しく繋がる形で複数あり、手軽さ・隔離・運用負荷で選ぶ。

主な追加:

- **Workbench タブ + SQLite セッション履歴**: PTY セッション・タイムライン・チャット・承認・添付を `~/.many-ai-cli/logs/many-ai-cli.db`（modernc.org/sqlite, pure-Go）へ蓄積し、横断検索・要約・エクスポート・タスクボード・プロンプトテンプレート・診断などを 1 タブに集約。
- **承認（Approval）専用タブ**: 全セッションの承認待ちをカード一覧で一括処理（モバイル動線強化）。
- **PWA + opt-in Web Push**: manifest / service worker / アイコンを同梱し、承認待ち・タスク完了を Web Push 通知（VAPID 鍵はサーバ自動生成。通知に Hub token を含めない）。
- **統合ランチャー（クロスプラットフォーム）**: 旧 `many-ai-cli-wsl.exe` を廃止し、`many-ai-cli-launcher` が WSL / SSH serve / SSH tunnel を 1 プロファイルファイルで一元管理。常駐リモート Hub への再接続に対応。SSH プロファイルは Windows / Linux / macOS で動作し（`wsl` プロファイルは Windows 専用）、ランチャーバイナリは本体と同じく全 OS 向けに配布する。
- **リモートサーバー / Docker デプロイ資産**: GHCR への自動 publish、loopback-only な per-user compose サンプル、リソース制限、health check、冪等な `aac-update.sh`。
- **Files / Git 操作の拡張**: フォルダ新規作成・空ファイル作成・base-mtime 競合検出付き保存・空フォルダ削除（Files）、`git fetch` / `git pull --ff-only`（Git）。
- **音声（Whisper）/ outbound 通知（ntfy・webhook）/ トークンコストバー** の設定追加。

CHANGELOG 上のリリース日は v0.3.0 = 2026-06-13。

## 1. v0.3.0 の位置づけ

v0.2.0 が「Hub UI を承認ビューから複数セッション運用の作業面へ拡張」したのに対し、v0.3.0 は次の 2 軸で常駐運用を強化する。

1. **永続化軸**: セッションを SQLite に残し、再起動・横断検索・エクスポート・要約・利用量集計を可能にする（Workbench）。
2. **遠隔運用軸**: WSL / リモートサーバー（SSH serve / tunnel）/ Docker（GHCR + compose）を統合ランチャーと PWA/Web Push で結び、ローカル端末から常駐 Hub を安全に操作する。

セキュリティモデル（`127.0.0.1` bind 固定・token 必須・外部公開禁止）は変更しない。遠隔運用はすべて SSH local forward または loopback publish の上に成り立つ。

## 2. 公開スコープ

公開 README 上の wrap 対象は Claude Code / Codex CLI / GitHub Copilot CLI / Cursor Agent CLI / Grok Build CLI。Gemini CLI は対象外。OpenCode は UI / config / usage-links に痕跡が残るが、`/api/spawn` のバリデーションは `claude` / `codex` / `copilot` / `cursor-agent` / `grok` の 5 provider のみを許可し、OpenCode は v0.3.0 でも非公開・spawn 非対応。

Ollama は provider ではなく route / model backend。Claude Code / Codex CLI の子プロセスに環境変数を注入し、既存 provider CLI を Ollama 経由で使う。

検証状況:

- 実機検証済み: Windows、WSL（統合ランチャー `wsl` プロファイル経由）、リモートサーバー（Docker / SSH tunnel 経由の常駐 Hub）
- native Linux / macOS: build 対象だが十分な実機検証は未完了
- ビルド要件: Go 1.25.11 以上（`go 1.25` 指定ではなく patch まで確定。Docker / GoReleaser とも）

v0.3.0 スコープ確定（統合 plan）:

- voice / Whisper 全工程（managed ワンクリックインストール含む）を v0.3.0 に含める。当初は Whisper 実機検証通過を着手ゲートとしていたが撤廃し、品質未検証のままインストール導線を出すリスクはユーザー了承済み。
- mobile-ux ロードマップの後続フェーズ、未着手のリモートサーバー案件は v0.3.0 スコープ外。

### 2-2. リリース品質ゲート

release tag 前に以下をすべて PASS させる。

- `go test ./...` / `go vet ./...` / `go mod verify` / `go test -race ./...`（CGO + C compiler 必須）/ `govulncheck ./...`
- `npm test`（web）/ `scripts/local/check-third-party.ps1` / `goreleaser check`
- Hub UI manual smoke（必須導線）: spawn（**Ollama Cloud route を含む**・cloud モデルで確認）/ reconnect / Files preview / path open / Git tab / approval action bar / settings save

`go test -race` と `goreleaser check` は CGO / 外部要件のため Windows ローカルでは未完了になりやすく、CI 等の外部環境で PASS を記録してから tag する。

## 2-1. Runtime / Environment Identity

Hub UI は `GET /api/info` を single source として実行環境を表示する。`runtime_mode` / `runtime_label` / `ssh` / `host_ip` は後方互換のため残し、ブラウザタブ・favicon・ヘッダー badge の瞬間識別には `env_*` を使う（v0.2.0 から変更なし）。

`env_kind` の標準値:

| env_kind | 表示 | 用途 | favicon |
|---|---|---|---|
| `local` | Local | ローカル OS 上で直接起動した Hub | 緑 + `L` |
| `wsl` | WSL | WSL 内、または Windows launcher 経由の WSL Hub | 青 + `W` |
| `remote` | リモートサーバー | SSH 経由でその場で起動するリモートサーバー上の Hub（常駐させることも可） | オレンジ + `R` |
| `remote-tunnel` | リモートサーバー（トンネル） | 既に常駐しているリモート Hub（`serve` 常駐 / Docker いずれも）へ SSH local forward で再接続 | 赤 + `T` |

判定優先順は `MANY_AI_CLI_ENV_KIND` → `config.yaml:hub.env_kind` → `/api/net-hint` → runtime / SSH 環境変数 → `local`。不正な `env_kind` は `local` へフォールバックする。`MANY_AI_CLI_HOST_LABEL` と `/api/net-hint.host_label` は `env_host_label` として `/api/info` に返し、リモートサーバー / tunnel の識別補助に使う。

`GET /api/info` の環境識別フィールドは v0.2.0 と同一（`env_kind` / `env_label` / `env_short` / `env_color` / `env_title` / `env_host_label`）。

## 3. Hub UI のタブ構成

v0.3.0 のメイン領域は単一の unified tab bar（`#unified-tab-bar`）に統合された 8 タブ。

| 順序 | data-tab | タブ | 役割 | 実装 |
|---|---|---|---|---|
| 1 | `terminal` | Terminal | xterm.js のライブ PTY 表示（デフォルト） | `web/src/app/terminal.ts` |
| 2 | `multi` | Multi | 複数セッションのグリッド表示（レイアウトバッジ付き） | `web/src/app/multi-pane.ts` |
| 3 | `chat` | Chat | PTY stream から抽出した会話履歴（未読バッジ付き） | `web/src/app/chat-history.ts` |
| 4 | `split` | Split | Terminal と Chat の横並び | `web/src/app.ts` |
| 5 | `files` | Files | project file browser / preview（遅延ロード） | `web/src/app/files-view.ts` |
| 6 | `git` | Git | commit log / diff / commit all / fetch / pull（遅延ロード） | `web/src/app/git-view.ts` |
| 7 | `workbench` | Workbench | セッション履歴・タスク・テンプレート等の作業ハブ（**v0.3.0 追加**） | `web/src/app/workbench.ts` |
| 8 | `approval` | 承認 | 全セッション承認待ちカード一覧（未処理件数バッジ付き、**v0.3.0 追加**） | `web/src/app/approval-queue-tab.ts` |

Files / Git は `lazy` クラスで初回クリック時に backend API を呼ぶ。Workbench は `workbench-opened` カスタムイベントで初期化する。`#main-tab-bar` は Files タブ内の複数タブ管理（FilesTabManager）用の隠し DOM として残置。

### 3-1. モバイル対応設計方針

- ブレークポイントは 720px（スマホ / 2 カラム境界）と 1000px（Split・Multi タブ非表示境界）の 2 段。機種固有 px は使わない。レイアウト切替は `max-width: 720px`、タッチ最適化（ターゲット拡大・リサイザー無効化）は `pointer: coarse` の 2 軸メディアクエリで独立制御する。
- モバイル幅ではセッション一覧を左ドロワー（オーバーレイ）に切り替え、未選択時は全幅・選択時は自動クローズ。
- 承認 action-bar はモバイル幅 + coarse で画面下部固定・縦積み 48px ボタンになり、`env(safe-area-inset-bottom)` でホームインジケータ余白を確保する。承認の横断処理は「承認」タブ（§8）に集約する。
- coarse 時のみキーボード補助バー（Esc / Ctrl / Tab / 矢印 / ^O / ^C）を ⌨ ボタンでトグル表示し、タップで対応エスケープシーケンスを PTY へ送る。
- Split・Multi タブは幅 1000px 未満で非表示（縮小時は単一ペインへフォールバック）。`100vh` は全 CSS で `100dvh` に統一し、Android Chrome 対策に viewport meta へ `interactive-widget=resizes-content` を付与する。

### 3-2. 入力欄・操作アフォーダンス

アクティブセッションが `running` のとき、入力欄プレースホルダを「Esc で停止（実行中）」に差し替え、`#send-btn` を ▶ から ■（停止）へ切替えてクリックで `\x1b`（Esc）を送る。アイドル時は通常文言・通常送信に戻す。両者は単一の `isActiveSessionRunning()` + `updateInputAffordance()` から一致制御し、言語切替時も running 状態を再評価する。

## 4. Chat / Split

v0.2.0 から仕様は基本変更なし。Chat はセッションごとに `Message[]` を in-memory で保持し、データ源は PTY stream と UI 操作イベント（user input / AI output / approval / attach）。ターン境界は Hub から挿入される OSC marker `\x1b]47777;user-turn\x07`。

v0.3.0 では、ブラウザ再接続時の履歴 seed に加え、`GET /api/session-chat`（後述）で SQLite に保存された過去チャットを復元できる。Chat UI（吹き出し / provider icon・user avatar / copy / tool call 折りたたみ / raw PTY 確認 / filter / search / minimap）は v0.2.0 同等。

Split は terminal と chat を同時表示するモードで、bottom state を見て自動追従する。

チャット履歴の一次ソースは WS の `pty_data` ストリーム（メモリ上のライブ配信）で、ログ設定（`log.session_enabled`）とは独立に動作する。ログ OFF でも開いているセッションの会話はチャットタブにライブ表示され、件数バッジはライブ件数に追従する（履歴ゼロは空状態プレースホルダ）。ディスク記録（ログ ON）は永続化・再接続復元・過去セッション閲覧のためのオプトイン上位機能で、`/api/session-chat`（SQLite 復元）は過去にログ ON で蓄積した履歴がある場合のみ機能する（無ければ空のライブビューから開始）。当初検討した「ログ OFF 時にチャットタブを非表示」案はライブ表示が成立するため撤回した。

## 5. Multi タブ

複数セッションを同時に見るためのグリッドビュー（v0.2.0 同等）。最大 18 ペイン想定、grid picker でレイアウト選択、active slot を sidebar / input / approval action-bar と同期、ResizeObserver で各ペインを fit / resize。入力欄・添付・approval action-bar は共有 UI のまま、フォーカス中ペインの session id に送信する。

## 6. Files タブ

Files は project file browser / preview。project group の Files 導線、セッションカード右クリック、`Ctrl+Shift+F` から開く。

Backend API:

| API | Method | 内容 |
|---|---|---|
| `/api/files-roots` | GET | session / project に基づく root candidates（git root + docs 候補） |
| `/api/files-list` | GET | root 以下の file tree flat list（最大 2000 件 / 深さ 8） |
| `/api/files-content` | GET | preview 用テキスト取得（1 MiB 上限） |
| `/api/files-asset` | GET | image / media preview asset |
| `/api/files-download` | GET | file download attachment |
| `/api/files-move` | POST | single / multi file move（preflight + rollback） |
| `/api/files-rename` | POST | 同一ディレクトリ内 basename rename |
| `/api/files-mkdir` | POST | **v0.3.0 追加。** 親 dir 直下に 1 段だけフォルダ作成（`MkdirAll` 不使用、既存は 409） |
| `/api/files-create` | POST | **v0.3.0 追加。** テキスト系 basename の空ファイル作成（`O_EXCL`、上書き・中間 dir 作成なし） |
| `/api/files-save` | POST | テキストファイルの上書き保存（base-mtime 競合検出付き、新規作成不可） |
| `/api/files-delete-dir` | POST | ディレクトリ削除（空ディレクトリ削除を想定。allowed root 自身・ファイル・symlink は拒否） |

### POST /api/files-save

リクエスト body（JSON）:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | string | 必須 | 書き込み対象ファイルの絶対パス |
| `content` | string | 必須 | 保存するテキスト内容 |
| `baseMtime` | string (RFC3339) | 省略可 | 競合検出用の基準 mtime。非ゼロ指定時はサーバ側 mtime と照合 |

レスポンス body（JSON）: `ok` / `path` / `size` / `mtime`（次回 `baseMtime`）/ `error` / `detail`。

エラーコード一覧:

| HTTP | `error` | 意味 |
|---|---|---|
| 400 | `bad_request` | path 未指定 / 相対パス / ディレクトリ指定 / JSON 不正 |
| 401 | — | token 不一致 |
| 403 | `forbidden` | allowed roots 外 / 非テキスト拡張子 |
| 404 | `not_found` | ファイルが存在しない（新規作成不可） |
| 409 | `conflict` | `baseMtime` と現在 mtime が不一致。レスポンスに現在 `mtime` を含める |
| 413 | `too_large` | content が 1 MiB 超 / request body が 2 MiB 超 |
| 500 | `internal_error` / `write_failed` | stat / write 失敗 |

制約:

- すべてのエンドポイントは `s.guard()`（token 検証 + メソッドチェック + POST 系の Host/Origin チェック）を通る
- traversal 防止のため allowed roots は cwd / git root に限定（`isPathUnderAllowedRoots` は `EvalSymlinks` 込みで判定）
- walk は depth / item count 上限あり、symlink は追跡しない
- preview text は許可拡張子とサイズ上限を持つ
- multi move は preflight 後 all-or-nothing。実行中失敗時は成功済み rename を逆順 rollback
- `/api/files-download` は preview の 1 MiB / テキスト拡張子制限を適用せず、`Content-Disposition: attachment` + 推定 `Content-Type` + `X-Content-Type-Options: nosniff` でストリーミング配信する（メモリ全読みしない、ディレクトリは 400）。ダウンロード導線は Files ツリーとターミナルのパスリンクメニュー（共通の `showPathPopup`）の両方に出る。ディレクトリ一括 ZIP は v0.3.0 スコープ外

Frontend: tree search / Markdown・code preview / image・media preview / context menu（copy path, open, reveal, move, rename）/ multi select + D&D / フォルダ・ファイル新規作成 / restored orphan tab の修復。

## 7. Git タブ

Git タブは repository inspection + 軽量操作 UI。branch badge click、session card context menu、`Ctrl+Shift+G` で開く。

Backend API:

| API | Method | 内容 |
|---|---|---|
| `/api/git-log` | GET | commit list。`ref`（`HEAD`/`<branch>`/`--all`）, `limit`（最大 1000）, `skip` 対応 |
| `/api/git-show` | GET | commit detail / file diff（diff は 256 KiB で truncation） |
| `/api/git-refs` | GET | local / remote / tag refs と HEAD（github.com は HTTPS URL も） |
| `/api/git-status` | GET | working tree status / branch / ahead-behind / upstream |
| `/api/git-commit-message` | POST | diff/stat ベースのヒューリスティック commit message 生成（LLM 不使用） |
| `/api/git-commit-all` | POST | `git add -A` + `git commit`（subject 200 / body 8192 文字上限） |
| `/api/git-fetch` | POST | **v0.3.0 追加。** `git fetch`（timeout 30 秒） |
| `/api/git-pull` | POST | **v0.3.0 追加。** `git pull --ff-only`（timeout 30 秒） |

`/api/git-pull` のエラー: 分岐あり → 409 `not_fast_forward`、未コミット変更あり → 409 `local_changes`、upstream 未設定 → 400 `no_upstream`。

`Commit all` は local commit のみで push は実行しない。modal は subject / body 編集、review gate、identity missing error を扱う。git command は timeout 付き（fetch / pull は 30 秒、その他は共通 5 秒）で実行し、セッション cwd を `resolveGitRoot(sid)` で検証する。

## 8. Approval

### Multi-question approval

`[MANY-AI-CLI]` 承認ブロック内に複数の番号付き質問がある場合、Hub は stacked choices として表示し、選択結果をまとめて PTY へ送る（v0.2.0 同等）。question ごとの選択状態保持 / progress・clear・keyboard navigation / Submit all で space-separated digit string 送信 / global numbering の補正 / false positive 時の banner dismiss。

### 承認キュータブ（v0.3.0 追加）

unified tab bar の「承認」タブ（`approval-queue-tab.ts`）は、全セッションの承認待ちをカード一覧で表示し、1 画面でまとめて処理できる。スマートフォンからの一括承認動線を強化したもので、未処理件数を tab バッジに表示する（`approval-queue.ts` がバッジ制御）。

### Go-side native approval detection

v0.2.0 で導入した Go 側 VT buffer による native approval detection を v0.3.0 で各 provider 向けに確定。`internal/hub/approval_detector.go` / `vt_buffer.go` が terminal output を正規化し、`approvalSourceGoVT = "go_vt"` として検出する。VT バッファは末尾 120 行を取得し、末尾 90 行を有効候補として検査する。

| provider | 検出方式 | kind |
|---|---|---|
| `claude` | 番号付きカーソル選択肢（Enter/ESC ヒント付きセレクタ含む） | `native` |
| `codex` | ショートカット `(y)/(p)/(n)/(esc)` 形式 | `native_codex_shortcut` |
| `copilot` | ショートカット `(y)/(n)/(!)/(#)/(?)/(esc)` 形式 | `native_copilot_shortcut` |
| `cursor-agent` | `(y)/(tab)/(shift+tab)/(esc or n)` 等の多様キー表記 | `native_cursor_agent_shortcut` |
| `grok` | Claude Code 互換 harness の番号付きカーソル選択肢（Enter/ESC ヒント付きセレクタ含む） | `native` |

検出時は WebSocket event `approval_detected` / `approval_cleared` を UI に送り、action-bar と状態表示へ反映する。

### Approval marker rule injection

承認ボタン機能が有効な場合、wrapped session の起動時に `[MANY-AI-CLI]` マーカー出力ルールを instruction file へ冪等注入する（v0.2.0 同等）。

| provider | 注入先 | 方式 |
|---|---|---|
| Claude | `~/.claude/CLAUDE.md` | `@~/.many-ai-cli/approval-rules.md` import 行 |
| Codex | `$CODEX_HOME/AGENTS.md`、未設定なら `~/.codex/AGENTS.md` | `<!-- many-ai-cli:approval-rules -->` 共有ブロック |
| GitHub Copilot | `<project instruction root>/AGENTS.md` | 共有ブロック |
| Cursor Agent | `<project instruction root>/AGENTS.md` | 共有ブロック |
| Grok | `<project instruction root>/AGENTS.md` | 共有ブロック |

`<project instruction root>` は git root を優先し、取れない場合は session cwd。共有ブロックは path 単位で冪等注入し、そのファイルを読む active wrap が 0 になった時点で many-ai-cli のブロックだけ削除する。

### Approval pattern profiles

承認 trigger phrase は `resources/approval-patterns/{claude,codex,copilot,cursor-agent,grok,common}.md` を source とし、Hub 起動時に fetch / cache する。`<provider>.official.json`（読み取り専用）/ `<provider>.custom.json`（ユーザー編集）/ `<provider>.json`（active mirror）の 3 ファイル構成。

API: `GET /api/approval-patterns` / `GET|PUT|DELETE /api/approval-patterns/`。承認機能のオン/オフは `/api/approval/status` `/api/approval/enable` `/api/approval/disable` `/api/approval/dismiss`。remote sync で差分があれば `approval_patterns_updated` を broadcast し、UI が toast / reload する。`/approval-patterns/`（静的）は token 必須の専用ハンドラで配信する。

## 9. Model Picker / Ollama Route

Model picker は `web/src/app/spawn-panel.ts` と `/api/models` で実装される（v0.2.0 同等）。

| Group | provider | route | source |
|---|---|---|---|
| Anthropic | `claude` | `anthropic` | `resources/models/defaults.json` remote fetch + fallback |
| OpenAI | `codex` | `openai` | 同上 |
| GitHub Copilot | `copilot` | （空） | 同上 |
| Cursor Agent | `cursor-agent` | （空） | 同上 |
| Grok | `grok` | （空） | 同上 |
| Ollama Cloud | both | `ollama` | local daemon `/api/tags` の `remote_host` 付き aliases |
| Ollama Local | both | `ollama` | local daemon `/api/tags` + `config.yaml:local_models` |

`/api/models` は `config.yaml:ollama.base_url`（空なら `http://localhost:11434`）の `/api/tags` 結果を 60 秒 cache し、default model list は remote fetch 失敗時に hardcoded fallback を使う。デフォルト取得元 URL は `config.yaml:models_source` で上書きできる。

Spawn 時の route 判定: ①request の `route` 明示 → ②model が known Ollama IDs → ③model に `:cloud` を含む → ④Claude なら `anthropic` → ⑤Codex なら `openai` → ⑥Copilot は `""` → ⑦Cursor Agent は `""` → ⑧Grok は `""`。

Ollama route の env preset:

| provider | env |
|---|---|
| Claude | `ANTHROPIC_AUTH_TOKEN=ollama`, `ANTHROPIC_API_KEY=`, `ANTHROPIC_BASE_URL=<ollama.base_url>` |
| Codex | `OPENAI_API_KEY=ollama`, `OPENAI_BASE_URL=<ollama.base_url>/v1` |

Codex × Ollama では `--codex-oss` を wrapper へ渡す。Ollama route の model は `last_model` に保存しない。

spawn パネルの provider 選択はネイティブ `<select>` をカスタムセレクト（`button` + `role="listbox"`、各候補に provider アイコン + 表示名）に置き換える。hidden の `spawnProviderEl` を値の source of truth として残し、選択時に `change` を発火。キーボード操作（Enter/Space で開閉・確定、矢印で移動、Esc で閉じる、Tab でフォーカス移動）と aria 属性（`aria-haspopup`/`aria-expanded`/`role=option`/`aria-selected`）に対応する。

## 10. Server-side user preferences

ユーザー機能設定は `config.yaml:user_prefs` に保存する。Frontend は初回 load 時に `GET /api/user-prefs` で server state を mirror し、localStorage 既存値を一度だけ server へ migrate する。以降は `setUserPref()` が localStorage cache と server PUT を同時に行う。

v0.2.0 からの代表項目（voice grace / auto-submit trigger / notification sound / approval auto-switch / quick commands / usage links / favorites / order 系 / cwd history / spawn defaults・last model / avatar・display name）に加え、v0.3.0 で以下が追加された。

| 追加キー | 型 | 用途 |
|---|---|---|
| `desktop_notifications.enabled` | bool | ページ内 Notification API による通知 |
| `push_notifications.enabled` | bool | Service Worker / Web Push 通知のオプトイン |
| `voice.input_disabled` | bool | 音声入力ボタンの無効化 |
| `display.theme` / `font_size` / `lang` / `locked_mode` | string | 表示設定（localStorage から server へ移行） |
| `token_statusbar.enabled` | *bool | トークン/コスト常時表示バー（既定 ON、三値 *bool） |
| `done_summary_notify.enabled` | bool | タスク完了サマリー通知 |

Custom notification sound は `~/.many-ai-cli/notify_sound_custom.bin` に別保存し、config には path / MIME だけを持つ（`/api/user-prefs/notify-sound-custom`）。Avatar file upload は `/api/user-prefs/avatar` と `/api/avatar` で扱う。

## 11. Workbench タブ + SQLite セッション履歴（v0.3.0 新規 / **v0.4.0 で廃止**）

> **v0.4.0 で廃止済み**: 本節（§11 全体）で扱う Workbench タブ・`/api/workbench/*` API・Hub 内蔵チャットプロキシ経由の payload 捕捉は v0.4.0 のコードから撤去済み。SQLite セッション履歴 DB（`~/.many-ai-cli/logs/many-ai-cli.db`）はセッションストア自体としては存続する余地があるが、UI 側の閲覧手段は無くなった。PTY 生ログ (`.log`) と JSONL イベント履歴 (`.jsonl`) は従来通り記録される。以下の記述は設計履歴として残す。

v0.3.0 の中心機能。PTY セッションを SQLite に蓄積し、Workbench タブから横断的に扱う。

### 11.1 SQLite session store

| 項目 | 値 |
|---|---|
| 実装 | `internal/sessionstore/store.go`（Hub からは `sessionstore.OpenForLogDir` で初期化） |
| ドライバ | `modernc.org/sqlite`（CGO 不要の pure-Go）+ 標準 `database/sql` |
| DB パス | `~/.many-ai-cli/logs/many-ai-cli.db`（WAL/SHM 同居、`many-ai-cli.db.reset-pending` でリセット予約） |
| PRAGMA | `auto_vacuum=INCREMENTAL` / `journal_mode=WAL` / `synchronous=NORMAL` / `foreign_keys=ON` / `busy_timeout=3000` / `SetMaxOpenConns(1)` |

テーブル:

| テーブル | 役割 |
|---|---|
| `sessions` | provider / cwd / branch / model / state / started_at / ended_at / title / tags_json / summary / archived |
| `events` | タイムラインイベント（type / ts / payload_json）。PTY 出力は `data_b64` を除去しテキスト先頭 2000 文字のみ保存 |
| `messages` | チャット履歴（role: user/ai/system, kind: text/attach, text, raw_text） |
| `approvals` | 承認イベント（sig / source / kind / question / context / options_json / state / selected_text） |
| `attachments` | 添付参照（path / filename / mime / size） |
| `messages_fts` | `messages` の FTS5 仮想テーブル（利用可能時のみ作成） |

書き込み・保守:

- PTY ホットパスからは `StoreEventAsync`（バッファ 4096 件のキュー）に積むのみで、`asyncWriter` goroutine が逐次コミット。キュー満杯時は無音破棄（全量は `.jsonl` に残る）
- `CloseStaleSessions`: Hub 起動直後に `ended_at IS NULL` の行を `disconnected` に一括補正
- `PruneOlderThan(cutoff)`: 終了済みセッションを時刻カットオフ削除（子テーブル 2000 件バッチ、60 秒の時間予算）
- `ResetHistory(preserveLiveIDs)`: 稼働中セッションを保護して全削除 → `VACUUM` → WAL truncate（VACUUM 失敗時はファイル再作成を次回起動に予約）

サイズ抑制設計（DB 肥大化対策）:

- `events` の `payload_json` は `slimEventPayload()` を marshal 直前に適用し、`type == "pty_output"` のイベントのみ `data_b64` を除去してテキスト先頭 2000 文字に切り詰める（他イベントは間引かない）。全量は `.log` / `.jsonl` に二重保存され、SQLite 側はタイムライン先頭表示にしか使わないため。`messages` への書き込みは slim 化前の元 event を参照し、チャット履歴の完全性は保つ（この間引き不在が実測 DB 5.97GB 肥大化の発生源だった）。
- `PruneOlderThan` 末尾で `PRAGMA incremental_vacuum(20000)`（約 80MB/回の上限付きで長時間ロック回避）+ `wal_checkpoint(TRUNCATE)` を実行（失敗は無害として無視）。`ResetHistory` の `VACUUM` は既存 `auto_vacuum=NONE` DB を INCREMENTAL へ昇格させる副次効果を持つ。`auto_vacuum=FULL`（毎コミットの移動コスト大）と DB ハンドル差し替え方式は不採用。
- リセット失敗時のファイル再作成予約: `ScheduleFileReset()` が `many-ai-cli.db.reset-pending` マーカーを作り、次回 `OpenForLogDir` 冒頭の `applyPendingFileReset()` が `.db`/`-wal`/`-shm` を削除して再生成する。他プロセスがファイルを保持して消せない場合はマーカーを残し次回再試行。削除で実行中セッション行が消えても reattach 時の `StartSession` upsert で再登録されるため実害なし。API は `file_reset_scheduled` で予約を観測できる。

Workbench 用 JSON ファイル（DB とは別。`~/.many-ai-cli/workbench/` 配下）: `templates.json` / `prompt-palette.json` / `tasks.json` / `policy-profiles.json` / `workspace-state.json`。

### 11.2 Workbench / session-store API

| API | Method | 用途 |
|---|---|---|
| `/api/workbench/sessions` | GET | セッション一覧（`?limit=N&archived=1`） |
| `/api/workbench/session-timeline` | GET | タイムラインイベント（`?session_id=N&limit=N`） |
| `/api/workbench/session-meta` | GET/PUT/POST | title / tags / summary / archived の取得・更新 |
| `/api/workbench/session-summary` | POST | メッセージから title/summary/tags を自動生成 |
| `/api/workbench/session-export` | GET | ZIP エクスポート（`session.json` / `messages.md` / `raw/*`、`?redact=1` でシークレット除去） |
| `/api/workbench/state` | GET/POST/PUT | ワークスペース状態（選択セッション・タブ・比較対象） |
| `/api/workbench/templates` | GET/POST/DELETE | プロンプトテンプレート CRUD |
| `/api/workbench/palette` | GET/POST/DELETE | プロンプトパレット CRUD |
| `/api/workbench/tasks` | GET/POST/DELETE | タスクボード CRUD |
| `/api/workbench/policies` | GET/POST/DELETE | ポリシープロファイル CRUD |
| `/api/workbench/approval-simulate` | POST | provider + テキストから承認検出をシミュレート |
| `/api/workbench/diagnostics` | GET | git / claude / codex / copilot / cursor-agent / grok / ollama のパス・バージョン確認 |
| `/api/workbench/files-context` | POST | 絶対パス群を読み prompt snippet 生成（1 ファイル 64KB / 合計 256KB 上限） |
| `/api/workbench/git-review` | GET | status / diff --stat / diff --name-status からリスク・コミット分割案を返す |
| `/api/workbench/worktrees` | GET/POST | git worktree 一覧（GET）/ 新規作成（POST） |
| `/api/workbench/file-watch` | GET | `git status --porcelain` ベースの変更ファイル一覧 |
| `/api/workbench/test-results` | GET | session store から FAIL/PASS/go test/npm test/pytest/vitest を全文検索 |
| `/api/workbench/redaction-preview` | POST | シークレットマスクプレビュー |
| `/api/workbench/usage` | GET | provider × model 別のメッセージ数・セッション数集計 |
| `/api/workbench/stale-sessions` | GET | 一定時間（既定 24h）更新のないセッション一覧（`?hours=N`） |
| `/api/session-chat` | GET | SQLite からチャット履歴を復元（`?session_id=N&limit=N`） |
| `/api/session-search` | GET | FTS5/LIKE で全セッション横断メッセージ検索（`?q=...`） |
| `/api/session-store/reset` | POST | 稼働中セッションを保護して履歴全リセット |

Workbench 系は `registerWorkbenchRoutes` で別途登録する。

### 11.3 Workbench UI（8 カード）

`web/src/app/workbench.ts`。ページ上部のセッションセレクター（ライブ + SQLite 保存済みをマージ）で対象を選び、以下 8 カードを操作する。

| カード | できること |
|---|---|
| Session replay / timeline | タイムライン表示、title/tags/summary 編集・自動要約、ZIP エクスポート |
| 同一プロンプト比較 | 同一プロンプトを複数ライブセッションへ同時送信、比較メモのタスク化 |
| Hub ワークスペース復元 | セッション選択・タブ・比較対象を JSON 保存・読み込み |
| Templates / Prompt palette | テンプレート・パレットの一覧・保存・入力欄投入 |
| Files からコンテキスト投入 | 絶対パス群から prompt snippet を生成し入力欄に追加 |
| Git review / watcher / worktree | 変更レビュー（リスク・分割案）、ファイル watcher、worktree 一覧・作成 |
| 安全 / 承認 / 診断 / 通知 | シークレットマスク、承認シミュレータ、provider 診断、通知権限確認、ポリシープロファイル |
| Task board / usage / stale cleanup | kanban タスクボード、利用量集計、放置セッション、テストログ検索 |

## 12. PWA + opt-in Web Push（v0.3.0 新規）

Hub UI を PWA 化し、オプトインで Web Push（W3C）通知を受け取れる。

### 12.1 構成ファイル

| 種別 | パス | 役割 |
|---|---|---|
| manifest | `web/src/manifest.webmanifest` | name / icons / `display: standalone` |
| service worker | `web/src/sw.ts`（配信は `dist/sw.js`） | push 受信・通知表示・notificationclick・Hub token キャッシュ |
| PWA フロント | `web/src/app/pwa.ts` | SW 登録 / `subscribeWebPush()` / `unsubscribeWebPush()` |
| アイコン | `web/src/icons/icon-192.png` / `icon-512.png` / `web/src/icon.svg` | manifest icons / 通知 icon・badge |
| サーバ | `internal/hub/push.go` | pushManager / VAPID 生成 / 購読 CRUD / sendApproval |
| 通知バックエンド | `internal/notify/notify.go` | ntfy / webhook への outbound 通知（Web Push とは別経路、§14） |

`web/web.go` の `//go:embed all:dist` により、SW / manifest / icons を含む `web/dist/` 全体がバイナリに同梱される（ビルド前にフロントエンドビルドが必須）。

### 12.2 VAPID 鍵と購読の保存

| 項目 | 値 |
|---|---|
| 保存先 | `~/.many-ai-cli/push_store.json`（perm `0o600`、tmp + atomic rename） |
| 鍵生成 | 起動時 `newPushManager()` 内で `webpush.GenerateVAPIDKeys()`。既存鍵があれば再利用 |
| ライブラリ | `github.com/SherClockHolmes/webpush-go` |
| 構造 | `vapid_public_key` / `vapid_private_key` / `subscriptions[]`（endpoint, keys{auth,p256dh}, user_agent, created_at, last_seen） |

`config.yaml` に VAPID 関連キーは持たせない（push_store.json で完結）。オプトイン状態のみ `user_prefs.push_notifications.enabled` に保存。

### 12.3 API

| Method | パス | 用途 |
|---|---|---|
| GET | `/api/push/status` | VAPID 公開鍵の有無・購読件数等のステータス |
| GET | `/api/push/vapid-public-key` | VAPID 公開鍵（SW 登録直前に取得） |
| POST | `/api/push/subscriptions` | 購読 upsert（`{endpoint, keys:{auth,p256dh}}`） |
| DELETE | `/api/push/subscriptions` | 購読解除 |

いずれも `s.guard()` で token 認証を通過後のみ処理。

### 12.4 通知挙動とセキュリティ

- 検出経路: PTY 出力処理で `approval_detected` を broadcast した直後に `notifyApprovalPush()` を goroutine 呼び出し。タスク完了は `notifyDonePush()` が同チャンネルを流用
- ペイロード: `type` / `id` / `session_id` / `provider` / `title` / `body`（最大 180 バイトに UTF-8 安全 truncate）/ `url`（`/?session_id=<id>`）
- TTL 300 秒、`pushManager.sent` map で 1 時間以内の再送を抑止
- **Hub token をペイロードに含めない**: `approvalPushURL()` は `token=` を一切付けず、`push_test.go` の `TestApprovalPushURLDoesNotIncludeToken` で回帰テスト。通知クリック時は SW が Cache Storage（`TOKEN_CACHE`、postMessage `many-ai-cli-token` 経由）からローカルに token を読み URL を構成するため、token が外部 push サーバ（FCM 等）に出ない
- 送信失敗ログは `endpointHash(endpoint)` のハッシュ先頭 12 文字のみ。SW の fetch handler は network-only（token-bound state をキャッシュしない）
- iOS Safari のブラウザタブ（PWA 未インストール）は `isLikelyIOSBrowserTabWithoutStandalone()` で検知し、登録前に「インストールが必要」と案内する

## 13. 統合ランチャー（Windows / Linux / macOS）

WSL 専用の旧ランチャー `many-ai-cli-wsl.exe` は v0.3.0 で削除し、統合ランチャー `many-ai-cli-launcher`（Windows では `many-ai-cli-launcher.exe`。実体は単一の `cmd/many-ai-cli-launcher/main.go` でクロスプラットフォーム）が WSL / SSH serve / SSH tunnel を一元管理する。

SSH `serve` / `tunnel` プロファイルは Windows / Linux / macOS で動作し、`wsl` プロファイルは Windows 専用（非 Windows では `connector_wsl_unix.go` の `connectorForWSL` が明示エラーを返す）。ランチャーバイナリは本体と同じビルドマトリクス（windows/linux/darwin、+ darwin/arm64。windows/arm64・linux/arm64 は ignore）で生成し、各リリースアーカイブ（`many-ai-cli` + `many-ai-cli-launcher` の 2 本）・deb/rpm（`nfpms.ids`）・Homebrew cask（post-install で両バイナリを de-quarantine）に同梱する。ブラウザは Windows は既定ブラウザ、Linux は `xdg-open`、macOS は `open` で開く（`browser_{windows,unix}.go`）。コンソール UTF-8 設定は Windows のみ実体を持ち、非 Windows は no-op（`console_{windows,unix}.go`）。

### プロファイルファイル

保存先: `~/.many-ai-cli/launcher-profiles.yaml`（`config.yaml` とは分離）。

```yaml
version: 1
last_used: my-wsl
profiles:
  - name: my-wsl
    type: wsl
    distro: Ubuntu-22.04
    hub_port: 0             # 0 = Windows 側衝突を避けて自動選択
    cwd: /home/user/projects

  - name: my-remote
    type: ssh
    mode: serve             # serve（既定）= リモートで many-ai-cli serve。この serve を systemd / tmux / nohup でリモート常駐させ、別途 tunnel モードで再接続する運用も可能
    host: remote.example.com
    user: your-user
    ssh_port: 22
    identity_file: ""
    hub_port: 47777
    cwd: /home/your-user/projects

  - name: remote-docker
    type: ssh
    mode: tunnel            # tunnel = すでに常駐している Hub（`serve` 常駐 / Docker いずれも可）へのポートフォワードのみ
    host: remote.example.com
    user: your-user
    hub_port: 47801         # 必須（0 不可）。リモート Hub と同ポート
    token_command: "docker exec aac-user1 sh -c 'grep ^token ~/.many-ai-cli/config.yaml | cut -d\" \" -f2'"
```

上記の `remote-docker` は接続先が Docker 常駐 Hub の例だが、tunnel モードの接続先は Docker に限らない。`serve` を systemd / tmux で常駐させた Hub にも同じ tunnel で繋げる（`token_command` をその常駐 config から token を読む形にすればよい）。

フィールド: `name` / `type`（wsl|ssh）/ `mode`（serve|tunnel、ssh のみ）/ `host` / `user` / `ssh_port` / `identity_file` / `hub_port` / `cwd` / `distro` / `binary` / `token_command`（tunnel のみ必須）。

### CLI フラグ

```
many-ai-cli-launcher [--profile <name>] [--last] [--ui]   # Windows は many-ai-cli-launcher.exe
```

`--profile <name>`（指定で即接続）/ `--last`（前回プロファイル）/ `--ui`（常に選択画面）/ （なし: 1 件なら即接続、複数なら選択画面）。

### 接続フロー

**WSL プロファイル**（`internal/launcher/connector_wsl_windows.go` の `WSLConnector`）:

1. Windows 側で port を選ぶ（47777 から 100 刻みで listener を probe）
2. `wsl.exe [-d distro] --cd <cwd> -- bash -ilc 'export MANY_AI_CLI_WSL_LAUNCHER=1; exec many-ai-cli serve --port <port>'`
3. WSL 側 stdout/stderr を scan し banner の Hub URL を抽出
4. Windows の default browser を開く
5. 終了時に同 port の WSL orphan `serve` を best-effort cleanup

`bash -ilc` は Ubuntu 既定 `.bashrc` の非対話 early return を避け、pnpm / nvm / cargo の PATH を読むため。`MANY_AI_CLI_WSL_LAUNCHER=1` のとき Linux 側 Hub は log dir を Windows user profile 配下へ寄せる。

**SSH serve / tunnel**（OS 共通ロジックは `internal/launcher/connector_ssh.go`。SSH 実行ファイル名は `connector_ssh_{windows,unix}.go` の `sshExe` で `ssh.exe` / `ssh` を出し分け。全 OS で動作）:

- serve: `ssh -t -L <port>:127.0.0.1:<port> [user@]host -- bash -ilc "many-ai-cli serve --port <port>"` を起動し、banner の Hub URL を抽出。port 不一致なら kill して次候補で再試行（最大 5 回）。Ctrl+C でリモート serve を cleanup
- tunnel: `ssh -N -L <port>:127.0.0.1:<port> [user@]host` でポートフォワードのみ確立 → `token_command` を SSH 経由実行（5 秒 timeout）→ `/api/info?token=<token>` を最大 20 回ポーリング（500ms 間隔）→ `/api/net-hint` に `ssh=true` / `host_label` / `env_kind=remote-tunnel` を登録 → ブラウザで `?token=...&via=ssh&host_label=...&env_kind=remote-tunnel` を開く。Ctrl+C でトンネルのみ閉じる（リモート Hub は停止しない）

tunnel モードのローカルポート衝突は `-o ExitOnForwardFailure=yes` で即失敗（+100 再試行はしない）。token は URL エンコードしてから付与する。

設計補足:

- serve モードは `ssh -t -L`（PTY 割り当て）で、切断時に SIGHUP がリモートへ届き孤児 `serve` を防ぐ。banner の実ポートが指定値と不一致なら kill して +100 刻みで最大 5 回再試行する。
- tunnel モードはローカル側ポートをずらせない。Hub の `isAllowedHubHost` が `Host: 127.0.0.1:<port>` をポート完全一致で検証するため、SSH local forward は左右同番号が必須。よって `hub_port: 0` 不可・`token_command` 必須・衝突時は即失敗（再試行なし）という非対称な制約になる。`launcher-profiles.yaml` はランチャーを動かすローカル端末（Windows / Linux / macOS）側に置き、リモートサーバー内 `config.yaml` とは分離する。

### セキュリティ前提

- Hub は `127.0.0.1` bind 固定。トンネルは `127.0.0.1` 同士の local forward のみ（`-g` / `GatewayPorts` 不使用）
- `token_command` の結果（token）は `launcher-profiles.yaml` に保存しない
- パスワード・パスフレーズは保存せず、`-o BatchMode=yes` で対話を禁止
- プロファイルの `host` / `user` / `binary` / `identity_file` は `-` 始まり（ssh ローカルオプション注入）を拒否し、`host` / `user` の空白・制御文字も拒否する（`validateSSH`）。`cleanupSSHOrphans` の pkill パターンは `regexp.QuoteMeta` + `ShellQuote` で 1 トークンに固定。Hub の `POST /api/servers`（プロファイル書込）も同じ `launcher.Validate` を通す

実装: `internal/launcher/profile.go`（スキーマ / 読み書き / バリデーション）/ `connector_for.go`（プロファイル種別→Connector 振り分け）/ `connect.go`（接続フロー `Connect` / `SelectProfile`。ランチャー exe と本体 `connect` サブコマンドで共用）/ `connector_wsl_windows.go`・`connector_wsl_unix.go`（WSL は Windows のみ実装。非 Windows はエラー）/ `connector_ssh.go`・`connector_ssh_{windows,unix}.go` / `proc_attr_{windows,other}.go`（子プロセス無窓起動の SysProcAttr）/ `browser_{windows,unix}.go`・`console_{windows,unix}.go` / `cmd/many-ai-cli-launcher/main.go`。

### Hub 内蔵 Server ボタン（v0.3.0 追加）

別 exe ランチャーと並んで、**稼働中の Hub ダッシュボードからも**リモート接続できる。ヘッダーの `🖥 Server` ボタン（電源ボタンの左）でモーダルを開き、`launcher-profiles.yaml` の一覧表示・接続/切断・追加を行う。接続成功時は対象 Hub の URL を**新規タブ**で開く（モーダル埋め込みはしない＝低リスク）。

- **接続マネージャを Hub プロセスに内蔵**: `internal/hub/servers.go` が `launcher.UIServer` の接続ライフサイクル（inflight / 確立済み conns / runConnection / promoteConnection / watchConnection）を移植したもの。純ロジック（`Connector` / `Profile` / `launcher-active.json`）は `internal/launcher` を再利用し、HTTP 層は Hub の既存 token ガード（`s.guard`）配下に作り直している。
- **子プロセスは Hub が抱える＝コンソール窓不要**: SSH/WSL の子プロセスは Hub プロセスの子になり、Hub 終了で全トンネルが落ちる（`serverConnManager.closeAll`）。Windows では `internal/launcher/proc_attr_windows.go` の `CREATE_NO_WINDOW` で無窓起動し、`launcher.ConnectorForQuiet` が子出力を破棄して Hub のコンソール／ログを汚さない（リモート Hub の URL+token を echo しない）。
- **併存**: Hub 接続分も `launcher-active.json` に登録するため、別 exe ランチャーの選択 UI からも「接続中」が見える（相互可視）。役割分担は「Hub 未起動からの入口＝別 exe ランチャー（または `many-ai-cli connect`）／稼働中 Hub からの入口＝🖥 Server ボタン」。
- API（いずれも token ガード配下）: `GET/POST /api/servers`（一覧 + active / replace-all 保存）・`POST /api/servers/connect`・`GET /api/servers/connect/status`（`hub_url` を返す）・`POST /api/servers/disconnect`。
- 実装: `internal/hub/servers.go` / `web/src/app/server-modal.ts` / `web/src/styles/server-modal.css` / `web/src/index.html`（ヘッダーボタン + `#server-modal`）。

### `many-ai-cli connect` サブコマンド（v0.3.0 追加 / SmartScreen フォールバック）

`many-ai-cli connect --profile <名前>`（または `--last`）で、別 exe ランチャーをダブルクリックせずに**ターミナルから**リモート接続できる。内部は `launcher.SelectProfile` + `launcher.Connect` を呼ぶ薄いディスパッチで、ランチャー exe の直接接続（`--profile`）と同一フロー。ターミナル（CreateProcess 経由）起動は Explorer の評価チェックを通らないため、ブラウザ DL した未署名 exe で出る SmartScreen の評価ダイアログを回避できる正規手順として位置づける（詳細は README のセキュリティ節）。なお SmartScreen の評価ダイアログ回避と、Defender による実検知/隔離は別問題（署名は本バージョンのスコープ外）。

## 14. リモートサーバー / Docker デプロイ（v0.3.0 新規）

リモート常駐は (A) リモートで `many-ai-cli serve` を systemd / tmux 等で常駐させランチャー tunnel で再接続する方式と、(B) Docker コンテナ常駐の 2 方式があり、本節は主に (B) を扱う。選択軸は常駐可否（どちらも常駐できる）ではなく、単一ユーザーの手軽運用か、マルチユーザー隔離・リソース制限・自動更新を仕組みに任せたいかである。

常駐リモート Hub を運用する手段は複数あり（リモートで `many-ai-cli serve` を systemd / tmux 等で常駐＋ランチャー tunnel 再接続、または Docker コンテナ常駐）、本節はそのうち Docker による常駐運用（マルチユーザー隔離・リソース制限・自動更新）の資産を `deploy/docker/` に追加する。

| ファイル | 役割 |
|---|---|
| `deploy/docker/Dockerfile` | 4 ステージ（web-build → build → whisper-build → runtime） |
| `deploy/docker/Dockerfile.dockerignore` | BuildKit per-Dockerfile ignore |
| `deploy/docker/entrypoint.sh` | PID 1。Hub 起動・socat 中継・graceful shutdown |
| `deploy/docker/compose.yaml` | `include` で per-user YAML を束ねる |
| `deploy/docker/users/example.yaml` | per-user サービス定義テンプレート |
| `deploy/docker/aac-update.sh` | cron 用の冪等な自動更新スクリプト |
| `deploy/docker/sshd-member.conf.template` | メンバー SSH トンネル専用 sshd_config スニペット |
| `.github/workflows/docker-image.yml` | GHCR への image publish |

### Dockerfile

- `web-build`（node:22-bookworm + bun 1.3.14）: `web/dist` 生成
- `build`（golang:1.25-bookworm）: `CGO_ENABLED=0` 静的バイナリ（`-trimpath -ldflags "-s -w"`、`web/dist` は go:embed）
- `whisper-build`（ubuntu:24.04）: whisper.cpp をソースから可搬・静的ビルド（既定 `v1.8.6`、`BUILD_SHARED_LIBS=OFF` 等）
- runtime（ubuntu:24.04）: provider CLI（claude-code / codex / copilot / cursor-agent / grok）をバージョン固定で導入し `DISABLE_AUTOUPDATER=1` で自己更新禁止。実行ユーザー ubuntu（uid 1000、sudo/adm 除外）、`EXPOSE 48000`、`MANY_AI_CLI_WHISPER_SERVER=/usr/local/bin/whisper-server`

HEALTHCHECK は Dockerfile ではなく per-user compose 側で定義。

### GHCR ワークフロー

- トリガー: `push`（main / develop）または `workflow_dispatch`
- タグ: main → `:latest`（リモートサーバー通常運用が追従）、develop → `:develop`（検証）、全 push に `:sha-<short>`
- 認証: `docker/login-action` + `GITHUB_TOKEN`（`packages: write`）、キャッシュ `type=gha`、platforms `linux/amd64`

### compose（per-user）

`compose.yaml` は `include` で `users/<user>.yaml` を取り込む。ユーザー追加 = YAML 1 ファイル + include 1 行。`users/example.yaml` の要点:

| 設定 | 値 / 方針 |
|---|---|
| image | `ghcr.io/ishizakahiroshi/many-ai-cli:${AAC_TAG:-latest}` |
| restart / stop_grace_period | `unless-stopped` / 40 秒 |
| ログ | json-file, max-size 10m, max-file 3 |
| security_opt | `no-new-privileges:true` |
| ports | `127.0.0.1:<USER_PORT>:48000`（ホスト側 loopback のみ） |
| volumes | named volume `aac-home-<user>` + work bind mount |
| networks | ユーザー専用 `aac-net-<user>`（コンテナ間 Hub 直アクセス遮断） |
| 制限 | mem/memswap 各 2g、cpus 2、pids_limit 1024 |
| healthcheck | `curl http://127.0.0.1:$HUB_PORT/api/info?token=<token>`（interval 60s / timeout 5s / retries 3 / start_period 15s） |

### aac-update.sh

`/opt/many-ai-cli/aac-update.sh`。cron 例 `30 4 * * * ...`（毎日 04:30）。同ディレクトリに `HOLD` ファイルがあればスキップ（idempotent、解除は `rm HOLD`）。フロー: `docker compose pull --quiet` → `docker compose up -d`（イメージ変化時のみ再作成）→ `docker image prune -f`。追従タグは `.env` の `AAC_TAG` で切替。

### localhost-only の維持

- compose の publish は必ず `127.0.0.1:<PORT>:48000`。コンテナ内の `0.0.0.0` bind は socat 中継（`TCP-LISTEN:48000 → 127.0.0.1:$HUB_PORT`）の Namespace 内に閉じる
- Hub は `HUB_PORT` 完全一致を要求（`isAllowedHubHost`）。entrypoint は `serve --port $HUB_PORT` で publish ポートと三者一致
- ユーザー間は専用 Docker network で分離。SSH は `sshd-member.conf.template` で `PermitOpen 127.0.0.1:__PORT__` / `ForceCommand nologin` / `PermitTTY no` / `GatewayPorts no` 等によりトンネル以外を遮断

### 14.1 マルチユーザー運用の制約

- **ポート採番規約**: ユーザー割当ポートは 47801 から連番。Docker publish ポート・コンテナ内 socat 受け口（48000）・Hub `HUB_PORT`・SSH forward ポートを全経路で同一番号に揃える（Host/Origin がポート完全一致を要求するため）。
- **provider CLI バージョン管理**: バージョンは Dockerfile で pin し、更新はイメージ再ビルドの一斉ロールアウトのみ。コンテナ内 self-update は禁止（`DISABLE_AUTOUPDATER=1`、root 所有領域に配置）。`~/.local` に self-update が残り PATH を奪う「亡霊バージョン」を防ぐ。
- **初回認証フロー**: コンテナは headless のため `codex login`（localhost:1455 コールバック）は失敗し `--device-auth` が必須、cursor-agent は `NO_OPEN_BROWSER=1` が必要。管理者がコンテナ内でコマンドを実行し、認可 URL だけ本人へ渡す「管理者実行・本人認可」を前提とする。
- **idle timeout**: トンネル切断が常態となる常駐運用（Docker / リモート `serve` 常駐いずれも）では `idle_timeout_min: 0`（UI 切断後の全 PTY kill を無効化）が要る。Docker では entrypoint が config に事前生成する。
- **停止シグナル**: `stop_grace_period: 40s` + entrypoint の SIGTERM 中継（wrapper → AI CLI）で、ファイル書き込みや git 操作中でも終了猶予を確保する。緊急時以外 `docker kill` / `stop -t 0` を使わない。
- **ソース転送**: `git archive HEAD | gzip | ssh ...` で HEAD のみ転送する（working tree 直 tar は並行編集中の中途半端なファイルを拾いビルドを壊す）。

### 14.2 メモリサイジング指針

共有リモートサーバーの収容セッション数は概算 `(RAM − OS 0.5GB − dockerd 0.1GB − Hub 0.05GB) ÷ 0.5GB`。

| 区分 | 目安 |
|---|---|
| Claude Code 1 session | 約 500 MB |
| Codex 1 session | 約 350 MB |
| wrapper | 約 25 MB/session |
| Hub 常駐 / dockerd / OS 最小 | 50 / 100 / 500 MB |

リモートサーバー RAM 別収容目安: 4GB → 6〜7 session（1 人用・swap 必須）、8GB → 14 session（2 人 × 5 の推奨最低ライン）、16GB → 30 session（3〜4 人）。per-user compose の推奨値（8GB / 5 人想定）は `mem_limit: 2g` / `mem_reservation: 1g` / `memswap_limit: 2.5g`。OOM 対策は ①swap = RAM × 50% 確保（OOM Killer 即発動防止）②`vm.swappiness=10` ③コンテナ cgroup 上限でユーザー単位の OOM kill が他ユーザーを巻き添えにしない、の 3 点。

### 14.3 モバイル接続（📱）と Tailscale serve

📱モバイル接続は **Hub が自分側の Tailscale 状態を自己診断し、`tailscale serve` の HTTPS 経由で「本物の URL（`https://<実DNS名>.<tailnet>.ts.net/?token=`）」の QR を生成する**。スマホでスキャンすれば実際に Hub が開く（ダミー URL を出さない）。要点:

- **bind は `127.0.0.1` 不変**。`tailscale serve` が loopback（`127.0.0.1:<HUB_PORT>`）へプロキシするため、bind を晒さずに tailnet 内端末から到達できる。設計の `127.0.0.1` 固定方針（§13）と矛盾しない。
- **Funnel は不使用**。`tailscale serve` は tailnet 内限定。Funnel（全世界公開）は方針に反するため使わず、tailnet の HTTPS 初回有効化時も「Funnel のチェックを外す」よう誘導する。
- **secure context のため HTTPS serve を第一推奨**。生IP（`100.x` 直）経路は `127.0.0.1` bind で到達不可な上、secure context を失い Service Worker / Web Push / PWA インストール / マイク音声が無効化されるため撤廃した。SSH ローカルフォワード（`http://127.0.0.1:<port>`）は secure context でフル機能を保つ唯一の生 URL 経路として残す。
- **allowed_hosts 自動登録**。serve 有効化時に自分の tailnet DNS 名を `hub.allowed_hosts` へ冪等追加し設定リロードする（host ガード＋WS handshake を通すため）。CSP も既存の動的展開で `wss://<host>:*` を許可する。
- **Tailscale CLI へ到達できない環境（Docker コンテナ内 Hub・headless 等）は degrade** し、SSH トンネル / launcher 経由のモバイル接続へ誘導する（コンテナ内に `tailscale` CLI が無く `tailscale serve` 不可）。
- **token は QR でスマホ端末に永続化される**。launcher の `token_command` 方式（毎回取り直し・非保存）との差異は運用 manual に明記。リモート Hub 上で動く場合も mobile-connect は当該 Hub 自身の token を読むため矛盾しない。

詳細プラン: `docs/local/plan_mobile-connect-flow-redesign.md`。

### 14.4 リモートアクセス保護（失効ボタン＋任意 PIN＋新規デバイス通知）

スマホ/リモート接続の紛失・漏洩対策。設計の芯（`127.0.0.1` bind 固定・token 必須・loopback は token のみで快適）は**不変**。Hub 側に重い認証を必須化せず、「安く効く失効ボタン」と「希望者向けの任意 PIN」に留め、本質的な守り方は manual の紛失時プレイブックで正直に伝える方針（詳細プラン: `docs/local/plan_hub-remote-auth.md`）。

- **全アクセス失効（キルスイッチ・必須）**: `POST /api/auth/revoke-all` が `cfg.Token` と `cfg.AuthCookieSecret`（cookie 署名鍵）を再生成し永続化する。これで token URL・token cookie・PIN セッション cookie がすべて無効化され、紛失端末を含む全デバイスが弾かれる。レスポンスで新 token / 新 URL を返し UI が新 URL へ誘導する（このPC自身も再ログインになる）。SSH/VPN の鍵失効は別途必要。
- **任意リモート PIN（既定 OFF）**: `cfg.RemotePINHash`（bcrypt・平文非保存）。設定すると **非 loopback アクセス時に PIN ログインを追加要求**する（`guard()` 内の `requireRemotePIN` ゲート。loopback は素通し）。PIN 認証成功で HMAC-SHA256 署名・期限付き cookie（`MANY_AI_CLI_pin`、`AuthCookieSecret` で署名）を発行し、revoke-all のローテーションで一括失効する。6 桁以上の数字 = 総当たり可能なため、連続失敗で IP 単位ロックアウト（5回→1分→5分→30分の指数バックオフ）＋全体上限（分散総当たり対策）で `429`。API: `GET /api/auth/status`（pin_enabled / authed / locked / retry_after）・`POST /api/auth/login {pin}`・`POST /api/auth/set-pin {pin|clear}`。login/status は PIN ゲートを通さない `guardBase`、set-pin は full `guard`（remote からの変更は PIN 認証済みのときだけ）。
- **新規デバイス接続通知（SEC-C）**: 未知デバイス（IP+UA の SHA-256 ハッシュ先頭 16 hex）の初回 remote 接続を `handleIndex` / WS UI attach / PIN ログイン成功で検知し、既存の push / ntfy / webhook 基盤で本人へ通知する（セキュリティ警告のため events フィルタは無視）。既知デバイスは連投しない（TTL 24h・ソフト上限 256）。盗まれた QR / token の使用を即検知する侵入検知。
- **ログ衛生**: PIN・token・認証 cookie・PIN 失敗時の入力値は slog に出さない。失敗ログは件数 / ロックアウト状態（retry_after）のみ。`/api/auth/*` レスポンスは `Cache-Control: no-store`。

## 15. Voice / Whisper

音声入力は WebSpeech API に加え、ローカル Whisper サーバ連携を `config.yaml:voice.whisper` で設定できる（`web/src/app/voice-whisper.ts` / `voice.ts`、`/api/voice/transcribe`、`/api/whisper/*`）。Docker runtime は whisper-server を同梱し、`MANY_AI_CLI_WHISPER_SERVER` で位置を Hub に通知する。wake word 関連 key は schema に残るが公開 UI では hidden / disabled。

| API | Method | 用途 |
|---|---|---|
| `/api/voice/transcribe` | POST | 音声文字起こし |
| `/api/whisper/status` | GET | Whisper サーバ状態 |
| `/api/whisper/install` / `uninstall` | POST | モデル導入 / 削除 |
| `/api/whisper/start` / `stop` | POST | managed サーバ起動 / 停止 |

### 15.1 エンジン選択とモバイル relay

音声認識エンジンは `off` / `browser` / `whisper` の 3 値で、端末ごとに localStorage に保存しサーバ側ユーザー設定の同期対象から外す（PC=browser・iPhone=whisper の共存を保証）。iOS Safari は WebKit 強制で WebSpeech が実用品質にならないため、マイクと推論を分離する。iPhone は AudioWorklet で 16kHz PCM を取得し JS 側で WAV 化して `/api/voice/transcribe` へ送り、Hub が PC/リモートサーバー上の Whisper サーバへリレーする。PC Chrome/Edge のブラウザ内蔵認識は置き換えない。録音は `MediaRecorder` を使わず WebAudio/AudioWorklet で全ブラウザ共通化し（iOS の AAC 出力とサーバ側 ffmpeg 依存を回避）、既存 `voice.ts` には極力触らず `voice-whisper.ts` を新設する。

### 15.2 誤送信・誤認識の抑止

- Whisper 経路では自動送信トリガー（末尾フレーズ検出）を既定無効とし、明示オプトインかつ完全一致時のみ有効化。結果はテキスト入力欄への挿入のみで、ユーザー目視を最終確認層とする。
- フロント 2 層フィルタ: ①録音側プリチェック（AnalyserNode の実音量がほぼ無音のまま確定したら送信しない）②定型幻覚フィルタ（「ご視聴ありがとうございました」等の既知句が結果**全体と完全一致**したときのみ破棄。部分一致では誤殺しない）。句リストは ja/en を定数化。いずれの破棄もトーストで理由表示（無言廃棄は不信感につながる）。サーバ側は silero VAD（whisper.cpp オプション）有効化を推奨設定とする。
- `server_url` は OpenAI 互換のため外部 API も指定可能だが外部利用はオプトイン扱いで、設定時は「音声データが外部送信される」旨を UI に明示。既定はローカル（127.0.0.1/localhost）のみ許可。

### 15.3 managed Whisper のライフサイクル

エンジン `whisper` で初回リクエスト時（または Hub 起動時）に whisper-server を子プロセス起動し、ポートを自動採番して `server_url` に反映。Hub 終了 / `many-ai-cli stop` 時に確実に kill する。Windows は Job Object（`KILL_ON_JOB_CLOSE`）でクラッシュ時も孤児を残さず、Linux/macOS は `Setpgid` + 明示 kill、Docker は `init: true`（tini を PID1）で孤児/ゾンビを防ぐ。Hub 再起動時に前回の孤児 whisper-server を検出・回収する（ポート占有・多重起動防止）。

### 15.4 バイナリ / モデル配布

managed インストールは初版 Windows x64 のみ。macOS/Linux は外部サーバ URL 指定（手動）へ誘導する。

- **入手元**: whisper-server バイナリは whisper.cpp GitHub Releases の Windows x64 zip を必要ファイルのみ選択抽出（SDL2.dll 非同梱）。Linux/macOS は公式 release に server が無いため many-ai-cli 自前 GitHub Actions でビルドし自リポジトリ release 資産でホストする（`-DGGML_OPENMP=OFF -DBUILD_SHARED_LIBS=OFF -DGGML_NATIVE=OFF` 既定、macOS arm64 は `-DGGML_METAL_EMBED_LIBRARY=1` で `.metallib` 内包）。モデルは Hugging Face の ggml 公式ミラー。
- **配置先**: `~/.many-ai-cli/whisper/{bin,models,tmp}/`。DL 前にディスク空きを確認し、SHA256 照合後に安全展開。失敗時は部分 DL を削除（冪等・再実行可）。アンインストールは配置ディレクトリを `os.RemoveAll`（System32 等に痕跡を残さない）。
- **manifest 構造**: `OS/arch → {URL, SHA256, ServerNames, KeepFromZip, Runtime}` のテーブルで、対応 OS/arch は manifest 追加だけで拡張する。
- **Windows VC++ ランタイム**: `vcomp140.dll`（OpenMP）/ `msvcp140.dll` / `vcruntime140.dll` / `vcruntime140_1.dll` を `go:embed` で同梱し `bin/` へ app-local 配置（UCRT は OS コンポーネントのため非同梱）。入手元は VS Redistributable の `/layout` 展開に限定。app-local DLL は Windows Update で更新されないため、脆弱性対応はリリース時差し替え運用とする。
- **macOS**: 自前ビルドは初回 quarantine でブロックされ得るため、ad-hoc 署名または `xattr -dr com.apple.quarantine` をインストールフロー / 案内に組み込む。
- **Docker リモートサーバー**: whisper-server はイメージに焼き込み、モデルは named volume（`aac-whisper-models:/models`）または bind mount で永続化。`up -d` 再作成後もモデルは再 DL 不要（初回のみ DL、以降は存在チェックでスキップ）。

## 16. Outbound 通知（ntfy / webhook）

Web Push とは別経路の outbound 通知を `config.yaml:notify` で設定する（`internal/notify/notify.go`）。承認待ち / タスク完了を ntfy トピックや webhook へ送る。

| API | Method | 用途 |
|---|---|---|
| `/api/notify-config` | GET/POST | 通知バックエンド設定 |
| `/api/notify-test` | POST | テスト通知送信 |
| `/api/notify-generate-topic` | POST | ntfy トピック生成 |

設定例は §18 の `notify:` を参照。`events: []`（空）の場合は送信しない（オプトイン）。

## 17. Path / open handlers・Attach・Logging

### Path / open handlers

Terminal / Chat / Files から local path を扱う API: `/api/open-file` / `/api/open-default-file` / `/api/open-folder` / `/api/open-terminal` / `/api/file-open-app` / `/api/terminal-app` / `/api/pick-file` / `/api/pick-directory` / `/api/path-exists` / `/api/open-dir`。Windows は explorer / configured app、WSL launcher mode は `wslpath -w` 経由で Windows path に変換してから開く。localhost-only 前提の host operation API で、loopback remote address を確認する。

パスリンク UI: ターミナル / Files の右クリックメニュー（共通 `showPathPopup`）に「モーダルで開く」を追加する（`isAnyAiCliPreviewable` なファイルのみ）。既存 `FilesPreview.bind()` をオーバーレイ内に単体マウントして Markdown/コード/画像/動画・検索・編集・リロードを流用する（z-index 9400、720px 以下はフルスクリーン、Esc は capture フェーズで先取り）。またターミナル選択テキストの右クリックに「入力欄に追加」を設け、クリップボードを経由せず `cleanCopiedText()` 整形後に入力欄末尾へ直接追記する（Claude Code の複数行貼り付けが「Pasted text」添付化されるのを回避する代替動線）。ターミナル行のクリック展開リンク（`expand-popup.ts` が ctrl+o 往復でバッファ差分をキャプチャ）は、従来の `… +N lines (ctrl+o to expand)` に加え、サブエージェント `Done` 行やツール要約行の `(ctrl+o to expand)` 単独表記も対象に拡張する。

### Attach

画像に加え generic file attach を受け付ける。paste / D&D / file picker から `pendingAttachFiles` に積み、送信時に `/api/attach` へ multipart POST。保存は `~/.many-ai-cli/attachments/<session-id>/`（timestamp + nanosecond + sanitized name）。inject は Claude `@<path>` / Codex `@<slash path>` / fallback `<path>`。画像は可能なら長辺 1568px 以下の JPEG へ normalize。添付の保持は `log.attachment_retention_days` / `attachment_max_total_mb` と `/api/attachments/purge` で管理。

### Logging / Transcript

| 種類 | path |
|---|---|
| Hub log | `~/.many-ai-cli/logs/hub.log` |
| spawn log | `~/.many-ai-cli/logs/spawn/<provider>-<timestamp>.log` |
| session raw log | `~/.many-ai-cli/logs/sessions/*.log` |
| session history | `~/.many-ai-cli/logs/sessions/*.jsonl` |
| clean transcript | `~/.many-ai-cli/logs/sessions/*.txt` |
| SQLite store | `~/.many-ai-cli/logs/many-ai-cli.db`（§11.1） |

Clean transcript は session end 時に自動生成し、crash で漏れた分は次回 `serve` 起動時に `recoverTranscripts` が補完する。手動生成は `many-ai-cli log-clean <session>.jsonl -o transcript.txt`。session log は v0.2.0 以降オプトイン（`log.session_enabled`、既定 false）で、保持は `log.session_retention_days` / `session_max_size_mb` と `/api/logs/purge`・`/api/logs/legacy-notice` で管理する。

session log オプトイン化の設計判断: `.log`（wrapper 直書き）は `MaskSecrets()` を通らず API キー等が平文で残り、任意パスワードはパターン検出も原理的に不可。よってマスク強化ではなく「既定でディスクに書かない」を採る（SQLite のセッション一覧メタは記録継続）。ゲートは 3 箇所に集約する: ①`.log` 生成 ②`.jsonl` writer 生成（spawn/reattach 両経路）③`writeHistory()` 冒頭の早期 return（`.jsonl` event + SQLite `StoreEvent` を一括停止）。`.txt` は `.jsonl` 不在時に自動生成されない。

legacy-notice モーダルは「未通知（`legacy_logs_notice_shown: false`）& `session_enabled: false` & 旧ログ残存（`hasSessionLogFiles()`）」の 3 条件 AND で表示する（バージョン非依存の代理条件）。✕・キャンセル・オーバーレイ・Escape をすべて無効化した閉じ不可設計で、「実行」を押すまで進めない（一度きりのセキュリティ移行用途、バージョン記録方式は採らない）。`POST /api/logs/legacy-notice` は `enable_logging` フラグで `session_enabled` を同時更新できる。

purge の保護対象: `/api/logs/purge` は `activeLogBases()`（稼働中セッションの拡張子なしベース名集合）で除外し、SQLite は `ResetHistory(activeSessionIDs)` で保護。`/api/attachments/purge` は稼働中セッション ID のフォルダで除外。いずれも Hub が把握する ID/パスのみが保護対象で、Hub 再起動をまたいだ「古い稼働中ファイル」は保護されず全削除される（意図どおりの仕様）。

## 18. CLI / サブコマンド

`cmd/many-ai-cli/main.go` のサブコマンド:

| サブコマンド | 引数 / フラグ | 用途 |
|---|---|---|
| （なし） | — | Hub 起動済みならブラウザを開く。未起動なら serve + auto-open |
| `serve` | `--open` / `--port <n>` / `--dev` / `--debug` | Hub HTTP サーバ起動 |
| `wrap <provider>` | provider + 任意引数 | 指定 provider を Hub 経由ラッパー起動 |
| `claude` / `codex` / `copilot` / `cursor-agent` / `grok` | 任意引数 | `wrap <provider>` の糖衣構文 |
| `shell-init` | — | シェル統合スクリプト出力（eval 用） |
| `status` / `stop` | — | Hub 稼働状況表示 / 停止 |
| `log-clean` | `<session.jsonl>` `[-o transcript.txt]` | JSONL → テキスト transcript 変換 |
| `uninstall` | `[--purge]` | 設定削除（`--purge` でバイナリ本体も） |
| `version` / `--version` / `-v` | — | バージョン表示（ldflags → git tag の順） |
| `usage-relay` | （内部） | Claude statusLine / Codex Stop フックからの隠しリレー（help 非表示） |

バイナリ構成: `cmd/many-ai-cli/`（全 OS、メイン CLI）/ `cmd/many-ai-cli-launcher/`（全 OS、統合ランチャー。SSH プロファイルは全 OS、WSL プロファイルは Windows のみ）。旧 `cmd/many-ai-cli-wsl/` は削除済み。

### 18-1. トークン / コストステータスバー

画面最下部のステータスバー（`token-statusbar.ts`、`user_prefs.token_statusbar.enabled` 既定 ON）は provider 別にトークン使用量とコストを表示する。relay（`usage-relay` サブコマンド）は数値メタ（トークン数・コスト・モデル名・経過時間）のみ Hub へ POST し、プロンプト本文は送らない。Hub はメモリ保持 + WS push のみでディスクに書かない。

| provider | 取得方式 | 備考 |
|---|---|---|
| Claude | `statusLine` 機構（`--settings` 一時ファイル優先、不可なら `.claude/settings.local.json` を冪等マージ）から `usage-relay` を起動 | stdin JSON の `cost.total_cost_usd` / `model.display_name` / `context_window.*` を抽出。トークン値は**累積ではなく現在のコンテキストウィンドウ使用量**（Claude Code v2.1.132 以降） |
| Codex | `Stop` フック（`~/.codex/config.toml` か `hooks.json` に冪等注入）が `transcript_path`（rollout JSONL）を渡し、最新 `token_count` イベントの input/cached/output を抽出 | コストは Hub 側の価格表（モデル ID → per-MTok 単価）で算出。不明モデルは `$ —` |
| Copilot / Cursor Agent / Grok | フック注入なし | 既知 model / 経過時間 / project のみ表示 |

フック注入は承認マーカーと同じ参照カウント方式で全セッション終了時に除去し、`token_statusbar.enabled` が false なら注入をスキップする。価格・コンテキスト上限はモデル ID の前方一致で解決し、未登録モデルは該当セグメントを非表示にする。

表示セグメント構成: `#N` セッション番号 + 状態 pill（running 緑 / waiting 黄 / standby 灰 / error 赤）/ provider アイコン + ラベル + モデル名 / コンテキスト使用率ゲージ（〜80% 緑・80〜90% 黄・90%+ 赤）/ キャッシュ率ゲージ / バーンレート（`~$X.X/h`・`~Xk tok/min`）/ 接続状態（🟢/🔴）/ Git 変更（`±files ~lines`、debounce 付き `git status` を WS 配信）/ 承認待ち横断バッジ（`▶稼働 ⏸待機 ⚠承認待ち`）/ project + `⎇ branch` / 本日累計コスト（`today $X.XX`、日跨ぎリセット）。セグメントはクリック操作対応（⚠ → 該当セッションへジャンプ、$ → コスト内訳、ctx/tok → 値コピー）。

## 19. HTTP API 一覧（カテゴリ別・静的アセット除く）

v0.3.0 時点で約 93 エンドポイント。主要カテゴリ:

- **セッション管理**: `/api/info` `/api/net-hint` `/api/spawn` `/api/kill-all` `/api/shutdown` `/api/idle-timeout` `/api/reconnect-grace` `/api/session-usage`
- **WebSocket**: `/ws`（UI 接続 / wrapper register / reattach）
- **セッション履歴**: `/api/session-chat` `/api/session-log` `/api/session-search` `/api/session-store/reset`
- **承認**: `/api/approval/status|enable|disable|dismiss` `/api/approval-patterns` `/api/approval-patterns/`
- **Files**: `/api/files-list|content|asset|download|roots|move|rename|mkdir|create|save|delete-dir`
- **Git**: `/api/git-log|show|refs|status|commit-all|commit-message|fetch|pull`
- **モデル / slash**: `/api/models` `/api/slash-cmd-sources` `/api/slash-commands` `/api/usage-link-defaults`
- **設定 / 通知**: `/api/log-config` `/api/notify-config` `/api/notify-test` `/api/notify-generate-topic` `/api/encoding-check`
- **user-prefs**: `/api/user-prefs` `/api/user-prefs/notify-sound-custom` `/api/user-prefs/avatar` `/api/avatar`
- **Push**: `/api/push/status` `/api/push/vapid-public-key` `/api/push/subscriptions`
- **Voice / Whisper**: `/api/voice/transcribe` `/api/whisper/status|install|uninstall|start|stop`
- **Path / open**: `/api/attach` `/api/pick-directory` `/api/pick-file` `/api/path-exists` `/api/open-file|default-file|folder|terminal|dir` `/api/file-open-app` `/api/terminal-app`
- **ログ保守**: `/api/logs/purge` `/api/logs/legacy-notice` `/api/attachments/purge`
- **Workbench**: `/api/workbench/*`（§11.2 参照）

旧 docs browser 系 `/api/docs-*` は `/api/files-*` へ移行済み（browser storage も one-shot migration）。

## 20. 設定スキーマ

`~/.many-ai-cli/config.yaml` の主要 schema（v0.2.0 §16 からの追加を含む）:

```yaml
hub:
  port: 47777
  open_browser: true
  auto_shutdown: true
  log_dir: ~/.many-ai-cli/logs
  idle_timeout_min: 60
  wrapper_reconnect_grace_sec: 3600
  allow_loopback_without_token: false
  trusted_networks: []
  allowed_hosts: []
  env_kind: ""           # local | wsl | remote | remote-tunnel

log:
  enabled: true
  max_size_mb: 10
  max_backups: 3
  compress: false
  session_enabled: false              # v0.3.0: PTY セッションログのオプトイン
  legacy_logs_notice_shown: false     # v0.3.0
  session_retention_days: 7           # v0.3.0
  session_max_size_mb: 50             # v0.3.0
  attachment_retention_days: 7        # v0.3.0
  attachment_max_total_mb: 500        # v0.3.0

approval:
  enabled: false
  first_launch_shown: false

models_source: ""        # v0.3.0: /api/models のデフォルト取得元 URL 上書き

ollama:
  base_url: ""            # 空なら http://localhost:11434。Hyper-V ホスト側 Ollama などは http://192.168.x.x:11434

voice:                   # v0.3.0
  whisper:
    server_url: ""
    request_path: ""
    language: ja
    timeout_seconds: 60
    managed: false
    model: small
    server_port: 0
    hallucination_phrases: []   # 既定 10 件

notify:                  # v0.3.0: outbound 通知（Web Push とは別経路）
  backends:
    - type: ntfy         # ntfy | webhook
      url: ""
      topic: ""
  events: []             # approval | done（空 = 送信しない）

slash_cmd_sources:
  claude: https://raw.githubusercontent.com/ishizakahiroshi/many-ai-cli/main/resources/slash-commands/claude.md
  codex: ...
  copilot: ...
  cursor-agent: ...
  grok: ...

approval_pattern_sources:
  claude: .../resources/approval-patterns/claude.md
  codex: ...
  copilot: ...
  cursor-agent: ...
  grok: ...
  common: .../resources/approval-patterns/common.md

approval_profiles:
  claude: official
  codex: official
  copilot: official
  cursor-agent: official
  grok: official
  common: official

local_models:
  - id: llama3.2:3b
    label: Llama 3.2

file_open_app: ""
terminal_app: ""
token: <32-byte-hex>

user_prefs:
  trigger: { enabled: false, phrase: "" }
  notify_sound: { enabled: false, type: default, custom_file: "", custom_mime: "" }
  approval: { auto_switch: false }
  quick_cmds: { cmd1: "", cmd2: "" }
  usage_links: { claude: "", codex: "", copilot: "", cursor-agent: "", grok: "" }
  voice: { grace_seconds: 2, wake_word_enabled: false, wake_word_phrase: "", input_disabled: false }  # input_disabled は v0.3.0
  desktop_notifications: { enabled: false }   # v0.3.0
  push_notifications: { enabled: false }      # v0.3.0
  display: { theme: "", font_size: "", lang: "", locked_mode: "" }  # v0.3.0
  token_statusbar: { enabled: null }          # v0.3.0（*bool。null = 既定 ON）
  done_summary_notify: { enabled: false }     # v0.3.0
  session_order: []
  group_order: []
  project_favorites: []
  cwd_history: []
  spawn: { defaults: {}, last_model: {} }
  avatar: ""
  display_name: ""
  migrated_from_localstorage: false
```

VAPID 鍵・Web Push 購読は `config.yaml` ではなく `~/.many-ai-cli/push_store.json` に保存する（§12.2）。launcher プロファイルは `~/.many-ai-cli/launcher-profiles.yaml`（§13）。Workbench の templates / tasks / palette / policies / state は `~/.many-ai-cli/workbench/*.json`、セッション履歴は `~/.many-ai-cli/logs/many-ai-cli.db`。

## 21. Security / Privacy

v0.3.0 は遠隔運用と通知が増えたため、localhost-only 前提とトークン分離をより重視する。

守る前提:

- Hub は `127.0.0.1` bind 固定。Docker は loopback publish + socat 中継、リモートは SSH local forward に限定
- token なし API / WebSocket は既定で拒否。例外は `hub.allow_loopback_without_token: true` の場合のみで、RemoteAddr が loopback または `hub.trusted_networks` の CIDR に入るリクエストを許可（`0.0.0.0/0` / `::/0` は設定エラー）
- `hub.allowed_hosts` は WireGuard 等の私設経路用の Host / Origin 許可リスト（IP literal / hostname のみ、wildcard / port 付きは設定エラー）
- POST 系は token + メソッド + Host/Origin チェックを通す。`/api/open-*` 等は loopback remote address を確認
- **Web Push 通知に Hub token を含めない**（§12.4）。push_store.json は perm 0o600、VAPID 秘密鍵を保護
- launcher は token / パスワード / パスフレーズを保存しない（§13）
- session raw log / jsonl / transcript / SQLite store / attach は機密情報として扱う
- reverse proxy / `0.0.0.0` bind / 認証なしのリモート公開は禁止

Outbound traffic:

- slash command sources / approval pattern sources / model defaults: GitHub raw
- Web Push: ブラウザが購読した push サービス（FCM 等）。token は送らない
- outbound 通知（任意設定時）: ユーザー設定の ntfy / webhook
- wrapped CLI traffic: Claude / Codex / Ollama 側の通常通信

`many-ai-cli` 自身は telemetry を送信しない。

### 21-1. WireGuard 運用（任意）

私設網経由で常駐 Hub に接続する場合の設計判断:

- WireGuard（日常用・UDP 51820）と SSH トンネル（fallback）の 2 系統を併存させ、どちらも撤去しない。`AllowedIPs = 10.8.0.0/24` のスプリットトンネルとし、フルトンネルにしない。
- Docker publish を `127.0.0.1:<PORT>:48000` と `10.8.0.1:<PORT>:48000` の 2 エントリに分ける。WireGuard 経路も SSH トンネル経路も publish 後は同一 gateway IP（例 `172.19.0.1`）として Hub に見えるため、`hub.trusted_networks` には `docker network inspect` で確認した実 gateway を `/32` で指定する（広い CIDR は禁止）。
- `wg0` が先に起動していないと `10.8.0.1` への bind に失敗するため `systemctl enable wg-quick@wg0` で boot 順を制御する。WireGuard サブネットのサーバー IP（例 `10.8.0.1`）は `hub.allowed_hosts` に追加して Host ヘッダー検証をパスさせる。

### 21-2. Windows 配布セキュリティ（署名なしビルド）

`many-ai-cli.exe` / `many-ai-cli-launcher.exe` は現時点で Authenticode コード署名なし（将来のコード署名導入を根本対策として留保）。Windows release zip には `unblock-windows.cmd` を同梱し、`Get-ChildItem -Filter 'many-ai-cli*.exe' | Unblock-File` で ZIP 展開時の Zone.Identifier（Mark-of-the-Web）を除去する。

- 解消できる: Mark-of-the-Web 起因のブロック、SmartScreen 警告（実行許可で回避可）
- 解消できない: Smart App Control による未署名アプリの完全ブロック、組織管理 PC の AppLocker / WDAC / EDR
- スクリプト設計制約: 管理者権限不要・`Set-ExecutionPolicy` 不使用・セキュリティ機能を無効化しない・対象は同梱 exe のみ。GoReleaser の Windows archive にのみ同梱し、非 Windows には含めない。winget / Scoop 配布は Smart App Control の根本解決にはならないが導入体験向上に有効。

## 22. 既知の注意点・保留

- `/api/files-delete-dir` は「空ディレクトリ削除」を意図する API だが、実装が `os.RemoveAll` を用いるため非空でも削除され得る点に注意（UI からは空 dir 削除導線のみ）。設計意図と実装の整合は要確認
- Wake word は実装痕跡があるが公開 UI では hidden / disabled
- Chat history は in-memory が主。SQLite からの復元は `/api/session-chat` で可能だが、完全な jsonl backfill は公開仕様外
- native Linux / macOS は build 対象だが十分な実機検証は未完了
- OpenCode は UI / config / usage-links に痕跡が残るが spawn 非対応（非公開）
- Cursor Agent の native approval パターンは実機での網羅検証が継続課題
- リモートサーバー SSH tunnel / Docker 運用では `/api/open-*`・`/api/pick-*` 等のローカルアプリ起動系は **Hub が動く側の OS**（リモートサーバー）で実行されるため、headless リモートサーバーでは失敗する。手元 PC のアプリを開く機能ではない
- remote-safe mode（reverse proxy + cookie 認証でブラウザから直接公開する方式）は v0.3.0 スコープ外。将来実装する場合は `hub.remote_mode` / `public_url` / `trusted_origins` / `workspaces` を追加し、bind は `127.0.0.1` を維持して TLS 公開は Caddy/nginx/Tailscale Funnel 等に委ね、URL token を無効化して Secure/HttpOnly/SameSite cookie + CSRF + rate limit + session revoke に置き換え、ローカルアプリ起動系 API を無効化し `/api/spawn` の cwd を `workspaces` 配下へ制限する方針が検討済み

## 23. 関連資料

- `CHANGELOG.md`（`[0.3.0] - 2026-06-13`）
- `README.md` / `README.ja.md`
- `docs/manual_release.md`（恒久リリース運用メモ）/ `docs/local/manual_release-v0-3-0_2026-06-13.md`（v0.3.0 実行チェックリスト）
- `.goreleaser.yaml`（全 OS 本体 + ランチャー / winget / Homebrew cask / nfpms deb・rpm / cosign / SBOM）・`.github/workflows/release.yml`
- `docs/v0.2.x-any-ai-cli-design.md`（前版設計書）
- `docs/manual_ollama-cloud-routing.md`
- `deploy/docker/`（Dockerfile / compose / aac-update.sh / sshd-member.conf.template）
- `.github/workflows/docker-image.yml`
- `internal/sessionstore/store.go` / `internal/hub/workbench_handlers.go` / `internal/hub/push.go` / `internal/launcher/`
- `docs/local/` の v0.3.0 plan 群（本書の設計レベル記述の追記元）: `plan_mobile-responsive-ui` / `plan_token-cost-statusbar` / `plan_claude-statusline-tokens` / `plan_statusbar-extra-segments` / `plan_voice-ios-whisper-relay`（+ c4/c5）/ `plan_unified-local-whisper-all-os` / `plan_remote-shared-dev-memory-sizing` / `manual_docker-multiuser` / `setup_wireguard-remote` / `plan_remote-remote-browser-mode` / `plan_remote-remote-ssh-tunnel-mvp` / `plan_launcher-connection-profiles_20260604221339` / `plan_sqlite-store-size-containment` / `plan_session-log-optin-and-legacy-reset` / `plan_chat-history-live-stream` / `plan_logs-attachments-purge` / `plan_v0-3-0-release-readiness-improvements_20260604115529` / `plan_windows_security_unblock`