@team-agent/installer 0.1.11 → 0.2.0

package/src/team_agent/quality_gates.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+
+@dataclass(frozen=True)
+class LineCountResult:
+    path: str
+    lines: int
+    allowed: bool
+    reason: str | None = None
+
+
+ALLOWLIST_KEYS = {"approved_exceptions", "temporary_debt"}
+
+
+def parse_line_count_allowlist_payload(payload: object, *, source: str = "line-count allowlist") -> dict[str, dict[str, Any]]:
+    if not isinstance(payload, dict):
+        raise ValueError(f"{source}: line-count allowlist must be a JSON object")
+    unexpected = sorted(set(payload) - ALLOWLIST_KEYS)
+    if unexpected:
+        keys = ", ".join(unexpected)
+        expected = ", ".join(sorted(ALLOWLIST_KEYS))
+        raise ValueError(f"{source}: unexpected top-level key(s): {keys}; expected new schema keys: {expected}")
+    approved = payload.get("approved_exceptions", {})
+    temporary = payload.get("temporary_debt", {})
+    if not isinstance(approved, dict):
+        raise ValueError(f"{source}: approved_exceptions must be an object")
+    if not isinstance(temporary, dict):
+        raise ValueError(f"{source}: temporary_debt must be an object")
+    for file_path, entry in approved.items():
+        if not isinstance(entry, dict):
+            raise ValueError(f"{source}: approved exception for {file_path} must be an object")
+        max_lines = entry.get("max_lines")
+        if not isinstance(max_lines, int) or max_lines < 1:
+            raise ValueError(f"{source}: approved exception for {file_path} must declare positive integer max_lines")
+    return {"approved_exceptions": approved, "temporary_debt": temporary}
+
+
+def load_line_count_allowlist(path: Path) -> dict[str, dict[str, Any]]:
+    text = path.read_text(encoding="utf-8").strip()
+    if not text:
+        return {"approved_exceptions": {}, "temporary_debt": {}}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path}: invalid JSON in line-count allowlist: {exc}") from exc
+    return parse_line_count_allowlist_payload(data, source=str(path))
+
+
+def check_python_file_line_counts(
+    root: Path,
+    *,
+    allowlist_path: Path,
+    include_roots: Iterable[str] = ("src/team_agent", "tests"),
+    max_lines: int = 500,
+) -> list[LineCountResult]:
+    allowlist = load_line_count_allowlist(allowlist_path)
+    approved = allowlist["approved_exceptions"]
+    results: list[LineCountResult] = []
+    for relative_path in _iter_python_files(root, include_roots):
+        full_path = root / relative_path
+        line_count = _line_count(full_path)
+        entry = approved.get(relative_path)
+        if line_count <= max_lines:
+            results.append(LineCountResult(relative_path, line_count, allowed=True))
+            continue
+        if entry:
+            allowed_max = int(entry["max_lines"])
+            results.append(
+                LineCountResult(
+                    relative_path,
+                    line_count,
+                    allowed=line_count <= allowed_max,
+                    reason=str(entry.get("reason") or ""),
+                )
+            )
+            continue
+        results.append(LineCountResult(relative_path, line_count, allowed=False))
+    return results
+
+
+def line_count_failures(results: Iterable[LineCountResult]) -> list[LineCountResult]:
+    return [result for result in results if not result.allowed]
+
+
+def _iter_python_files(root: Path, include_roots: Iterable[str]) -> list[str]:
+    paths: list[str] = []
+    for include_root in include_roots:
+        base = root / include_root
+        if not base.exists():
+            continue
+        for path in base.rglob("*.py"):
+            if "__pycache__" in path.parts:
+                continue
+            paths.append(path.relative_to(root).as_posix())
+    return sorted(paths)
+
+
+def _line_count(path: Path) -> int:
+    return len(path.read_text(encoding="utf-8").splitlines())

