Configured terminal workspace manager for the dashboard #423

New issue

Open

opened 2026-08-20 08:36:42 +00:00 by mph · 0 comments

mph commented

2026-08-20 08:36:42 +00:00

Owner

Problem

iw picks its terminal workspace manager by reading the environment of the
terminal it was invoked from: HERDR_ENV=1 selects herdr, otherwise tmux
(IW-422). That works for the CLI and cannot work for the dashboard.

The dashboard is a long-lived server process with no invoking terminal, so
there is no environment to detect. dashboard/jvm/src/CaskServer.scala:1264
therefore calls TmuxAdapter.createSession directly and is knowingly tmux-only,
which IW-422 left in place deliberately. A worktree created from the dashboard
gets a tmux session even when the user works in herdr.

The server needs to be told which manager to drive.

Scope

A global setting that names the terminal workspace manager, and the dashboard
reading it.

The setting names the backend, following the precedent set by
IW_WORKSPACE_BACKEND in IW-422 — the same vocabulary, not a new one.
The dashboard's worktree-creation path repoints at the same selection object
the CLI uses, so the two stop diverging.
WorktreeCreationError.TmuxError is renamed once the path is no longer
tmux-only.

Depends on IW-422, which introduces the port (TerminalWorkspaceOps), the two
adapters, and the selection rule this setting feeds.

Design notes carried over from IW-422

IW-422's selection rule is deliberately shaped to take a second input. Its
precedence is:

IW_WORKSPACE_BACKEND, when set to a recognised name
(this issue: the configured default)
HERDR_ENV=1 -> herdr
otherwise tmux

Where the configured default sits relative to environment detection is this
issue's decision, not IW-422's. The CLI case argues for detection winning (you
are literally inside herdr); the server case has no detection at all, so the
setting is its only input.

IW-422 also requires that the selection rule and isInside stay separate
functions precisely because this issue makes them diverge: once a configured
default exists, "which manager do we drive" and "are we inside one of its
workspaces" are no longer the same question, and the attach path stops being
unreachable.

Acceptance

A global setting names the terminal workspace manager.
The dashboard drives the manager the setting names when it creates a worktree.
The CLI and the dashboard resolve the backend through the same code.
With no setting present, behaviour is unchanged.

## Problem `iw` picks its terminal workspace manager by reading the environment of the terminal it was invoked from: `HERDR_ENV=1` selects herdr, otherwise tmux (IW-422). That works for the CLI and cannot work for the dashboard. The dashboard is a long-lived server process with no invoking terminal, so there is no environment to detect. `dashboard/jvm/src/CaskServer.scala:1264` therefore calls `TmuxAdapter.createSession` directly and is knowingly tmux-only, which IW-422 left in place deliberately. A worktree created from the dashboard gets a tmux session even when the user works in herdr. The server needs to be *told* which manager to drive. ## Scope A global setting that names the terminal workspace manager, and the dashboard reading it. - The setting names the backend, following the precedent set by `IW_WORKSPACE_BACKEND` in IW-422 — the same vocabulary, not a new one. - The dashboard's worktree-creation path repoints at the same selection object the CLI uses, so the two stop diverging. - `WorktreeCreationError.TmuxError` is renamed once the path is no longer tmux-only. Depends on IW-422, which introduces the port (`TerminalWorkspaceOps`), the two adapters, and the selection rule this setting feeds. ## Design notes carried over from IW-422 IW-422's selection rule is deliberately shaped to take a second input. Its precedence is: 1. `IW_WORKSPACE_BACKEND`, when set to a recognised name 2. *(this issue: the configured default)* 3. `HERDR_ENV=1` -> herdr 4. otherwise tmux Where the configured default sits relative to environment detection is this issue's decision, not IW-422's. The CLI case argues for detection winning (you are literally inside herdr); the server case has no detection at all, so the setting is its only input. IW-422 also requires that the selection rule and `isInside` stay separate functions precisely because this issue makes them diverge: once a configured default exists, "which manager do we drive" and "are we inside one of its workspaces" are no longer the same question, and the attach path stops being unreachable. ## Acceptance - A global setting names the terminal workspace manager. - The dashboard drives the manager the setting names when it creates a worktree. - The CLI and the dashboard resolve the backend through the same code. - With no setting present, behaviour is unchanged.