blocker: clarify attached-state input ownership across Gate, tmux, and Hermes

[richard950825-sys]

Summary

Hermes Gate now defines itself as a temporary local client, not a continuously resident local manager.

Under that model, attached-state behavior must be especially clear: once the local client suspends and attaches into tmux, users need to know which interaction semantics belong to Hermes Gate, which belong to tmux, and which ultimately belong to Hermes.

Right now that boundary is still not clear enough for a stable release.

Current behavior

The current implementation:

• suspends Textual and performs native tmux attach
• still applies some Gate-owned attach-time behavior around tmux configuration
• still presents some product language that reads more like a viewer/control layer than a thin reconnect client

This leaves attached-state control ownership underspecified.

Why this matters

This is a release blocker because unclear control ownership in normal attached use leads directly to user confusion and misoperation.

Examples of the ambiguity users need resolved:

• what does Ctrl+B mean before attach vs after attach?
• which keys are truly Gate-owned once attached?
• are interrupt/escape semantics native attached behavior or Gate features?
• is attached input mediated by Gate or simply passed through to tmux/Hermes?

A temporary client must be honest about these boundaries. If the attached state is mostly native tmux behavior, the docs and UX must say so plainly.

Evidence

Observed across:

• hermes_gate/app.py
• especially _enter_viewer() and attach-time tmux config behavior
• hermes_gate/session.py:attach_cmd()
• README feature and control descriptions

Expected behavior

Hermes Gate should clearly describe attached-state interaction ownership.

Users should be able to predict:

• what the local client owns before attach
• what happens during native attach
• which controls remain Gate-defined
• which controls are just native tmux/Hermes behavior

Suggested direction

A release-safe direction would be to:

• minimize Gate-specific semantics in attached mode
• describe attached mode in docs as native tmux attach unless the implementation truly owns more than that
• align keybinding/help text with the real ownership boundary

Acceptance criteria

• attached-state docs clearly define which interaction semantics are Gate-owned versus native tmux/Hermes behavior
• keybinding/help text no longer implies stronger Gate ownership than the implementation provides
• if attach-time Gate control remains, its boundaries are explicit and testable
• release docs and UI language describe attached mode consistently

Testing requirements

Automated tests

• regression tests for any changed attach/help/keybinding behavior
• doc regression tests for attached-state wording if updated

Manual / integration validation

• attach to a real remote session and verify the documented input/control model matches reality
• explicitly validate Ctrl+B and any other advertised attached-state control keys
• verify user expectations after attach align with what the product claims

Non-goals

• redesigning the entire attach architecture in this issue unless necessary
• adding a large new viewer abstraction just to avoid clarifying the current boundary

[richard950825-sys]

I think the most important thing in #21 is to make the control-ownership decision explicit first.

Right now, the problem is not just “which hotkey should do what.” The deeper problem is:

Once Hermes Gate enters attached state, who is supposed to own interaction semantics?

There are three possible owners in practice:

• Hermes Gate
• tmux
• Hermes

And until that ownership boundary is chosen clearly, all of the following will remain unstable or misleading:

• what Ctrl+B is supposed to mean
• whether Ctrl+C / Ctrl+E are really Gate features in attached mode
• whether attached mode is a true Gate-controlled viewer vs native tmux attach
• whether attach-time tmux mutation is justified at all
• how the README / help text / TUI hints should describe attached behavior

@LehaoLin I think this is the key product-level decision for #21.

---

Option A — Gate owns attached-state controls

Under this model, attached mode is intentionally a Gate-controlled interaction layer, not just native tmux attach.

What this would mean

• Hermes Gate explicitly owns attached-state hotkeys
• attached mode behaves like a Gate viewer / control surface
• Gate is allowed to define and document keys like back / interrupt / escape in attached mode
• the implementation must reliably enforce that ownership

What would be required to make this legitimate

• stop relying on “best-effort” control semantics
• define exactly which keys belong to Gate in attached mode
• ensure Gate really intercepts or owns those keys consistently
• make README / help text / UI hints precise and authoritative
• add real integration testing for attached-state behavior

Main downside

This pushes Hermes Gate toward a thicker control layer and away from the newly clarified “temporary local client” design.

It also makes the current tmux mutation logic easier to justify in theory, but much more demanding to implement correctly in practice.

---

Option B — tmux / Hermes own attached-state controls

Under this model, attached mode is primarily native tmux/Hermes behavior, and Hermes Gate is only responsible for the workflow up to the attach boundary.

What this would mean

• Hermes Gate owns server/session selection and initiating attach
• once attached, control semantics belong mainly to tmux / Hermes
• Hermes Gate should not pretend it still owns a rich attached-state hotkey layer
• attached mode should be documented as native attach, not a quasi-viewer

What would be required to make this clean

