[v0.1/SSH Review] SSH 周りリリース前設計レビュー — 親トラッキング（7件） #44

New issue

Closed

opened 2026-09-03 16:30:58 +09:00 by natsukium · 1 comment

natsukium commented

2026-09-03 16:30:58 +09:00

Owner

概要

1.0 リリースに向けて API / UI / その他（wire / config / docs / リリース契約）の整理中、今回は SSH 周りを重点的に横断レビューした。互換性を無視して破壊的変更可能な今のうちに、凍結前に設計を直すべき箇所を洗い出し、以下の 7 件に分割した。

本 issue は SSH レビューの親トラッキングとする。#11（1.0 Review 親 8件）と #12（v0.1 Tracker）は既存の release-readiness トラッキングであり、本 SSH レビューはその補足として SSH にフォーカスした論点を整理する。重複する論点（carrier 命名など）は #3 と相互参照。

分割 issue 一覧（SSH 重点）

#	タイトル	主な対象	1.0 での決定粒度
#37	--host フラグ名と URI/destination 表記の不一致	`Cli::host` / `Carrier::Ssh` / `proto` / `cli.md`	リネーム or 現行維持 + rationale 追記
#38	--ssh-arg のトークン分割 UX と ControlMaster 委譲	`relay_command` / `--ssh-arg` / `how-to/attach-over-ssh.md`	UX 改善 or 自動 ControlMaster or 凍結
#39	グローバル carrier と window retarget carrier の非対称	`Cli::host` vs `WindowOp::Retarget` / `control-surfaces.md`	エラーメッセージ/ docs 強化 or 統一 or alias 廃止
#40	SSH_AUTH_SOCK 間接化とエージェント可観測性の欠如	`<socket>.agent` symlink / `daemon status`	可観測性追加 or opt-in or 明示 verb
#41	macOS TMPDIR 非共有による daemon 二重起動	`local_socket::resolve_local_socket` / `TMPDIR`	`$HOME` 起点移行 or 警告 or 二重検出
#42	SSH stdio のタイムアウト/ハンドシェイク/スポーン方針の未統一	`RemoteSpawn` / `connect_carrier` / `doctor`	`--spawn` opt-in / タイムアウト / 構造化エラー
#43	retarget 経由の env_base 漏洩とリモート spawn の env 継承	`env_base::capture` / `FRLY` / `SpawnArgs`	allowlist / no-send / 警告

レビュー観点