package/src/team_agent/restart/__init__.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from team_agent.restart.orchestration import restart, rollback_restart_session
+from team_agent.restart.selection import (
+    format_restart_candidates,
+    quick_start_existing_context,
+    restart_candidate_from_state,
+    restart_candidates,
+    select_restart_state,
+    state_has_restart_context,
+)
+from team_agent.restart.snapshot import (
+    load_snapshot_state,
+    safe_snapshot_name,
+    save_team_runtime_snapshot,
+    state_team_name,
+    team_runtime_snapshot_dir,
+)
+
+__all__ = [
+    "format_restart_candidates",
+    "load_snapshot_state",
+    "quick_start_existing_context",
+    "restart",
+    "restart_candidate_from_state",
+    "restart_candidates",
+    "rollback_restart_session",
+    "safe_snapshot_name",
+    "save_team_runtime_snapshot",
+    "select_restart_state",
+    "state_has_restart_context",
+    "state_team_name",
+    "team_runtime_snapshot_dir",
+]

package/src/team_agent/restart/orchestration.py

@@ -0,0 +1,328 @@
+from __future__ import annotations
+
+import copy
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from team_agent.events import EventLog
+from team_agent.message_store import MessageStore
+from team_agent.permissions import resolve_permissions
+from team_agent.restart.selection import select_restart_state
+from team_agent.restart.snapshot import save_team_runtime_snapshot
+from team_agent.spec import load_spec
+from team_agent.state import (
+    check_team_owner,
+    load_runtime_state,
+    populate_team_owner_from_env,
+    save_runtime_state,
+    write_team_state,
+)
+
+
+def restart(workspace: Path, allow_fresh: bool = False, team: str | None = None) -> dict[str, Any]:
+    # Lazy-import everything from team_agent.runtime so existing tests that
+    # patch runtime.shell_resume_command_for_agent / runtime.run_cmd /
+    # runtime.start_coordinator / runtime.get_adapter continue to take effect
+    # at call time. Runtime re-exports the provider helpers, so this also
+    # routes through the providers module without binding it directly.
+    from team_agent.runtime import (
+        GHOSTTY_DISPLAY_BACKENDS,
+        ResumeUnavailable,
+        RuntimeError,
+        _attach_profile_resume_root,
+        _attach_team_profile_dirs,
+        _capture_agent_session,
+        _clear_session_capture_fields,
+        _close_ghostty_display,
+        _close_ghostty_workspace,
+        _compile_team_dir_spec,
+        _effective_runtime_config,
+        _ensure_agent_start_requirements,
+        _handle_startup_prompts_and_verify_window,
+        _is_team_doc_dir,
+        _open_worker_displays,
+        _prepare_resume_state,
+        _spec_team_dir,
+        _tmux_session_conflict_error,
+        _tmux_session_exists,
+        _tmux_start_command_for_agent_window,
+        _tmux_window_exists,
+        ensure_workspace_dirs,
+        get_adapter,
+        run_cmd,
+        shell_command_for_agent,
+        shell_resume_command_for_agent,
+        start_coordinator,
+    )
+    state = select_restart_state(workspace, team)
+    gate = check_team_owner(state)
+    if gate:
+        return gate
+    spec_path = Path(state.get("spec_path", workspace / "team.spec.yaml"))
+    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)
+    session_name = state.get("session_name") or spec.get("runtime", {}).get("session_name") or f"team-{spec['team']['name']}"
+    state.setdefault("team_dir", str(team_dir))
+    if _tmux_session_exists(session_name):
+        event_log.write(
+            "restart.session_conflict",
+            session=session_name,
+            action="use a different team name or runtime.session_name; do not terminate existing tmux sessions from restart",
+        )
+        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
+        for agent in spec.get("agents", [])
+        if state.get("agents", {}).get(agent["id"], {}).get("status") != "paused" and not agent.get("paused")
+    ]
+    _ensure_agent_start_requirements(workspace, restart_agents, event_log, "restart")
+    first = True
+    restarted: list[dict[str, Any]] = []
+    new_agents: dict[str, Any] = {}
+    display_jobs: list[tuple[str, dict[str, Any]]] = []
+    for agent in spec.get("agents", []):
+        previous = state.get("agents", {}).get(agent["id"], {})
+        if previous.get("status") == "paused" or agent.get("paused"):
+            new_agents[agent["id"]] = dict(previous or {"status": "paused", "provider": agent["provider"]})
+            new_agents[agent["id"]]["status"] = "paused"
+            continue
+        adapter = get_adapter(agent["provider"])
+        if not adapter.is_installed():
+            event_log.write(
+                "restart.provider_missing",
+                agent_id=agent["id"],
+                provider=agent["provider"],
+                command=adapter.command_name,
+            )
+            raise RuntimeError(
+                f"Provider {agent['provider']} command {adapter.command_name!r} not found for agent {agent['id']}"
+            )
+        mcp_config = adapter.mcp_config(workspace, agent["id"])
+        mcp_path = adapter.install_mcp(workspace, agent["id"], mcp_config)
+        command_agent = copy.deepcopy(agent)
+        command_agent["_runtime"] = runtime_cfg
+        previous = _attach_profile_resume_root(workspace, command_agent, previous)
+        known_session_ids = {
+            str(item.get("session_id"))
+            for aid, item in {**state.get("agents", {}), **new_agents}.items()
+            if aid != agent["id"] and item.get("session_id")
+        }
+        try:
+            previous = _prepare_resume_state(
+                workspace,
+                agent["id"],
+                previous,
+                adapter,
+                event_log,
+                known_session_ids,
+                allow_fresh_on_resume_failure=allow_fresh,
+            )
+        except ResumeUnavailable as exc:
+            try:
+                adapter.cleanup_mcp(workspace, agent["id"], mcp_path)
+            except Exception as cleanup_exc:
+                event_log.write(
+                    "restart.mcp_cleanup_failed",
+                    agent_id=agent["id"],
+                    provider=agent["provider"],
+                    mcp_config=str(mcp_path),
+                    error=str(cleanup_exc),
+                )
+            raise RuntimeError(str(exc)) from exc
+        restart_mode = "resumed" if previous.get("session_id") else "fresh"
+        if restart_mode == "resumed":
+            try:
+                command = shell_resume_command_for_agent(command_agent, previous, workspace, mcp_config)
+            except ResumeUnavailable as exc:
+                event_log.write("restart.resume_unavailable", agent_id=agent["id"], error=str(exc))
+                if not allow_fresh:
+                    try:
+                        adapter.cleanup_mcp(workspace, agent["id"], mcp_path)
+                    except Exception as cleanup_exc:
+                        event_log.write(
+                            "restart.mcp_cleanup_failed",
+                            agent_id=agent["id"],
+                            provider=agent["provider"],
+                            mcp_config=str(mcp_path),
+                            error=str(cleanup_exc),
+                        )
+                    raise RuntimeError(
+                        f"Cannot resume agent {agent['id']}: {exc}. "
+                        "Use team-agent restart --allow-fresh only if losing that worker context is acceptable."
+                    ) from exc
+                command = shell_command_for_agent(command_agent, workspace, mcp_config)
+                restart_mode = "fresh"
+        else:
+            command = shell_command_for_agent(command_agent, workspace, mcp_config)
+            event_log.write("restart.fresh_spawn", agent_id=agent["id"], provider=agent["provider"], reason="session_id_missing")
+        event_log.write(
+            "restart.agent_start",
+            agent_id=agent["id"],
+            provider=agent["provider"],
+            restart_mode=restart_mode,
+            session_id=previous.get("session_id"),
+            session=session_name,
+            window=agent["id"],
+            tmux_start_mode="new-session" if first else "new-window",
+            command=command,
+            mcp_config=str(mcp_path),
+        )
+        if first:
+            proc = run_cmd(["tmux", "new-session", "-d", "-s", session_name, "-n", agent["id"], "sh", "-lc", command])
+            first = False
+        else:
+            proc = run_cmd(["tmux", "new-window", "-t", session_name, "-n", agent["id"], "sh", "-lc", command])
+        if proc.returncode != 0:
+            raise RuntimeError(f"Failed to restart agent {agent['id']}: {proc.stderr.strip()}")
+        if not _handle_startup_prompts_and_verify_window(
+            adapter, event_log, "restart", agent["id"], agent["provider"], session_name, restart_mode
+        ):
+            if restart_mode != "resumed":
+                raise RuntimeError(f"Failed to restart agent {agent['id']}: tmux window exited after start")
+            if not allow_fresh:
+                try:
+                    adapter.cleanup_mcp(workspace, agent["id"], mcp_path)
+                except Exception as cleanup_exc:
+                    event_log.write(
+                        "restart.mcp_cleanup_failed",
+                        agent_id=agent["id"],
+                        provider=agent["provider"],
+                        mcp_config=str(mcp_path),
+                        error=str(cleanup_exc),
+                    )
+                raise RuntimeError(
+                    f"Cannot resume agent {agent['id']}: resume window exited or did not become visible. "
+                    "Use team-agent restart --allow-fresh only if losing that worker context is acceptable."
+                )
+            event_log.write(
+                "restart.resume_window_missing_fallback_fresh",
+                agent_id=agent["id"],
+                provider=agent["provider"],
+                session_id=previous.get("session_id"),
+            )
+            command = shell_command_for_agent(command_agent, workspace, mcp_config)
+            restart_mode = "fresh"
+            tmux_cmd, tmux_start_mode = _tmux_start_command_for_agent_window(session_name, agent["id"], command)
+            event_log.write(
+                "restart.agent_start",
+                agent_id=agent["id"],
+                provider=agent["provider"],
+                restart_mode=restart_mode,
+                session_id=None,
+                session=session_name,
+                window=agent["id"],
+                tmux_start_mode=tmux_start_mode,
+                command=command,
+                mcp_config=str(mcp_path),
+            )
+            proc = run_cmd(tmux_cmd)
+            if proc.returncode != 0:
+                raise RuntimeError(f"Failed to restart agent {agent['id']} fresh after resume exit: {proc.stderr.strip()}")
+            if not _handle_startup_prompts_and_verify_window(
+                adapter, event_log, "restart", agent["id"], agent["provider"], session_name, restart_mode
+            ):
+                raise RuntimeError(f"Failed to restart agent {agent['id']} fresh: tmux window exited after start")
+        spawn_time = datetime.now(timezone.utc)
+        agent_state = dict(previous)
+        agent_state.update(
+            {
+                "status": "running",
+                "provider": agent["provider"],
+                "agent_id": agent["id"],
+                "model": agent.get("model"),
+                "auth_mode": agent.get("auth_mode"),
+                "profile": agent.get("profile"),
+                "window": agent["id"],
+                "mcp_config": str(mcp_path),
+                "permissions": resolve_permissions(agent),
+                "spawn_cwd": str(workspace),
+                "spawned_at": spawn_time.isoformat(),
+            }
+        )
+        profile_launch = command_agent.get("_provider_profile") or {}
+        if profile_launch.get("claude_projects_root"):
+            agent_state["claude_projects_root"] = profile_launch["claude_projects_root"]
+        if restart_mode == "fresh":
+            _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 display_backend in GHOSTTY_DISPLAY_BACKENDS:
+            display_jobs.append((agent["id"], agent))
+        new_agents[agent["id"]] = agent_state
+        restarted.append(
+            {
+                "agent_id": agent["id"],
+                "restart_mode": restart_mode,
+                "session_id": agent_state.get("session_id"),
+                "display_target": None,
+            }
+        )
+    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
+    for item in restarted:
+        agent_id = item["agent_id"]
+        if agent_id in display_results:
+            item["display_target"] = display_results[agent_id]
+    missing_after_start = [item["agent_id"] for item in restarted if not _tmux_window_exists(session_name, item["agent_id"])]
+    if missing_after_start:
+        for agent_id in missing_after_start:
+            event_log.write("restart.agent_missing_after_start", agent_id=agent_id, target=f"{session_name}:{agent_id}")
+        rollback = rollback_restart_session(session_name, event_log)
+        raise RuntimeError(
+            f"Failed to restart agent {missing_after_start[0]}: tmux window exited after start; "
+            f"rollback_session_ok={rollback.get('ok')}"
+        )
+    state["session_name"] = session_name
+    state["agents"] = new_agents
+    populate_team_owner_from_env(state, source="restart")
+    save_runtime_state(workspace, state)
+    save_team_runtime_snapshot(workspace, state)
+    MessageStore(workspace)
+    write_team_state(workspace, spec, state)
+    from team_agent.leader import autobind_leader_receiver_from_env
+    leader_provider = str(spec.get("leader", {}).get("provider") or "codex")
+    autobind_leader_receiver_from_env(workspace, leader_provider, source="restart")
+    coordinator = start_coordinator(workspace)
+    event_log.write("restart.complete", session=session_name, agents=restarted, coordinator=coordinator)
+    return {"ok": True, "session_name": session_name, "agents": restarted, "coordinator": coordinator}
+
+
+def rollback_restart_session(session_name: str, event_log: EventLog) -> dict[str, Any]:
+    from team_agent.runtime import run_cmd
+    proc = run_cmd(["tmux", "kill-session", "-t", session_name], timeout=10)
+    result = {
+        "ok": proc.returncode == 0,
+        "session": session_name,
+        "stdout": proc.stdout.strip(),
+        "stderr": proc.stderr.strip(),
+    }
+    event_log.write("restart.rollback_session", **result)
+    return result

