[1.0 Review] session id / env var / lifecycle 用語の凍結 #6

New issue

Closed

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

natsukium commented

2026-09-03 16:03:27 +09:00

Owner

背景

session は daemon が所有し、client は attach/detach で借りる。explanation/architecture/session-lifecycle.md に attach additive（same-user mirroring）、post-exit grace（5s）、FELIS_SESSION_ID / FELIS_SOCKET の stamping、cross-carrier re-dial が仕様化されている。id は 32 hex 桁（u128）で short_id は表示用の最短一意 prefix（floor 8桁）。

現状の問題 / 凍結前に決めるべき点

1. session id 表現

32 hex（128bit）は衝突耐性が高いが、人間が読むには冗長。short_id の動的 prefix で緩和しているが、prefix は roster 依存で保存不可（docs/reference/cli.md で警告）。tmux の %3 のような短い stable handle を持たないのは、handle 再利用の危険を避ける意図。
代替: ULID / UUIDv7（時系列順、26文字 Crockford base32）。hex より短く、生成順が roster 順と一致する利点。ただし wire 上 bytes(16) → string 変換、log の既存 hex 記法、$FELIS_SESSION_ID の互換を全て壊す。今しか変えられない。

問い: 1.0 で u128 hex を凍結するか、ULID 等への移行を今検討するか？現行の「hex は wire / log / env / docs で一つの綴り」という一貫性は強い。

2. prefix resolution の所在

現行は daemon-side で id_prefix → ResolvedId::{Ok, NoMatch, Ambiguous{count}} に解決。client-side で list 取得→ローカル match する案は「2 round-trip + race」で却下されている。1.0 でこの daemon-side 解決を凍結として明記すべき。Ambiguous が count のみで候補 id を返さないのも、情報漏洩を避ける設計だが、UX として候補提示が欲しくなる余地はあるか。

3. `kill` vs `destroy` vs `evict` vs `detach` の用語

wire: OpsMsg::Destroy / Detached / PushMsg::Evicted / SessionMsg::Detach
CLI: sessions kill / evict
keymap: kill_session / detach

kill は Unix プロセス由来、destroy はオブジェクトライフサイクル由来。control-surfaces.md に命名規則の記録はあるが、1.0 で CLI を destroy に改名する破壊的統一の是非は今しか議論できない（現状 kill は tmux kill-session との類推で選ばれている）。

4. `switch` / `retarget` の scope

Default（last window input owner or sole window）/ Attachment(id) / All の3 scope と、--from <prefix> の from-session 指定。accepted は outbox 受理数で landing 保証しない（acceptance, not landing）。denied は resolve-time のみ。

1.0 で accepted を「window が land した」まで拡張する operation_id + landed/failed の追跡を導入するか、現行の acceptance 止まりで凍結するか。explanation/architecture/ipc.md の「Acceptance, not landing」は defer 決定だが、1.0 で defer を維持するか再評価。

5. 環境変数の surface

FELIS_SESSION_ID（32 hex, 全 spawn で強制）
FELIS_SOCKET（daemon endpoint, --socket 優先, FELIS_SESSION_ID と同様に scrub/deny 対象, REQ-912）
FELIS_HOST / FELIS_ORIGIN_SESSION_ID / FELIS_CWD（pipe/run transient の origin context）
FELIS_TERM / FELIS_TERM_PROGRAM（terminal identity hatch, daemon 環境からの読み出し）

FELIS_SOCKET は window retarget が global --host/--socket を拒否する代わりに FELIS_SOCKET を読むことで「non-default socket の window からでも retarget 可能」にしている。FELIS_HOST は transient が remote かどうかを判定するために使う。

問い: 1.0 で env var の命名を FELIS_* で凍結するか？ FELIX 的な typo 耐性、XDG との衝突は無いか。FELIS_TERM が TERM を override する hatch であることを reference/terminal-identity.md でより強調すべき。

6. 暗黙の auto-spawn ポリシー

