@team-agent/installer 0.1.7 → 0.1.10

package/src/team_agent/runtime.py

@@ -54,6 +54,8 @@ TMUX_PANE_FORMAT = (
     "#{pane_current_path}\t#{session_attached}"
 )
 HEALTH_STATUSES = {"RUNNING", "IDLE", "AWAITING_APPROVAL", "BLOCKED", "ERROR", "DONE"}
+GHOSTTY_DISPLAY_BACKENDS = {"ghostty", "ghostty_window", "ghostty_workspace"}
+GHOSTTY_WORKSPACE_PANES_PER_WINDOW = 3
 PEEK_MAX_LINES = 80
 PEEK_SEARCH_SCAN_LINES = 300
 PEEK_MAX_MATCHES = 5
@@ -226,6 +228,22 @@ def _spec_team_dir(spec_path: Path, workspace: Path) -> Path:
     return workspace.resolve() / ".team" / "current"
 
 
+def _is_team_doc_dir(team_dir: Path) -> bool:
+    return (team_dir / "TEAM.md").exists() and (team_dir / "agents").is_dir()
+
+
+def _compile_team_dir_spec(team_dir: Path, workspace: Path) -> dict[str, Any]:
+    from team_agent.compiler import compile_team
+
+    spec_path = team_dir / "team.spec.yaml"
+    compiled = compile_team(team_dir, spec_path)
+    if compiled["spec"].get("context", {}).get("state_file") == "team_state.md":
+        state_file = str(team_dir.relative_to(workspace) / "team_state.md") if team_dir.is_relative_to(workspace) else "team_state.md"
+        compiled["spec"]["context"]["state_file"] = state_file
+        spec_path.write_text(dumps(compiled["spec"]), encoding="utf-8")
+    return compiled
+
+
 def _attach_team_profile_dirs(spec: dict[str, Any], spec_path: Path, workspace: Path | None = None, team_dir: Path | None = None) -> None:
     workspace = workspace.resolve() if workspace else workspace_from_spec(spec, spec_path)
     team_dir = team_dir.resolve() if team_dir else _spec_team_dir(spec_path, workspace)
@@ -456,10 +474,16 @@ def launch(
             timeout_s=1.5,
             exclude_session_ids=known_session_ids,
         )
-        if state.get("display_backend") in {"ghostty", "ghostty_window"}:
+        if state.get("display_backend") in GHOSTTY_DISPLAY_BACKENDS:
             display_jobs.append((agent["id"], agent))
         started.append({"agent_id": agent["id"], "provider": agent["provider"], "window": agent["id"]})
-    for agent_id, display in _open_worker_displays(workspace, session_name, display_jobs, event_log).items():
+    for agent_id, display in _open_worker_displays(
+        workspace,
+        session_name,
+        display_jobs,
+        event_log,
+        state.get("display_backend", "none"),
+    ).items():
         if agent_id in state["agents"]:
             state["agents"][agent_id]["display"] = display
     save_runtime_state(workspace, state)
@@ -1753,15 +1777,21 @@ def shutdown(workspace: Path, keep_logs: bool = True) -> dict[str, Any]:
             if proc.returncode == 0:
                 log_path.write_text(proc.stdout, encoding="utf-8")
                 captured.append(str(log_path))
+        _close_ghostty_workspace(state, event_log)
         for agent_id, agent_state in state.get("agents", {}).items():
             _close_ghostty_display(agent_id, agent_state, event_log)
             closed_displays.add(agent_id)
         proc = run_cmd(["tmux", "kill-session", "-t", session_name], timeout=10)
         if proc.returncode != 0:
-            raise RuntimeError(f"tmux kill-session failed: {proc.stderr.strip()}")
-        event_log.write("shutdown.kill_session", session=session_name, keep_logs=keep_logs, captured=captured)
+            if "can't find session" in proc.stderr:
+                event_log.write("shutdown.idempotent", session=session_name, reason="session disappeared before kill")
+            else:
+                raise RuntimeError(f"tmux kill-session failed: {proc.stderr.strip()}")
+        else:
+            event_log.write("shutdown.kill_session", session=session_name, keep_logs=keep_logs, captured=captured)
     else:
         event_log.write("shutdown.idempotent", session=session_name, reason="session missing")
+        _close_ghostty_workspace(state, event_log)
     for agent_id, agent_state in state.get("agents", {}).items():
         if agent_id not in closed_displays:
             _close_ghostty_display(agent_id, agent_state, event_log)