package/src/team_agent/restart/selection.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+from typing import Any
+
+from team_agent.paths import runtime_dir
+from team_agent.state import load_runtime_state, runtime_state_path
+from team_agent.restart.snapshot import load_snapshot_state, state_team_name
+
+
+def restart_candidates(workspace: Path) -> list[dict[str, Any]]:
+    by_session: dict[str, dict[str, Any]] = {}
+    snapshots_root = runtime_dir(workspace) / "teams"
+    for path in sorted(snapshots_root.glob("*/state.json")) if snapshots_root.exists() else []:
+        state = load_snapshot_state(path)
+        if not state or not state.get("session_name"):
+            continue
+        session_name = str(state["session_name"])
+        by_session[session_name] = restart_candidate_from_state(state, path)
+    active = load_runtime_state(workspace)
+    if active.get("session_name"):
+        by_session[str(active["session_name"])] = restart_candidate_from_state(active, runtime_state_path(workspace))
+    return sorted(by_session.values(), key=lambda item: item.get("session_name") or "")
+
+
+def restart_candidate_from_state(state: dict[str, Any], state_path: Path) -> dict[str, Any]:
+    session_name = str(state.get("session_name") or "")
+    return {
+        "session_name": session_name,
+        "team_name": state_team_name(state),
+        "state_path": str(state_path),
+        "spec_path": state.get("spec_path"),
+        "agents": sorted(state.get("agents", {}).keys()),
+        "has_context": state_has_restart_context(state),
+        "state": state,
+    }
+
+
+def state_has_restart_context(state: dict[str, Any]) -> bool:
+    for agent_state in state.get("agents", {}).values():
+        if not isinstance(agent_state, dict):
+            continue
+        if agent_state.get("session_id") or agent_state.get("rollout_path") or agent_state.get("captured_at"):
+            return True
+    return bool(state.get("agents"))
+
+
+def select_restart_state(workspace: Path, team: str | None = None) -> dict[str, Any]:
+    from team_agent.runtime import RuntimeError
+    candidates = [item for item in restart_candidates(workspace) if item.get("has_context")]
+    if team:
+        matches = [
+            item
+            for item in candidates
+            if team in {item.get("session_name"), item.get("team_name"), Path(str(item.get("state_path"))).parent.name}
+        ]
+        if len(matches) == 1:
+            return copy.deepcopy(matches[0]["state"])
+        if len(matches) > 1:
+            raise RuntimeError("restart team selector is ambiguous. " + format_restart_candidates(matches))
+        raise RuntimeError(f"restart team {team!r} not found. " + format_restart_candidates(candidates))
+    if len(candidates) == 1:
+        return copy.deepcopy(candidates[0]["state"])
+    if len(candidates) > 1:
+        raise RuntimeError(
+            "multiple restartable teams found in this workspace; pass --team <session_name> to choose. "
+            + format_restart_candidates(candidates)
+        )
+    return load_runtime_state(workspace)
+
+
+def format_restart_candidates(candidates: list[dict[str, Any]]) -> str:
+    if not candidates:
+        return "No restartable team state was found."
+    parts = []
+    for item in candidates:
+        parts.append(
+            f"{item.get('session_name')} team={item.get('team_name') or '-'} "
+            f"agents={','.join(item.get('agents') or []) or '-'}"
+        )
+    return "Candidates: " + "; ".join(parts)
+
+
+def quick_start_existing_context(workspace: Path, session_name: str) -> dict[str, Any] | None:
+    for item in restart_candidates(workspace):
+        if item.get("session_name") == session_name and item.get("has_context"):
+            return item
+    return None

