Skip to content

Sessions

The session-manager layer takes LayoutConfig objects and turns them into running terminal sessions. The shared pieces are:

  • session-name conflict planning
  • backend-specific layout launchers
  • attach, status, monitoring, and persistence helpers

Supported managers

Manager Module path What it manages
ZellijLocalManager stackops.cluster.sessions_managers.zellij.zellij_local_manager Local zellij sessions generated from list[LayoutConfig]
TmuxLocalManager stackops.cluster.sessions_managers.tmux.tmux_local_manager Local tmux sessions generated from list[LayoutConfig]
WTLocalManager stackops.cluster.sessions_managers.windows_terminal.wt_local_manager Local Windows Terminal sessions generated from list[LayoutConfig]
ZellijSessionManager stackops.cluster.sessions_managers.zellij.zellij_remote_manager Remote zellij sessions across SSH hosts
WTSessionManager stackops.cluster.sessions_managers.windows_terminal.wt_remote_manager Remote Windows Terminal sessions across remote machines

Conflict policies

stackops.cluster.sessions_managers.session_conflict defines the shared conflict planner.

Supported actions

Action Meaning
error Fail if a requested session already exists or if two requested layouts target the same name
restart Reuse the requested name and restart an existing session when necessary
rename Keep the requested name as a base and allocate name_1, name_2, and so on
mergeNewWindowsOverwriteMatchingWindows Keep the requested session name and merge new windows into an existing tmux or Windows Terminal session, overwriting matching windows where supported
mergeNewWindowsSkipMatchingWindows Keep the requested session name and merge only missing windows where supported

The two merge actions are only valid for the tmux and windows-terminal backends.

Backend-specific behavior

Zellij local

ZellijLocalManager:

  • always prefixes managed session names with LocalJobMgr_
  • requires start_all_sessions(on_conflict, poll_seconds, poll_interval)
  • launches zellij sessions non-blockingly and then polls zellij list-sessions
  • supports attach_to_session(), check_all_sessions_status(), run_monitoring_routine(), save(), load(), and list_active_sessions()

Example:

from stackops.cluster.sessions_managers.zellij.zellij_local_manager import ZellijLocalManager

manager = ZellijLocalManager(session_layouts=[layout])
manager.start_all_sessions(
    on_conflict="rename",
    poll_seconds=10.0,
    poll_interval=0.5,
)
print(manager.attach_to_session(None))

tmux local

TmuxLocalManager requires explicit session_name_prefix and exit_mode values:

from stackops.cluster.sessions_managers.tmux.tmux_local_manager import TmuxLocalManager

manager = TmuxLocalManager(
    session_layouts=[layout],
    session_name_prefix="ops",
    exit_mode="backToShell",
)

manager.start_all_sessions(on_conflict="rename")
print(manager.attach_to_session(None))
report = manager.check_all_sessions_status()

tmux is also the backend where merge conflict actions produce merge scripts instead of only rename-or-restart plans.

Windows Terminal local

WTLocalManager also takes session_layouts, session_name_prefix, and exit_mode, but start_all_sessions() currently has no on_conflict parameter. It simply runs the generated PowerShell launcher for each managed layout.

Useful current helpers include:

  • attach_to_session()
  • check_all_sessions_status()
  • run_monitoring_routine()
  • save() / load()
  • get_wt_overview()
  • list_active_sessions()

Remote managers

The remote managers keep the same status and persistence ideas, but their inputs are backend-specific:

  • ZellijSessionManager(machine_layouts: dict[str, LayoutConfig], session_name_prefix: str)
  • WTSessionManager(machine2wt_tabs: dict[str, dict[str, tuple[str, str]]], session_name_prefix: str | None = "WTJobMgr")

Representative helpers:

  • ssh_to_all_machines()
  • start_all_sessions() or start_zellij_sessions()
  • run_monitoring_routine()
  • save() / load()

Monitoring and reporting helpers

Representative utility modules include:

  • stackops.cluster.sessions_managers.zellij.zellij_utils.process_monitor
  • stackops.cluster.sessions_managers.zellij.zellij_utils.status_reporter
  • stackops.cluster.sessions_managers.windows_terminal.wt_utils.status_reporting
  • stackops.cluster.sessions_managers.windows_terminal.wt_utils.manager_persistence

These modules power the status summaries returned by the manager classes rather than replacing them.

See also

API reference

Conflict planning

session_conflict

Zellij local manager

zellij_local_manager

ZellijLocalManager 

ZellijLocalManager(session_layouts: list[LayoutConfig])