@@ -1792,10 +1822,16 @@ def shutdown(workspace: Path, keep_logs: bool = True) -> dict[str, Any]:
 def restart(workspace: Path, allow_fresh: bool = False, team: str | None = None) -> dict[str, Any]:
     state = _select_restart_state(workspace, team)
     spec_path = Path(state.get("spec_path", workspace / "team.spec.yaml"))
-    if not spec_path.exists():
-        raise RuntimeError(f"missing spec for restart: {spec_path}")
-    spec = load_spec(spec_path)
     team_dir = Path(str(state.get("team_dir"))) if state.get("team_dir") else _spec_team_dir(spec_path, workspace)
+    if _is_team_doc_dir(team_dir):
+        compiled = _compile_team_dir_spec(team_dir, workspace)
+        spec = compiled["spec"]
+        spec_path = team_dir / "team.spec.yaml"
+        state["spec_path"] = str(spec_path)
+    else:
+        if not spec_path.exists():
+            raise RuntimeError(f"missing spec for restart: {spec_path}")
+        spec = load_spec(spec_path)
     _attach_team_profile_dirs(spec, spec_path, workspace, team_dir)
     ensure_workspace_dirs(workspace)
     event_log = EventLog(workspace)
@@ -1810,6 +1846,9 @@ def restart(workspace: Path, allow_fresh: bool = False, team: str | None = None)
         raise RuntimeError(_tmux_session_conflict_error(session_name))
     runtime_cfg = _effective_runtime_config(spec.get("runtime", {}))
     display_backend = spec.get("runtime", {}).get("display_backend", state.get("display_backend", "none"))
+    _close_ghostty_workspace(state, event_log)
+    for agent_id, agent_state in state.get("agents", {}).items():
+        _close_ghostty_display(agent_id, agent_state, event_log)
     state["display_backend"] = display_backend
     restart_agents = [
         agent
@@ -1995,7 +2034,7 @@ def restart(workspace: Path, allow_fresh: bool = False, team: str | None = None)
                 timeout_s=1.5,
                 exclude_session_ids=known_session_ids,
             )
-        if display_backend in {"ghostty", "ghostty_window"}:
+        if display_backend in GHOSTTY_DISPLAY_BACKENDS:
             display_jobs.append((agent["id"], agent))
         new_agents[agent["id"]] = agent_state
         restarted.append(
@@ -2006,7 +2045,7 @@ def restart(workspace: Path, allow_fresh: bool = False, team: str | None = None)
                 "display_target": None,
             }
         )
-    display_results = _open_worker_displays(workspace, session_name, display_jobs, event_log)
+    display_results = _open_worker_displays(workspace, session_name, display_jobs, event_log, display_backend)
     for agent_id, display in display_results.items():
         if agent_id in new_agents:
             new_agents[agent_id]["display"] = display