connect_or_spawn_daemon が felis-client-core にあり、sessions spawn と window launch は auto-spawn、sessions list 等は --no-spawn（relay では relay --no-spawn）で cold socket を exit 2 にする。control-surfaces.md の「A session verb never spawns...」は意図的。1.0 でこの「spawn する verb だけが daemon を起こす」線引きを変える余地は無いか。

提案

session id の hex / short_id floor 8 / never-reuse / daemon-side prefix 解決を reference/cli.md と reference/ipc.md で「1.0 凍結」として明記し、将来の ULID 移行は explanation/architecture/session-lifecycle.md に Revisit trigger として記録。
kill/destroy 用語を 1.0 で統一しないなら、control-surfaces.md の命名規則表に「なぜ CLI は kill で wire は Destroy か」を残し、CLI を destroy に alias 追加する案は却下として記録（alias は永続の互換負債になるため）。
env var 一覧を reference/terminal-identity.md に normative table として凍結し、各 var の生成元（daemon stamp vs relay carrier block vs client SpawnArgs.env）を明記。

判定基準

新しい session 操作 verb を追加する際に、id prefix 解決・scope 解決・accepted 報告の既存パターンに一意に収まること。
FELIS_* を知らない shell script が、誤って FELIS_SESSION_ID を上書きしてしまう事故を SpawnArgs.env の deny で防げること（REQ-912）。

cc @natsukium

