feat(editor): Remote-SSH 跨ホストの attach 対応 + up 時のターミナル自動表示 (PLAN31_3)

Windows VS Code → Remote-SSH(Mac) → Mac の Docker 上コンテナ、という構成で
devbase up の自動オープンが「コンテナが存在しません」で失敗する問題を修正。
実機検証の結果、ネスト authority attached-container+...@ssh-remote+<host> は
実際にサポートされており、これを使うと docker ルックアップが ssh 先(コンテナの
ある側)で行われ解決できる(PLAN31_3 §2.3/§2.4 の当初想定を訂正)。

- build_attach_uri に ssh_host / docker_context を追加しネスト URI を生成
- DEVBASE_EDITOR_SSH_HOST(明示) / DEVBASE_EDITOR_DOCKER_CONTEXT(既定 docker context show)
  ※ ssh ホスト別名は VS Code が ssh 先端末 env に渡さず自動取得不可のため明示必須
- DEVBASE_OPEN_TERMINAL(既定 ON): up 時に folderOpen タスク .vscode/tasks.json を
  docker exec で配置し、フォルダを開くと統合ターミナルを自動表示(既存はスキップ)
- CLI: --open-terminal / --no-open-terminal を追加
- docs / PLAN31_3 を実態へ更新、テスト追加

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: takemi-ohama

docs/user/environment-variables.md

@@ -149,20 +149,48 @@ devbase はホストマシンの認証情報を自動収集し、コンテナ内
 | `DEVBASE_OPEN_EDITOR` | 真（`1`/`true`/`yes`/`on`）で `up` 後にエディタを開く（既定: OFF） |
 | `DEVBASE_EDITOR` | 起動コマンド（既定: `code`）。`cursor` / `code-insiders` 等も可 |
 | `DEVBASE_OPEN_INDEX` | scale 時に開く dev インスタンス番号（既定: `1`） |
+| `DEVBASE_EDITOR_SSH_HOST` | Remote-SSH 跨ホスト構成での ssh-remote ホスト名（例 `mac2`）。下記「跨ホスト」参照 |
+| `DEVBASE_EDITOR_DOCKER_CONTEXT` | 跨ホスト時に ssh 先で使う docker context（既定: ホストの `docker context show`） |
+| `DEVBASE_OPEN_TERMINAL` | 真で `up` 後に folderOpen ターミナル用 `.vscode/tasks.json` を配置（**既定: ON**） |
 
-都度の上書きは CLI フラグで行います: `devbase up --open` / `devbase up --no-open` / `devbase up --open-index N`（env より優先）。
+都度の上書きは CLI フラグで行います: `devbase up --open` / `--no-open` / `--open-index N` / `--open-terminal` / `--no-open-terminal`（env より優先）。
+
+### 起動時に統合ターミナルを自動表示（`DEVBASE_OPEN_TERMINAL`）
+
+`up` 時に、開く dev コンテナのワークスペース（`/work/$GIT_REPO`）へ folderOpen タスク（`.vscode/tasks.json`）を `docker exec` で配置します（既存があれば変更しません）。VS Code はフォルダを開いた時にこのタスクで統合ターミナルを前面表示します。
+
+VS Code 公式には「起動時にターミナルを開く」専用設定が無く、folderOpen タスクが唯一の方法です。なお自動実行には次の 2 つの **VS Code クライアント側ユーザー設定**が関わり、devbase からは制御できません（いずれも application/user スコープ専用）:
+
+- **Workspace Trust**: 信頼していないフォルダではタスクは自動実行されません（初回は「フォルダを信頼」が必要）。
+- **`task.allowAutomaticTasks`**: 既定 `off` ではフォルダごとに 1 回「自動タスクを許可」を尋ねます。`on` にするとプロンプト無しで実行されます。
+
+→ 実際は「初回のみ信頼（＋許可）クリック、以降は自動でターミナルが開く」挙動になります。無効化は `DEVBASE_OPEN_TERMINAL=0` または `devbase up --no-open-terminal`。
 
 ### 実行コンテキスト別の挙動
 
 | コンテキスト | 挙動 |
 |------|------|
 | ローカル端末（Mac/Linux） | ローカル VS Code が開く |
 | WSL 端末 | Windows 側 VS Code が開く（`code` ラッパ経由） |