Manages multiple local zellij sessions and monitors their tabs and processes.

get_all_session_names 

get_all_session_names() -> list[str]

Get all managed session names.

start_all_sessions 

start_all_sessions(
    on_conflict: SessionConflictAction,
    poll_seconds: float,
    poll_interval: float,
) -> dict[str, StartResult]

Start all zellij sessions with their layouts without blocking on the interactive TUI.

Rationale

Previous implementation used subprocess.run(... timeout=30) on an "attach" command which never returns (interactive) causing a timeout. We now: 1. Ensure any old session is deleted (best-effort, short timeout) 2. Launch new session in background with Popen (no wait) 3. Poll 'zellij list-sessions' to confirm creation

Parameters:

Name Type Description Default
poll_seconds float

Total seconds to wait for session to appear

 required
poll_interval float

Delay between polls

 required

Returns: Dict mapping session name to success metadata.

kill_all_sessions 

kill_all_sessions() -> dict[str, StartResult]

Kill all managed zellij sessions.

attach_to_session 

attach_to_session(session_name: str | None) -> str

Generate command to attach to a specific session or list attachment commands for all.

Parameters:

Name Type Description Default
session_name str | None

Specific session to attach to, or None for all sessions

 required

Returns:

Type Description
str

Command string to attach to session(s)

check_all_sessions_status 

check_all_sessions_status() -> dict[str, SessionReport]

Check the status of all sessions and their commands.

get_global_summary 

get_global_summary() -> GlobalSummary

Get a global summary across all sessions.

print_status_report 

print_status_report() -> None

Print a comprehensive status report for all sessions.

run_monitoring_routine 

run_monitoring_routine(wait_ms: int) -> None

Run a continuous monitoring routine that checks status periodically.

Parameters:

Name Type Description Default
wait_ms int

How long to wait between checks in milliseconds

 required

save 

save(session_id: str | None) -> str

Save the manager state to disk.

load classmethod 

load(session_id: str) -> ZellijLocalManager

Load a saved manager state from disk.

list_saved_sessions staticmethod 

list_saved_sessions() -> list[str]

List all saved session IDs.

delete_session staticmethod 

delete_session(session_id: str) -> bool

Delete a saved session.

list_active_sessions 

list_active_sessions() -> list[ActiveSessionInfo]

List currently active zellij sessions managed by this instance.

tmux local manager

tmux_local_manager

Windows Terminal local manager

wt_local_manager

WTLocalManager 

WTLocalManager(
    session_layouts: list[LayoutConfig],
    session_name_prefix: str | None,
    exit_mode: SessionExitMode,
)

Manages multiple local Windows Terminal sessions and monitors their tabs and processes.

Parameters:

Name Type Description Default
session_layouts list[LayoutConfig]

Dict mapping session names to their layout configs Format: {session_name: LayoutConfig, ...}

 required
session_name_prefix str | None

Prefix for session names

 required

get_all_session_names 

get_all_session_names() -> list[str]

Get all managed session names.

start_all_sessions 

start_all_sessions() -> dict[str, StartResult]

Start all Windows Terminal sessions with their layouts.

kill_all_sessions 

kill_all_sessions() -> dict[str, StartResult]

Kill all managed Windows Terminal sessions.

attach_to_session 

attach_to_session(session_name: str | None = None) -> str

Generate command to attach to a specific session or list attachment commands for all.

Parameters:

Name Type Description Default
session_name str | None

Specific session to attach to, or None for all sessions

 None

Returns:

Type Description
str

Command string to attach to session(s)

run_monitoring_routine 

run_monitoring_routine(wait_ms: int = 30000) -> None

Run a continuous monitoring routine that checks status periodically.

Parameters:

Name Type Description Default
wait_ms int

How long to wait between checks in milliseconds (default: 30000ms = 30s)

 30000

get_wt_overview 

get_wt_overview() -> dict[str, Any]

Get overview of all Windows Terminal windows and processes.

Zellij remote manager

zellij_remote_manager

Windows Terminal remote manager

wt_remote_manager

WTSessionManager 

WTSessionManager(
    machine2wt_tabs: dict[str, dict[str, tuple[str, str]]],
    session_name_prefix: str | None = "WTJobMgr",
)

start_all_sessions 

start_all_sessions() -> dict[str, Any]

Start all Windows Terminal sessions on their respective remote machines.

get_remote_overview 

get_remote_overview() -> dict[str, Any]

Get overview of all remote machines and their Windows Terminal status.

print_remote_overview 

print_remote_overview() -> None

Print overview of all remote machines.