## 背景 session は daemon が所有し、client は attach/detach で借りる。`explanation/architecture/session-lifecycle.md` に attach additive（same-user mirroring）、post-exit grace（5s）、`FELIS_SESSION_ID` / `FELIS_SOCKET` の stamping、cross-carrier re-dial が仕様化されている。id は 32 hex 桁（`u128`）で `short_id` は表示用の最短一意 prefix（floor 8桁）。 ## 現状の問題 / 凍結前に決めるべき点 ### 1. session id 表現 - 32 hex（128bit）は衝突耐性が高いが、人間が読むには冗長。`short_id` の動的 prefix で緩和しているが、prefix は roster 依存で保存不可（`docs/reference/cli.md` で警告）。tmux の `%3` のような短い stable handle を持たないのは、handle 再利用の危険を避ける意図。 - 代替: ULID / UUIDv7（時系列順、26文字 Crockford base32）。hex より短く、生成順が roster 順と一致する利点。ただし wire 上 `bytes(16)` → string 変換、log の既存 hex 記法、`$FELIS_SESSION_ID` の互換を全て壊す。今しか変えられない。 **問い:** 1.0 で `u128` hex を凍結するか、ULID 等への移行を今検討するか？現行の「hex は wire / log / env / docs で一つの綴り」という一貫性は強い。 ### 2. prefix resolution の所在現行は daemon-side で `id_prefix` → `ResolvedId::{Ok, NoMatch, Ambiguous{count}}` に解決。client-side で `list` 取得→ローカル match する案は「2 round-trip + race」で却下されている。1.0 でこの daemon-side 解決を凍結として明記すべき。`Ambiguous` が count のみで候補 id を返さないのも、情報漏洩を避ける設計だが、UX として候補提示が欲しくなる余地はあるか。 ### 3. `kill` vs `destroy` vs `evict` vs `detach` の用語 - wire: `OpsMsg::Destroy` / `Detached` / `PushMsg::Evicted` / `SessionMsg::Detach` - CLI: `sessions kill` / `evict` - keymap: `kill_session` / `detach` `kill` は Unix プロセス由来、`destroy` はオブジェクトライフサイクル由来。`control-surfaces.md` に命名規則の記録はあるが、1.0 で CLI を `destroy` に改名する破壊的統一の是非は今しか議論できない（現状 `kill` は `tmux kill-session` との類推で選ばれている）。 ### 4. `switch` / `retarget` の scope `Default`（last window input owner or sole window）/ `Attachment(id)` / `All` の3 scope と、`--from <prefix>` の from-session 指定。`accepted` は outbox 受理数で landing 保証しない（acceptance, not landing）。`denied` は resolve-time のみ。 1.0 で `accepted` を「window が land した」まで拡張する `operation_id` + `landed/failed` の追跡を導入するか、現行の acceptance 止まりで凍結するか。`explanation/architecture/ipc.md` の「Acceptance, not landing」は defer 決定だが、1.0 で defer を維持するか再評価。 ### 5. 環境変数の surface - `FELIS_SESSION_ID`（32 hex, 全 spawn で強制） - `FELIS_SOCKET`（daemon endpoint, `--socket` 優先, `FELIS_SESSION_ID` と同様に scrub/deny 対象, REQ-912） - `FELIS_HOST` / `FELIS_ORIGIN_SESSION_ID` / `FELIS_CWD`（`pipe`/`run` transient の origin context） - `FELIS_TERM` / `FELIS_TERM_PROGRAM`（terminal identity hatch, daemon 環境からの読み出し） `FELIS_SOCKET` は `window retarget` が global `--host/--socket` を拒否する代わりに `FELIS_SOCKET` を読むことで「non-default socket の window からでも retarget 可能」にしている。`FELIS_HOST` は transient が remote かどうかを判定するために使う。 **問い:** 1.0 で env var の命名を `FELIS_*` で凍結するか？ `FELIX` 的な typo 耐性、`XDG` との衝突は無いか。`FELIS_TERM` が `TERM` を override する hatch であることを `reference/terminal-identity.md` でより強調すべき。 ### 6. 暗黙の auto-spawn ポリシー `connect_or_spawn_daemon` が `felis-client-core` にあり、`sessions spawn` と window launch は auto-spawn、`sessions list` 等は `--no-spawn`（relay では `relay --no-spawn`）で cold socket を `exit 2` にする。`control-surfaces.md` の「A session verb never spawns...」は意図的。1.0 でこの「spawn する verb だけが daemon を起こす」線引きを変える余地は無いか。 ## 提案 - session id の hex / `short_id` floor 8 / never-reuse / daemon-side prefix 解決を `reference/cli.md` と `reference/ipc.md` で「1.0 凍結」として明記し、将来の ULID 移行は `explanation/architecture/session-lifecycle.md` に Revisit trigger として記録。 - `kill`/`destroy` 用語を 1.0 で統一しないなら、`control-surfaces.md` の命名規則表に「なぜ CLI は `kill` で wire は `Destroy` か」を残し、CLI を `destroy` に alias 追加する案は却下として記録（alias は永続の互換負債になるため）。 - env var 一覧を `reference/terminal-identity.md` に normative table として凍結し、各 var の生成元（daemon stamp vs relay carrier block vs client `SpawnArgs.env`）を明記。 ## 判定基準 - 新しい session 操作 verb を追加する際に、id prefix 解決・scope 解決・`accepted` 報告の既存パターンに一意に収まること。 - `FELIS_*` を知らない shell script が、誤って `FELIS_SESSION_ID` を上書きしてしまう事故を `SpawnArgs.env` の deny で防げること（REQ-912）。 cc @natsukium

natsukium referenced this issue

2026-09-03 16:05:02 +09:00

[1.0 Review] リリース前設計レビュー — 親トラッキング（8件） #11

natsukium referenced this issue

2026-09-03 16:18:03 +09:00

[v0.1/P1] Move detached spawn to correlated Ops and make create atomic #20

natsukium referenced this issue

2026-09-03 16:18:04 +09:00

[v0.1/P1] Close on shell exit and reconnect the same session after transport loss #22

natsukium referenced this issue

2026-09-03 16:18:05 +09:00

[v0.1/P1] Track retarget completion with operation IDs #24

natsukium commented

2026-09-03 16:19:13 +09:00

Author

Owner

Superseded by #20, #22, and #24. The later review retained the session-id/environment model and split the remaining spawn, lifecycle, and retarget-completion changes under #12.