-| VS Code の Remote-SSH 統合ターミナル | **クライアント側（手元）の VS Code** が開く（`code` シムが委譲） |
+| VS Code の Remote-SSH 統合ターミナル（同一ホストの Docker） | **クライアント側（手元）の VS Code** が開く（`code` シムが委譲） |
+| VS Code の Remote-SSH 統合ターミナル（**跨ホスト**: ssh 先の Docker にコンテナ） | `DEVBASE_EDITOR_SSH_HOST` 設定時にネスト URI で開く（下記「跨ホスト」参照） |
 | 手元から素の SSH（VS Code 外）で接続中 | クライアントへ自動で開く公式手段が無いため、手元で実行する `code --folder-uri ...` コマンドを提示 |
 | CI / 非対話（非 TTY） / `code` 不在 | 理由を表示してスキップ（`up` 自体は成功） |
 
-> SSH 越しに「手元の VS Code」を自動で開きたい場合は、手元の VS Code から **Remote-SSH で接続した統合ターミナル内**で `devbase up` を実行してください。そのターミナルの `code` はクライアント側 VS Code に委譲するため、リモートホスト上のコンテナへ接続した窓が手元に開きます。
+#### 跨ホスト（Windows VS Code → Remote-SSH → Mac のコンテナ）
+
+手元（例 Windows）の VS Code から Remote-SSH で別ホスト（例 Mac）へ入り、その統合ターミナルで `devbase up` を実行する構成では、コンテナは **ssh 先（Mac）の Docker** 上にあります。このとき `code` の開く要求はクライアント（Windows）へ委譲されるため、フラットな attach URI のままだと **クライアント側の Docker** を見に行きコンテナが見つかりません（「コンテナーにアタッチできません。すでに存在しません」）。
+
+これを解決するには、ssh-remote ホスト名（手元 `~/.ssh/config` の `Host` 別名。VS Code はこの別名を ssh 先の端末 env に渡さないため自動取得不可）を明示します:
+
+```sh
+# $DEVBASE_ROOT/env など（全プロジェクト共通にしたい場合）
+DEVBASE_EDITOR_SSH_HOST=mac2
+```
+
+これで devbase は `vscode-remote://attached-container+<hex>@ssh-remote+mac2/work/...`（必要に応じ payload に `settings.context` を埋める）というネスト URI を生成し、docker ルックアップが ssh 先（コンテナのある Mac）で行われて正しくアタッチします。docker context は `docker context show` から自動取得し、`DEVBASE_EDITOR_DOCKER_CONTEXT` で上書きできます。
+
+> 同一ホスト構成（手元 Mac/Linux で直接、または ssh 先の Docker にコンテナが無い場合）では `DEVBASE_EDITOR_SSH_HOST` は不要で、従来どおりフラット URI で開きます。
 
 ## ソースファイル変更検出
 

issues/PLAN31_3_up-open-editor.md

@@ -41,24 +41,41 @@ vscode-remote://attached-container+<hex>/work/$GIT_REPO
 `<hex>` は **`{"containerName":"/<実コンテナ名>"}` を UTF-8 hex 化**した文字列。
 （単純な名前の hex ではない点に注意。Docker 内部のコンテナ名は先頭 `/` 付き。）
 
-### 2.3 ネスト authority は公式未サポート
+### 2.3 ネスト authority（**実機で動作することを確認・当初想定を訂正**）
 
