@team-agent/installer 0.1.4 → 0.1.9

package/src/team_agent/runtime.py

@@ -35,7 +35,15 @@ from team_agent.providers import ResumeUnavailable, get_adapter, shell_command_f
 from team_agent.routing import route_task
 from team_agent.simple_yaml import dumps
 from team_agent.spec import load_spec, validate_result_envelope, workspace_from_spec
-from team_agent.state import load_runtime_state, runtime_state_path, save_runtime_state, write_team_state
+from team_agent.state import (
+    SESSION_CAPTURE_FIELDS,
+    SESSION_STATE_FIELDS,
+    load_runtime_state,
+    normalize_agent_session_state,
+    runtime_state_path,
+    save_runtime_state,
+    write_team_state,
+)
 from team_agent.task_graph import ready_tasks, update_task_status
 from team_agent.task_graph import TASK_STATUSES
 
@@ -46,6 +54,7 @@ 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"}
 PEEK_MAX_LINES = 80
 PEEK_SEARCH_SCAN_LINES = 300
 PEEK_MAX_MATCHES = 5
@@ -448,10 +457,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)
@@ -520,10 +535,7 @@ def _load_snapshot_state(path: Path) -> dict[str, Any] | None:
         state = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
         return None
-    for agent_state in state.get("agents", {}).values():
-        if isinstance(agent_state, dict):
-            for field in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence", "spawn_cwd"]:
-                agent_state.setdefault(field, None)
+    normalize_agent_session_state(state)
     return state
 
 
@@ -1570,8 +1582,7 @@ def _capture_agent_session(
     result = adapter.capture_session_id(agent_id, spawn_context, timeout_s=timeout_s)
     if not isinstance(result, dict) or not result.get("session_id"):
         return None
-    for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence", "spawn_cwd"]:
-        agent_state[key] = result.get(key)
+    _copy_session_metadata(agent_state, result)
     agent_state.pop("_pending_session_id", None)
     event_log.write(
         "session.captured",
@@ -1585,6 +1596,16 @@ def _capture_agent_session(
     return result
 
 
+def _copy_session_metadata(target: dict[str, Any], source: dict[str, Any]) -> None:
+    for key in SESSION_STATE_FIELDS:
+        target[key] = source.get(key)
+
+
+def _clear_session_capture_fields(target: dict[str, Any]) -> None:
+    for key in SESSION_CAPTURE_FIELDS:
+        target[key] = None
+
+
 def _attach_profile_resume_root(workspace: Path, command_agent: dict[str, Any], previous: dict[str, Any]) -> dict[str, Any]:
     profile_launch = command_agent.get("_provider_profile") or prepare_agent_profile_launch(workspace, command_agent)
     if not profile_launch:
@@ -1631,8 +1652,7 @@ def _prepare_resume_state(
     if not repaired:
         repaired = adapter.recover_session_id(agent_id, prepared, workspace, exclude_session_ids or set())
     if repaired:
-        for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence", "spawn_cwd"]:
-            prepared[key] = repaired.get(key)
+        _copy_session_metadata(prepared, repaired)
         event_log.write(
             "resume.session_repaired",
             agent_id=agent_id,
@@ -1657,8 +1677,7 @@ def _prepare_resume_state(
             f"Cannot resume agent {agent_id}: stored session {session_id} is not available. "
             "Use --allow-fresh only if losing that worker context is acceptable."
         )
-    for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence"]:
-        prepared[key] = None
+    _clear_session_capture_fields(prepared)
     event_log.write(
         "resume.session_unavailable",
         agent_id=agent_id,
@@ -1741,6 +1760,7 @@ 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)
@@ -1750,6 +1770,7 @@ def shutdown(workspace: Path, keep_logs: bool = True) -> dict[str, Any]:
         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)
@@ -1972,8 +1993,7 @@ def restart(workspace: Path, allow_fresh: bool = False, team: str | None = None)
         if profile_launch.get("claude_projects_root"):
             agent_state["claude_projects_root"] = profile_launch["claude_projects_root"]
         if restart_mode == "fresh":
-            for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence"]:
-                agent_state[key] = None
+            _clear_session_capture_fields(agent_state)
             if command_agent.get("_session_id"):
                 agent_state["_pending_session_id"] = command_agent["_session_id"]
             _capture_agent_session(
@@ -1984,7 +2004,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(
@@ -1995,7 +2015,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
@@ -2061,6 +2081,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)
@@ -2231,13 +2255,20 @@ def _start_agent_unlocked(workspace: Path, agent_id: str, force: bool, open_disp
     if profile_launch.get("claude_projects_root"):
         agent_state["claude_projects_root"] = profile_launch["claude_projects_root"]
     if start_mode == "fresh":
-        for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence"]:
-            agent_state[key] = None
+        _clear_session_capture_fields(agent_state)
         if command_agent.get("_session_id"):
             agent_state["_pending_session_id"] = command_agent["_session_id"]
         _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)
@@ -3020,7 +3051,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)
@@ -4498,14 +4529,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)}
@@ -4540,7 +4591,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",
@@ -4582,15 +4633,129 @@ 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,
+            "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]
@@ -4618,6 +4783,284 @@ 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_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]:
+    window_name = "overview"
+    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()}
+
+    panes: list[dict[str, Any]] = []
+    first_agent_id, first_agent, first_linked_session = linked_jobs[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()}
+    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"]:
+        run_cmd(["tmux", "kill-session", "-t", aggregator_session], timeout=10)
+        return title_result
+    panes.append({"agent_id": first_agent_id, "pane_id": first_pane_id, "title": first_title, "linked_session": first_linked_session})
+
+    proc = run_cmd(["tmux", "set-window-option", "-t", f"{aggregator_session}:{window_name}", "remain-on-exit", "on"], timeout=10)
+    if proc.returncode != 0:
+        run_cmd(["tmux", "kill-session", "-t", aggregator_session], timeout=10)
+        return {"ok": False, "reason": "display_session_remain_on_exit_failed", "error": proc.stderr.strip()}
+
+    for index, (agent_id, agent, linked_session) in enumerate(linked_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:
+            run_cmd(["tmux", "kill-session", "-t", aggregator_session], timeout=10)
+            return {"ok": False, "reason": "display_session_split_failed", "error": proc.stderr.strip(), "target": 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"]:
+            run_cmd(["tmux", "kill-session", "-t", aggregator_session], timeout=10)
+            return title_result
+        panes.append({"agent_id": agent_id, "pane_id": pane_id, "title": title, "linked_session": linked_session})
+
+    proc = run_cmd(["tmux", "select-layout", "-t", f"{aggregator_session}:{window_name}", "even-horizontal"], timeout=10)
+    if proc.returncode != 0:
+        run_cmd(["tmux", "kill-session", "-t", aggregator_session], timeout=10)
+        return {"ok": False, "reason": "display_session_layout_failed", "error": proc.stderr.strip()}
+    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 "")
+    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}:overview",
+                "-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}:overview", "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,
+        "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",
@@ -4633,7 +5076,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
@@ -4641,9 +5088,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)
@@ -4664,6 +5109,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")