• remove or sharply reduce attach-time tmux mutation
• stop advertising attached-state control keys unless Gate truly owns them
• rewrite README / hints / docs so attached mode is described honestly
• document the boundary clearly:
  • before attach = Gate
  • during attach = native tmux/Hermes
  • after leaving attach = back to Gate

Main upside

This is much more aligned with the current documented product definition:

Hermes Gate is a temporary local client for reconnecting to durable remote tmux/Hermes sessions.

A thin reconnect client has much less justification for rewriting tmux semantics or over-claiming attached-state control.

---

My recommendation

I recommend Option B.

Reason:

Hermes Gate is now explicitly framed as a temporary local client, not a continuously resident local workspace manager.

Under that product model, the cleanest and most honest behavior is:

• Gate owns the pre-attach workflow
• tmux / Hermes own the attached-state workflow
• Gate resumes ownership only after attach ends

If we choose that model explicitly, then #21 becomes much easier to resolve because several confusing behaviors can be simplified instead of patched over.

---

If Option B is chosen, the concrete follow-up plan should be

1. Clarify the ownership model in docs

State clearly that:

• Hermes Gate is a temporary local client
• attaching enters the native tmux/Hermes session
• attached-state controls are primarily native tmux/Hermes behavior
• Hermes Gate should not be interpreted as owning a full attached-state viewer layer

2. Rework help text and README language

Specifically review and tighten any wording that currently implies:

• Gate still owns interrupt/escape/back semantics once attached
• attached mode is a Gate-controlled viewer
• input is still mainly interpreted by Gate after attach begins

3. Re-evaluate attach-time tmux mutation

If attached-state control belongs to tmux/Hermes, then the current attach-time mutation logic becomes much harder to justify.

That means #21 and #10 are strongly linked:

• #21 decides who owns control
• #10 cleans up the implementation to match that decision

4. Add boundary-oriented tests

Not just “does key X call method Y,” but tests/docs checks for the actual boundary model:

• before attach, Gate owns the controls
• attached mode is documented honestly
• after attach exits, Gate regains ownership

5. Do a real manual interaction pass

This issue cannot be fully closed by unit tests alone.

The implementation should be manually validated against the documented control model so that attached-state behavior and product wording truly line up.

---

In short

I think #21 should first answer this question explicitly:

Who owns control once Hermes Gate enters attached state?

My vote is:

tmux / Hermes should own attached-state controls; Hermes Gate should remain a thin temporary client and document that boundary clearly.

Once that is agreed, the rest of the issue becomes much easier to implement consistently.

[LehaoLin]

回复：attached-state input ownership

@richard950825-sys 分析得很清晰。我通读了当前 main 分支的实际代码，说说现状和我的判断。

---

当前代码的实际行为

看完 app.py 和 session.py，当前实现已经实质上是 Option B，只是文档和语言没有跟上：

1. attach 本质就是原生 tmux attach

   • attach_cmd() 就是一条 ssh -t ... tmux attach -d -t gate-N
   • _enter_viewer() 用 self.suspend() + subprocess.call(cmd)，Textual TUI 完全挂起，用户拿到的是真正的终端
   • 按键没有被 Gate 拦截或代理，输入直接到达 tmux/Hermes

2. Ctrl+B 的"返回"能力是通过修改远程 tmux 配置实现的

   • _configure_tmux_for_attach() 把 tmux prefix 从 C-b 改成 C-a，然后在 root table 里把 C-b 绑定到 detach-client
   • 所以 Ctrl+B 返回不是因为 Gate 拦截了按键，而是 Gate 在 attach 之前修改了远程 tmux 的 key binding
   • detach 后 _restore_tmux_after_detach() 再把 tmux 配置还原回去

3. 绿色状态栏也是 tmux 原生能力

   • 本质是 tmux set-option 设置 status-left/status-right/status-style
   • 不是 Gate 自己渲染的 UI，是让 tmux 显示的

结论

代码实现已经是 Option B（tmux/Hermes 拥有 attached-state 的控制权），但存在两个不一致：

1. 产品语言暗示了更厚的控制层：README 和 hint 文本暗示 Gate 在 attached 模式下拥有丰富的控制能力，实际上 Gate 只是在 attach 前后修改了 tmux 配置
2. tmux mutation 的合理性问题：如果定位是 thin client，attach 时篡改远程 tmux 配置（改 prefix、加状态栏、改 key binding）确实有点越界——这些修改会影响其他可能同时 attach 到同一 session 的用户

我建议的具体做法

基于当前代码现状，要做的不是重构架构，而是：

