runshell

Documentation

Overview

Package runshell spawns interactive post-mortem shells in preserved run worktrees (the studio's "Open shell" on a failed run). One Session per WebSocket connection — the worktree is the state, the shell is a viewer: no persistent multiplexer, a reconnect is a fresh shell. Unix-only; the Windows build carries a typed stub.

Index

• Variables
• type Session
  • func Spawn(opts SpawnOptions) (*Session, error)
  • func (s *Session) Resize(cols, rows uint16) error
  • func (s *Session) Terminate()
• type SpawnOptions

Variables

var ErrUnsupported = errors.New("runshell: post-mortem shell is not supported on this platform")

ErrUnsupported marks a platform without PTY support (Windows). The server handler maps it to 501 so the desktop build stays green while the feature remains Unix-only.

Types

type Session

type Session struct {
	PTY *os.File
	Cmd *exec.Cmd
}

Session is one live shell attached to a PTY.

func Spawn

func Spawn(opts SpawnOptions) (*Session, error)

Spawn starts `$SHELL -l` (bash fallback) inside opts.WorkDir on a fresh PTY. pty.Start runs the shell with Setsid (mandatory for a controlling terminal), which ALSO makes it its own process-group leader — do NOT add Setpgid on top, the two are mutually exclusive and the combination fails fork/exec with EPERM. Terminate kills the whole job through that session's group (a `sleep 999 &` left behind must not outlive the socket).

func (*Session) Resize

func (s *Session) Resize(cols, rows uint16) error

Resize applies a client-side window resize to the PTY.

func (*Session) Terminate

func (s *Session) Terminate()

Terminate tears the whole job down: SIGTERM to the process group, then PTY close (which delivers SIGHUP to stragglers). Idempotent.

type SpawnOptions

type SpawnOptions struct {
	// WorkDir is the preserved worktree the shell opens in.
	WorkDir string
	// Env entries appended to the inherited environment.
	Env []string
	// Cols/Rows are the initial terminal size (0 → 80x24).
	Cols, Rows uint16
}

SpawnOptions configures one interactive shell.