@team-agent/installer 0.1.11 → 0.2.1

package/src/team_agent/diagnose/quick_start.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import json
+import shutil
+import time
+from pathlib import Path
+from typing import Any
+
+from team_agent.diagnose.preflight import ensure_profiles_for_roles, preflight
+from team_agent.events import EventLog
+from team_agent.message_store import MessageStore
+from team_agent.paths import logs_dir, team_workspace
+from team_agent.spec import load_spec
+from team_agent.state import load_runtime_state, save_runtime_state, write_team_state
+from team_agent.task_graph import TASK_STATUSES
+
+
+def quick_start(
+    agents_dir: Path,
+    name: str | None = None,
+    yes: bool = False,
+    fresh: bool = False,
+    team_id: str | None = None,
+) -> dict[str, Any]:
+    from team_agent.runtime import (
+        RuntimeError,
+        _compile_team_dir_spec,
+        _quick_start_existing_context,
+        ensure_workspace_dirs,
+        launch,
+        start_coordinator,
+    )
+
+    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"
+    existing = _quick_start_existing_context(workspace, compiled["spec"]["runtime"]["session_name"])
+    if existing and not fresh:
+        return {
+            "ok": False,
+            "step": "existing_runtime_state",
+            "summary": (
+                "quick-start would start fresh workers from role docs for an existing team. "
+                "Use restart to continue the previous worker context, or pass --fresh to intentionally start new workers."
+            ),
+            "team": existing.get("team_name"),
+            "session_name": existing.get("session_name"),
+            "state_path": existing.get("state_path"),
+            "next_actions": [
+                f"team-agent restart {workspace} --team {existing.get('session_name')}",
+                f"team-agent quick-start {team_dir} --fresh",
+            ],
+        }
+    preflight_result = preflight(team_dir)
+    if not preflight_result.get("ok"):
+        return {
+            "ok": False,
+            "step": "preflight",
+            "summary": preflight_result.get("summary"),
+            "details_log": preflight_result.get("details_log"),
+            "blockers": preflight_result.get("blockers", []),
+            "next_actions": preflight_result.get("next_actions", []),
+            "checks": preflight_result.get("checks", []),
+        }
+    dangerous = bool(compiled["spec"].get("runtime", {}).get("dangerous_auto_approve"))
+    if dangerous and not yes:
+        raise RuntimeError("quick-start requires --yes when dangerous_auto_approve is true")
+    launched = launch(spec_path, auto_approve=True, skip_profile_smoke=True)
+    from team_agent.leader import autobind_leader_receiver_from_env
+    leader_provider = str(compiled["spec"].get("leader", {}).get("provider") or "codex")
+    autobind_leader_receiver_from_env(workspace, leader_provider, source="quick_start")
+    coordinator = start_coordinator(workspace)
+    ready = wait_ready(workspace, timeout=120)
+    summary = (
+        f"team {compiled['spec']['team']['name']} ready: "
+        f"{len(launched.get('agents', []))} agent"
+        f"{'' if len(launched.get('agents', [])) == 1 else 's'} "
+        f"in session {launched.get('session_name')} (coordinator pid {coordinator.get('pid')})"
+    )
+    ready_signal = (
+        "quick-start completed; workers are ready. "
+        "Do not wait, sleep, or poll status after this success line unless diagnosing a failure."
+    )
+    details_log = logs_dir(workspace) / f"quick-start-{int(time.time())}.json"
+    details_log.write_text(
+        json.dumps(
+            {
+                "team_dir": str(team_dir),
+                "preflight": preflight_result,
+                "compile": compiled,
+                "launch": launched,
+                "ready": ready,
+                "coordinator": coordinator,
+            },
+            indent=2,
+            ensure_ascii=False,
+        ),
+        encoding="utf-8",
+    )
+    return {
+        "ok": bool(launched.get("ok") and ready.get("ok") and coordinator.get("ok")),
+        "summary": summary,
+        "ready_signal": ready_signal,
+        "next_actions": ["Dispatch work with team-agent send, or return control to the user."],
+        "team_dir": str(team_dir),
+        "spec": str(spec_path),
+        "session_name": launched.get("session_name"),
+        "coordinator": coordinator,
+        "details_log": str(details_log),
+    }
+
+
+def prepare_quick_start_team(agents_dir: Path, workspace: Path, name: str | None, team_id: str | None = None) -> Path:
+    from team_agent.runtime import RuntimeError, _safe_snapshot_name
+
+    if (agents_dir / "TEAM.md").exists() and (agents_dir / "agents").is_dir():
+        return agents_dir
+    team_source = agents_dir / "TEAM.md"
+    role_docs = [path for path in sorted(agents_dir.glob("*.md")) if path.name != "TEAM.md"] if agents_dir.is_dir() else []
+    if not role_docs:
+        raise RuntimeError(f"{agents_dir}: expected .team/current or a directory of role .md files")
+    team_dir = workspace / ".team" / (_safe_snapshot_name(team_id) if team_id else "current")
+    target_agents = team_dir / "agents"
+    target_profiles = team_dir / "profiles"
+    target_agents.mkdir(parents=True, exist_ok=True)
+    target_profiles.mkdir(parents=True, exist_ok=True)
+    for role_doc in role_docs:
+        shutil.copy2(role_doc, target_agents / role_doc.name)
+    team_doc = team_dir / "TEAM.md"
+    if team_source.exists():
+        shutil.copy2(team_source, team_doc)
+        if name:
+            EventLog(workspace).write("quick_start.name_ignored_existing_team_doc", name=name, team_doc=str(team_doc))
+    elif not team_doc.exists():
+        team_name = name or agents_dir.name.replace(" ", "-") or "team-agent-team"
+        team_doc.write_text(
+            f"---\nname: {team_name}\nobjective: Quick-start Team Agent team.\n---\n\nQuick-start team.\n",
+            encoding="utf-8",
+        )
+    elif name:
+        # Keep the existing body; name override is only for fresh TEAM.md to avoid hand-editing user docs.
+        EventLog(workspace).write("quick_start.name_ignored_existing_team_doc", name=name, team_doc=str(team_doc))
+    return team_dir
+
+
+def wait_ready(workspace: Path, timeout: int = 120) -> dict[str, Any]:
+    from team_agent.runtime import status
+
+    start_time = time.monotonic()
+    last: dict[str, Any] = {}
+    while time.monotonic() - start_time <= timeout:
+        last = status(workspace, as_json=True)
+        agents = last.get("agents", {})
+        if agents and all(agent.get("tmux_window_present") and agent.get("status") in {"running", "busy"} for agent in agents.values()):
+            break
+        time.sleep(1.0)
+    readiness = {
+        "process_started": bool(last.get("tmux_session_present")),
+        "cli_prompt_ready": all(agent.get("status") in {"running", "busy"} for agent in last.get("agents", {}).values()) if last.get("agents") else False,
+        "mcp_ready": all(Path(agent.get("mcp_config", "")).exists() for agent in last.get("agents", {}).values()) if last.get("agents") else False,
+        "task_prompt_delivered": bool(MessageStore(workspace).message_counts()),
+    }
+    ok = readiness["process_started"] and readiness["cli_prompt_ready"] and readiness["mcp_ready"]
+    details_log = logs_dir(workspace) / f"wait-ready-{int(time.time())}.json"
+    details_log.write_text(json.dumps({"readiness": readiness, "status": last}, indent=2, ensure_ascii=False), encoding="utf-8")
+    return {
+        "ok": ok,
+        "summary": "workers ready" if ok else "workers not fully ready before timeout",
+        "next_actions": ["Dispatch a task with team-agent send."] if ok else ["Run team-agent diagnose --json."],
+        "details_log": str(details_log),
+        "readiness": readiness,
+    }
+
+
+def settle(workspace: Path) -> dict[str, Any]:
+    from team_agent.runtime import collect, status
+
+    collected = collect(workspace)
+    current = status(workspace, as_json=True)
+    details_log = logs_dir(workspace) / f"settle-{int(time.time())}.json"
+    details_log.write_text(json.dumps({"collect": collected, "status": current}, indent=2, ensure_ascii=False), encoding="utf-8")
+    return {
+        "ok": collected.get("ok", False),
+        "summary": f"collected {len(collected.get('collected', []))} result(s)",
+        "next_actions": ["Review team_state.md and decide whether to continue or shutdown."],
+        "details_log": str(details_log),
+        "collect": collected,
+    }
+
+
+def repair_state(
+    workspace: Path,
+    task_id: str,
+    assignee: str | None = None,
+    status_value: str | None = None,
+    summary: str | None = None,
+) -> dict[str, Any]:
+    from team_agent.runtime import RuntimeError, _find_task, _leader_id
+
+    state = load_runtime_state(workspace)
+    spec_path = Path(state.get("spec_path", workspace / "team.spec.yaml"))
+    spec = load_spec(spec_path)
+    task = _find_task(state.get("tasks", []), task_id)
+    if assignee is not None:
+        valid_agents = {agent["id"] for agent in spec.get("agents", [])}
+        valid_agents.add(_leader_id(state, spec))
+        if assignee not in valid_agents:
+            raise RuntimeError(f"unknown agent id for repair: {assignee}")
+    if status_value is not None and status_value not in TASK_STATUSES:
+        raise RuntimeError(f"unknown task status for repair: {status_value}")
+    before = {
+        "assignee": task.get("assignee"),
+        "status": task.get("status"),
+        "last_result_summary": task.get("last_result_summary"),
+    }
+    if assignee is not None:
+        task["assignee"] = assignee
+    if status_value is not None:
+        task["status"] = status_value
+    if summary is not None:
+        task["last_result_summary"] = summary
+    after = {
+        "assignee": task.get("assignee"),
+        "status": task.get("status"),
+        "last_result_summary": task.get("last_result_summary"),
+    }
+    save_runtime_state(workspace, state)
+    state_path = write_team_state(workspace, spec, state)
+    EventLog(workspace).write("repair_state.task", task_id=task_id, before=before, after=after)
+    return {"ok": True, "task_id": task_id, "before": before, "after": after, "state_file": str(state_path)}