-`ssh-remote+<host>` と `attached-container+...` を 1 本の URI に合成する記法は
-**存在しない**（microsoft/vscode#242489 は *Closed as not planned*）。
-→ 「リモートホスト上のコンテナ」を単発 `code` で直接指定する手段は無い。
+> ⚠️ 訂正（2026-06-13 実装時の実機検証）。当初は「合成記法は存在しない
+> （microsoft/vscode#242489 *not planned*）」と記載していたが、**誤り**だった。
+
+`attached-container+<hex>@ssh-remote+<host>` という**ネスト authority は実際に
+サポートされており動作する**（VS Code 1.124.2 / Dev Containers 0.459.1 で確認）。
+正常動作中の窓の resource URI を採取したところ:
+
+```
+vscode-remote://attached-container+<hex>@ssh-remote+mac2/work/...
+hex = {"containerName":"/<name>","settings":{"context":"desktop-linux"}}
+```
+
+`@ssh-remote+<host>` を付けると docker ルックアップが **ssh 先（コンテナのある
+ホスト）** で行われるため、跨ホスト（手元 Windows VS Code → ssh → Mac のコンテナ）
+でも単発 `code --folder-uri` で直接アタッチできる。`settings.context` は ssh 先で
+使う docker context を指定する。
 
 ### 2.4 結論（実行コンテキスト別マトリクス）
 
 | コンテキスト | 自動オープン | 機構 / 根拠 |
 |---|---|---|
 | Mac/Linux ローカル端末 | ✓ | ローカル `code` が attach URI を解決 |
 | WSL 端末 | ✓ (Windows VS Code) | `code` ラッパ→`code.exe`、Docker Desktop のコンテナへ attach |
-| VS Code **Remote-SSH 統合端末**（リモート=Mac） | ✓ (クライアント側) | `code` シム + `VSCODE_IPC_HOOK_CLI`。シムは既にクライアントへ接続済みなのでネスト URI 不要で attached-container を解決し、**クライアント(Windows)に窓が開く** |
-| plain SSH（WSL→ssh→Mac 等、VS Code 外） | ✗ → コマンド表示 | IPC hook 無し。公式にクライアントへ push 不可（§2.3）。手元で叩く `code` コマンドを提示するのが上限 |
+| VS Code **Remote-SSH 統合端末**（リモート=Mac・**同一ホストの Docker**） | ✓ (クライアント側) | `code` シムが委譲。同一ホストの Docker にコンテナがある場合はフラット URI で解決 |
+| VS Code **Remote-SSH 統合端末**（**跨ホスト**: ssh 先 Mac の Docker にコンテナ） | ✓ (要 `DEVBASE_EDITOR_SSH_HOST`) | フラット URI だとクライアント(Windows)の Docker を見て失敗。**ネスト URI `@ssh-remote+<host>`（§2.3）で ssh 先の Docker を解決**。ssh ホスト名は env から取得不可のため明示設定が要る |
+| plain SSH（WSL→ssh→Mac 等、VS Code 外） | ✗ → コマンド表示 | IPC hook 無し。手元で叩く `code` コマンドを提示するのが上限 |
 | CI / 非TTY / `code` 不在 | ✗ → info スキップ | エディタ起動の前提を満たさない |
 
-→ ユーザ理想チェーンは **「手元 VS Code で Remote-SSH→Mac に入った統合ターミナルで
-`devbase up`」の場合に自動成立**。plain ssh の場合は正直にコマンド提示で degrade する。
+→ 跨ホスト（手元 Windows VS Code → Remote-SSH→Mac で `devbase up`、コンテナは Mac の
+Docker）が最頻ユースケース。**`DEVBASE_EDITOR_SSH_HOST`（例 `mac2`）の設定で自動成立**。
+ssh ホスト名（クライアント `~/.ssh/config` の Host 別名）は VS Code が ssh 先端末 env に
+渡さない（`SSH_CONNECTION` は IP のみ）ため自動取得できず、明示が必須（実機調査で確認）。
+plain ssh はコマンド提示で degrade。
 
 ## 3. 既存コード調査結果
 