package/src/team_agent/restart/snapshot.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from team_agent.paths import runtime_dir
+from team_agent.spec import load_spec
+from team_agent.state import normalize_agent_session_state
+
+
+def save_team_runtime_snapshot(workspace: Path, state: dict[str, Any]) -> Path | None:
+    from team_agent.runtime import _spec_team_dir
+    session_name = state.get("session_name")
+    if not session_name:
+        return None
+    snapshot_dir = team_runtime_snapshot_dir(workspace, str(session_name))
+    snapshot_dir.mkdir(parents=True, exist_ok=True)
+    snapshot_state = copy.deepcopy(state)
+    spec_path = Path(str(state.get("spec_path") or ""))
+    if spec_path.is_file():
+        if not snapshot_state.get("team_dir"):
+            snapshot_state["team_dir"] = str(_spec_team_dir(spec_path, workspace))
+        snapshot_spec = snapshot_dir / "team.spec.yaml"
+        if spec_path.resolve() != snapshot_spec.resolve():
+            shutil.copy2(spec_path, snapshot_spec)
+        snapshot_state["spec_path"] = str(snapshot_spec)
+    snapshot_state["team_snapshot"] = {
+        "session_name": session_name,
+        "team_name": state_team_name(snapshot_state),
+        "snapshot_dir": str(snapshot_dir),
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+    }
+    state_path = snapshot_dir / "state.json"
+    tmp_path = state_path.with_suffix(".json.tmp")
+    tmp_path.write_text(json.dumps(snapshot_state, indent=2, ensure_ascii=False), encoding="utf-8")
+    os.replace(tmp_path, state_path)
+    return state_path
+
+
+def team_runtime_snapshot_dir(workspace: Path, session_name: str) -> Path:
+    return runtime_dir(workspace) / "teams" / safe_snapshot_name(session_name)
+
+
+def safe_snapshot_name(value: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_.-]", "_", value).strip("._-") or "team"
+
+
+def state_team_name(state: dict[str, Any]) -> str | None:
+    spec_path = state.get("spec_path")
+    if not spec_path:
+        return None
+    try:
+        return str(load_spec(Path(str(spec_path))).get("team", {}).get("name") or "")
+    except Exception:
+        return None
+
+
+def load_snapshot_state(path: Path) -> dict[str, Any] | None:
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    normalize_agent_session_state(state)
+    return state