fix: tighten session resolution for ssh workflows

Author: acmore

docs/quickstart.md

@@ -141,8 +141,9 @@ okdev resolves the target cluster in this order:
 ## SSH Details
 
 - SSH connects to the `dev` container via `okdev-sshd` on port 2222.
-- Tmux is enabled by default with a built-in okdev profile (history, mouse, vi-copy, status bar) using the standard `Ctrl-b` prefix.
-- Use `okdev ssh --no-tmux` to bypass tmux for a single connection, or set `spec.ssh.persistentSession: false` to disable it globally.
+- `okdev ssh` uses tmux by default with a built-in okdev profile (history, mouse, vi-copy, status bar) using the standard `Ctrl-b` prefix.
+- The generated `ssh okdev-<session>` host entry bypasses tmux by default for a plain shell.
+- Use `okdev ssh --no-tmux` to bypass tmux for a single `okdev ssh` connection, or set `spec.ssh.persistentSession: false` to disable it globally.
 - The managed SSH host entry uses tight proxy keepalive settings so hung sessions fail fast instead of freezing.
 - Tune keepalive with `spec.ssh.keepAliveIntervalSeconds` (default `30`) and `spec.ssh.keepAliveTimeoutSeconds` (default `90`, must be >= interval).
 - Proxy diagnostics are written to `~/.okdev/logs/okdev.log`, not the SSH session.

docs/troubleshooting.md

@@ -29,8 +29,9 @@
 - Run `okdev ssh --setup-key` at least once per key pair.
 - If local bind conflicts occur, use `okdev ssh --local-port <port>`.
 - Verify the managed entry exists in `~/.ssh/config`: `Host okdev-<session>`.
-- For tmux-enabled sessions, use interactive TTY mode: `okdev ssh` or `ssh -tt okdev-<session>`.
-- To bypass tmux for one connection, use `okdev ssh --no-tmux`.
+- For tmux-enabled sessions, use interactive TTY mode with `okdev ssh`.
+- `ssh okdev-<session>` opens a plain shell by default.
+- To bypass tmux for one `okdev ssh` connection, use `okdev ssh --no-tmux`.
 - For unstable links, increase `spec.ssh.keepAliveIntervalSeconds` and `spec.ssh.keepAliveTimeoutSeconds`.
 - If `ssh okdev-<session>` exits after a long stall, inspect `~/.okdev/logs/okdev.log` for proxy health events such as port-forward degradation or idle watchdog disconnects.
 - Managed proxy sessions are designed to fail closed and return control to the local terminal rather than hang indefinitely on a dead port-forward.

internal/cli/common.go

@@ -209,31 +209,75 @@ func isTerminalFD(v any) bool {
 	return term.IsTerminal(int(f.Fd()))
 }
 
