@team-agent/installer 0.2.1 → 0.2.3

package/src/team_agent/rust_core.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import platform
 import re
 import shutil
 import subprocess
@@ -10,6 +11,18 @@ from typing import Any
 from team_agent.paths import repo_root
 
 
+_LEADER_ENV_KEYS = (
+    "TEAM_AGENT_LEADER_SESSION_UUID",
+    "TEAM_AGENT_LEADER_PANE_ID",
+    "TEAM_AGENT_LEADER_PROVIDER",
+    "TEAM_AGENT_MACHINE_FINGERPRINT",
+    "TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE",
+)
+_LEADER_SHAPED_COMMANDS = {"codex", "claude", "claude.exe", "node", "nodejs"}
+_PANE_ENV_SCAN_TIMEOUT_SECONDS = 2.0
+_run_subprocess = subprocess.run  # test-injectable indirection
+
+
 def core_binary() -> Path | None:
     configured = shutil.which("team-agent-core")
     if configured:
@@ -105,13 +118,13 @@ def list_targets() -> dict[str, Any]:
     result = call_core("list-targets")
     if result.get("ok"):
         return result
-    proc = subprocess.run(
+    proc = _run_subprocess(
         [
             "tmux",
             "list-panes",
             "-a",
             "-F",
-            "#{pane_id}\t#{session_name}\t#{window_index}\t#{window_name}\t#{pane_index}\t#{pane_tty}\t#{pane_current_command}\t#{pane_active}",
+            "#{pane_id}\t#{session_name}\t#{window_index}\t#{window_name}\t#{pane_index}\t#{pane_tty}\t#{pane_current_command}\t#{pane_active}\t#{pane_pid}",
         ],
         text=True,
         capture_output=True,
@@ -123,7 +136,7 @@ def list_targets() -> dict[str, Any]:
     targets = []
     for line in proc.stdout.splitlines():
         parts = line.split("\t")
-        if len(parts) != 8:
+        if len(parts) not in {8, 9}:
             continue
         target = {
             "pane_id": parts[0],
@@ -135,11 +148,152 @@ def list_targets() -> dict[str, Any]:
             "pane_current_command": parts[6],
             "pane_active": parts[7] == "1",
         }
+        pane_pid = parts[8].strip() if len(parts) == 9 else ""
+        if pane_pid:
+            target["pane_pid"] = pane_pid
         target["fingerprint"] = f"{target['session_name']}|{target['window_index']}|{target['pane_index']}|{target['pane_tty']}"
+        _attach_leader_env(target)
         targets.append(target)
     return {"ok": True, "targets": targets, "engine": "python_fallback", "fallback_reason": result.get("error")}
 
 
+def _attach_leader_env(target: dict[str, Any]) -> None:
+    pane_pid = str(target.get("pane_pid") or "").strip()
+    if not pane_pid:
+        target["leader_env"] = None
+        return
+    env = _read_process_env(pane_pid)
+    if env is None:
+        target["leader_env"] = None
+        return
+    leader_env = {key: env[key] for key in _LEADER_ENV_KEYS if key in env}
+    if "TEAM_AGENT_LEADER_SESSION_UUID" not in leader_env:
+        for child_pid in _walk_leader_shaped_children(pane_pid):
+            child_env = _read_process_env(child_pid)
+            if child_env is None:
+                continue
+            for key in _LEADER_ENV_KEYS:
+                if key not in leader_env and key in child_env:
+                    leader_env[key] = child_env[key]
+            if "TEAM_AGENT_LEADER_SESSION_UUID" in leader_env:
+                break
+    target["leader_env"] = leader_env
+    uuid_value = leader_env.get("TEAM_AGENT_LEADER_SESSION_UUID")
+    if uuid_value:
+        target["leader_session_uuid"] = uuid_value
+
+
+def _read_process_env(pid: str) -> dict[str, str] | None:
+    if platform.system() == "Linux":
+        return _read_proc_environ(pid)
+    return _read_ps_eww_env(pid)
+
+
+def _read_proc_environ(pid: str) -> dict[str, str] | None:
+    path = Path(f"/proc/{pid}/environ")
+    try:
+        raw = path.read_bytes()
+    except (FileNotFoundError, PermissionError, OSError):
+        return None
+    env: dict[str, str] = {}
+    for token in raw.split(b"\x00"):
+        if not token or b"=" not in token:
+            continue
+        try:
+            text = token.decode("utf-8", errors="replace")
+        except Exception:
+            continue
+        key, _, value = text.partition("=")
+        env[key] = value
+    return env
+
+
+def _read_ps_eww_env(pid: str) -> dict[str, str] | None:
+    try:
+        proc = _run_subprocess(
+            ["ps", "-E", "-ww", "-p", str(pid)],
+            text=True,
+            capture_output=True,
+            timeout=_PANE_ENV_SCAN_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None
+    if proc.returncode != 0 or not proc.stdout:
+        return None
+    return _parse_ps_eww_output(proc.stdout, pid)
+
+
+def _parse_ps_eww_output(text: str, pid: str) -> dict[str, str]:
+    env: dict[str, str] = {}
+    lines = text.splitlines()
+    if len(lines) < 2:
+        return env
+    target_row = None
+    for line in lines[1:]:
+        stripped = line.lstrip()
+        if stripped.split(" ", 1)[0] == str(pid):
+            target_row = stripped
+            break
+    if target_row is None:
+        # Spark MEDIUM #2 (da436a3): never fall back to lines[1] — that row may belong to
+        # an unrelated process and would leak its env (incl. another team's
+        # TEAM_AGENT_LEADER_SESSION_UUID) into this pane's leader_env, corrupting rediscovery.
+        return env
+    for token in target_row.split():
+        if "=" not in token:
+            continue
+        key, _, value = token.partition("=")
+        if not key or " " in key:
+            continue
+        if not (key[0].isalpha() or key[0] == "_"):
+            continue
+        if not all(ch.isalnum() or ch == "_" for ch in key):
+            continue
+        env[key] = value
+    return env
+
+
+def _walk_leader_shaped_children(parent_pid: str) -> list[str]:
+    try:
+        proc = _run_subprocess(
+            ["ps", "-o", "pid=,ppid=,comm="],
+            text=True,
+            capture_output=True,
+            timeout=_PANE_ENV_SCAN_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return []
+    if proc.returncode != 0 or not proc.stdout:
+        return []
+    return _select_leader_shaped_descendants(proc.stdout, parent_pid)
+
+
+def _select_leader_shaped_descendants(ps_output: str, parent_pid: str) -> list[str]:
+    rows: list[tuple[str, str, str]] = []
+    for line in ps_output.splitlines():
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        pid, ppid, command = parts[0], parts[1], " ".join(parts[2:])
+        rows.append((pid, ppid, Path(command).name))
+    descendants: set[str] = set()
+    frontier = {str(parent_pid)}
+    while frontier:
+        next_frontier: set[str] = set()
+        for pid, ppid, _ in rows:
+            if ppid in frontier and pid not in descendants:
+                descendants.add(pid)
+                next_frontier.add(pid)
+        frontier = next_frontier
+    return [
+        pid
+        for pid, _, command in rows
+        if pid in descendants and command in _LEADER_SHAPED_COMMANDS
+    ]
+
+
 def contains_inline_secret(value: str) -> bool:
     return (
         _contains_secret_assignment(value)

package/src/team_agent/sessions/capture.py

@@ -1,14 +1,25 @@
 from __future__ import annotations
 
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
+from team_agent.errors import RuntimeError as TeamAgentRuntimeError
 from team_agent.events import EventLog
 from team_agent.providers import get_adapter
 from team_agent.state import SESSION_CAPTURE_FIELDS, SESSION_STATE_FIELDS
 
 
+# Stage 7 S6 (2026-05-27): capture_agent_session used to do a single adapter
+# call and silently return None on miss, leaving status='running' workers with
+# session_id=null. Slow worker startups (Codex writing the rollout file a few
+# tenths of a second after window creation) raced this check. We now poll on a
+# small interval inside the caller's timeout_s budget so the adapter's own
+# fast-path call doesn't have to absorb all the latency on its own.
+_CAPTURE_POLL_INTERVAL_SECONDS = 0.05
+
+
 def capture_missing_sessions(
     workspace: Path,
     state: dict[str, Any],
@@ -25,6 +36,10 @@ def capture_missing_sessions(
             for aid, item in state.get("agents", {}).items()
             if aid != agent_id and item.get("session_id")
         }
+        # capture_missing_sessions is invoked from coordinator_tick, diagnose,
+        # status, etc. with very short timeouts; a transient miss should NOT
+        # crash those paths. The loud raise contract belongs to direct callers
+        # (e.g. lifecycle start/restart) who own the worker's atomicity.
         result = capture_agent_session(
             workspace,
             agent_id,
@@ -32,6 +47,7 @@ def capture_missing_sessions(
             event_log,
             timeout_s=timeout_s,
             exclude_session_ids=known_session_ids,
+            raise_on_missed=False,
         )
         if result:
             captured.append(agent_id)
@@ -53,6 +69,7 @@ def capture_agent_session(
     event_log: EventLog,
     timeout_s: float,
     exclude_session_ids: set[str] | None = None,
+    raise_on_missed: bool = True,
 ) -> dict[str, Any] | None:
     if agent_state.get("session_id"):
         return None
@@ -66,21 +83,54 @@ def capture_agent_session(
         "exclude_session_ids": sorted(exclude_session_ids or set()),
         "claude_projects_root": agent_state.get("claude_projects_root"),
     }
-    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
-    copy_session_metadata(agent_state, result)
-    agent_state.pop("_pending_session_id", None)
-    event_log.write(
-        "session.captured",
-        agent_id=agent_id,
-        provider=agent_state.get("provider"),
-        session_id=agent_state.get("session_id"),
-        rollout_path=agent_state.get("rollout_path"),
-        captured_via=agent_state.get("captured_via"),
-        attribution_confidence=agent_state.get("attribution_confidence"),
-    )
-    return result
+    deadline = time.monotonic() + max(timeout_s, 0.0)
+    while True:
+        # Pass timeout_s=0 so the adapter does a single fast-path check; the
+        # outer loop owns the polling budget so behaviour stays consistent
+        # whether or not the adapter has its own internal sleep.
+        result = adapter.capture_session_id(agent_id, spawn_context, timeout_s=0)
+        if isinstance(result, dict) and result.get("session_id"):
+            copy_session_metadata(agent_state, result)
+            agent_state.pop("_pending_session_id", None)
+            event_log.write(
+                "session.captured",
+                agent_id=agent_id,
+                provider=agent_state.get("provider"),
+                session_id=agent_state.get("session_id"),
+                rollout_path=agent_state.get("rollout_path"),
+                captured_via=agent_state.get("captured_via"),
+                attribution_confidence=agent_state.get("attribution_confidence"),
+            )
+            return result
+        if time.monotonic() >= deadline:
+            break
+        time.sleep(_CAPTURE_POLL_INTERVAL_SECONDS)
+    # Timeout. Slice 1 atomicity contract: a worker whose status is 'running'
+    # must NEVER be left with session_id=null — that half-state is what made
+    # Mac mini Stage 7 S5/S6 unreproducible and breaks resume on next restart.
+    # Emit a structured attention event so the coordinator/operator sees the
+    # miss, then raise so callers cannot accidentally treat the None as a
+    # silent "no-op". Non-running workers (still starting, paused, stopped)
+    # legitimately have no session yet, so they still get the silent-None
+    # return that existing callers expect.
+    if agent_state.get("status") == "running":
+        event_log.write(
+            "session.capture_required_attention",
+            agent_id=agent_id,
+            provider=agent_state.get("provider"),
+            timeout_s=timeout_s,
+            spawn_cwd=agent_state.get("spawn_cwd"),
+            session_name=agent_state.get("session_name"),
+            window=agent_state.get("window", agent_id),
+        )
+        if raise_on_missed:
+            raise TeamAgentRuntimeError(
+                f"Failed to capture session_id for agent {agent_id}: adapter "
+                f"did not produce a session within {timeout_s}s. Worker is "
+                "running but unidentifiable; this is a Slice 1 atomicity "
+                "violation."
+            )
+    return None
 
 
 def copy_session_metadata(target: dict[str, Any], source: dict[str, Any]) -> None:

package/src/team_agent/spec.py

@@ -27,9 +27,60 @@ def load_yaml(path: Path) -> dict[str, Any]:
 def load_spec(path: Path) -> dict[str, Any]:
     spec = load_yaml(path)
     validate_spec(spec, base_dir=path.parent)
+    _emit_load_time_deprecations(spec, path)
     return spec
 
 
+def _emit_load_time_deprecations(spec: dict[str, Any], path: Path) -> None:
+    """Stage 7 S7 (2026-05-27): deprecation signals attached to the spec field
+    itself must fire when the YAML is read, not lazily inside the trust-prompt
+    code path. A user with the deprecated field in team.spec.yaml needs to see
+    the warning even when startup never reaches attempt_trust_auto_answer.
+
+    The leader-panes helper owns the one-shot stderr guard + the structured
+    audit event, so we reuse it. EventLog points at the WORKSPACE ROOT (not
+    the spec file's directory) so a quick-start layout that stores the spec
+    under <workspace>/.team/current/team.spec.yaml still routes the audit
+    event into the single canonical <workspace>/.team/logs/events.jsonl
+    instead of a doubled <workspace>/.team/current/.team/logs/events.jsonl
+    nesting.
+    """
+    runtime = spec.get("runtime")
+    if not isinstance(runtime, dict):
+        return
+    if not bool(runtime.get("auto_trust_own_workspace")):
+        return
+    # Local import keeps the spec module free of messaging-layer coupling at
+    # import time; only YAMLs that opt into the deprecated field pay the cost.
+    from team_agent.events import EventLog
+    from team_agent.messaging.leader_panes import _emit_spec_opt_in_deprecation
+    _emit_spec_opt_in_deprecation(EventLog(_resolve_workspace_root(path)))
+
+
+def _resolve_workspace_root(spec_path: Path) -> Path:
+    """Find the workspace root that owns this spec.
+
+    A workspace root is the directory whose `.team/` subdirectory holds the
+    runtime state, logs, artifacts, and (for quick-start layouts) the spec
+    itself under `.team/current/`. We climb from the spec file's parent
+    looking for the first ancestor that has a `.team/` child. If no ancestor
+    qualifies (fresh workspace before init, or a spec deliberately placed
+    outside any team workspace), we fall back to `spec_path.parent` which is
+    the legacy single-layout behaviour.
+
+    Implementation note: we use real filesystem evidence (`(dir/.team).is_dir()`)
+    rather than path-string parsing so the resolver works correctly even when
+    workspace paths legitimately contain a `.team` segment.
+    """
+    direct_parent = spec_path.parent
+    if (direct_parent / ".team").is_dir():
+        return direct_parent
+    for ancestor in direct_parent.parents:
+        if (ancestor / ".team").is_dir():
+            return ancestor
+    return direct_parent
+
+
 def validate_spec(spec: dict[str, Any], base_dir: Path | None = None) -> None:
     messages = _basic_schema_errors(spec)
     messages.extend(_semantic_errors(spec, base_dir or Path.cwd()))
@@ -190,6 +241,12 @@ def _check_runtime(runtime: Any, errors: list[str]) -> None:
         "tick_interval_sec",
         "push_min_interval_sec",
         "stuck_timeout_sec",
+        # Gap 29 / F3 deprecation (2026-05-26): accept the legacy spec opt-in so
+        # YAMLs that still set it validate and the deprecation warning + structured
+        # event in messaging/leader_panes.py can fire. The preferred per-session
+        # opt-in is the env var TEAM_AGENT_AUTO_TRUST_OWN_WORKSPACE; this spec
+        # field will be removed in 0.3.0.
+        "auto_trust_own_workspace",
     }
     _check_keys(runtime, "/runtime", required, allowed, errors)
     if not isinstance(runtime, dict):
@@ -200,6 +257,8 @@ def _check_runtime(runtime: Any, errors: list[str]) -> None:
         errors.append("/runtime/display_backend: invalid display backend")
     if "dangerous_auto_approve" in runtime and not isinstance(runtime["dangerous_auto_approve"], bool):
         errors.append("/runtime/dangerous_auto_approve: must be a boolean")
+    if "auto_trust_own_workspace" in runtime and not isinstance(runtime["auto_trust_own_workspace"], bool):
+        errors.append("/runtime/auto_trust_own_workspace: must be a boolean")
     _check_list(runtime.get("startup_order"), "/runtime/startup_order", errors)
 
 

package/src/team_agent/state.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import copy
@@ -23,6 +24,14 @@ SESSION_STATE_FIELDS = [
     *SESSION_CAPTURE_FIELDS,
     "spawn_cwd",
 ]
+_UUID_SEPARATOR = "\0"
+
+
+def derive_leader_session_uuid(machine_fingerprint: str, workspace_abspath: str, os_user: str, team_id: str) -> str:
+    parts = [machine_fingerprint, workspace_abspath, os_user, team_id]
+    if any(_UUID_SEPARATOR in part for part in parts):
+        raise ValueError("leader_session_uuid inputs must not contain NUL")
+    return hashlib.sha256(_UUID_SEPARATOR.join(parts).encode("utf-8")).hexdigest()[:32]
 
 
 def runtime_state_path(workspace: Path) -> Path:
@@ -45,6 +54,8 @@ def load_runtime_state(workspace: Path) -> dict[str, Any]:
         return {"agents": {}, "tasks": [], "session_name": None}
     state = json.loads(path.read_text(encoding="utf-8"))
     normalize_agent_session_state(state)
+    if _migrate_state_identity(state, workspace):
+        save_runtime_state(workspace, state)
     return state
 
 
@@ -163,11 +174,75 @@ def resolve_team_scoped_state(
         }
 
 
-def _caller_identity_from_env() -> dict[str, str]:
+def _identity_workspace_abspath(state: dict[str, Any], workspace: Path | None = None) -> str:
+    if state.get("workspace"):
+        return str(Path(str(state["workspace"])).resolve())
+    if state.get("team_dir"):
+        return str(Path(str(state["team_dir"])).resolve().parent.parent)
+    if state.get("spec_path"):
+        spec_path = Path(str(state["spec_path"])).resolve()
+        return str(spec_path.parent.parent.parent if spec_path.parent.parent.name == ".team" else spec_path.parent)
+    return str((workspace or Path(os.environ.get("TEAM_AGENT_WORKSPACE") or os.getcwd())).resolve())
+
+
+def _identity_os_user() -> str:
+    return os.environ.get("USER") or os.environ.get("USERNAME") or ""
+
+
+def _identity_machine_fingerprint(state: dict[str, Any]) -> str:
+    for record in (state.get("team_owner"), state.get("leader_receiver")):
+        if isinstance(record, dict) and record.get("machine_fingerprint"):
+            return str(record["machine_fingerprint"])
+    return os.environ.get("TEAM_AGENT_MACHINE_FINGERPRINT") or ""
+
+
+def _leader_session_uuid_for_state(state: dict[str, Any], workspace: Path | None = None, team_id: str | None = None) -> str:
+    return derive_leader_session_uuid(
+        _identity_machine_fingerprint(state),
+        _identity_workspace_abspath(state, workspace),
+        _identity_os_user(),
+        team_id or team_state_key(state),
+    )
+
+
+def _migrate_team_identity(state: dict[str, Any], workspace: Path, team_id: str | None = None) -> bool:
+    leader_uuid = _leader_session_uuid_for_state(state, workspace, team_id)
+    changed = False
+    for key in ("team_owner", "leader_receiver"):
+        record = state.get(key)
+        if isinstance(record, dict) and not record.get("leader_session_uuid"):
+            record["leader_session_uuid"] = leader_uuid
+            changed = True
+    return changed
+
+
+def _migrate_state_identity(state: dict[str, Any], workspace: Path) -> bool:
+    changed = _migrate_team_identity(state, workspace) if state.get("session_name") else False
+    teams = state.get("teams")
+    if isinstance(teams, dict):
+        for team_id, team_state in teams.items():
+            if isinstance(team_state, dict):
+                changed = _migrate_team_identity(team_state, workspace, str(team_id)) or changed
+    return changed
+
+
+def _caller_identity_from_env(state: dict[str, Any] | None = None, team_id: str | None = None, workspace: Path | None = None) -> dict[str, str]:
+    state = state or {}
+    machine_fingerprint = os.environ.get("TEAM_AGENT_MACHINE_FINGERPRINT") or ""
+    override = os.environ.get("TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE") or ""
+    env_uuid = os.environ.get("TEAM_AGENT_LEADER_SESSION_UUID") or ""
+    leader_uuid = override or env_uuid or derive_leader_session_uuid(
+        machine_fingerprint,
+        _identity_workspace_abspath(state, workspace),
+        _identity_os_user(),
+        team_id or os.environ.get("TEAM_AGENT_TEAM_ID") or team_state_key(state),
+    )
     return {
         "pane_id": os.environ.get("TEAM_AGENT_LEADER_PANE_ID") or "",
         "provider": os.environ.get("TEAM_AGENT_LEADER_PROVIDER") or "",
-        "machine_fingerprint": os.environ.get("TEAM_AGENT_MACHINE_FINGERPRINT") or "",
+        "machine_fingerprint": machine_fingerprint,
+        "leader_session_uuid": leader_uuid,
+        "leader_session_uuid_source": "explicit-override" if override else ("env" if env_uuid else "derived"),
     }
 
 
@@ -175,19 +250,22 @@ def check_team_owner(state: dict[str, Any]) -> dict[str, Any] | None:
     owner = state.get("team_owner") or {}
     if not owner:
         return None
-    caller = _caller_identity_from_env()
-    if (
-        caller["pane_id"] == (owner.get("pane_id") or "")
-        and caller["provider"] == (owner.get("provider") or "")
-        and caller["machine_fingerprint"] == (owner.get("machine_fingerprint") or "")
-    ):
+    _migrate_team_identity(state, Path(_identity_workspace_abspath(state)), team_state_key(state))
+    caller = _caller_identity_from_env(state, team_state_key(state))
+    owner_uuid = str(owner.get("leader_session_uuid") or "")
+    caller_uuid = caller["leader_session_uuid"]
+    owner_pane = str(owner.get("pane_id") or "")
+    caller_pane = caller.get("pane_id") or ""
+    if caller_uuid == owner_uuid and (not caller_pane or caller_pane == owner_pane):
         return None
+    same_uuid = caller_uuid == owner_uuid
     return {
         "ok": False,
         "status": "refused",
         "reason": "team_owner_mismatch",
+        "reason_kind": "sticky_bind_collision" if same_uuid else "owner_takeover_required",
         "error": "not_owner",
-        "action": "use team-agent takeover --confirm",
+        "action": "team-agent claim-leader --confirm" if same_uuid else "team-agent takeover --confirm",
         "team_owner": owner,
         "caller": caller,
     }
@@ -209,14 +287,16 @@ def worker_sender_bypasses_owner_gate(state: dict[str, Any], sender: str | None)
 
 def populate_team_owner_from_env(state: dict[str, Any], source: str = "autopopulate") -> dict[str, Any] | None:
     if state.get("team_owner"):
+        _migrate_team_identity(state, Path(_identity_workspace_abspath(state)), team_state_key(state))
         return state["team_owner"]
-    caller = _caller_identity_from_env()
+    caller = _caller_identity_from_env(state, team_state_key(state))
     if not caller["pane_id"]:
         return None
     owner = {
         "pane_id": caller["pane_id"],
         "provider": caller["provider"],
         "machine_fingerprint": caller["machine_fingerprint"],
+        "leader_session_uuid": caller["leader_session_uuid"],
         "claimed_at": datetime.now(timezone.utc).isoformat(),
         "claimed_via": source,
     }
@@ -224,7 +304,70 @@ def populate_team_owner_from_env(state: dict[str, Any], source: str = "autopopul
     return owner
 
 
+def apply_first_time_leader_binding(
+    workspace: Path,
+    state: dict[str, Any],
+    receiver: dict[str, Any],
+    pane_info: dict[str, Any],
+    identity: dict[str, Any],
+    source: str,
+) -> dict[str, Any]:
+    from team_agent.messaging.leader_panes import _leader_command_looks_usable
+    command = pane_info.get("pane_current_command", "")
+    provider = str(receiver.get("provider") or "")
+    if not _leader_command_looks_usable(command, provider):
+        return {"ok": False, "reason": "leader_pane_wrong_command", "error": f"pane command {command!r} is not a leader host", "pane": pane_info}
+    current_path = pane_info.get("pane_current_path")
+    if not current_path or os.path.realpath(current_path) != os.path.realpath(str(workspace.resolve())):
+        return {"ok": False, "reason": "leader_pane_wrong_workspace", "error": f"pane cwd {current_path!r} does not match workspace {str(workspace.resolve())!r}", "pane": pane_info}
+    receiver.update({
+        "leader_session_uuid": identity["leader_session_uuid"],
+        "machine_fingerprint": identity["machine_fingerprint"],
+        "owner_epoch": 0,
+    })
+    state["team_owner"] = {
+        "pane_id": receiver["pane_id"],
+        "provider": provider,
+        "machine_fingerprint": identity["machine_fingerprint"],
+        "leader_session_uuid": identity["leader_session_uuid"],
+        "owner_epoch": 0,
+        "claimed_at": datetime.now(timezone.utc).isoformat(),
+        "claimed_via": source,
+    }
+    state["leader_receiver"] = receiver
+    return {"ok": True, "pane": pane_info, "warning": None, "first_time": True}
+
+
+def leader_env_exports(receiver: dict[str, Any], identity: dict[str, Any]) -> dict[str, str]:
+    return {
+        "TEAM_AGENT_LEADER_PANE_ID": str(receiver.get("pane_id") or ""),
+        "TEAM_AGENT_LEADER_PROVIDER": str(receiver.get("provider") or ""),
+        "TEAM_AGENT_LEADER_SESSION_UUID": str(identity.get("leader_session_uuid") or ""),
+        "TEAM_AGENT_MACHINE_FINGERPRINT": str(identity.get("machine_fingerprint") or ""),
+        "TEAM_AGENT_WORKSPACE": str(identity.get("workspace_abspath") or ""),
+        "TEAM_AGENT_TEAM_ID": str(identity.get("team_id") or ""),
+    }
+
+
+def validate_leader_uuid_from_targets(receiver: dict[str, Any], targets: dict[str, Any]) -> dict[str, Any]:
+    expected_uuid = str(receiver.get("leader_session_uuid") or "")
+    if not expected_uuid or receiver.get("provider") == "fake":
+        return {"ok": True}
+    if not targets.get("ok"):
+        return {"ok": False, "reason": "leader_uuid_lookup_failed", "error": targets.get("error") or "tmux target scan failed"}
+    pane_id = receiver.get("pane_id")
+    target = next((item for item in targets.get("targets", []) if item.get("pane_id") == pane_id), None)
+    env = target.get("leader_env") if isinstance((target or {}).get("leader_env"), dict) else {}
+    actual_uuid = str((target or {}).get("leader_session_uuid") or env.get("TEAM_AGENT_LEADER_SESSION_UUID") or "")
+    if not actual_uuid:
+        return {"ok": False, "reason": "leader_uuid_missing", "error": "bound pane has no TEAM_AGENT_LEADER_SESSION_UUID", "pane": target}
+    if actual_uuid != expected_uuid:
+        return {"ok": False, "reason": "leader_uuid_mismatch", "error": "bound pane TEAM_AGENT_LEADER_SESSION_UUID does not match stored team owner", "pane": target}
+    return {"ok": True}
+
+
 def save_runtime_state(workspace: Path, state: dict[str, Any]) -> None:
+    _migrate_state_identity(state, workspace)
     path = runtime_state_path(workspace)
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp_path = path.with_name(f"{path.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp")