workstreams-cli 0.6.1__tar.gz → 0.6.2__tar.gz

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstreams-cli
-Version: 0.6.1
+Version: 0.6.2
 Summary: Visually dispatch coding-agent work to subagents in real terminal windows and monitor it in one dashboard - for any coding agent (Claude Code, Codex, OpenCode, Qwen Code, Hermes, Cline, and more).
 Author: Dream-Pixels-Forge
 License: MIT
@@ -114,7 +114,7 @@ pip install -e ".[yaml,dev]"   # dev extras add pytest
 Verify:
 
 ```bash
-workstreams --version   # -> workstreams 0.6.1
+workstreams --version   # -> workstreams 0.6.2
 ```
 
 > **Note:** every command also accepts `--json` to emit machine-readable output (where supported), which coding agents can parse. All read-side commands work without a multiplexer installed; only `start`/`dispatch`/`work`/`attach` need one.
@@ -139,10 +139,36 @@ The terminal tool that hosts the visible windows. `workstreams` currently suppor
 
 | Multiplexer | Layouts | Notes |
 |-------------|---------|-------|
-| `tmux` (default) | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
+| `default` (auto-detect) | per backend | **Picks the best multiplexer installed for your OS**: `tmux` on macOS, `lmux` on Linux, `wmux` on Windows — falling back to `zellij` when the platform primary is missing. This is now the out-of-the-box behaviour. |
+| `tmux` | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
 | `zellij` | tabs | One **tab per workstream**. Simpler scripting surface; `dispatch` targets the current tab only. |
+| `nami` / `lmux` / `wmux` / `herdr` | tmux-compatible | tmux-compatible CLIs wrapped by `TmuxCompatibleMultiplexer`. |
 
-The tmux/zellij session is auto-named `workstreams-<project>`.
+**Auto-detect** — you normally don't pick one. `load_config` resolves the
+platform default at startup:
+
+```
+macOS   → tmux first, then zellij, nami, lmux, wmux
+Linux   → lmux first, then zellij, then tmux
+Windows → wmux first, then lmux, zellij, tmux
+```
+
+The first *installed* binary in that list wins — **and** for the
+tmux-compatible wrapper family (`nami` / `lmux` / `wmux` / `herdr`)
+workstreams validates that the binary actually exposes tmux-style verbs
+(`new-session` / `send-keys` / …) before committing. For example `lmux`
+v1 has a completely different CLI shape (`workspace.create`,
+`surface.send-key`) so the validator rejects it and auto-detect falls
+through to `zellij` or `tmux`. If you *know* your `lmux` build exposes
+the tmux dialect, pin it explicitly with `multiplexer: lmux` — the
+validator is only consulted on the `default` auto-pick path. If you want a specific one:
+
+- Set it in your `.workstreams.yaml` / `.json`: `multiplexer: zellij`
+- Or pass `--multiplexer zellij` on `init` / `start` / `dispatch` / `work`
+- Or run `workstreams init --choose` to interactively pick, which persists the
+  choice into your config file so later commands use it.
+
+The tmux/zellij/lmux/wmux session is auto-named `workstreams-<project>`.
 
 ### 3. Subagent
 The coding agent doing the work inside a workstream. This is deliberately **free-form**: `claude-code`, `codex`, `opencode`, `qwen-code`, `mimocode`, `hermes`, `kilo-code`, `cline`, or any label you want. There is no vendor lock-in — a subagent is just an identifier used in the event log. The agent that actually runs is whatever command you send into the pane (see `dispatch`/`work`).

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/README.md

@@ -84,7 +84,7 @@ pip install -e ".[yaml,dev]"   # dev extras add pytest
 Verify:
 
 ```bash
-workstreams --version   # -> workstreams 0.6.1
+workstreams --version   # -> workstreams 0.6.2
 ```
 
 > **Note:** every command also accepts `--json` to emit machine-readable output (where supported), which coding agents can parse. All read-side commands work without a multiplexer installed; only `start`/`dispatch`/`work`/`attach` need one.
@@ -109,10 +109,36 @@ The terminal tool that hosts the visible windows. `workstreams` currently suppor
 
 | Multiplexer | Layouts | Notes |
 |-------------|---------|-------|