-func resolveSessionName(opts *Options, cfg *config.DevEnvironment) (string, error) {
-	return session.Resolve(opts.Session, cfg.Spec.Session.DefaultNameTemplate)
+// applySessionArg uses the first positional argument as the session name
+// when --session was not explicitly provided.
+func applySessionArg(opts *Options, args []string) {
+	if len(args) > 0 && strings.TrimSpace(args[0]) != "" && strings.TrimSpace(opts.Session) == "" {
+		opts.Session = args[0]
+	}
+}
+
+func resolveSessionName(opts *Options, cfg *config.DevEnvironment, namespace string) (string, error) {
+	return resolveSessionNameWithState(opts, cfg, namespace, true)
 }
 
 func resolveSessionNameForUpDown(opts *Options, cfg *config.DevEnvironment, namespace string) (string, error) {
+	return resolveSessionNameWithState(opts, cfg, namespace, true)
+}
+
+func resolveSessionNameWithState(opts *Options, cfg *config.DevEnvironment, namespace string, inferExisting bool) (string, error) {
+	return resolveSessionNameWithReader(opts, cfg, namespace, inferExisting, newKubeClient(opts))
+}
+
+func resolveSessionNameWithReader(opts *Options, cfg *config.DevEnvironment, namespace string, inferExisting bool, reader sessionAccessReader) (string, error) {
 	if strings.TrimSpace(opts.Session) != "" {
-		return resolveSessionName(opts, cfg)
+		return session.Resolve(opts.Session, cfg.Spec.Session.DefaultNameTemplate)
 	}
 	active, err := session.LoadActiveSession()
 	if err != nil {
 		return "", err
 	}
 	if strings.TrimSpace(active) != "" {
-		return session.Resolve(active, cfg.Spec.Session.DefaultNameTemplate)
-	}
-	inferred, err := inferExistingSessionForRepo(opts, cfg, namespace)
-	if err != nil {
-		return "", err
+		resolvedActive, err := session.Resolve(active, cfg.Spec.Session.DefaultNameTemplate)
+		if err != nil {
+			return "", err
+		}
+		exists, existsErr := sessionPodExists(reader, namespace, resolvedActive)
+		if existsErr == nil {
+			if exists {
+				return resolvedActive, nil
+			}
+			_ = session.ClearActiveSession()
+		} else {
+			slog.Debug("failed to verify active session pod", "session", resolvedActive, "namespace", namespace, "error", existsErr)
+			return resolvedActive, nil
+		}
 	}
-	if strings.TrimSpace(inferred) != "" {
-		return inferred, nil
+	if inferExisting {
+		inferred, err := inferExistingSessionForRepo(opts, cfg, namespace)
+		if err != nil {
+			return "", err
+		}
+		if strings.TrimSpace(inferred) != "" {
+			return inferred, nil
+		}
 	}
 	return session.Resolve("", cfg.Spec.Session.DefaultNameTemplate)
 }
 
+func sessionPodExists(k sessionAccessReader, namespace, sessionName string) (bool, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	_, err := k.GetPodSummary(ctx, namespace, podName(sessionName))
+	if err == nil {
+		return true, nil
+	}
+	if apierrors.IsNotFound(err) {
+		return false, nil
+	}
+	return false, err
+}
+
 func inferExistingSessionForRepo(opts *Options, cfg *config.DevEnvironment, namespace string) (string, error) {
 	root, err := session.RepoRoot()
 	if err != nil || strings.TrimSpace(root) == "" {
@@ -417,11 +461,26 @@ func isSessionShareable(p kube.PodSummary) bool {
 }
 
 func ensureSessionOwnership(opts *Options, k *kube.Client, namespace, sessionName string, allowShareable bool) error {
+	return ensureSessionAccess(opts, k, namespace, sessionName, allowShareable, false)
+}
+
+func ensureExistingSessionOwnership(opts *Options, k *kube.Client, namespace, sessionName string, allowShareable bool) error {
+	return ensureSessionAccess(opts, k, namespace, sessionName, allowShareable, true)
+}
+
+type sessionAccessReader interface {
+	GetPodSummary(context.Context, string, string) (*kube.PodSummary, error)
+}
+
+func ensureSessionAccess(opts *Options, k sessionAccessReader, namespace, sessionName string, allowShareable bool, requireExisting bool) error {
 	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
 	defer cancel()
 	pod, err := k.GetPodSummary(ctx, namespace, podName(sessionName))
 	if err != nil {
 		if apierrors.IsNotFound(err) {
+			if requireExisting {
+				return fmt.Errorf("session %q does not exist in namespace %q", sessionName, namespace)
+			}
 			return nil
 		}
 		return err

internal/cli/connect.go

@@ -12,19 +12,21 @@ func newConnectCmd(opts *Options) *cobra.Command {
 	var noTTY bool
 
 	cmd := &cobra.Command{
-		Use:   "connect",
+		Use:   "connect [session]",
 		Short: "Open shell or run command in session pod",
+		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
+			applySessionArg(opts, args)
 			cfg, ns, err := loadConfigAndNamespace(opts)
 			if err != nil {
 				return err
 			}
-			sn, err := resolveSessionName(opts, cfg)
+			sn, err := resolveSessionName(opts, cfg, ns)
 			if err != nil {
 				return err
 			}
 			k := newKubeClient(opts)
-			if err := ensureSessionOwnership(opts, k, ns, sn, true); err != nil {
+			if err := ensureExistingSessionOwnership(opts, k, ns, sn, true); err != nil {
 				return err
 			}
 			stopMaintenance := startSessionMaintenance(opts, cfg, ns, sn, cmd.OutOrStdout(), true, true)

internal/cli/ports.go

@@ -27,7 +27,7 @@ func newPortsCmd(opts *Options) *cobra.Command {
 				return err
 			}
 			k := newKubeClient(opts)
-			if err := ensureSessionOwnership(opts, k, ns, sn, true); err != nil {
+			if err := ensureExistingSessionOwnership(opts, k, ns, sn, true); err != nil {
 				return err
 			}
 			effectiveSSHPort := sshPort

internal/cli/session_access_test.go

@@ -0,0 +1,120 @@
+package cli
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/acmore/okdev/internal/config"
+	"github.com/acmore/okdev/internal/kube"
+	"github.com/acmore/okdev/internal/session"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+)
+
+type fakeSessionAccessReader struct {
+	pod *kube.PodSummary
+	err error
+}
+
+func (f fakeSessionAccessReader) GetPodSummary(_ context.Context, _, _ string) (*kube.PodSummary, error) {
+	if f.err != nil {
+		return nil, f.err
+	}
+	return f.pod, nil
+}
+
+func TestEnsureSessionAccessRequiresExistingSessionWhenRequested(t *testing.T) {
+	err := ensureSessionAccess(&Options{}, fakeSessionAccessReader{
+		err: apierrors.NewNotFound(schema.GroupResource{Group: "", Resource: "pods"}, "okdev-old"),
+	}, "default", "old", true, true)
+	if err == nil || !strings.Contains(err.Error(), `session "old" does not exist in namespace "default"`) {
+		t.Fatalf("expected missing session error, got %v", err)
+	}
+}
+
+func TestEnsureSessionAccessAllowsMissingSessionWhenNotRequired(t *testing.T) {
+	err := ensureSessionAccess(&Options{}, fakeSessionAccessReader{
+		err: apierrors.NewNotFound(schema.GroupResource{Group: "", Resource: "pods"}, "okdev-old"),
+	}, "default", "old", true, false)
+	if err != nil {
+		t.Fatalf("expected missing session to be allowed, got %v", err)
+	}
+}
+
+func TestEnsureSessionAccessRejectsOtherOwner(t *testing.T) {
+	t.Setenv("USER", "alice")
+	err := ensureSessionAccess(&Options{}, fakeSessionAccessReader{
+		pod: &kube.PodSummary{
+			Labels: map[string]string{
+				"okdev.io/owner":     "bob",
+				"okdev.io/shareable": "false",
+			},
+			Annotations: map[string]string{},
+		},
+	}, "default", "team", false, true)
+	if err == nil || !strings.Contains(err.Error(), `session "team" is owned by "bob"`) {
+		t.Fatalf("expected owner mismatch error, got %v", err)
+	}
+}
+
+func TestEnsureSessionAccessAllowsShareableOtherOwner(t *testing.T) {
+	t.Setenv("USER", "alice")
+	err := ensureSessionAccess(&Options{}, fakeSessionAccessReader{
+		pod: &kube.PodSummary{
+			Labels: map[string]string{
+				"okdev.io/owner":     "bob",
+				"okdev.io/shareable": "true",
+			},
+			Annotations: map[string]string{
+				"okdev.io/shareable": "true",
+			},
+		},
+	}, "default", "team", true, true)
+	if err != nil {
+		t.Fatalf("expected shareable session to be allowed, got %v", err)
+	}
+}
+
+func TestEnsureSessionAccessAllowsCurrentOwner(t *testing.T) {
+	t.Setenv("USER", "alice")
+	err := ensureSessionAccess(&Options{}, fakeSessionAccessReader{
+		pod: &kube.PodSummary{
+			Labels: map[string]string{
+				"okdev.io/owner": "alice",
+			},
+			Annotations: map[string]string{},
+		},
+	}, "default", "team", false, true)
+	if err != nil {
+		t.Fatalf("expected current owner to be allowed, got %v", err)
+	}
+}
+
+func TestResolveSessionNameWithReaderIgnoresStaleActiveSession(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	if err := session.SaveActiveSession("old-session"); err != nil {
+		t.Fatalf("SaveActiveSession: %v", err)
+	}
+
+	cfg := &config.DevEnvironment{}
+	cfg.Spec.Session.DefaultNameTemplate = "fresh-session"
+
+	got, err := resolveSessionNameWithReader(&Options{}, cfg, "default", false, fakeSessionAccessReader{
+		err: apierrors.NewNotFound(schema.GroupResource{Group: "", Resource: "pods"}, "okdev-old-session"),
+	})
+	if err != nil {
+		t.Fatalf("resolveSessionNameWithReader: %v", err)
+	}
+	if got != "fresh-session" {
+		t.Fatalf("expected stale active session to be ignored, got %q", got)
+	}
+
+	active, err := session.LoadActiveSession()
+	if err != nil {
+		t.Fatalf("LoadActiveSession: %v", err)
+	}
+	if active != "" {
+		t.Fatalf("expected stale active session to be cleared, got %q", active)
+	}
+}

internal/cli/ssh.go

@@ -34,24 +34,26 @@ func newSSHCmd(opts *Options) *cobra.Command {
 	var noTmux bool
 
 	cmd := &cobra.Command{
-		Use:   "ssh",
+		Use:   "ssh [session]",
 		Short: "Connect to session pod over SSH",
+		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return withQuietConfigAnnounce(func() error {
 				errOut := cmd.ErrOrStderr()
+				applySessionArg(opts, args)
 				cfg, ns, err := loadConfigAndNamespace(opts)
 				if err != nil {
 					return err
 				}
 				stopResolve := startTransientStatus(errOut, "Resolving SSH session")
-				sn, err := resolveSessionName(opts, cfg)
+				sn, err := resolveSessionName(opts, cfg, ns)
 				stopResolve()
 				if err != nil {
 					return err
 				}
 				k := newKubeClient(opts)
 				stopOwnership := startTransientStatus(errOut, "Verifying session access")
-				if err := ensureSessionOwnership(opts, k, ns, sn, true); err != nil {
+				if err := ensureExistingSessionOwnership(opts, k, ns, sn, true); err != nil {
 					stopOwnership()
 					return err
 				}
@@ -416,6 +418,7 @@ func ensureSSHConfigEntry(hostAlias, sessionName, namespace, user string, remote
 		"  IdentityFile " + keyPath,
 		"  StrictHostKeyChecking no",
 		"  UserKnownHostsFile /dev/null",
+		"  SetEnv OKDEV_NO_TMUX=1",
 		"  ProxyCommand " + proxyCmd,
 	}
 	// Hardcoded keepalive values for the proxy path — sshSpec values are
@@ -509,12 +512,12 @@ func newSSHProxyCmd(opts *Options) *cobra.Command {
 				if err != nil {
 					return err
 				}
-				sn, err := resolveSessionName(opts, cfg)
+				sn, err := resolveSessionName(opts, cfg, ns)
 				if err != nil {
 					return err
 				}
 				k := newKubeClient(opts)
-				if err := ensureSessionOwnership(opts, k, ns, sn, true); err != nil {
+				if err := ensureExistingSessionOwnership(opts, k, ns, sn, true); err != nil {
 					return err
 				}
 				if remotePort == 0 {

internal/cli/ssh_config_test.go

@@ -42,6 +42,9 @@ func TestEnsureSSHConfigEntryIncludesNamespaceInProxyCommand(t *testing.T) {
 	if !strings.Contains(text, "Host okdev-test") {
 		t.Fatalf("missing host block: %s", text)
 	}
+	if !strings.Contains(text, "SetEnv OKDEV_NO_TMUX=1") {
+		t.Fatalf("expected managed ssh host to disable tmux by default: %s", text)
+	}
 	if !strings.Contains(text, "--session") || !strings.Contains(text, "test-session") || !strings.Contains(text, " -n ") || !strings.Contains(text, "dev-ns") || !strings.Contains(text, "ssh-proxy --remote-port 2222") {
 		t.Fatalf("proxy command missing namespace: %s", text)
 	}

internal/cli/status.go

@@ -13,9 +13,11 @@ func newStatusCmd(opts *Options) *cobra.Command {
 	var allUsers bool
 
 	cmd := &cobra.Command{
-		Use:   "status",
+		Use:   "status [session]",
 		Short: "Show session status",
+		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
+			applySessionArg(opts, args)
 			cfg, ns, err := loadConfigAndNamespace(opts)
 			if err != nil {
 				return err
@@ -25,7 +27,7 @@ func newStatusCmd(opts *Options) *cobra.Command {
 				label = label + "," + ownerLabelSelector(opts)
 			}
 			if !all {
-				sn, err := resolveSessionName(opts, cfg)
+				sn, err := resolveSessionName(opts, cfg, ns)
 				if err != nil {
 					return err
 				}

internal/cli/sync.go

@@ -38,7 +38,7 @@ func newSyncCmd(opts *Options) *cobra.Command {
 				return err
 			}
 			k := newKubeClient(opts)
-			if err := ensureSessionOwnership(opts, k, ns, sn, true); err != nil {
+			if err := ensureExistingSessionOwnership(opts, k, ns, sn, true); err != nil {
 				return err
 			}
 			engine := cfg.Spec.Sync.Engine