release: pre-release audit tracker for security, interaction, compatibility, and documentation blockers

[richard950825-sys]

Summary

This issue tracks the current pre-release audit status for Hermes Gate after the product definition, issue severities, and current resolution path were clarified in follow-up owner comments and a GUIDE-focused documentation pass.

Updated audit baseline: Hermes Gate is evaluated as a temporary local client for reconnecting to durable remote tmux / Hermes sessions. Under that model, several originally filed concerns are no longer treated as release blockers, and the current release-alignment work is focused primarily on making the shipped behavior and supported contract explicit in GUIDE.md for both human readers and AI agents.

This umbrella issue is intentionally a tracker, not the place for detailed fix discussion. Detailed evidence, reproduction notes, implementation debate, and resolution work belong in the linked child issues and their follow-up PRs.

Updated audit baseline

Current audit and release-readiness judgments are based on the following product model:

• Hermes Gate is a temporary local client, not a continuously resident local workspace manager
• Quitting the local TUI / container does not imply the remote tmux / Hermes session stops
• Reconnect means launching a fresh local client and reattaching to the durable remote session
• Once Gate enters attached state, the experience is primarily native tmux / Hermes behavior, not a thick Gate-owned viewer layer

Under this baseline:

• local lifecycle semantics are less central than in the original audit
• the most important remaining release-alignment questions are the supported remote launch/session contract and the compatibility boundary it implies
• attached-state wording should match the actual Option B-style implementation on current main
• the current first-step resolution path is a GUIDE-only clarification pass that keeps the original onboarding structure while making the shipped behavior and assumptions explicit for both users and future agents

Current priority items

Contract / documentation alignment in progress

• blocker: define the supported remote Hermes launch/session contract explicitly for stable release #20 — supported remote Hermes launch/session contract clarification; current resolution path is to document the shipped remote model explicitly in GUIDE.md
• blocker: clarify attached-state input ownership across Gate, tmux, and Hermes #21 — attached-state ownership clarification; current resolution path is to align GUIDE.md with the current Option B implementation on main

Compatibility boundary expected to downgrade with clearer docs

• compatibility: remote command execution assumes bash-based login shells on target systems #13 — remote command execution assumes bash-based login shells on target systems; expected to narrow materially once GUIDE.md states this assumption explicitly

Reclassified by owner comments

The original audit issue list is preserved for history, but several items have been explicitly reclassified after review of newer code and owner comments.

• interaction: attach flow mutates remote tmux configuration and cannot reliably restore user state #10 — interaction: owner marked this as a future enhancement, not a current release blocker
• blocker: use secure SSH host-key verification defaults for the temporary local client control path #22 — SSH host-key policy concern is better treated as security-hardening / policy clarification; current resolution path is to document the shipped StrictHostKeyChecking=accept-new behavior in GUIDE.md
• lifecycle: start.sh stops the container on normal exit and breaks detach-and-return workflows #11 — lifecycle: no longer treated as a release blocker after the product was clarified as a temporary local client
• security: stop disabling SSH host key verification by default #9 — the original SSH-blocker framing is no longer the canonical one for current main; later discussion and blocker: use secure SSH host-key verification defaults for the temporary local client control path #22 reflect the updated facts more accurately
• documentation: README and GUIDE overstate reconnect, detach, and zero-config behavior relative to the implementation #15 — the original broad docs-overstatement concern has effectively been split into more precise follow-up issues, especially blocker: define the supported remote Hermes launch/session contract explicitly for stable release #20 and blocker: clarify attached-state input ownership across Gate, tmux, and Hermes #21

Current resolution path

A GUIDE-only clarification PR is being used as the first alignment step because the remaining issues are currently more about making the shipped contract explicit than about changing runtime behavior.

That GUIDE pass is intended to:

• clarify the temporary-local-client lifecycle
• clarify attached-state ownership as native tmux / Hermes behavior
• document the current bash-based login-shell and PATH assumptions
• document the current SSH host-trust behavior based on StrictHostKeyChecking=accept-new
• make the shipped contract easier for both humans and future agents to interpret without over-inferring unsupported capabilities

README repositioning, broader wording cleanup, and any further behavior changes can follow later if needed.

Release recommendation

Current recommendation: do not call the project fully release-aligned until the shipped behavior and supported remote contract are documented clearly enough for both users and future agents, or the remaining scope is explicitly accepted with rationale.

Under the updated temporary-client baseline and current docs-first approach, the main remaining release-alignment questions are:

• whether the supported remote Hermes launch/session contract is explicit enough for a stable release
• whether the current compatibility boundary (especially shell assumptions) is stated clearly enough for users and future contributors
• whether docs / help text describe attached-state ownership honestly enough for users to form correct expectations

Definition of done for this umbrella issue

This tracker can be closed when:

• the remaining contract / docs-alignment issues are resolved, explicitly deferred with owner rationale, or removed from release scope
• attached-state docs / help text match the actual attached-state ownership model on current main
• the supported remote environment / launch contract is stated clearly enough for users and future contributors to test against the same expectations
• required manual validation has been performed for any interaction-heavy changes that remain in release scope

Notes for implementers and agents

When addressing these issues, please keep the following bar:

• do not evaluate Hermes Gate as if it promised a continuously resident local runtime unless the product definition changes again
• do not use wording that implies Gate owns attached-state controls if the implementation is native tmux attach
• do not treat StrictHostKeyChecking=accept-new as equivalent to disabling host-key verification entirely
• do not close compatibility concerns without stating the supported environment / shell contract clearly
• when updating docs, prefer stable terminology and explicit assumptions so both humans and future agents derive the same behavior expectations from the repository

Linked issue map

Current alignment items

• blocker: define the supported remote Hermes launch/session contract explicitly for stable release #20 — supported remote contract clarification
• blocker: clarify attached-state input ownership across Gate, tmux, and Hermes #21 — attached-state ownership clarification
• compatibility: remote command execution assumes bash-based login shells on target systems #13 — compatibility boundary clarification expected to narrow after GUIDE updates

Reclassified from the original audit

• interaction: attach flow mutates remote tmux configuration and cannot reliably restore user state #10 — future enhancement, not a current release blocker
• blocker: use secure SSH host-key verification defaults for the temporary local client control path #22 — security-hardening / policy clarification, now on a docs-first path
• lifecycle: start.sh stops the container on normal exit and breaks detach-and-return workflows #11 — lifecycle concern downgraded under the temporary-local-client baseline
• security: stop disabling SSH host key verification by default #9 — superseded as the umbrella’s canonical SSH blocker framing
• documentation: README and GUIDE overstate reconnect, detach, and zero-config behavior relative to the implementation #15 — split into more precise release-alignment issues