-| `tmux` (default) | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
+| `default` (auto-detect) | per backend | **Picks the best multiplexer installed for your OS**: `tmux` on macOS, `lmux` on Linux, `wmux` on Windows — falling back to `zellij` when the platform primary is missing. This is now the out-of-the-box behaviour. |
+| `tmux` | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
 | `zellij` | tabs | One **tab per workstream**. Simpler scripting surface; `dispatch` targets the current tab only. |
+| `nami` / `lmux` / `wmux` / `herdr` | tmux-compatible | tmux-compatible CLIs wrapped by `TmuxCompatibleMultiplexer`. |
 
-The tmux/zellij session is auto-named `workstreams-<project>`.
+**Auto-detect** — you normally don't pick one. `load_config` resolves the
+platform default at startup:
+
+```
+macOS   → tmux first, then zellij, nami, lmux, wmux
+Linux   → lmux first, then zellij, then tmux
+Windows → wmux first, then lmux, zellij, tmux
+```
+
+The first *installed* binary in that list wins — **and** for the
+tmux-compatible wrapper family (`nami` / `lmux` / `wmux` / `herdr`)
+workstreams validates that the binary actually exposes tmux-style verbs
+(`new-session` / `send-keys` / …) before committing. For example `lmux`
+v1 has a completely different CLI shape (`workspace.create`,
+`surface.send-key`) so the validator rejects it and auto-detect falls
+through to `zellij` or `tmux`. If you *know* your `lmux` build exposes
+the tmux dialect, pin it explicitly with `multiplexer: lmux` — the
+validator is only consulted on the `default` auto-pick path. If you want a specific one:
+
+- Set it in your `.workstreams.yaml` / `.json`: `multiplexer: zellij`
+- Or pass `--multiplexer zellij` on `init` / `start` / `dispatch` / `work`
+- Or run `workstreams init --choose` to interactively pick, which persists the
+  choice into your config file so later commands use it.
+
+The tmux/zellij/lmux/wmux session is auto-named `workstreams-<project>`.
 
 ### 3. Subagent
 The coding agent doing the work inside a workstream. This is deliberately **free-form**: `claude-code`, `codex`, `opencode`, `qwen-code`, `mimocode`, `hermes`, `kilo-code`, `cline`, or any label you want. There is no vendor lock-in — a subagent is just an identifier used in the event log. The agent that actually runs is whatever command you send into the pane (see `dispatch`/`work`).

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "workstreams-cli"
-version = "0.6.1"
+version = "0.6.2"
 description = "Visually dispatch coding-agent work to subagents in real terminal windows and monitor it in one dashboard - for any coding agent (Claude Code, Codex, OpenCode, Qwen Code, Hermes, Cline, and more)."
 readme = "README.md"
 requires-python = ">=3.9"

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/src/workstreams/__init__.py

@@ -42,7 +42,7 @@ from .confidence import (
     extract_score,
 )
 
-__version__ = "0.6.1"
+__version__ = "0.6.2"
 
 __all__ = [
     # models

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/src/workstreams/cli.py

@@ -98,7 +98,8 @@ def build_parser() -> argparse.ArgumentParser:
     # init
     init = common_parent("init")
     init.add_argument("--workstreams", type=int, default=4, help="Number of workstreams to create (default: 4)")
-    init.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None, help="Multiplexer type")
+    init.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None, help="Multiplexer type ('default' = auto-detect: tmux/mac, lmux/linux, wmux/win)")
+    init.add_argument("--choose", action="store_true", help="Interactively pick the multiplexer (writes choice to .workstreams.yaml)")
     init.add_argument("--layout", choices=["even-horizontal", "even-vertical", "main-horizontal", "tiled"], default=None)
     init.add_argument("--base-branch", default=None, help="Base branch (default: main)")
     init.add_argument("--mode", choices=["worktree", "branch"], default=None, help="worktree (isolated) or branch (shared dir)")
@@ -110,12 +111,12 @@ def build_parser() -> argparse.ArgumentParser:
     start = common_parent("start")
     start.add_argument("--workstream", type=int, help="Start a single workstream by ID")
     start.add_argument("--cmd", help="Override the command sent to each pane")
-    start.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
+    start.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
     start.add_argument("--layout", choices=["even-horizontal", "even-vertical", "main-horizontal", "tiled"], default=None)
 
     # attach
     attach = common_parent("attach")
-    attach.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
+    attach.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
     attach.add_argument("--session", help="Override session name")
 
     # status
