bug(cli): forward start reports 'ssh exited before local forward listener opened' while the listener is live — and leaks an orphaned ssh mux holding the port #3738

Activity

1. github-actions

   added

   state:triage-neededOpened without agent diagnostics and needs triageOpened without agent diagnostics and needs triage

   on Sep 26, 2026
2. kvnloo commented on Sep 27, 2026

   

   kvnloo

   on Sep 27, 2026

   More actions

   I think the key invariant here should be stronger than fixing the readiness timing:

   forward start returning an error must leave no listener, child process, mux, or registry entry behind

   and:

   forward start returning success must leave exactly one tracked forward

   That gives us a clean lifecycle contract regardless of why readiness fails.

   For the regression I would force the race rather than rely on normal SSH timing:

   1. launch the SSH child;
   2. make listener detection miss/delay once;
   3. take the failure path;
   4. assert the child/mux is terminated and reaped;
   5. assert the port can immediately be rebound;
   6. assert forward list has no entry.

   Then separately test a slow-but-successful listener startup and make sure we don't kill a forward that became ready just before the deadline.

   That should prevent both false failure and invisible orphan variants.
3. drew

   added

   state:validated

   state:acceptedA maintainer decided OpenShell should pursue this issueA maintainer decided OpenShell should pursue this issue

   and removed

   state:triage-neededOpened without agent diagnostics and needs triageOpened without agent diagnostics and needs triage

   on Sep 28, 2026
4. drew commented on Sep 28, 2026

   

   drew

   on Sep 28, 2026

   Collaborator

   More actions

   🏗️ build-plan

   Implementation Plan

   Issue type: fix
   Complexity: Medium
   Confidence: High — reproduced against a local gateway with real OpenSSH

   Summary

   Make CLI-owned SSH forwards ignore user multiplexing and automatic backgrounding settings, so the spawned PID remains the listener owner. Reap the child on startup/tracking failures and ensure a background forward is still alive before writing its PID record.

   Scope

   • crates/openshell-cli/src/ssh.rs: add forward-only SSH options, tighten startup ownership checks, and await failed-child cleanup.
   • crates/openshell-cli/tests/sandbox_create_lifecycle_integration.rs: cover the affected forward startup and cleanup paths.
   • architecture/sandbox.md, docs/how-it-works/sandboxes/overview.mdx, and skills/openshell-cli/SKILL.md: document the forward lifecycle and SSH config boundary.

   Implementation Steps

   1. Build forward SSH commands with explicit multiplexing and forking overrides.
   2. Ensure startup errors and PID-record failures terminate and reap the owned SSH process; avoid tracking an exited process.
   3. Add regression coverage, then verify with the same real SSH configuration used to reproduce bug(cli): forward start reports 'ssh exited before local forward listener opened' while the listener is live — and leaks an orphaned ssh mux holding the port #3738.

   Test Plan

   • Unit tests: verify forward-only SSH options and child cleanup/ownership decisions.
   • Integration tests: exercise successful background tracking and startup failure cleanup using the CLI test gateway.
   • E2E tests: manually rerun the reproduced local Podman gateway workflow with real OpenSSH; no e2e/ fixture changes planned.

   Risks & Open Questions

   • A user SSH config can alter other SSH behaviors; this fix targets process ownership for port forwarding without changing normal connect/exec/editor behavior. A port probe alone does not prove socket ownership, so the spawned child's liveness must be checked before tracking.
   • Foreground forwards are intentionally not in the local registry. The comment's “exactly one tracked forward” success contract applies to background mode.

   Documentation Impact

   Update the existing architecture overview, sandbox port-forwarding guide, and CLI skill. No gateway TOML or driver configuration changes.

   ---

   Revision 1 — initial plan
5. drew commented on Sep 28, 2026

   

   drew

   on Sep 28, 2026

   Collaborator

   More actions

   🏗️ build-from-issue-agent

   Implemented the SSH forward ownership fix in #3759. CLI forwards now override user SSH multiplexing and automatic forking settings, clean up failed child processes, and only accept a listener while the spawned SSH process is still running. A regression test checks the effective OpenSSH configuration. Linux gateway smoke testing confirmed foreground and background forwards stay live without leaving a mux socket.

   mise run pre-commit, mise run test, and the CLI forward integration tests passed. The full mise run ci was attempted, but its Go gateway tests see this host's existing /etc/openshell/gateways/default and fail their isolated fixture expectations; mise run go:lint passed after clearing a stale cache.
6. drew

   closed this as completedin #3759on Sep 28, 2026