Durable Sessions v0.14

Keep your shell sessions alive through network changes, computer sleep, and DanteTerm restarts — for remote SSH connections, and, if you opt in, local terminals too.

Overview

Durable sessions protect your terminal state when working with remote SSH connections or local terminals, similar to tmux or screen but built directly into DanteTerm. Unlike a standard session that ends when the connection drops or its panel closes, a durable session maintains your:

• Shell state - Current directory, environment variables, and shell history
• Running programs - Background jobs and long-running commands continue executing
• Terminal history - Full scrollback buffer preserved across reconnections

Durable sessions automatically reconnect when your connection is restored, picking up right where you left off.

Local sessions are opt-in

Remote SSH connections are durable by default. Local terminals can be durable too, but you turn it on per block — a local shell dies with its panel unless you ask otherwise. WSL connections do not support durable sessions yet.

How It Works

When you start a durable session, DanteTerm launches a lightweight job manager on the machine the session belongs to — the remote server for an SSH connection, or your local machine for a local terminal. Similar to how tmux and screen work, this manager:

1. Keeps your shell process running independently of the DanteTerm connection
2. Buffers terminal output while disconnected
3. Enables DanteTerm to seamlessly reattach when you reconnect
4. Survives DanteTerm restarts, network interruptions, and DanteTerm quitting entirely (including a force-quit)

The session continues running on its host machine even if you close DanteTerm, put your computer to sleep, or switch networks.

Session Status Indicator

The shield icon in your terminal header shows the current session status:

Icon	Status	Description
	Standard Session	Connection drops will end the session
	Durable (Attached)	Session is protected and connected
	Durable (Detached)	Session running, currently disconnected
	Durable (Awaiting)	Configured but not yet started

Hover over the shield icon to see detailed status information and available actions.

Configuration

Durable sessions can be configured at three levels, with more specific settings overriding general ones:

Global Settings (Lowest Priority)

Set the default in your settings.json — this turns on durable sessions for every local terminal (off by default) and, since SSH connections are already durable by default, lets you turn them off globally instead:

{
  "term:durable": true
}

Connection Settings (Medium Priority)

Configure durability per connection in your connections.json:

{
  "connections": {
    "user@host": {
      "term:durable": true
    }
  }
}

Block Settings (Highest Priority)

Override for individual terminal blocks through:

• Context Menu: Right-click terminal → Advanced → Session Durability
• Flyover Actions: Click shield icon → "Restart as Durable" or "Restart as Standard"
• Command Line: Use dsh setmeta term:durable=true or dsh setmeta term:durable=false

Configuration hierarchy (highest to lowest priority):

1. Block-level setting
2. Connection-level setting
3. Global setting

Default Behavior

• SSH connections: Durable sessions enabled by default (opt-out via configuration)
• Local terminals: Durable sessions disabled by default (opt-in via configuration)
• WSL connections: Always use standard sessions (durability not supported)

Switching Between Modes

Standard to Durable

1. Hover over the regular shield icon
2. Click "Restart as Durable" in the flyover
3. Your session will restart with durability enabled

Or use the context menu:

• Right-click terminal → Advanced → Session Durability → Restart Session in Durable Mode

Durable to Standard

1. Access the terminal context menu (right-click)
2. Navigate to Advanced → Session Durability
3. Select "Restart Session in Standard Mode"

Switching Modes Restarts the Session

Converting between standard and durable modes requires restarting the shell. Any running processes in the current session will be terminated.

Session States

Attached

Your terminal is connected to the session. You can interact with the shell and see real-time output.

Detached

The connection dropped (remote), or the panel was closed (local) — either way, the session keeps running on its host machine. DanteTerm reconnects automatically for a remote session; for a local session, click its entry in the widget-bar list to restore it into a panel. Any commands you ran continue executing.

Awaiting Start

Session configured for durability but not yet started. Click "Start Session" or run a command to begin.

Starting

Job manager is initializing on the session's host machine — the remote server for SSH, your local machine for a local terminal. The session will become attached shortly.

Ended

Session has terminated. Common reasons:

• Exited: Shell was closed normally (e.g., typed exit)
• Lost: Session not found on its host machine (may have been terminated or the machine rebooted)
• Failed to Start: Job manager encountered an error during initialization

Click "Restart Session" to start a new durable session, or "Restart as Standard" to switch modes.

Use Cases

Long-Running Commands