@@ -162,7 +163,7 @@ def build_parser() -> argparse.ArgumentParser:
     dispatch.add_argument("--prompt", help="Prompt / task description sent to the pane")
     dispatch.add_argument("--agent", help="Agent binary to invoke (e.g. 'claude', 'codex', 'opencode run'). If omitted, sends --prompt verbatim to the pane.")
     dispatch.add_argument("--wait", action="store_true", help="Block until subagent reports done/failed")
-    dispatch.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
+    dispatch.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
 
     # work (run agent command directly)
     work = common_parent("work")
@@ -172,7 +173,7 @@ def build_parser() -> argparse.ArgumentParser:
     work.add_argument("--subagent", default="agent", help="Identifier used in event log")
     work.add_argument("--issue", type=int, default=0)
     work.add_argument("--wait", action="store_true", help="Block until terminal event")
-    work.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
+    work.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
 
     # run
     run = common_parent("run")
@@ -266,6 +267,13 @@ def _cmd_init(args) -> int:
         manager.config.mode = args.mode
     if args.agent:
         manager.config.agent = args.agent
+    # Interactive picker: ask the user which multiplexer to persist,
+    # then write it to the config file.
+    if getattr(args, "choose", False):
+        from .multiplexer import resolve_default_multiplexer
+        chosen = resolve_default_multiplexer(interactive=True)
+        manager.config.multiplexer = chosen
+        print(f"Multiplexer: {chosen} (persisted to config)")
     if args.no_worktrees:
         # Skip git worktree creation; just write config
         from .models import WorkstreamConfig

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/src/workstreams/config.py

