fix: honor worktree config in TUI launches

Author: Bob Yang

cli.py

@@ -1247,6 +1247,34 @@ def _path_is_within_root(path: Path, root: Path) -> bool:
         return False
 
 
+def _worktree_slug(name: str, *, fallback: str = "session", max_len: int = 40) -> str:
+    """Return a filesystem/git-ref-safe slug for a human workspace name."""
+    slug = re.sub(r"[^a-z0-9._-]+", "-", str(name or "").strip().lower())
+    slug = re.sub(r"[-_.]{2,}", "-", slug).strip("-_.")
+    slug = slug[:max_len].strip("-_.")
+    return slug or fallback
+
+
+def _workspace_name_for_worktree(repo_root: str) -> str:
+    """Best-effort human workspace label for naming auto-created worktrees.
+
+    Prefer an explicit Hermes Project that owns the repo; otherwise fall back to
+    the repository directory name. This keeps bare ``hermes -w`` / configured
+    worktree launches human-readable without adding a new user-facing setting.
+    """
+    try:
+        from hermes_cli import projects_db as _projects_db
+
+        if _projects_db.projects_db_path().exists():
+            with _projects_db.connect_closing() as conn:
+                project = _projects_db.project_for_path(conn, repo_root)
+                if project is not None:
+                    return project.slug or project.name
+    except Exception as exc:
+        logger.debug("worktree workspace-name project lookup failed: %s", exc)
+    return Path(repo_root).name or "session"
+
+
 def _resolve_worktree_base(repo_root: str) -> tuple:
     """Resolve the freshest base ref to branch a new worktree from.
 
@@ -1322,7 +1350,11 @@ def _git(args, timeout=20):
     return "HEAD", "HEAD (local — could not reach remote)"
 
 
-def _setup_worktree(repo_root: str = None, sync_base: bool = True) -> Optional[Dict[str, str]]:
+def _setup_worktree(
+    repo_root: Optional[str] = None,
+    sync_base: bool = True,
+    workspace_name: Optional[str] = None,
+) -> Optional[Dict[str, str]]:
     """Create an isolated git worktree for this CLI session.
 
     Returns a dict with worktree metadata on success, None on failure.