package/src/team_agent/display/__init__.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from team_agent.display.close import (
+    close_ghostty_display,
+    close_ghostty_workspace,
+    close_ghostty_workspace_slot,
+)
+from team_agent.display.ghostty import (
+    ghostty_app_exists,
+    ghostty_attach_args,
+    ghostty_command,
+    ghostty_display_session_name,
+    ghostty_pids_by_title,
+    prepare_ghostty_display_session,
+)
+from team_agent.display.worker_window import (
+    open_ghostty_worker_window,
+    open_worker_displays,
+)
+from team_agent.display.workspace import (
+    GHOSTTY_WORKSPACE_PANES_PER_WINDOW,
+    ghostty_workspace_aggregator_name,
+    ghostty_workspace_blocked,
+    ghostty_workspace_pane_command,
+    ghostty_workspace_pane_title,
+    ghostty_workspace_partial_update_display,
+    ghostty_workspace_window_name,
+    kill_ghostty_workspace_linked_sessions,
+    open_ghostty_workspace,
+    open_ghostty_workspace_agent_display,
+    prepare_ghostty_workspace_aggregator,
+    prepare_ghostty_workspace_linked_sessions,
+    set_ghostty_workspace_pane_title,
+)
+
+__all__ = [
+    "GHOSTTY_WORKSPACE_PANES_PER_WINDOW",
+    "close_ghostty_display",
+    "close_ghostty_workspace",
+    "close_ghostty_workspace_slot",
+    "ghostty_app_exists",
+    "ghostty_attach_args",
+    "ghostty_command",
+    "ghostty_display_session_name",
+    "ghostty_pids_by_title",
+    "ghostty_workspace_aggregator_name",
+    "ghostty_workspace_blocked",
+    "ghostty_workspace_pane_command",
+    "ghostty_workspace_pane_title",
+    "ghostty_workspace_partial_update_display",
+    "ghostty_workspace_window_name",
+    "kill_ghostty_workspace_linked_sessions",
+    "open_ghostty_worker_window",
+    "open_ghostty_workspace",
+    "open_ghostty_workspace_agent_display",
+    "open_worker_displays",
+    "prepare_ghostty_display_session",
+    "prepare_ghostty_workspace_aggregator",
+    "prepare_ghostty_workspace_linked_sessions",
+    "set_ghostty_workspace_pane_title",
+]

