Durable Sessions v0.14

Keep local, WSL and supported SSH shells alive when DanteTerm closes or restarts. Remote durability requires a compatible helper on the execution host.

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 - A bounded screen and scrollback history preserved across reconnections

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

Current defaults

New local terminals are durable by default on macOS, Windows, and Linux. SSH terminals are durable by default when the remote dsh extension is available. If you decline its installation, a new SSH terminal opens as a standard shell and saves that choice for the block. WSL terminals are durable by default. Explicit global, connection and block settings of term:durable=false take precedence for new terminals. Existing jobs keep their original owner.

How It Works

For local terminals, one user-scoped daemon owns the shells for multiple blocks independently of the app window and its server. Remote SSH durable sessions use a job manager on the remote host. These processes:

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)

Local sessions continue running when you close or restart DanteTerm. A remote durable session continues running on its host when the SSH connection drops.

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)

Local, WSL and supported SSH durability are already on by default. Set term:durable to false in settings.json to start standard sessions by default:

{
  "term:durable": false
}

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: A new standard session offers "Restart as Durable". Retained common sessions offer End or Retry End.
• 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

• Local terminals on macOS, Windows, and Linux: Durable by default; term:durable=false opts out.
• SSH connections: Durable by default with a compatible helper. A known unsupported or declined helper opens a standard shell only for a new unbound block and saves term:durable=false with the reason. An existing or pending durable owner is not replaced automatically.
• WSL connections: Durable by default inside the selected Linux distribution; term:durable=false opts out.

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

End the retained durable session and wait for confirmed cleanup, then open a new standard terminal using term:durable=false. Changing settings on an existing bound session does not restart it, migrate its owner or replace it with a standard shell. A pending create also keeps its original identity until it can be resolved or ended.

Starting a Replacement

End stops the retained session's processes and removes its saved history after confirmed cleanup. Open any history you need before ending it.

Session States

Attached

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

Detached

Closing a durable terminal block ends its session. To keep the session running instead, use Park Session and Close — the button in the block header or the header menu. A parked session stays on the execution host; use the sessions list to attach it in another panel. Closing a window or quitting the app disconnects the display and does not end the session. A network interruption may show Checking process until ownership and process identity can be verified. Available cached history can still be opened read only.

Awaiting Start

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

Starting

The local daemon or remote job manager is initializing. 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

A retained common session can show History only, Checking process or End pending. Read its available cache and use End before starting a replacement; uncertain process state does not authorize an automatic restart. Older job entries retain their original controls.

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

Return to a parked session in another tab or workspace in the same DanteTerm installation. Automatic discovery and simultaneous control from another installation are not supported.

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, WSL or supported SSH terminal keeps running in the background when you park it with Park Session and Close, when you close its window, or when you quit DanteTerm. Closing the block or its tab ends the session instead.

Parked 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.

When you close a block in which a program is still running (an agent such as Claude Code or Codex, or a command reported by shell integration), DanteTerm asks first: Close and End, Park and Close (offered only when the block has a durable session to park), or Cancel. A block with only an idle shell closes without asking. Replacing a block with the launcher (Ctrl+Shift+X) ends its session too and asks the same way.

Closing a tab with its close button or the tab menu always asks. Cmd+Shift+W and closing a tab's last block ask when tab:confirmclose is on or when something is running in the tab. The dialog lists the running blocks, marking those that cannot be parked, and offers Park All and Close only when something running can be parked; it parks every durable session in the tab, and blocks that cannot be parked end with the tab.

A session also ends when you exit the shell, right-click its entry in the session list and choose End Session, delete the workspace it belongs to, or replace its block (dsh createblock --position replace, dsh web open --replace, or Ctrl+Shift+X). Nothing is reaped on a timer.

Choose a standard session for an individual new block with:

dsh setmeta term:durable=false

Or make standard sessions the global default in settings.json:

{
  "term:durable": false
}

Session Lifecycle

WSL terminals now keep their session by default. Closing a terminal block ends the session; Park Session and Close parks it. Use End Session to stop its process and remove its saved history. If the connection is unavailable, End pending remains visible until the remote process and history cleanup are confirmed.

If ending cannot be confirmed when you close a block (for example, the connection is down), the block still closes and the session stays in the list as End pending; reconnect and retry End to finish cleanup. A termination request or missing PID alone is not confirmation. No timer removes parked sessions. Task jobs retain their existing lifetime policy.

History and compatibility

The sessions list shows the recorded execution connection and the retained status: connected, parked, checking, resuming, history only or incompatible. Open History uses saved desktop cache in a controller-free terminal. It does not start a shell, launch AI or force reconnection. Legacy history and Truncated labels describe limits of saved output.

Existing jobs retain their original owner and helper protocol. Legacy jobs can reconnect using that original protocol; some old helpers provide only limited history or no verified identity. Those entries cannot use common input attachment. End may remain pending when the old protocol cannot confirm process and source history cleanup. Installing a new helper does not upgrade a running owner automatically.

AI conversation recovery

Only a verified tool and an exact recorded conversation can be considered for automatic resume. The source owner must verify the current execution, installed CLI support and process identity. A Verified tool support label describes historical support, not a currently running CLI or permission to launch. Missing or unsupported metadata remains unverified.

Resume opens the original conversation without sending a prompt. It is attempted at most once per process generation, and restarting DanteTerm or its connection helper does not reset that attempt. A normal CLI exit, uncertain process state, missing identity or pending End does not authorize recovery. A host restart cannot restore an arbitrary interrupted command.

Limitations

• Local terminals: The shared daemon runs on macOS, Windows, and Linux. If the daemon and shell die, DanteTerm can restore saved output but cannot revive the interrupted command.
• WSL connections: The owner runs inside the Linux distribution. Stopping that distribution stops its processes; cached history remains available.
• Remote host support: Enhanced remote durability targets Linux and macOS execution hosts, including Linux inside WSL. Native Windows SSH is outside this durable host boundary. Specific OS and AI CLI versions require platform validation.
• Unavailable or unsupported remote helper: A known unsupported or declined helper can select a standard shell for a new unbound block and display the reason. Standard shells do not survive connection loss or app exit. Existing or pending durable ownership is never replaced automatically.
• Network latency: Detached remote sessions buffer output; reconnecting may take a moment to sync
• Host resources: Local sessions share one daemon per OS user. Remote durable sessions use a job manager on the SSH host.

Troubleshooting

Session Shows as Checking or History Only

DanteTerm cannot yet verify the original process, or only saved output remains. The host may have restarted or the owner may be unreachable. Open cached history and reconnect to refresh the status. End the retained session before starting a replacement. An uncertain or missing process does not authorize an automatic restart of an arbitrary command.

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: Reconnect and check the session status. Open cached history while the owner is unavailable. An existing bound session is not replaced by a standard shell automatically.

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 local terminal daemon and shell are 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 local daemon or remote job manager could not initialize. Check the error message for details.

Try: Reconnect and refresh the saved session. A pending create keeps its original identity; it must not be replaced automatically. If the issue persists, file a bug report with the error details.

Technical Details

Local durable sessions use a user-only Unix socket on macOS/Linux or a named pipe on Windows to connect DanteTerm to the independent terminal daemon. Output is saved to user-only files before it is shown in the app. Remote SSH durable sessions use a job manager and socket on the remote host. Both source history and the desktop cache are bounded, stored in plaintext, and restricted to the OS user. Sensitive terminal output can remain in these files until you end the session.

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 daemon is a local process, and DanteTerm talks to it over a user-only socket or named pipe
• When parked or disconnected, output is saved on the execution host and mirrored to a user-only desktop cache when connected
• No session-control TCP listener is opened; remote control uses the existing SSH or WSL connection
• History is plaintext, not encrypted storage; End removes saved history only after confirmed cleanup
• Sessions are isolated per user and use your (remote or local) user's permissions