@@ -2072,6 +2111,10 @@ def _start_agent_unlocked(workspace: Path, agent_id: str, force: bool, open_disp
             display = agent_state.get("display") or {}
             if display.get("status") != "opened":
                 agent_state["display"] = _open_ghostty_worker_window(workspace, session_name, agent_id, agent, event_log)
+        elif open_display and state.get("display_backend") == "ghostty_workspace":
+            display = agent_state.get("display") or {}
+            if display.get("status") != "opened":
+                agent_state["display"] = _open_ghostty_workspace_agent_display(session_name, agent_id, agent, display, event_log)
         state["agents"][agent_id] = agent_state
         save_runtime_state(workspace, state)
         write_team_state(workspace, spec, state)
@@ -2248,6 +2291,14 @@ def _start_agent_unlocked(workspace: Path, agent_id: str, force: bool, open_disp
         _capture_agent_session(workspace, agent_id, agent_state, event_log, timeout_s=1.5, exclude_session_ids=known_session_ids)
     if open_display and state.get("display_backend") in {"ghostty", "ghostty_window"}:
         agent_state["display"] = _open_ghostty_worker_window(workspace, session_name, agent_id, agent, event_log)
+    elif open_display and state.get("display_backend") == "ghostty_workspace":
+        agent_state["display"] = _open_ghostty_workspace_agent_display(
+            session_name,
+            agent_id,
+            agent,
+            previous.get("display") or {},
+            event_log,
+        )
     state["agents"][agent_id] = agent_state
     save_runtime_state(workspace, state)
     store = MessageStore(workspace)
@@ -3030,7 +3081,7 @@ def preflight(team_dir: Path) -> dict[str, Any]:
     ok = ok and bool(tmux_path)
     ghostty = _ghostty_command()
     ghostty_check = {"name": "ghostty", "ok": bool(ghostty), "path": ghostty, "required": False}
-    if spec and spec.get("runtime", {}).get("display_backend") in {"ghostty", "ghostty_window"}:
+    if spec and spec.get("runtime", {}).get("display_backend") in GHOSTTY_DISPLAY_BACKENDS:
         ghostty_check["required"] = True
         ok = ok and bool(ghostty)
     checks.append(ghostty_check)
@@ -3105,18 +3156,12 @@ def quick_start(
     fresh: bool = False,
     team_id: str | None = None,
 ) -> dict[str, Any]:
-    from team_agent.compiler import compile_team
-
     team_dir = _prepare_quick_start_team(agents_dir.resolve(), Path.cwd().resolve(), name, team_id=team_id)
     workspace = team_workspace(team_dir)
     ensure_workspace_dirs(workspace)
     _ensure_profiles_for_roles(team_dir)
+    compiled = _compile_team_dir_spec(team_dir, workspace)
     spec_path = team_dir / "team.spec.yaml"
-    compiled = compile_team(team_dir, spec_path)
-    if compiled["spec"].get("context", {}).get("state_file") == "team_state.md":
-        state_file = str(team_dir.relative_to(workspace) / "team_state.md") if team_dir.is_relative_to(workspace) else "team_state.md"
-        compiled["spec"]["context"]["state_file"] = state_file
-        spec_path.write_text(dumps(compiled["spec"]), encoding="utf-8")
     existing = _quick_start_existing_context(workspace, compiled["spec"]["runtime"]["session_name"])
     if existing and not fresh:
         return {
@@ -4508,14 +4553,34 @@ def _ghostty_command() -> str | None:
     )
 
 
+def _ghostty_app_exists() -> bool:
+    return Path("/Applications/Ghostty.app").exists()
+
+
+def _ghostty_pids_by_title(title: str, wait_s: float = 0.0) -> list[int]:
+    deadline = time.monotonic() + max(wait_s, 0.0)
+    while True:
+        pgrep = run_cmd(["pgrep", "-f", f"--title={title}"], timeout=5)
+        if pgrep.returncode == 0:
+            pids = [int(pid) for pid in pgrep.stdout.split() if pid.isdigit()]
+            if pids:
+                return pids
+        if time.monotonic() >= deadline:
+            return []
+        time.sleep(0.2)
+
+
 def _open_worker_displays(
     workspace: Path,
     session_name: str,
     jobs: list[tuple[str, dict[str, Any]]],
     event_log: EventLog,
+    display_backend: str = "ghostty_window",
 ) -> dict[str, dict[str, Any]]:
     if not jobs:
         return {}
+    if display_backend == "ghostty_workspace":
+        return _open_ghostty_workspace(workspace, session_name, jobs, event_log)
     if len(jobs) == 1:
         agent_id, agent = jobs[0]
         return {agent_id: _open_ghostty_worker_window(workspace, session_name, agent_id, agent, event_log)}
@@ -4550,7 +4615,7 @@ def _open_ghostty_worker_window(
     agent: dict[str, Any],
     event_log: EventLog,
 ) -> dict[str, Any]:
-    if not Path("/Applications/Ghostty.app").exists():
+    if not _ghostty_app_exists():
         blocker = {
             "backend": "ghostty_window",
             "status": "blocked",
@@ -4592,15 +4657,130 @@ def _open_ghostty_worker_window(
     if proc.returncode != 0:
         display["reason"] = proc.stderr.strip() or proc.stdout.strip() or "open Ghostty.app failed"
     else:
-        time.sleep(0.2)
-        pgrep = run_cmd(["pgrep", "-f", f"--title={title}"], timeout=5)
-        if pgrep.returncode == 0:
-            display["pids"] = [int(pid) for pid in pgrep.stdout.split() if pid.isdigit()]
-            display["pid"] = display["pids"][0] if display["pids"] else None
+        display["pids"] = _ghostty_pids_by_title(title, wait_s=3.0)
+        display["pid"] = display["pids"][0] if display["pids"] else None
     event_log.write("display.ghostty_window", agent_id=agent["id"], **display)
     return display
 
 
+def _open_ghostty_workspace(
+    workspace: Path,
+    session_name: str,
+    jobs: list[tuple[str, dict[str, Any]]],
+    event_log: EventLog,
+) -> dict[str, dict[str, Any]]:
+    if not _ghostty_app_exists():
+        return _ghostty_workspace_blocked(jobs, event_log, "ghostty_app_missing")
+    aggregator_session = _ghostty_workspace_aggregator_name(session_name)
+    linked_results = _prepare_ghostty_workspace_linked_sessions(session_name, jobs)
+    displays: dict[str, dict[str, Any]] = {}
+    linked_jobs: list[tuple[str, dict[str, Any], str]] = []
+    for agent_id, agent in jobs:
+        linked = linked_results.get(agent_id, {})
+        linked_session = linked.get("linked_session") or _ghostty_display_session_name(session_name, agent_id)
+        if linked.get("ok"):
+            linked_jobs.append((agent_id, agent, linked_session))
+            continue
+        displays.update(
+            _ghostty_workspace_blocked(
+                [(agent_id, agent)],
+                event_log,
+                linked.get("reason", "display_session_create_failed"),
+                aggregator_session=aggregator_session,
+                linked_sessions={agent_id: linked_session},
+                error=linked.get("error"),
+                target=f"{session_name}:{agent_id}",
+            )
+        )
+    if not linked_jobs:
+        return displays
+    prepared = _prepare_ghostty_workspace_aggregator(aggregator_session, linked_jobs)
+    if not prepared["ok"]:
+        _kill_ghostty_workspace_linked_sessions([linked_session for _agent_id, _agent, linked_session in linked_jobs])
+        displays.update(
+            _ghostty_workspace_blocked(
+                [(agent_id, agent) for agent_id, agent, _linked_session in linked_jobs],
+                event_log,
+                prepared["reason"],
+                aggregator_session=aggregator_session,
+                linked_sessions={agent_id: linked_session for agent_id, _agent, linked_session in linked_jobs},
+                error=prepared.get("error"),
+                target=prepared.get("target"),
+            )
+        )
+        return displays
+    title = f"team-agent:{session_name}:workspace"
+    launch_args = _ghostty_attach_args(aggregator_session, title)
+    proc = run_cmd(launch_args, timeout=10)
+    if proc.returncode != 0:
+        run_cmd(["tmux", "kill-session", "-t", aggregator_session], timeout=10)
+        _kill_ghostty_workspace_linked_sessions([linked_session for _agent_id, _agent, linked_session in linked_jobs])
+        displays.update(
+            _ghostty_workspace_blocked(
+                [(agent_id, agent) for agent_id, agent, _linked_session in linked_jobs],
+                event_log,
+                "open Ghostty.app failed",
+                aggregator_session=aggregator_session,
+                linked_sessions={agent_id: linked_session for agent_id, _agent, linked_session in linked_jobs},
+                error=proc.stderr.strip() or proc.stdout.strip(),
+            )
+        )
+        return displays
+    pids = _ghostty_pids_by_title(title, wait_s=3.0)
+    panes = {pane["agent_id"]: pane for pane in prepared["panes"]}
+    for agent_id, agent, linked_session in linked_jobs:
+        pane = panes.get(agent_id, {})
+        display = {
+            "backend": "ghostty_workspace",
+            "status": "opened",
+            "title": title,
+            "pane_title": pane.get("title") or _ghostty_workspace_pane_title(agent),
+            "target": f"{session_name}:{agent_id}",
+            "linked_session": linked_session,
+            "aggregator_session": aggregator_session,
+            "display_session": aggregator_session,
+            "workspace_window": pane.get("window_name"),
+            "pane_id": pane.get("pane_id"),
+            "launch_args": launch_args,
+            "pid": pids[0] if pids else None,
+            "pids": pids,
+            "tty": None,
+            "fallback": "tmux_headless",
+            "note": "Ghostty opens one aggregator tmux session; each pane attaches to a distinct linked session pinned to one base worker window, so runtime injection remains session:agent_id addressed.",
+        }
+        event_log.write("display.ghostty_workspace", agent_id=agent_id, **display)
+        displays[agent_id] = display
+    return displays
+
+
+def _ghostty_workspace_blocked(
+    jobs: list[tuple[str, dict[str, Any]]],
+    event_log: EventLog,
+    reason: str,
+    aggregator_session: str | None = None,
+    linked_sessions: dict[str, str] | None = None,
+    error: str | None = None,
+    target: str | None = None,
+) -> dict[str, dict[str, Any]]:
+    displays: dict[str, dict[str, Any]] = {}
+    for agent_id, _agent in jobs:
+        linked_session = (linked_sessions or {}).get(agent_id)
+        display = {
+            "backend": "ghostty_workspace",
+            "status": "blocked",
+            "reason": reason,
+            "error": error,
+            "target": target or f"{agent_id}",
+            "linked_session": linked_session,
+            "aggregator_session": aggregator_session,
+            "display_session": aggregator_session,
+            "fallback": "tmux_headless",
+        }
+        event_log.write("display.ghostty_workspace_blocked", agent_id=agent_id, **display)
+        displays[agent_id] = display
+    return displays
+
+
 def _ghostty_display_session_name(session_name: str, window_name: str) -> str:
     raw = f"{session_name}:{window_name}"
     digest = hashlib.sha1(raw.encode("utf-8")).hexdigest()[:8]
@@ -4628,6 +4808,336 @@ def _prepare_ghostty_display_session(session_name: str, window_name: str, displa
     return {"ok": True, "display_session": display_session}
 
 
+def _ghostty_workspace_aggregator_name(session_name: str) -> str:
+    raw = f"{session_name}:workspace"
+    digest = hashlib.sha1(raw.encode("utf-8")).hexdigest()[:8]
+    safe_session = re.sub(r"[^A-Za-z0-9_.-]", "_", session_name)[:80].strip("._-") or "team"
+    return f"{safe_session}__display__workspace__{digest}"
+
+
+def _ghostty_workspace_window_name(index: int) -> str:
+    return "overview" if index == 0 else f"overview-{index + 1}"
+
+
+def _ghostty_workspace_pane_command(linked_session: str) -> str:
+    return f"TMUX= tmux attach-session -t {shlex.quote(linked_session)}"
+
+
+def _ghostty_workspace_pane_title(agent: dict[str, Any]) -> str:
+    return f"team-agent:{agent['id']}:{agent.get('role', '')}"
+
+
+def _prepare_ghostty_workspace_linked_sessions(
+    session_name: str,
+    jobs: list[tuple[str, dict[str, Any]]],
+) -> dict[str, dict[str, Any]]:
+    def prepare(agent_id: str) -> dict[str, Any]:
+        linked_session = _ghostty_display_session_name(session_name, agent_id)
+        result = _prepare_ghostty_display_session(session_name, agent_id, linked_session)
+        result["linked_session"] = linked_session
+        return result
+
+    if len(jobs) == 1:
+        agent_id, _agent = jobs[0]
+        return {agent_id: prepare(agent_id)}
+    results: dict[str, dict[str, Any]] = {}
+    max_workers = min(4, len(jobs))
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {executor.submit(prepare, agent_id): agent_id for agent_id, _agent in jobs}
+        for future in as_completed(futures):
+            agent_id = futures[future]
+            try:
+                results[agent_id] = future.result()
+            except Exception as exc:
+                results[agent_id] = {
+                    "ok": False,
+                    "reason": "display_session_create_exception",
+                    "error": str(exc),
+                    "linked_session": _ghostty_display_session_name(session_name, agent_id),
+                }
+    return results
+
+
+def _prepare_ghostty_workspace_aggregator(
+    aggregator_session: str,
+    linked_jobs: list[tuple[str, dict[str, Any], str]],
+) -> dict[str, Any]:
+    if _tmux_session_exists(aggregator_session):
+        proc = run_cmd(["tmux", "kill-session", "-t", aggregator_session], timeout=10)
+        if proc.returncode != 0:
+            return {"ok": False, "reason": "display_session_cleanup_failed", "error": proc.stderr.strip()}
+
+    def fail(reason: str, proc: Any | None = None, target: str | None = None) -> dict[str, Any]:
+        run_cmd(["tmux", "kill-session", "-t", aggregator_session], timeout=10)
+        result = {"ok": False, "reason": reason}
+        if proc is not None:
+            result["error"] = proc.stderr.strip()
+        if target:
+            result["target"] = target
+        return result
+
+    panes: list[dict[str, Any]] = []
+    for window_index, start in enumerate(range(0, len(linked_jobs), GHOSTTY_WORKSPACE_PANES_PER_WINDOW)):
+        window_name = _ghostty_workspace_window_name(window_index)
+        window_jobs = linked_jobs[start : start + GHOSTTY_WORKSPACE_PANES_PER_WINDOW]
+        first_agent_id, first_agent, first_linked_session = window_jobs[0]
+        if window_index == 0:
+            proc = run_cmd(
+                [
+                    "tmux",
+                    "new-session",
+                    "-d",
+                    "-P",
+                    "-F",
+                    "#{pane_id}",
+                    "-s",
+                    aggregator_session,
+                    "-n",
+                    window_name,
+                    _ghostty_workspace_pane_command(first_linked_session),
+                ],
+                timeout=10,
+            )
+            if proc.returncode != 0:
+                return {"ok": False, "reason": "display_session_create_failed", "error": proc.stderr.strip()}
+        else:
+            proc = run_cmd(
+                [
+                    "tmux",
+                    "new-window",
+                    "-t",
+                    aggregator_session,
+                    "-n",
+                    window_name,
+                    "-P",
+                    "-F",
+                    "#{pane_id}",
+                    _ghostty_workspace_pane_command(first_linked_session),
+                ],
+                timeout=10,
+            )
+            if proc.returncode != 0:
+                return fail("display_session_window_create_failed", proc, first_linked_session)
+        first_pane_id = _tmux_stdout_last_line(proc.stdout) or f"{aggregator_session}:{window_name}.0"
+        first_title = _ghostty_workspace_pane_title(first_agent)
+        title_result = _set_ghostty_workspace_pane_title(first_pane_id, first_title)
+        if not title_result["ok"]:
+            return fail(title_result["reason"], target=first_pane_id)
+        panes.append(
+            {
+                "agent_id": first_agent_id,
+                "pane_id": first_pane_id,
+                "title": first_title,
+                "linked_session": first_linked_session,
+                "window_name": window_name,
+            }
+        )
+
+        proc = run_cmd(["tmux", "set-window-option", "-t", f"{aggregator_session}:{window_name}", "remain-on-exit", "on"], timeout=10)
+        if proc.returncode != 0:
+            return fail("display_session_remain_on_exit_failed", proc)
+
+        for index, (agent_id, agent, linked_session) in enumerate(window_jobs[1:], start=1):
+            proc = run_cmd(
+                [
+                    "tmux",
+                    "split-window",
+                    "-t",
+                    f"{aggregator_session}:{window_name}",
+                    "-h",
+                    "-P",
+                    "-F",
+                    "#{pane_id}",
+                    _ghostty_workspace_pane_command(linked_session),
+                ],
+                timeout=10,
+            )
+            if proc.returncode != 0:
+                return fail("display_session_split_failed", proc, linked_session)
+            pane_id = _tmux_stdout_last_line(proc.stdout) or f"{aggregator_session}:{window_name}.{index}"
+            title = _ghostty_workspace_pane_title(agent)
+            title_result = _set_ghostty_workspace_pane_title(pane_id, title)
+            if not title_result["ok"]:
+                return fail(title_result["reason"], target=pane_id)
+            panes.append(
+                {
+                    "agent_id": agent_id,
+                    "pane_id": pane_id,
+                    "title": title,
+                    "linked_session": linked_session,
+                    "window_name": window_name,
+                }
+            )
+
+        proc = run_cmd(["tmux", "select-layout", "-t", f"{aggregator_session}:{window_name}", "even-horizontal"], timeout=10)
+        if proc.returncode != 0:
+            return fail("display_session_layout_failed", proc)
+
+    proc = run_cmd(["tmux", "set-option", "-t", aggregator_session, "mouse", "on"], timeout=10)
+    if proc.returncode != 0:
+        return fail("display_session_mouse_failed", proc)
+    run_cmd(["tmux", "select-window", "-t", f"{aggregator_session}:{_ghostty_workspace_window_name(0)}"], timeout=10)
+    return {"ok": True, "aggregator_session": aggregator_session, "panes": panes}
+
+
+def _set_ghostty_workspace_pane_title(pane_id: str, title: str) -> dict[str, Any]:
+    proc = run_cmd(["tmux", "select-pane", "-t", pane_id, "-T", title], timeout=10)
+    if proc.returncode != 0:
+        return {"ok": False, "reason": "display_session_pane_title_failed", "error": proc.stderr.strip()}
+    return {"ok": True}
+
+
+def _tmux_stdout_last_line(stdout: str) -> str | None:
+    lines = [line.strip() for line in stdout.splitlines() if line.strip()]
+    return lines[-1] if lines else None
+
+
+def _open_ghostty_workspace_agent_display(
+    session_name: str,
+    agent_id: str,
+    agent: dict[str, Any],
+    previous_display: dict[str, Any],
+    event_log: EventLog,
+) -> dict[str, Any]:
+    if not _ghostty_app_exists():
+        return _ghostty_workspace_blocked(
+            [(agent_id, agent)],
+            event_log,
+            "ghostty_app_missing",
+            aggregator_session=_ghostty_workspace_aggregator_name(session_name),
+            linked_sessions={agent_id: _ghostty_display_session_name(session_name, agent_id)},
+            target=f"{session_name}:{agent_id}",
+        )[agent_id]
+    aggregator_session = str(
+        previous_display.get("aggregator_session")
+        or previous_display.get("display_session")
+        or _ghostty_workspace_aggregator_name(session_name)
+    )
+    linked_session = _ghostty_display_session_name(session_name, agent_id)
+    prepared = _prepare_ghostty_display_session(session_name, agent_id, linked_session)
+    if not prepared["ok"]:
+        return _ghostty_workspace_blocked(
+            [(agent_id, agent)],
+            event_log,
+            prepared["reason"],
+            aggregator_session=aggregator_session,
+            linked_sessions={agent_id: linked_session},
+            error=prepared.get("error"),
+            target=f"{session_name}:{agent_id}",
+        )[agent_id]
+    if not _tmux_session_exists(aggregator_session):
+        return _ghostty_workspace_partial_update_display(
+            session_name,
+            agent_id,
+            agent,
+            event_log,
+            reason="aggregator_session_missing",
+            note="pane refresh requires full team restart",
+        )
+
+    pane_title = _ghostty_workspace_pane_title(agent)
+    command = _ghostty_workspace_pane_command(linked_session)
+    pane_id = str(previous_display.get("pane_id") or "")
+    workspace_window = str(previous_display.get("workspace_window") or _ghostty_workspace_window_name(0))
+    refreshed = False
+    if pane_id:
+        proc = run_cmd(["tmux", "respawn-pane", "-k", "-t", pane_id, command], timeout=10)
+        refreshed = proc.returncode == 0
+    if not refreshed:
+        proc = run_cmd(
+            [
+                "tmux",
+                "split-window",
+                "-t",
+                f"{aggregator_session}:{workspace_window}",
+                "-h",
+                "-P",
+                "-F",
+                "#{pane_id}",
+                command,
+            ],
+            timeout=10,
+        )
+        if proc.returncode != 0:
+            return _ghostty_workspace_partial_update_display(
+                session_name,
+                agent_id,
+                agent,
+                event_log,
+                reason="aggregator_pane_refresh_failed",
+                note=proc.stderr.strip() or "pane refresh requires full team restart",
+            )
+        pane_id = _tmux_stdout_last_line(proc.stdout) or pane_id
+    title_result = _set_ghostty_workspace_pane_title(pane_id, pane_title)
+    if not title_result["ok"]:
+        return _ghostty_workspace_partial_update_display(
+            session_name,
+            agent_id,
+            agent,
+            event_log,
+            reason=title_result["reason"],
+            note=title_result.get("error") or "pane refresh requires full team restart",
+        )
+    run_cmd(["tmux", "select-layout", "-t", f"{aggregator_session}:{workspace_window}", "even-horizontal"], timeout=10)
+    title = str(previous_display.get("title") or f"team-agent:{session_name}:workspace")
+    pids = [int(pid) for pid in previous_display.get("pids", []) if str(pid).isdigit()]
+    display = {
+        "backend": "ghostty_workspace",
+        "status": "opened",
+        "title": title,
+        "pane_title": pane_title,
+        "target": f"{session_name}:{agent_id}",
+        "linked_session": linked_session,
+        "aggregator_session": aggregator_session,
+        "display_session": aggregator_session,
+        "workspace_window": workspace_window,
+        "pane_id": pane_id,
+        "pid": pids[0] if pids else None,
+        "pids": pids,
+        "tty": None,
+        "fallback": "tmux_headless",
+        "note": "Refreshed this worker's Ghostty workspace pane by respawning it against a distinct linked session.",
+    }
+    event_log.write("display.ghostty_workspace", agent_id=agent_id, **display)
+    return display
+
+
+def _ghostty_workspace_partial_update_display(
+    session_name: str,
+    agent_id: str,
+    agent: dict[str, Any],
+    event_log: EventLog,
+    reason: str = "partial_update_requires_team_restart",
+    note: str = "pane refresh requires full team restart",
+) -> dict[str, Any]:
+    aggregator_session = _ghostty_workspace_aggregator_name(session_name)
+    display = {
+        "backend": "ghostty_workspace",
+        "status": "blocked",
+        "reason": reason,
+        "target": f"{session_name}:{agent_id}",
+        "linked_session": _ghostty_display_session_name(session_name, agent_id),
+        "aggregator_session": aggregator_session,
+        "display_session": aggregator_session,
+        "pane_title": _ghostty_workspace_pane_title(agent),
+        "fallback": "tmux_headless",
+        "note": note,
+        "action": "restart the team to rebuild the Ghostty workspace layout",
+    }
+    event_log.write("display.ghostty_workspace_partial_update", agent_id=agent_id, **display)
+    return display
+
+
+def _kill_ghostty_workspace_linked_sessions(linked_sessions: list[str]) -> list[str]:
+    killed: list[str] = []
+    for linked_session in dict.fromkeys(linked_sessions):
+        if _tmux_session_exists(linked_session):
+            proc = run_cmd(["tmux", "kill-session", "-t", linked_session], timeout=10)
+            if proc.returncode == 0:
+                killed.append(linked_session)
+    return killed
+
+
 def _ghostty_attach_args(display_session: str, title: str) -> list[str]:
     return [
         "open",
@@ -4643,7 +5153,11 @@ def _ghostty_attach_args(display_session: str, title: str) -> list[str]:
     ]
 
 
-def _close_ghostty_display(agent_id: str, agent_state: dict[str, Any], event_log: EventLog) -> None:
+def _close_ghostty_display(
+    agent_id: str,
+    agent_state: dict[str, Any],
+    event_log: EventLog,
+) -> None:
     display = agent_state.get("display") or {}
     if display.get("backend") != "ghostty_window":
         return
@@ -4651,9 +5165,7 @@ def _close_ghostty_display(agent_id: str, agent_state: dict[str, Any], event_log
     pids = [str(pid) for pid in display.get("pids", []) if str(pid).isdigit()]
     title = display.get("title")
     if not pids and title:
-        pgrep = run_cmd(["pgrep", "-f", f"--title={title}"], timeout=5)
-        if pgrep.returncode == 0:
-            pids = [pid for pid in pgrep.stdout.split() if pid.isdigit()]
+        pids = [str(pid) for pid in _ghostty_pids_by_title(str(title))]
     killed: list[str] = []
     for pid in pids:
         proc = run_cmd(["kill", pid], timeout=5)
@@ -4674,6 +5186,66 @@ def _close_ghostty_display(agent_id: str, agent_state: dict[str, Any], event_log
             )
 
 
+def _close_ghostty_workspace(state: dict[str, Any], event_log: EventLog) -> None:
+    displays = [
+        (agent_id, agent_state.get("display") or {})
+        for agent_id, agent_state in state.get("agents", {}).items()
+        if (agent_state.get("display") or {}).get("backend") == "ghostty_workspace"
+    ]
+    if not displays:
+        return
+    aggregator_session = next(
+        (
+            str(display.get("aggregator_session") or display.get("display_session"))
+            for _agent_id, display in displays
+            if display.get("aggregator_session") or display.get("display_session")
+        ),
+        None,
+    )
+    title = next((str(display.get("title")) for _agent_id, display in displays if display.get("title")), None)
+    pids = {
+        str(pid)
+        for _agent_id, display in displays
+        for pid in display.get("pids", [])
+        if str(pid).isdigit()
+    }
+    if not pids and title:
+        pids = {str(pid) for pid in _ghostty_pids_by_title(str(title))}
+
+    aggregator_closed = False
+    if aggregator_session and _tmux_session_exists(aggregator_session):
+        proc = run_cmd(["tmux", "kill-session", "-t", aggregator_session], timeout=10)
+        if proc.returncode == 0:
+            aggregator_closed = True
+        else:
+            event_log.write(
+                "display.ghostty_workspace_close_failed",
+                aggregator_session=aggregator_session,
+                error=proc.stderr.strip(),
+            )
+
+    linked_sessions = [
+        str(display.get("linked_session"))
+        for _agent_id, display in displays
+        if display.get("linked_session")
+    ]
+    linked_closed = _kill_ghostty_workspace_linked_sessions(linked_sessions)
+
+    killed: list[str] = []
+    for pid in sorted(pids):
+        proc = run_cmd(["kill", pid], timeout=5)
+        if proc.returncode == 0:
+            killed.append(pid)
+    event_log.write(
+        "display.ghostty_workspace_closed",
+        pids=killed,
+        title=title,
+        aggregator_session=aggregator_session,
+        linked_sessions=linked_closed,
+        aggregator_closed=aggregator_closed,
+    )
+
+
 def get_adapter_or_raise(name: str) -> str:
     if name == "tmux" and not shutil_which("tmux"):
         raise RuntimeError("tmux is not installed; install tmux 3.3+ before launch")