@@ -156,12 +173,19 @@ env 解釈は既存 `_parse_env_assignment`（`container.py:121`）に合わせ
   `--no-open`/`DEVBASE_OPEN_EDITOR=0` で呼ばれないこと
 - 既存 706 passed を維持
 
-## 8. リスク・未確定
-
-- **plain SSH では自動オープン不可**（§2.3 公式未サポート）。コマンド提示で degrade。
-  この制約は README に明記する
-- VS Code Remote-SSH 統合端末でのクライアント側 attach は実機検証が必要
-  （`/ndf:investigation-rules`: 実機未検証の挙動は「推定」と明示）
+## 8. リスク・未確定（実機検証で更新）
+
+- ~~VS Code Remote-SSH 統合端末でのクライアント側 attach は実機検証が必要~~
+  → **検証済み（2026-06-13）**。跨ホストではフラット URI だと失敗し、ネスト URI
+  `@ssh-remote+<host>` + `settings.context` で成立することを確認（§2.3/§2.4 を訂正）。
+- ssh ホスト名（`DEVBASE_EDITOR_SSH_HOST`）は env 自動取得不可のため**ユーザ明示が前提**。
+  未設定の跨ホストではフラット URI にフォールバックし、従来同様アタッチ失敗ダイアログが出る
+  （実害は無いが体験は劣化）。`$DEVBASE_ROOT/env` への 1 行設定を案内する。
+- **plain SSH（VS Code 外）では自動オープン不可**。コマンド提示で degrade（変更なし）。
+- 統合ターミナル自動表示は `.vscode/tasks.json`(folderOpen) 配置で実現。VS Code 公式に
+  起動時ターミナル設定は無く（`hideOnStartup` は復元セッションの表示制御のみ）folderOpen
+  が唯一。自動実行は Workspace Trust と `task.allowAutomaticTasks`（共に user スコープ専用・
+  devbase 制御外）に依存し、初回のみ承認クリックが要る。
 - `code` ラッパの非ブロッキング起動が `up` プロセス終了をブロックしないこと確認
 
 ## 9. 参考（一次情報）

lib/devbase/cli.py

@@ -112,6 +112,13 @@ def _add_open_args(parser):
     parser.add_argument('--open-index', dest='open_index', type=int, default=None,
                         metavar='N',
                         help='Container index to open (default: 1)')
+    parser.add_argument('--open-terminal', dest='open_terminal', action='store_true',
+                        default=None,
+                        help='Place .vscode/tasks.json so the integrated terminal '
+                             'auto-opens on folder open (overrides DEVBASE_OPEN_TERMINAL)')
+    parser.add_argument('--no-open-terminal', dest='open_terminal', action='store_false',
+                        help='Do not place the folderOpen terminal tasks.json '
+                             '(overrides DEVBASE_OPEN_TERMINAL)')
     return parser
 
 

lib/devbase/commands/container.py

@@ -290,7 +290,8 @@ def _dispatch_lifecycle(args) -> int:
         'up':    lambda: cmd_up(project_name=project_name,
                                 scale=getattr(args, 'scale', None),
                                 open_editor=getattr(args, 'open_editor', None),
-                                open_index=getattr(args, 'open_index', None)),
+                                open_index=getattr(args, 'open_index', None),
+                                open_terminal=getattr(args, 'open_terminal', None)),
         'down':  lambda: cmd_down(),
         'login': lambda: cmd_login(index=getattr(args, 'index', '1')),
         'ps':    lambda: cmd_ps(all_containers=getattr(args, 'all', False)),