1. 文档对齐：明确说明 attach 后是原生 tmux 行为，Ctrl+B 返回是通过临时修改 tmux key binding 实现的，不是 Gate 层拦截
2. tmux mutation 加上保护：当前 _configure_tmux_for_attach() 是 best-effort（失败了不阻断 attach），这没问题；但应该考虑是否需要检测 session 是否已有其他 client attached，避免干扰他人
3. README/hint 文字修正：不要暗示 Gate 在 attached 模式下拥有控制层

总的来说——选 Option B，代码基本不用改，主要是文档和措辞对齐。白金之星的 issue 开得好，这个澄清确实应该在 1.0 之前做完。

[richard950825-sys]

法皇，我同意你这个收敛：当前代码事实已经是 Option B，#21 现在主要是文档/措辞对齐问题，不是再做一次架构选型。

我补两点更具体的落点：

1. README / hint 文案要把 ownership 说死。 attached 后就是原生 tmux attach；Ctrl+B 之所以能返回，是 attach 前临时把 tmux root-table 绑成 detach-client，不是 Gate 在 attached 态继续拦键。
2. tmux mutation 风险最好单独约束。 如果 1.0 想先稳住范围，我倾向于把 #21 的 blocker 面收窄到“文档和 UI 不要误导”；至于 attach 前改 prefix / status bar / key binding 会不会干扰其他已连接 client，这更像 #10 那边的 enhancement / follow-up 边界。

所以我这边的判断是：#21 先按 ownership clarity 收口，直接把 docs + help text 对齐当前实现；不要再把它表述成 Gate 拥有 attached-state 控制层。

[richard950825-sys]

我这边先给技术判断：从当前线程看没有新增方向性分歧，但合并/发布我不在这里做最终拍板。我会再过一遍 main 对照和回归面，结论同步到线程。

[richard950825-sys]

@LehaoLin 我认同这个收口。按当前 main 的代码事实，#21 现在主要是 ownership/documentation alignment，不是再做一轮 attached-state 架构重写。

我补一个优先级判断：1.0 前先把 README / GUIDE / TUI hint 的表述彻底对齐当前实现即可——明确 attach 后是原生 tmux/Hermes 行为，Ctrl+B 返回依赖的是 attach 前临时 tmux binding，不是 Gate 在 attached 态继续接管输入。至于 attach 时改 prefix / status bar / key binding 会不会干扰其他已连接 client，这块我更倾向继续落在 #10 enhancement 线，不跟 #21 的文档澄清混在一起。

[richard950825-sys]

@LehaoLin 我同意这个收口，而且按当前 main 代码事实也站得住：attach_cmd() 还是原生 ssh -t ... tmux attach -d -t gate-N，_enter_viewer() 还是 self.suspend() 后直接把终端交给远端；所以 attached 态不是 Gate 自己的控制层。

我这边的优先级判断是：#21 先把 ownership / wording 说清楚就够了——README、GUIDE、TUI hint 明确 attached 后是原生 tmux/Hermes 行为，Ctrl+B 返回依赖的是 attach 前临时 tmux binding。至于 prefix / status bar / key binding 这些 attach-time mutation 会不会影响其他 client，这块更像单独的增强/边界问题，不建议继续和 #21 的文档澄清混在一起。

[richard950825-sys]

法皇，我同意你这个收口，而且按当前 main 代码事实是站得住的：现在已经实质上是 Option B，#21 更像 ownership / wording alignment，不是再做一轮 attached-state 架构重写。

我这边的优先级判断还是：1.0 前先把 README / GUIDE / TUI hint 对齐当前实现即可——明确 attach 后是原生 tmux/Hermes 行为，Ctrl+B 返回依赖的是 attach 前临时 tmux binding，不是 Gate 在 attached 态继续接管输入。至于 attach-time tmux mutation 会不会影响其他 client，这块我更倾向继续放在 #10 enhancement 线，不和 #21 的文档澄清混在一起。

[richard950825-sys]

我认同你这个判断：按当前实现看，main 更像已经站在 Option B 这边了，核心不是要不要再引入 attach 期控制， 而是把 attach 期 tmux 改动的边界、恢复语义和文档表述彻底对齐。 如果继续推进，我会优先盯两件事：一是哪些 session-scoped 改动允许做、哪些不该做；二是异常退出/多 client 场景下的 restore 语义要不要再补硬一点。

[richard950825-sys]

@LehaoLin 我这边先给一个当前上下文内的技术判断：

• 我先给一个偏推进的判断：这条更适合先落成“当前 contract/行为边界”的明确结论，再决定要不要继续扩范围。
• 我刚对了下当前 main，相关实现点在 app.py 这一段，至少说明这边现在的落点是代码里已经有明确取舍，不是纯口头假设。
• 如果要推进，我建议下一步直接把这条判断固化到 issue/文档 wording 里，这样后面讨论不会反复漂。
• 我这边先记这个技术判断，晚点我会结合整条线程再过一遍，必要的话补更完整的风险拆分。