package/src/team_agent/display/close.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from typing import Any
+
+from team_agent.events import EventLog
+from team_agent.display.ghostty import ghostty_pids_by_title
+from team_agent.display.workspace import kill_ghostty_workspace_linked_sessions
+
+
+def close_ghostty_display(
+    agent_id: str,
+    agent_state: dict[str, Any],
+    event_log: EventLog,
+) -> None:
+    from team_agent.runtime import _tmux_session_exists, run_cmd
+    display = agent_state.get("display") or {}
+    if display.get("backend") != "ghostty_window":
+        return
+    display_session = display.get("display_session")
+    pids = [str(pid) for pid in display.get("pids", []) if str(pid).isdigit()]
+    title = display.get("title")
+    if not pids and title:
+        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)
+        if proc.returncode == 0:
+            killed.append(pid)
+    if killed:
+        event_log.write("display.ghostty_closed", agent_id=agent_id, pids=killed, title=title)
+    if display_session and _tmux_session_exists(str(display_session)):
+        proc = run_cmd(["tmux", "kill-session", "-t", str(display_session)], timeout=10)
+        if proc.returncode == 0:
+            event_log.write("display.ghostty_display_session_closed", agent_id=agent_id, display_session=display_session)
+        else:
+            event_log.write(
+                "display.ghostty_display_session_close_failed",
+                agent_id=agent_id,
+                display_session=display_session,
+                error=proc.stderr.strip(),
+            )
+
+
+def close_ghostty_workspace_slot(
+    agent_id: str,
+    display: dict[str, Any],
+    event_log: EventLog,
+) -> None:
+    from team_agent.runtime import _tmux_session_exists, run_cmd
+    pane_id = display.get("pane_id")
+    linked_session = display.get("linked_session")
+    stopped_title = f"stopped: {agent_id}"
+    relabeled = False
+    if pane_id:
+        proc = run_cmd(["tmux", "select-pane", "-t", str(pane_id), "-T", stopped_title], timeout=10)
+        if proc.returncode == 0:
+            relabeled = True
+        else:
+            event_log.write(
+                "display.ghostty_workspace_slot_relabel_failed",
+                agent_id=agent_id,
+                pane_id=pane_id,
+                error=proc.stderr.strip(),
+            )
+    linked_session_closed = False
+    if linked_session and _tmux_session_exists(str(linked_session)):
+        proc = run_cmd(["tmux", "kill-session", "-t", str(linked_session)], timeout=10)
+        if proc.returncode == 0:
+            linked_session_closed = True
+        else:
+            event_log.write(
+                "display.ghostty_workspace_slot_linked_session_close_failed",
+                agent_id=agent_id,
+                linked_session=linked_session,
+                error=proc.stderr.strip(),
+            )
+    display["status"] = "stopped"
+    display["pane_title"] = stopped_title
+    event_log.write(
+        "display.ghostty_workspace_slot_closed",
+        agent_id=agent_id,
+        pane_id=pane_id,
+        linked_session=linked_session,
+        relabeled=relabeled,
+        linked_session_closed=linked_session_closed,
+    )
+
+
+def close_ghostty_workspace(state: dict[str, Any], event_log: EventLog) -> None:
+    from team_agent.runtime import _tmux_session_exists, run_cmd
+    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,
+    )

