feat(snapshot,status): スナップショットのグループ対応と可視化・ドキュメント (PLAN39 PR4)

[takemi-ohama]

Pull Request

概要

PLAN39 の 4 本目。スナップショットの対象を 2 ボリュームに広げ、いま自分がどの
アカウントグループにいるのかを devbase status と起動ログで分かるようにします。
あわせてボリューム構造まわりのドキュメントを新しい構成へ更新します。

PR1〜PR3 で「認証と会話ログをグループ側へ分ける」仕組みは動きますが、この PR が無いと
グループボリュームがバックアップされず、また利用者が自分のグループを確認する手段が
ありません。

関連 Issue

• Refs feat: 永続化ボリュームをアカウントグループ単位に分離し、gcloud/gws の認証情報を永続化する #116
• release PR: release: PLAN39 永続化ボリュームをアカウントグループ単位に分離する #122 / 前の PR: feat(gcp): 設定ディレクトリをグループ単位にし GCP_AUTH_MODE を新設する (PLAN39 PR3) #125

変更点

スナップショット（Task 6 / AC9）

対象が devbase_home_ubuntu 固定から「共通 + 解決されたグループ」の 2 本になります。
1 つのアーカイブにまとめるため、コンテナ内では /source/ai と /source/group に
並べてマウントします。

メタデータ	意味
volumes: {ai: devbase_home_ubuntu, group: devbase_home_kkg}	PLAN39 以降。サブディレクトリ名 → ボリューム名
volume: devbase_home_ubuntu	PLAN39 以前。共通ボリュームをルートへ直接マウントする旧レイアウト

旧スナップショットはそのまま復元できます。 復元時は作成時の解決結果ではなく
スナップショット自身のメタデータを見るため、別グループのスナップショットを
取り違えることもありません。

対象ボリュームの構成が変わったとき（PLAN39 への移行、グループ切替）は
新しい世代を作ります。旧世代の snapshot.snar は別のレイアウトを記録しており、
そこへ差分を積むと全ファイルが移動したものとして扱われて差分が壊れるためです。
世代を分ければ旧世代はそのまま復元できます。構成の違う世代を明示的に指定された場合は、
黙って壊れた差分を積まず理由を出して止めます。

復元前のクリアは各マウントの直下を消します。マウントポイント自身は busy で消せません。

devbase snapshot list に対象ボリュームの列を足しました。

可視化（Task 7 / AC10）

devbase status の [環境] セクションに解決結果を出します。

[環境]
  devbase/.env            42変数 (最終更新: 2026-08-29)
  アカウントグループ          default (devbase_home_default / 既定)

末尾は値が env 由来か未設定によるフォールバックかを示します。グループ名が不正でも
例外にせず「(設定エラー)」として表示に留めます。status は状態を見るコマンドであり、
設定の誤りで一覧全体を出せなくする必要はないためです。

entrypoint の起動ログにも 1 行出します。

Account group: kkg (gcloud account: someone@kk-generation.com, CLOUDSDK_CONFIG: /persistent/group/gcloud)

entrypoint.sh は set -e で動くため、未ログインで gcloud が非 0 を返しても
gcloud を含まないイメージでも起動を落とさないようフォールバックします。

ドキュメント

• docs/user/container-operations.md — ボリューム構造の表（3 種類）、「アカウントグループ」節、
  AI 設定の永続化を 2 層構成へ、初回シードの説明、起動ログ
• docs/user/environment-variables.md — DEVBASE_ACCOUNT_GROUP の節
• docs/user/snapshot-guide.md — 対象ボリューム、list の出力例、世代分割の説明
• docs/plugin-dev/compose-yml-guidelines.md / quickstart.md — 標準ボリュームの表
• README.md / CHANGELOG.md

やらないこと（スコープ外）

• Google 認証の手順書 docs/user/google-auth.md — PR5。本 PR のドキュメントから
  リンクしていますが実体は PR5 で追加するため、release ブランチ内では PR5 の merge まで
  リンク切れです

満たす受け入れ条件

• AC9: スナップショットが共通・グループ両方を対象にし、復元できる（旧世代の互換を含む）
• AC10: devbase status に解決されたアカウントグループが表示される

影響と互換性

• 既存スナップショットは復元可能です（旧レイアウトとして扱われます）
• 初回の devbase up では対象ボリュームの構成が変わるため新しい世代が作られます
• 起動ログの追加のため base イメージの再ビルドが必要です（PR2 / PR3 と同じ）

動作確認

• uv run pytest が green
• bash -n containers/base/entrypoint.sh が pass
• devbase status の表示を実機で確認
• スナップショットの作成・復元の実機確認は release PR でまとめて実施

🤖 Generated with Claude Code

https://claude.ai/code/session_01S5oA2PqY6UX2Ca3t78886t

[takemi-ohama]

🤖 cross-review | round 1 | codex | APPROVE

差分内に修正が必要な問題はありません。

[takemi-ohama]

🤖 cross-review | round 1 | gemini | APPROVE

設計・実装ともに PLAN39 の要件を適切に満たしており、問題ありません。