@@ -412,9 +413,72 @@ def _maybe_open_editor(project_name: str, open_flag: Optional[bool],
         logger.warning("エディタの自動オープンに失敗しましたがデプロイは成功しています: %s", e)
 
 
+def _maybe_place_terminal_task(project_name: str, open_flag: Optional[bool],
+                               open_index: Optional[int], scale: int,
+                               compose_file=None) -> None:
+    """`up` 後、開く dev コンテナの作業ディレクトリへ folderOpen ターミナル tasks.json を配置。
+
+    フォルダを開いた時に統合ターミナルを自動表示するための ``.vscode/tasks.json`` を、
+    対象 dev インスタンスのワークスペース (``/work/$GIT_REPO``) に置く。作業ディレクトリは
+    コンテナ内 (named volume) のためホストから直接書けず、起動済みコンテナへ ``docker exec``
+    で書き込む。**既存の ``.vscode/tasks.json`` があれば一切触らない**。
+
+    有効判定は ``open_flag`` (CLI ``--open-terminal``/``--no-open-terminal``) が優先、None なら
+    env ``DEVBASE_OPEN_TERMINAL`` (既定 ON)。配置失敗は warning に握り潰し ``up`` を倒さない。
+    ``open_index`` は開くインスタンスに合わせる (範囲外は 1 へフォールバック)。
+    """
+    from devbase.editor import opener
+
+    enabled = open_flag if open_flag is not None else opener.is_open_terminal_enabled()
+    if not enabled:
+        return
+
+    if open_index is None:
+        raw = os.environ.get('DEVBASE_OPEN_INDEX')
+        try:
+            open_index = int(raw) if raw else 1
+        except ValueError:
+            open_index = 1
+    if not (1 <= open_index <= scale):
+        open_index = 1
+
+    if compose_file is None and _SCALE_COMPOSE_FILE.exists():
+        compose_file = _SCALE_COMPOSE_FILE
+
+    dev_service_name = get_dev_service_name()
+    container = opener.resolve_container_name(dev_service_name, project_name,
+                                              open_index, compose_file=compose_file)
+    workdir = opener.resolve_workdir(os.environ, project_name)
+    content = opener.build_folder_open_tasks_json()
+
+    # 既存があれば書かず、無ければ stdin から書き込む (冪等)。workdir は引数で渡し
+    # シェル内クォートを避ける ($1)。
+    script = (
+        'set -e; d="$1/.vscode"; mkdir -p "$d"; '
+        'if [ -e "$d/tasks.json" ]; then echo keep; '
+        'else cat > "$d/tasks.json"; echo placed; fi'
+    )
+    try:
+        proc = subprocess.run(
+            ["docker", "exec", "-i", container, "sh", "-c", script, "_", workdir],
+            input=content, text=True, capture_output=True, timeout=15,
+        )
+    except Exception as e:  # noqa: BLE001 - 配置失敗で up を倒さない
+        logger.warning("ターミナル用 tasks.json の配置に失敗しましたが続行します: %s", e)
+        return
+    if proc.returncode != 0:
+        logger.warning("ターミナル用 tasks.json の配置に失敗しましたが続行します: %s",
+                       (proc.stderr or "").strip())
+        return
+    if (proc.stdout or "").strip() == "placed":
+        logger.info("[6/6] 統合ターミナル自動表示用 tasks.json を配置: %s/.vscode/tasks.json",
+                    workdir)
+
+
 def cmd_up(project_name: str = None, scale: int = None,
            open_editor: Optional[bool] = None,
-           open_index: Optional[int] = None) -> int:
+           open_index: Optional[int] = None,
+           open_terminal: Optional[bool] = None) -> int:
     """Deploy containers with specified scale"""
     if project_name is None:
         project_name = get_project_name()
@@ -481,6 +545,9 @@ def cmd_up(project_name: str = None, scale: int = None,
         if deploy_script.exists() and deploy_script.is_file():
             _run_deploy_script_for_instances(deploy_script, range(1, scale + 1))
 
+        # エディタを開く前に tasks.json を置く (開いた瞬間に folderOpen が効くように)。
+        _maybe_place_terminal_task(project_name, open_terminal, open_index, scale,
+                                   compose_file=override_file)
         _maybe_open_editor(project_name, open_editor, open_index, scale,
                            compose_file=override_file)