@@ -1342,7 +1374,8 @@ def _setup_worktree(repo_root: str = None, sync_base: bool = True) -> Optional[D
         return None
 
     short_id = uuid.uuid4().hex[:8]
-    wt_name = f"hermes-{short_id}"
+    workspace_slug = _worktree_slug(workspace_name or _workspace_name_for_worktree(repo_root))
+    wt_name = f"hermes-{workspace_slug}-{short_id}"
     branch_name = f"hermes/{wt_name}"
 
     worktrees_dir = Path(repo_root) / ".worktrees"
@@ -1481,6 +1514,7 @@ def _setup_worktree(repo_root: str = None, sync_base: bool = True) -> Optional[D
         "branch": branch_name,
         "repo_root": repo_root,
         "base": base_ref,
+        "workspace_slug": workspace_slug,
     }
 
     print(f"\033[32m✓ Worktree created:\033[0m {wt_path}")
@@ -15269,7 +15303,13 @@ def main(
         # ── Git worktree isolation (#652) ──
         # Create an isolated worktree so this agent instance doesn't collide
         # with other agents working on the same repo.
-        use_worktree = worktree or w or CLI_CONFIG.get("worktree", False)
+        from hermes_cli.config import resolve_worktree_options
+
+        use_worktree, _sync_base = resolve_worktree_options(
+            CLI_CONFIG,
+            explicit_worktree=worktree,
+            short_flag=w,
+        )
         wt_info = None
         if use_worktree:
             # Prune stale worktrees from crashed/killed sessions
@@ -15279,8 +15319,7 @@ def main(
             # Branch the worktree from the freshly-fetched remote tip by
             # default so it starts current with the project. Opt out with
             # worktree_sync: false to branch from local HEAD instead.
-            _sync_base = CLI_CONFIG.get("worktree_sync", True)
-            wt_info = _setup_worktree(sync_base=_sync_base)
+            wt_info = _setup_worktree(repo_root=_repo, sync_base=_sync_base)
             if wt_info:
                 _active_worktree = wt_info
                 os.environ["TERMINAL_CWD"] = wt_info["path"]

hermes_cli/config.py

@@ -6035,6 +6035,21 @@ def load_config_readonly() -> Dict[str, Any]:
     return _load_config_impl(want_deepcopy=False)
 
 
+def resolve_worktree_options(
+    config: Optional[Dict[str, Any]] = None,
+    *,
+    explicit_worktree: bool = False,
+    short_flag: bool = False,
+) -> tuple[bool, bool]:
+    """Resolve worktree enablement and base-sync behavior from flags + config."""
+    cfg = config if isinstance(config, dict) else load_config_readonly()
+    use_worktree = bool(
+        explicit_worktree or short_flag or cfg.get("worktree", False)
+    )
+    sync_base = bool(cfg.get("worktree_sync", True))
+    return use_worktree, sync_base
+
+
 def write_platform_config_field(
     platform_key: str,
     field_key: str,

hermes_cli/main.py

@@ -1973,6 +1973,25 @@ def _resolve_tui_heap_mb(default_mb: int = 8192) -> int:
     return max(1536, sized) if limit_mb > 2048 else sized
 
 
+def _resolve_tui_worktree_options(
+    explicit_worktree: bool = False,
+    config: Optional[dict] = None,
+) -> tuple[bool, bool]:
+    """Return ``(use_worktree, sync_base)`` for a TUI launch.
+
+    Classic CLI worktree setup already honors the persistent ``worktree`` and
+    ``worktree_sync`` config keys. TUI startup needs the same decision in the
+    Python wrapper before spawning Node, because the child receives its working
+    directory via ``HERMES_CWD`` / ``TERMINAL_CWD``.
+    """
+    try:
+        from hermes_cli.config import resolve_worktree_options
+
+        return resolve_worktree_options(config, explicit_worktree=explicit_worktree)
+    except Exception:
+        return bool(explicit_worktree), True
+
+
 def _launch_tui(
     resume_session_id: Optional[str] = None,
     tui_dev: bool = False,
@@ -1996,9 +2015,12 @@ def _launch_tui(
     import tempfile
 
     env = os.environ.copy()
+    config = None
     try:
-        from hermes_cli.config import apply_terminal_config_to_env
-        apply_terminal_config_to_env(env=env)
+        from hermes_cli.config import apply_terminal_config_to_env, load_config_readonly
+
+        config = load_config_readonly() or {}
+        apply_terminal_config_to_env(env=env, config=config)
     except Exception:
         logger.debug("Failed to apply terminal config bridge for TUI launch", exc_info=True)
     active_session_fd, active_session_file = tempfile.mkstemp(
@@ -2014,7 +2036,8 @@ def _launch_tui(
     env.setdefault("NODE_ENV", "development" if tui_dev else "production")
 
     wt_info = None
-    if worktree:
+    use_worktree, sync_base = _resolve_tui_worktree_options(worktree, config=config)
+    if use_worktree:
         try:
             from cli import (
                 _cleanup_worktree,
@@ -2026,7 +2049,7 @@ def _launch_tui(
             repo = _git_repo_root()
             if repo:
                 _prune_stale_worktrees(repo)
-            wt_info = _setup_worktree()
+            wt_info = _setup_worktree(repo_root=repo, sync_base=sync_base)
         except Exception as exc:
             print(f"✗ Failed to create TUI worktree: {exc}", file=sys.stderr)
             wt_info = None
@@ -2102,9 +2125,9 @@ def _launch_tui(
     if resume_session_id:
         env["HERMES_TUI_RESUME"] = resume_session_id
 
-    argv, cwd = _make_tui_argv(tui_dir, tui_dev)
     code: Optional[int] = None
     try:
+        argv, cwd = _make_tui_argv(tui_dir, tui_dev)
         try:
             code = subprocess.call(argv, cwd=str(cwd), env=env)
         except KeyboardInterrupt:

tests/cli/test_worktree_sync_base.py

@@ -122,3 +122,55 @@ def test_default_is_sync_true(self, remote_and_clone):
         info = cli._setup_worktree(str(clone))
         assert info is not None
         assert _head(info["path"]) == remote_head
+
+    def test_workspace_name_is_reflected_in_worktree_and_branch(self, remote_and_clone):
+        clone, _, _ = remote_and_clone
+        info = cli._setup_worktree(
+            str(clone), sync_base=False, workspace_name="JARVIS Workspace!"
+        )
+        assert info is not None
+
+        leaf = Path(info["path"]).name
+        assert leaf.startswith("hermes-jarvis-workspace-")
+        assert info["branch"].startswith("hermes/hermes-jarvis-workspace-")
+        assert info["workspace_slug"] == "jarvis-workspace"
+
+    def test_workspace_name_falls_back_to_repo_directory(self, remote_and_clone):
+        clone, _, _ = remote_and_clone
+        info = cli._setup_worktree(str(clone), sync_base=False)
+        assert info is not None
+
+        leaf = Path(info["path"]).name
+        assert leaf.startswith("hermes-clone-")
+        assert info["branch"].startswith("hermes/hermes-clone-")
+        assert info["workspace_slug"] == "clone"
+
+    def test_workspace_name_lookup_does_not_create_projects_db(self, remote_and_clone):
+        from hermes_cli import projects_db
+
+        clone, _, _ = remote_and_clone
+        db_path = projects_db.projects_db_path()
+        assert not db_path.exists()
+
+        assert cli._workspace_name_for_worktree(str(clone)) == "clone"
+        assert not db_path.exists()
+
+    def test_workspace_name_uses_owning_project_slug(self, remote_and_clone):
+        from hermes_cli import projects_db
+
+        clone, _, _ = remote_and_clone
+        with projects_db.connect_closing() as conn:
+            projects_db.create_project(
+                conn,
+                name="Bob Workspace",
+                slug="bob-workspace",
+                primary_path=str(clone),
+            )
+
+        info = cli._setup_worktree(str(clone), sync_base=False)
+        assert info is not None
+
+        leaf = Path(info["path"]).name
+        assert leaf.startswith("hermes-bob-workspace-")
+        assert info["branch"].startswith("hermes/hermes-bob-workspace-")
+        assert info["workspace_slug"] == "bob-workspace"

tests/hermes_cli/test_tui_resume_flow.py

@@ -962,6 +962,121 @@ def test_launch_tui_applies_terminal_backend_config(
     assert captured["env"]["TERMINAL_DOCKER_EXTRA_ARGS"] == '["--network=host"]'
 
 
+def test_resolve_tui_worktree_options_uses_persistent_config(main_mod):
+    config = {"worktree": True, "worktree_sync": False}
+
+    assert main_mod._resolve_tui_worktree_options(
+        explicit_worktree=False, config=config
+    ) == (
+        True,
+        False,
+    )
+    assert main_mod._resolve_tui_worktree_options(
+        explicit_worktree=True, config=config
+    ) == (
+        True,
+        False,
+    )
+
+
+def test_launch_tui_creates_worktree_from_persistent_config(monkeypatch, main_mod):
+    import cli as cli_mod
+    import hermes_cli.config as config_mod
+
+    captured = {}
+    wt_info = {
+        "path": "/repo/.worktrees/hermes-jarvis-deadbeef",
+        "branch": "hermes/hermes-jarvis-deadbeef",
+        "repo_root": "/repo",
+    }
+
+    monkeypatch.setattr(
+        config_mod,
+        "load_config_readonly",
+        lambda: {"worktree": True, "worktree_sync": False},
+    )
+    monkeypatch.setattr(
+        config_mod, "apply_terminal_config_to_env", lambda **_kwargs: None
+    )
+    monkeypatch.setattr(
+        main_mod,
+        "_make_tui_argv",
+        lambda tui_dir, tui_dev: (["node", "dist/entry.js"], Path(".")),
+    )
+    monkeypatch.setattr(cli_mod, "_git_repo_root", lambda: "/repo")
+    monkeypatch.setattr(
+        cli_mod,
+        "_prune_stale_worktrees",
+        lambda repo: captured.update({"pruned_repo": repo}),
+    )
+
+    def fake_setup_worktree(*, repo_root=None, sync_base=True):
+        captured["repo_root"] = repo_root
+        captured["sync_base"] = sync_base
+        return wt_info
+
+    monkeypatch.setattr(cli_mod, "_setup_worktree", fake_setup_worktree)
+    monkeypatch.setattr(
+        cli_mod,
+        "_cleanup_worktree",
+        lambda info: captured.update({"cleaned": info}),
+    )
+    monkeypatch.setattr(
+        main_mod.subprocess,
+        "call",
+        lambda argv, cwd=None, env=None: captured.update({"env": env}) or 1,
+    )
+
+    with pytest.raises(SystemExit):
+        main_mod._launch_tui(worktree=False)
+
+    assert captured["pruned_repo"] == "/repo"
+    assert captured["repo_root"] == "/repo"
+    assert captured["sync_base"] is False
+    assert captured["env"]["HERMES_CWD"] == wt_info["path"]
+    assert captured["env"]["TERMINAL_CWD"] == wt_info["path"]
+    assert captured["cleaned"] is wt_info
+
+
+def test_launch_tui_cleans_worktree_when_tui_argv_setup_fails(monkeypatch, main_mod):
+    import cli as cli_mod
+    import hermes_cli.config as config_mod
+
+    captured = {}
+    wt_info = {
+        "path": "/repo/.worktrees/hermes-jarvis-deadbeef",
+        "branch": "hermes/hermes-jarvis-deadbeef",
+        "repo_root": "/repo",
+    }
+
+    monkeypatch.setattr(
+        config_mod,
+        "load_config_readonly",
+        lambda: {"worktree": True, "worktree_sync": False},
+    )
+    monkeypatch.setattr(
+        config_mod, "apply_terminal_config_to_env", lambda **_kwargs: None
+    )
+    monkeypatch.setattr(cli_mod, "_git_repo_root", lambda: "/repo")
+    monkeypatch.setattr(cli_mod, "_prune_stale_worktrees", lambda repo: None)
+    monkeypatch.setattr(cli_mod, "_setup_worktree", lambda **_kwargs: wt_info)
+    monkeypatch.setattr(
+        cli_mod,
+        "_cleanup_worktree",
+        lambda info: captured.update({"cleaned": info}),
+    )
+    monkeypatch.setattr(
+        main_mod,
+        "_make_tui_argv",
+        lambda tui_dir, tui_dev: (_ for _ in ()).throw(RuntimeError("missing node")),
+    )
+
+    with pytest.raises(RuntimeError, match="missing node"):
+        main_mod._launch_tui(worktree=False)
+
+    assert captured["cleaned"] is wt_info
+
+
 def test_launch_tui_exit_code_42_relaunches_update(monkeypatch, main_mod):
     from unittest.mock import patch