package/src/team_agent/display/ghostty.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import hashlib
+import re
+import time
+from pathlib import Path
+from typing import Any
+
+
+def ghostty_command() -> str | None:
+    from team_agent.runtime import shutil_which
+    return shutil_which("ghostty") or (
+        "/Applications/Ghostty.app/Contents/MacOS/ghostty"
+        if Path("/Applications/Ghostty.app/Contents/MacOS/ghostty").exists()
+        else 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]:
+    from team_agent.runtime import run_cmd
+    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 ghostty_attach_args(display_session: str, title: str) -> list[str]:
+    return [
+        "open",
+        "-na",
+        "Ghostty.app",
+        "--args",
+        f"--title={title}",
+        "-e",
+        "tmux",
+        "attach-session",
+        "-t",
+        display_session,
+    ]
+
+
+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]
+    safe_session = re.sub(r"[^A-Za-z0-9_.-]", "_", session_name)[:80].strip("._-") or "team"
+    safe_window = re.sub(r"[^A-Za-z0-9_.-]", "_", window_name)[:40].strip("._-") or "agent"
+    return f"{safe_session}__display__{safe_window}__{digest}"
+
+
+def prepare_ghostty_display_session(session_name: str, window_name: str, display_session: str) -> dict[str, Any]:
+    from team_agent.runtime import _tmux_session_exists, _tmux_window_exists, run_cmd
+    if not _tmux_window_exists(session_name, window_name):
+        return {"ok": False, "reason": "tmux_target_missing"}
+    if display_session == session_name:
+        return {"ok": False, "reason": "display_session_conflicts_with_base_session"}
+    if _tmux_session_exists(display_session):
+        proc = run_cmd(["tmux", "kill-session", "-t", display_session], timeout=10)
+        if proc.returncode != 0:
+            return {"ok": False, "reason": "display_session_cleanup_failed", "error": proc.stderr.strip()}
+    proc = run_cmd(["tmux", "new-session", "-d", "-t", session_name, "-s", display_session], timeout=10)
+    if proc.returncode != 0:
+        return {"ok": False, "reason": "display_session_create_failed", "error": proc.stderr.strip()}
+    proc = run_cmd(["tmux", "select-window", "-t", f"{display_session}:{window_name}"], timeout=10)
+    if proc.returncode != 0:
+        run_cmd(["tmux", "kill-session", "-t", display_session], timeout=10)
+        return {"ok": False, "reason": "display_session_select_window_failed", "error": proc.stderr.strip()}
+    return {"ok": True, "display_session": display_session}