互換性は無視 → 1.0 でしか変えられない「凍結」決定を洗い出す（本レビューは release 前の breakable window を前提）
1.0 で凍結するものは reference/* に normative として明記し、explanation/* に rationale と Revisit trigger を残す
追加は additive（#[serde(default)] / minor ledger）で読める契約を維持しつつ、キー名・名詞階層・wire 値自体は今しか変えられない
SSH は ~/.ssh/config / ssh 自体に委譲する部分と felis が持つべき部分の境界が曖昧になりやすいため、control surface の placement criterion（control-surfaces.md）に照らして判定

推奨進め方

各 issue で「凍結（現行維持）」か「1.0 で破壊的変更」かを決める。破壊的変更を選んだものは reference/* と explanation/* の twin を同時に更新し、just check / just schema / just proto を回す（implement-feature skill の手順）。
#41（TMPDIR）は socket パスを変えると既存セッションが orphan になるため、1.0 で最も優先度が高い。#37（命名）と合わせて最初に決める。
#40（agent）と #42（タイムアウト/スポーン）は daemon status / doctor の可観測性に影響するため、#26（daemon status resource scopes）や #14-#16（admission/backpressure）と合わせて整理すると docs の整合が取りやすい。
全 issue が closed したら CHANGELOG.md の Unreleased → v0.1 に凍結した SSH 契約（--host/--ssh-arg/--to-socket の意味、FRLY block、SSH_AUTH_SOCK 間接化、TMPDIR 既定）を明記。
#12 の P0/P1 が close したら本親も close。残った deferred は backlog.md または non-goals.md に昇格。

参考: レビューで使ったソース

crates/felis-cli/src/main.rs / conn.rs / cli_sessions.rs / cli_doctor.rs / cli_completions.rs
crates/felis-client/src/main.rs
crates/felis-client-core/src/connector.rs / dial.rs / env_base.rs / local_socket.rs
crates/felis-daemon/src/relay.rs / serve.rs / main.rs
crates/felis-protocol/proto/felis.proto / src/messages.rs / src/messages/session.rs / src/messages/ops.rs
crates/felis-transport/src/preface.rs / stdio.rs / local.rs
docs/reference/{cli,ipc,config,control-surfaces,terminal-identity}.md
docs/explanation/{architecture/ipc,architecture/daemon-client-split,architecture/session-lifecycle,architecture/control-surfaces,security-model}.md
docs/how-to/attach-over-ssh.md

cc @natsukium

## 概要 1.0 リリースに向けて API / UI / その他（wire / config / docs / リリース契約）の整理中、今回は **SSH 周り**を重点的に横断レビューした。互換性を無視して破壊的変更可能な今のうちに、凍結前に設計を直すべき箇所を洗い出し、以下の 7 件に分割した。本 issue は SSH レビューの親トラッキングとする。#11（1.0 Review 親 8件）と #12（v0.1 Tracker）は既存の release-readiness トラッキングであり、本 SSH レビューはその補足として SSH にフォーカスした論点を整理する。重複する論点（carrier 命名など）は #3 と相互参照。 ## 分割 issue 一覧（SSH 重点） | # | タイトル | 主な対象 | 1.0 での決定粒度 | |---|---|---|---| | #37 | --host フラグ名と URI/destination 表記の不一致 | `Cli::host` / `Carrier::Ssh` / `proto` / `cli.md` | リネーム or 現行維持 + rationale 追記 | | #38 | --ssh-arg のトークン分割 UX と ControlMaster 委譲 | `relay_command` / `--ssh-arg` / `how-to/attach-over-ssh.md` | UX 改善 or 自動 ControlMaster or 凍結 | | #39 | グローバル carrier と window retarget carrier の非対称 | `Cli::host` vs `WindowOp::Retarget` / `control-surfaces.md` | エラーメッセージ/ docs 強化 or 統一 or alias 廃止 | | #40 | SSH_AUTH_SOCK 間接化とエージェント可観測性の欠如 | `<socket>.agent` symlink / `daemon status` | 可観測性追加 or opt-in or 明示 verb | | #41 | macOS TMPDIR 非共有による daemon 二重起動 | `local_socket::resolve_local_socket` / `TMPDIR` | `$HOME` 起点移行 or 警告 or 二重検出 | | #42 | SSH stdio のタイムアウト/ハンドシェイク/スポーン方針の未統一 | `RemoteSpawn` / `connect_carrier` / `doctor` | `--spawn` opt-in / タイムアウト / 構造化エラー | | #43 | retarget 経由の env_base 漏洩とリモート spawn の env 継承 | `env_base::capture` / `FRLY` / `SpawnArgs` | allowlist / no-send / 警告 | ## レビュー観点 - 互換性は無視 → 1.0 でしか変えられない「凍結」決定を洗い出す（本レビューは release 前の breakable window を前提） - 1.0 で凍結するものは `reference/*` に normative として明記し、`explanation/*` に rationale と Revisit trigger を残す - 追加は additive（`#[serde(default)]` / minor ledger）で読める契約を維持しつつ、キー名・名詞階層・wire 値自体は今しか変えられない - SSH は `~/.ssh/config` / `ssh` 自体に委譲する部分と felis が持つべき部分の境界が曖昧になりやすいため、control surface の placement criterion（`control-surfaces.md`）に照らして判定 ## 推奨進め方 1. 各 issue で「凍結（現行維持）」か「1.0 で破壊的変更」かを決める。破壊的変更を選んだものは `reference/*` と `explanation/*` の twin を同時に更新し、`just check` / `just schema` / `just proto` を回す（`implement-feature` skill の手順）。 2. #41（TMPDIR）は socket パスを変えると既存セッションが orphan になるため、1.0 で最も優先度が高い。#37（命名）と合わせて最初に決める。 3. #40（agent）と #42（タイムアウト/スポーン）は `daemon status` / `doctor` の可観測性に影響するため、#26（daemon status resource scopes）や #14-#16（admission/backpressure）と合わせて整理すると docs の整合が取りやすい。 4. 全 issue が closed したら `CHANGELOG.md` の Unreleased → v0.1 に凍結した SSH 契約（`--host`/`--ssh-arg`/`--to-socket` の意味、`FRLY` block、`SSH_AUTH_SOCK` 間接化、`TMPDIR` 既定）を明記。 5. #12 の P0/P1 が close したら本親も close。残った deferred は `backlog.md` または `non-goals.md` に昇格。 ## 参考: レビューで使ったソース - `crates/felis-cli/src/main.rs` / `conn.rs` / `cli_sessions.rs` / `cli_doctor.rs` / `cli_completions.rs` - `crates/felis-client/src/main.rs` - `crates/felis-client-core/src/connector.rs` / `dial.rs` / `env_base.rs` / `local_socket.rs` - `crates/felis-daemon/src/relay.rs` / `serve.rs` / `main.rs` - `crates/felis-protocol/proto/felis.proto` / `src/messages.rs` / `src/messages/session.rs` / `src/messages/ops.rs` - `crates/felis-transport/src/preface.rs` / `stdio.rs` / `local.rs` - `docs/reference/{cli,ipc,config,control-surfaces,terminal-identity}.md` - `docs/explanation/{architecture/ipc,architecture/daemon-client-split,architecture/session-lifecycle,architecture/control-surfaces,security-model}.md` - `docs/how-to/attach-over-ssh.md` cc @natsukium

natsukium referenced this issue

2026-09-03 16:44:28 +09:00

[v0.1/Proto Review] Freeze protobuf and IPC contracts (7 issues) #52

natsukium commented

2026-09-03 16:57:50 +09:00

Author

Owner

The SSH review is now triaged into actionable owners, so this temporary parent can close. #37 and #39 are folded into #23; #38 and #40 retain the documented design with no new surface; #43 was based on an incorrect reading of the relay environment source; #41 is valid but deferred to post-v0.1/P2 because macOS is not a v0.1 supported target; and #42 is narrowed to the release-blocking local-only completion fix. #12 remains the release tracker, so a second SSH tracker would add no scheduling information.