Start a build, deployment, or data processing job and close your laptop. The command continues executing, and you can check on it later.

# Start a long build
./build.sh

# Close your laptop, get coffee
# Later: reconnect and see the completed output

Unstable Networks

Work from a café, train, or cellular connection. Brief disconnections won't terminate your session or lose your work.

Multiple Locations

Start work on your desktop, continue on your laptop, both connecting to the same remote server. Your SSH session and its state are preserved there.

System Maintenance

DanteTerm updates, restarts, or crashes won't interrupt a durable session. Reconnect (remote) or reopen the session from the widget bar (local) and resume immediately.

Background Sessions

A durable local terminal keeps running when you close its panel. Closing the panel detaches the session rather than ending it; the shell, and anything running in it, carries on.

Detached sessions live behind the sessions icon in the widget bar, which shows a magenta dot while any session is running. Click the icon to list them, then click one to bring it back into a panel — it does not have to be the tab it started in.

Sessions end only when you end them: exit the shell, use Close and End Session from the panel's context menu, or right-click the entry in the session list and choose End Session. Nothing is reaped on a timer.

Enable it for a block with:

dsh setmeta term:durable=true

Or for every local terminal, in settings.json:

{
  "term:durable": true
}

Session Lifecycle

For a remote durable session, the session is tied to the terminal block: closing the block, switching the block's connection, or deleting the workspace/tab terminates the session on the remote server.

For a local durable session, closing the block instead parks the session — see Background Sessions above. Deleting the tab or workspace parks it too, so it stays available in the widget-bar list. Switching the block's connection still ends it, the same as for remote sessions. Otherwise a local session ends only when you end it: exiting the shell, "Close and End Session" from the panel, or "End Session" from the entry's right-click menu in the session list.

Cleanup Behavior

If you close a remote block while disconnected, the remote session continues running until the next reconnection. When DanteTerm reconnects to that server, it will automatically clean up any orphaned sessions from closed blocks.

This ensures that remote sessions don't accumulate on your servers when you close terminals while offline. Local durable sessions are never cleaned up automatically — they wait in the widget-bar list until you restore or end them.

Limitations

• Local terminals: Durable sessions are macOS and Linux only; Windows local terminals always use standard sessions.
• WSL connections: Not applicable (WSL sessions managed by Windows)
• Network latency: Detached remote sessions buffer output; reconnecting may take a moment to sync
• Host resources: Each durable session maintains a lightweight Go process on its host machine — the remote server for SSH, your local machine for a local terminal — for session management

Troubleshooting

Session Shows as "Lost"

The session was terminated on its host machine — the remote server for SSH, your local machine for a local terminal — possibly due to:

• The host machine rebooting
• Manual termination of the job manager process
• The host machine running out of resources

Solution: Click "Restart Session" to start a new durable session.

Session Won't Reconnect (Remote)

Verify that:

• Your SSH connection to the server is working (check the connection status)
• The job manager process is still running on the remote server

Try: Right-click terminal → Advanced → Force Restart Controller

Session Won't Restore (Local)

If a parked local session doesn't reattach when you click it in the widget-bar list, verify that:

• The job manager process is still running on your machine
• The session hasn't already been ended (it won't appear in the list anymore if so)

Try: Close and reopen the widget-bar list — it refreshes every few seconds. If the entry is still listed but won't restore, right-click it → "End Session" and open a new durable terminal.

"Failed to Start" Error

The job manager couldn't initialize on the session's host machine — the remote server for SSH, your local machine for a local terminal. Check the error message for specific details.

Try: Restart the session. If the issue persists, file a bug report with the error details.

Technical Details

Durable sessions use Unix domain sockets on the session's host machine — the remote server for SSH, your local machine for a local terminal — to maintain persistent connections between the shell and DanteTerm's job manager. The job manager process runs independently and survives both a dropped connection and DanteTerm quitting, including a force-quit.

Privacy & Security

• A durable session runs entirely on its host machine — the remote server for SSH, your local machine for a local terminal
• For a remote session, all data is transmitted over SSH between your local DanteTerm instance and the remote machine; no open ports on the remote machine are required, since communication happens through your existing SSH connection
• For a local session, nothing leaves the machine — the job manager is a local process, and DanteTerm talks to it over a local socket
• When detached, output is buffered on the host machine until you reconnect or restore the session
• Sessions are isolated per user and use your (remote or local) user's permissions