@@ -80,9 +80,17 @@ def load_config(
     if not project:
         project = base_path.name or "myproject"
 
+    # Resolve the multiplexer: explicit config/env value wins; the literal
+    # string "default" (or absence) auto-detects the best installed
+    # multiplexer for this platform (tmux/mac, lmux/linux, wmux/win).
+    multiplexer = data.get("multiplexer") or os.environ.get("WORKSTREAMS_MULTIPLEXER") or "default"
+    if multiplexer == "default":
+        from .multiplexer import resolve_default_multiplexer
+        multiplexer = resolve_default_multiplexer(interactive=False)
+
     return WorkstreamsConfig(
         project=project,
-        multiplexer=data.get("multiplexer") or os.environ.get("WORKSTREAMS_MULTIPLEXER") or "tmux",
+        multiplexer=multiplexer,
         layout=data.get("layout") or os.environ.get("WORKSTREAMS_LAYOUT") or "even-horizontal",
         base_branch=data.get("base_branch") or os.environ.get("WORKSTREAMS_BASE_BRANCH") or "main",
         mode=data.get("mode") or os.environ.get("WORKSTREAMS_WORKTREE_MODE") or "worktree",

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/src/workstreams/models.py

@@ -39,7 +39,7 @@ class WorkstreamsConfig:
     """Project-level configuration."""
 
     project: str
-    multiplexer: str = "tmux"
+    multiplexer: str = "default"  # "default" = auto-detect platform best
     layout: str = "even-horizontal"
     base_branch: str = "main"
     mode: str = "worktree"  # worktree|branch

workstreams_cli-0.6.2/src/workstreams/multiplexer/__init__.py

@@ -0,0 +1,173 @@
+"""Terminal multiplexer implementations + platform-aware default detection."""
+
+import shutil
+import sys
+from typing import Dict
+
+from .base import MultiplexerBase
+from .tmux import TmuxMultiplexer
+from .zellij import ZellijMultiplexer
+from .tmux_compatible import TmuxCompatibleMultiplexer
+
+__all__ = [
+    "MultiplexerBase",
+    "TmuxMultiplexer",
+    "ZellijMultiplexer",
+    "get_multiplexer",
+    "resolve_default_multiplexer",
+]
+
+# Name -> binary that must be on PATH. The TmuxCompatibleMultiplexer wraps
+# any binary whose CLI is compatible with tmux (send-keys, new-window, ...).
+_TMUX_COMPATIBLE = {
+    "nami": "nami",
+    "lmux": "lmux",
+    "wmux": "wmux",
+    "herdr": "herdr",
+}
+
+# Ordered preference list per platform. We pick the FIRST that is installed.
+_PLATFORM_PREFERENCE = {
+    "win": ["wmux", "lmux", "zellij", "tmux"],
+    "mac": ["tmux", "zellij", "nami", "lmux", "wmux"],
+    "linux": ["lmux", "zellij", "tmux"],
+}
+
+
+def _installed(name: str) -> bool:
+    """Return True if the CLI binary for `name` is on PATH.
+
+    For tmux-compatible wrappers (lmux, wmux, nami, herdr) we additionally
+    require that the binary actually exposes a tmux-style command, because
+    'installed' alone is not sufficient — e.g. `lmux` has a completely
+    different CLI (`workspace.create`, `surface.send-key`) and is not
+    tmux-compatible despite the name.
+    """
+    if name in ("tmux", "zellij"):
+        binary = name
+    elif name in _TMUX_COMPATIBLE:
+        binary = _TMUX_COMPATIBLE[name]
+    else:
+        return False
+    if shutil.which(binary) is None:
+        return False
+    if name in _TMUX_COMPATIBLE:
+        return _supports_tmux_dialect(binary)
+    return True
+
+
+_tmux_dialect_cache: Dict[str, bool] = {}
+
+
+def _supports_tmux_dialect(binary: str) -> bool:
+    """Heuristic: does `binary` accept tmux-style subcommands?
+
+    Probing method:
+      1. Run `<binary> help` — look for canonical tmux verbs
+         (new-session / has-session / send-keys / capture-pane).
+      2. If that's inconclusive (tmux has no `help` subcommand and dumps
+         to stderr instead), run `<binary> new-session -P` and treat
+         "command not found" / "unknown command" in stderr as a negative.
+
+    For `lmux` the help text exposes `workspace.create` / `surface.send-key`
+    instead of the tmux verbs, so this probe correctly returns False and
+    auto-detect skips it — only an explicit user-configured `lmux` will
+    attempt the wrapper.
+    """
+    import subprocess as _sp
+    key = binary
+    if key in _tmux_dialect_cache:
+        return _tmux_dialect_cache[key]
+    result = False
+    try:
+        proc = _sp.run([binary, "help"], capture_output=True, text=True, timeout=5)
+        help_text = (proc.stdout or "") + (proc.stderr or "")
+        # Require BOTH a session verb and a key verb. `lmux` happens to
+        # mention "capture-pane" in one subcommand's description but is
+        # missing session.send-keys / new-session entirely, so a single
+        # hit is not enough to call it tmux-compatible.
+        has_session = any(m in help_text for m in ("new-session", "has-session"))
+        has_keys = any(m in help_text for m in ("send-keys", "send-text"))
+        result = has_session and has_keys
+    except (_sp.TimeoutExpired, FileNotFoundError, OSError):
+        result = False
+    if not result:
+        # Secondary probe: tmux has no `help`; `new-session -P` on a bad
+        # socket prints an error but the command exists. Only count as
+        # "no dialect" when we see an explicit unknown-command message.
+        try:
+            proc = _sp.run([binary, "new-session", "-P"],
+                           capture_output=True, text=True, timeout=5)
+            err = (proc.stderr or "").lower()
+            if proc.returncode != 0 and ("unknown command" in err or "invalid command" in err):
+                result = False
+        except (_sp.TimeoutExpired, FileNotFoundError, OSError):
+            pass
+    _tmux_dialect_cache[key] = result
+    return result
+
+
+def resolve_default_multiplexer(interactive: bool = False, quiet: bool = False) -> str:
+    """Pick the best available multiplexer for the current platform.
+
+    Returns a string name (tmux, zellij, lmux, wmux, ...). When
+    `interactive` and no preference is installed, asks the user. When
+    `quiet`, never prompts — falls back to the first available, or "tmux".
+    """
+    platform = sys.platform
+    if platform.startswith("win"):
+        key = "win"
+    elif platform == "darwin":
+        key = "mac"
+    else:
+        key = "linux"
+
+    preference = _PLATFORM_PREFERENCE[key]
+    available = [m for m in preference if _installed(m)]
+
+    primary = preference[0]
+    if _installed(primary):
+        return primary
+    if available:
+        return available[0]
+
+    # Nothing on the preference list is installed.
+    if interactive and sys.stdin.isatty():
+        options = [m for m in preference if _installed(m)] or _PLATFORM_PREFERENCE[key]
+        print("No preferred multiplexer found on this system. Available options:")
+        for i, opt in enumerate(options, start=1):
+            print(f"  {i}. {opt}")
+        print("Which one? [1]: ", end="", flush=True)
+        try:
+            choice = int(input().strip() or "1")
+        except (ValueError, EOFError):
+            choice = 1
+        return options[choice - 1] if 1 <= choice <= len(options) else options[0]
+
+    # Quiet / non-interactive: fall back to tmux (the most universal one).
+    if _installed("tmux"):
+        return "tmux"
+    return "tmux"  # the caller will surface the "install tmux" hint
+
+
+def get_multiplexer(name: str, config) -> MultiplexerBase:
+    """Get a multiplexer instance by name."""
+    if name == "default" or not name:
+        # Resolve the platform-aware default; the user can override this in
+        # .workstreams.yaml by setting `multiplexer: tmux` (or any other).
+        name = resolve_default_multiplexer(interactive=False)
+    multiplexers = {
+        "tmux": TmuxMultiplexer,
+        "zellij": ZellijMultiplexer,
+    }
+    if name in _TMUX_COMPATIBLE:
+        binary = _TMUX_COMPATIBLE[name]
+        return TmuxCompatibleMultiplexer(config, binary)
+    cls = multiplexers.get(name)
+    if not cls:
+        raise ValueError(
+            f"Unknown multiplexer: {name}. "
+            f"Supported: {', '.join(multiplexers)} plus tmux-compatible: {', '.join(_TMUX_COMPATIBLE)} "
+            f"or 'default' (auto-detect)."
+        )
+    return cls(config)

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/src/workstreams_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstreams-cli
-Version: 0.6.1
+Version: 0.6.2
 Summary: Visually dispatch coding-agent work to subagents in real terminal windows and monitor it in one dashboard - for any coding agent (Claude Code, Codex, OpenCode, Qwen Code, Hermes, Cline, and more).
 Author: Dream-Pixels-Forge
 License: MIT
@@ -114,7 +114,7 @@ pip install -e ".[yaml,dev]"   # dev extras add pytest
 Verify:
 
 ```bash
-workstreams --version   # -> workstreams 0.6.1
+workstreams --version   # -> workstreams 0.6.2
 ```
 
 > **Note:** every command also accepts `--json` to emit machine-readable output (where supported), which coding agents can parse. All read-side commands work without a multiplexer installed; only `start`/`dispatch`/`work`/`attach` need one.
@@ -139,10 +139,36 @@ The terminal tool that hosts the visible windows. `workstreams` currently suppor
 
 | Multiplexer | Layouts | Notes |
 |-------------|---------|-------|
-| `tmux` (default) | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
+| `default` (auto-detect) | per backend | **Picks the best multiplexer installed for your OS**: `tmux` on macOS, `lmux` on Linux, `wmux` on Windows — falling back to `zellij` when the platform primary is missing. This is now the out-of-the-box behaviour. |
+| `tmux` | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
 | `zellij` | tabs | One **tab per workstream**. Simpler scripting surface; `dispatch` targets the current tab only. |
+| `nami` / `lmux` / `wmux` / `herdr` | tmux-compatible | tmux-compatible CLIs wrapped by `TmuxCompatibleMultiplexer`. |
 
-The tmux/zellij session is auto-named `workstreams-<project>`.
+**Auto-detect** — you normally don't pick one. `load_config` resolves the
+platform default at startup:
+
+```
+macOS   → tmux first, then zellij, nami, lmux, wmux
+Linux   → lmux first, then zellij, then tmux
+Windows → wmux first, then lmux, zellij, tmux
+```
+
+The first *installed* binary in that list wins — **and** for the
+tmux-compatible wrapper family (`nami` / `lmux` / `wmux` / `herdr`)
+workstreams validates that the binary actually exposes tmux-style verbs
+(`new-session` / `send-keys` / …) before committing. For example `lmux`
+v1 has a completely different CLI shape (`workspace.create`,
+`surface.send-key`) so the validator rejects it and auto-detect falls
+through to `zellij` or `tmux`. If you *know* your `lmux` build exposes
+the tmux dialect, pin it explicitly with `multiplexer: lmux` — the
+validator is only consulted on the `default` auto-pick path. If you want a specific one:
+
+- Set it in your `.workstreams.yaml` / `.json`: `multiplexer: zellij`
+- Or pass `--multiplexer zellij` on `init` / `start` / `dispatch` / `work`
+- Or run `workstreams init --choose` to interactively pick, which persists the
+  choice into your config file so later commands use it.
+
+The tmux/zellij/lmux/wmux session is auto-named `workstreams-<project>`.
 
 ### 3. Subagent
 The coding agent doing the work inside a workstream. This is deliberately **free-form**: `claude-code`, `codex`, `opencode`, `qwen-code`, `mimocode`, `hermes`, `kilo-code`, `cline`, or any label you want. There is no vendor lock-in — a subagent is just an identifier used in the event log. The agent that actually runs is whatever command you send into the pane (see `dispatch`/`work`).

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/src/workstreams_cli.egg-info/SOURCES.txt

@@ -26,4 +26,5 @@ tests/test_confidence.py
 tests/test_config.py
 tests/test_event_log.py
 tests/test_models.py
+tests/test_multiplexer_default.py
 tests/test_notifier.py

{workstreams_cli-0.6.1 → workstreams_cli-0.6.2}/tests/test_config.py

@@ -64,7 +64,11 @@ def test_load_nonexistent_returns_default_project(tmp_path):
     loaded = load_config(project_dir, "fallback-proj")
     assert loaded is not None
     assert loaded.project == "fallback-proj"
-    assert loaded.multiplexer == "tmux"
+    # A bare load now auto-resolves the platform default multiplexer (e.g.
+    # lmux on Linux), so assert it's a *concrete* name, not the "default"
+    # sentinel.
+    assert loaded.multiplexer != "default"
+    assert loaded.multiplexer in {"tmux", "zellij", "lmux", "wmux", "nami", "herdr"}
 
 
 def test_load_json_when_no_yaml_present(tmp_path):

workstreams_cli-0.6.2/tests/test_multiplexer_default.py

@@ -0,0 +1,130 @@
+"""Tests for platform-aware default multiplexer resolution."""
+
+import sys
+sys.path.insert(0, "src")
+
+from unittest import mock
+from pathlib import Path
+
+from workstreams.multiplexer import (
+    resolve_default_multiplexer,
+    get_multiplexer,
+    _PLATFORM_PREFERENCE,
+    _installed,
+)
+from workstreams.models import WorkstreamsConfig
+
+
+def _cfg():
+    return WorkstreamsConfig(
+        project="p", multiplexer="default", layout="even-horizontal",
+        base_branch="main", workstreams=[], shared_deps=[], base_path=".",
+        agent="auto",
+    )
+
+
+def test_default_resolves_to_a_concrete_name():
+    # Whatever this machine has, "default" must never come back as "default".
+    name = resolve_default_multiplexer(interactive=False)
+    assert name != "default"
+    assert name in {"tmux", "zellij", "lmux", "wmux", "nami", "herdr"}
+
+
+def test_primary_wins_when_installed(monkeypatch):
+    # Simulate: only the platform primary is installed.
+    monkeypatch.setattr("workstreams.multiplexer._installed",
+                        lambda n: n == _PLATFORM_PREFERENCE["linux"][0])
+    got = resolve_default_multiplexer(interactive=False)
+    assert got == _PLATFORM_PREFERENCE["linux"][0]
+
+
+def test_falls_back_to_first_available_when_primary_missing(monkeypatch):
+    # Primary not installed, but the second preference is.
+    primary = _PLATFORM_PREFERENCE["linux"][0]
+    second = _PLATFORM_PREFERENCE["linux"][1]
+    monkeypatch.setattr("workstreams.multiplexer._installed",
+                        lambda n: n == second)
+    got = resolve_default_multiplexer(interactive=False)
+    assert got == second
+    assert got != primary
+
+
+def test_nothing_installed_returns_tmux(monkeypatch):
+    monkeypatch.setattr("workstreams.multiplexer._installed", lambda n: False)
+    got = resolve_default_multiplexer(interactive=False)
+    assert got == "tmux"
+
+
+def test_get_multiplexer_default_returns_concrete_class():
+    mux = get_multiplexer("default", _cfg())
+    # Should be one of the concrete multiplexer classes, not None / not default.
+    from workstreams.multiplexer import MultiplexerBase
+    assert isinstance(mux, MultiplexerBase)
+    assert mux.name != "default"
+
+
+def test_get_multiplexer_empty_string_resolves():
+    mux = get_multiplexer("", _cfg())
+    from workstreams.multiplexer import MultiplexerBase
+    assert isinstance(mux, MultiplexerBase)
+    assert mux.name != "default"
+
+
+def test_explicit_name_still_works(monkeypatch):
+    # "tmux" must be honored even if the resolver would pick otherwise.
+    monkeypatch.setattr("workstreams.multiplexer._installed", lambda n: False)
+    mux = get_multiplexer("tmux", _cfg())
+    assert mux.name == "tmux"
+
+
+def test_unknown_name_raises():
+    try:
+        get_multiplexer("definitely-not-a-mux", _cfg())
+        raised = False
+    except ValueError:
+        raised = True
+    assert raised, "unknown multiplexer name should raise ValueError"
+
+
+def test_platform_preference_lists_are_sane():
+    # Each platform's primary must be a known multiplexer name.
+    for key, pref in _PLATFORM_PREFERENCE.items():
+        assert len(pref) >= 3
+        for m in pref:
+            assert m in {"tmux", "zellij", "lmux", "wmux", "nami", "herdr"}
+
+def test_lmux_not_tmux_compatible(monkeypatch):
+    """Regression: lmux's CLI is workspace/surface-based, not tmux-
+    compatible. Even when installed, _installed('lmux') must return
+    False so auto-detect skips it and falls to zellij/tmux."""
+    import workstreams.multiplexer as m
+    m._tmux_dialect_cache.clear()
+    import shutil
+    monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/lmux" if name == "lmux" else None)
+    monkeypatch.setattr("workstreams.multiplexer._supports_tmux_dialect", lambda b: False)
+    assert m._installed("lmux") is False
+
+
+def test_zellij_dialect_recognised(monkeypatch):
+    """zellij IS in the platform list and we trust its CLI shape via
+    the explicit class; the dialect probe is only for the wrapper
+    family."""
+    import workstreams.multiplexer as m
+    m._tmux_dialect_cache.clear()
+    import shutil
+    monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/zellij")
+    # zellij goes through the non-wrapper path, so _installed is True
+    # purely based on `shutil.which`.
+    assert m._installed("zellij") is True
+
+
+def test_auto_detect_falls_past_incompatible_lmux(monkeypatch):
+    """On Linux, if only 'lmux' and 'zellij' are installed and lmux is
+    not tmux-compatible, auto-detect must return zellij."""
+    import workstreams.multiplexer as m
+    import shutil
+    m._tmux_dialect_cache.clear()
+    monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/lmux" if name in ("lmux","zellij") else None)
+    monkeypatch.setattr("workstreams.multiplexer._supports_tmux_dialect", lambda b: b == "zellij")
+    got = m.resolve_default_multiplexer(interactive=False)
+    assert got == "zellij"

workstreams_cli-0.6.1/src/workstreams/multiplexer/__init__.py

@@ -1,32 +0,0 @@
-"""Terminal multiplexer implementations."""
-"""Terminal multiplexer implementations."""
-
-from .base import MultiplexerBase
-from .tmux import TmuxMultiplexer
-from .zellij import ZellijMultiplexer
-from .tmux_compatible import TmuxCompatibleMultiplexer
-
-__all__ = ["MultiplexerBase", "TmuxMultiplexer", "ZellijMultiplexer", "get_multiplexer"]
-
-_TMUX_COMPATIBLE = {
-    "nami": "nami",
-    "lmux": "lmux",
-    "wmux": "wmux",
-    "herdr": "herdr",
-}
-
-def get_multiplexer(name: str, config) -> MultiplexerBase:
-    """Get a multiplexer instance by name."""
-    multiplexers = {
-        "tmux": TmuxMultiplexer,
-        "zellij": ZellijMultiplexer,
-    }
-    if name in _TMUX_COMPATIBLE:
-        binary = _TMUX_COMPATIBLE[name]
-        return TmuxCompatibleMultiplexer(config, binary)
-    cls = multiplexers.get(name)
-    if not cls:
-        raise ValueError(
-            f"Unknown multiplexer: {name}. Supported: {', '.join(multiplexers)} plus tmux-compatible: {', '.join(_TMUX_COMPATIBLE)}"
-        )
-    return cls(config)