package/src/team_agent/display/worker_window.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+from team_agent.events import EventLog
+from team_agent.display.ghostty import (
+    ghostty_app_exists,
+    ghostty_attach_args,
+    ghostty_display_session_name,
+    ghostty_pids_by_title,
+    prepare_ghostty_display_session,
+)
+from team_agent.display.workspace import open_ghostty_workspace
+
+
+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)}
+    results: dict[str, dict[str, Any]] = {}
+    max_workers = min(4, len(jobs))
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {
+            executor.submit(open_ghostty_worker_window, workspace, session_name, agent_id, agent, event_log): 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:
+                display = {
+                    "backend": "ghostty_window",
+                    "status": "blocked",
+                    "reason": "display_open_exception",
+                    "error": str(exc),
+                    "fallback": "tmux_headless",
+                }
+                event_log.write("display.ghostty_blocked", agent_id=agent_id, **display)
+                results[agent_id] = display
+    return results
+
+
+def open_ghostty_worker_window(
+    workspace: Path,
+    session_name: str,
+    window_name: str,
+    agent: dict[str, Any],
+    event_log: EventLog,
+) -> dict[str, Any]:
+    from team_agent.runtime import run_cmd
+    _ = workspace
+    if not ghostty_app_exists():
+        blocker = {
+            "backend": "ghostty_window",
+            "status": "blocked",
+            "reason": "ghostty_app_missing",
+            "fallback": "tmux_headless",
+        }
+        event_log.write("display.ghostty_blocked", agent_id=agent["id"], **blocker)
+        return blocker
+    title = f"team-agent:{agent['id']}:{agent.get('role', '')}"
+    display_session = ghostty_display_session_name(session_name, window_name)
+    prepared = prepare_ghostty_display_session(session_name, window_name, display_session)
+    if not prepared["ok"]:
+        blocker = {
+            "backend": "ghostty_window",
+            "status": "blocked",
+            "reason": prepared["reason"],
+            "error": prepared.get("error"),
+            "target": f"{session_name}:{window_name}",
+            "display_session": display_session,
+            "fallback": "tmux_headless",
+        }
+        event_log.write("display.ghostty_blocked", agent_id=agent["id"], **blocker)
+        return blocker
+    launch_args = ghostty_attach_args(display_session, title)
+    proc = run_cmd(launch_args, timeout=10)
+    display = {
+        "backend": "ghostty_window",
+        "status": "opened" if proc.returncode == 0 else "blocked",
+        "title": title,
+        "target": f"{session_name}:{window_name}",
+        "display_session": display_session,
+        "launch_args": launch_args,
+        "pid": None,
+        "pids": [],
+        "tty": None,
+        "fallback": "tmux_headless",
+        "note": "Ghostty opens a dedicated linked tmux session per worker so each display has an independent active window; runtime injection remains tmux-backed.",
+    }
+    if proc.returncode != 0:
+        display["reason"] = proc.stderr.strip() or proc.stdout.strip() or "open Ghostty.app failed"
+    else:
+        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