@team-agent/installer 0.2.4 → 0.2.6

package/src/team_agent/runtime.py

@@ -70,7 +70,7 @@ from team_agent.leader import (
     LEADER_OWNERSHIP_LOCK,
     attach_leader,
     attach_leader_to_state as _attach_leader_to_state,
-    claim_leader,
+    claim_leader as _legacy_claim_leader,
     leader_identity,
     leader_session_name as _leader_session_name,
     leader_start_plan,
@@ -137,7 +137,7 @@ from team_agent.diagnose import (
     preflight_next_actions as _preflight_next_actions,
     profile_checks_for_agents as _profile_checks_for_agents,
     profile_smoke_checks_for_agents as _profile_smoke_checks_for_agents,
-    quick_start,
+    quick_start as _legacy_quick_start,
     repair_state,
     settle,
     start,
@@ -491,6 +491,11 @@ def shutdown(workspace: Path, keep_logs: bool = True, team: str | None = None) -
     if gate:
         return gate
     session_name = state.get("session_name")
+    resolved_team_id = (
+        team
+        or state.get("active_team_key")
+        or (team_state_key(state) if state.get("session_name") else None)
+    )
     event_log = EventLog(workspace)
     captured: list[str] = []
     closed_displays: set[str] = set()
@@ -561,7 +566,72 @@ def shutdown(workspace: Path, keep_logs: bool = True, team: str | None = None) -
             agent_state["status"] = "stopped"
     save_team_scoped_state(workspace, state)
     _save_team_runtime_snapshot(workspace, state)
-    return {"ok": True, "session_name": session_name, "logs": captured, "coordinator": coordinator}
+    # 0.2.6 Family B (C10/C11/C12): atomically unregister the team and
+    # archive its runtime snapshot directory. Both branches of --keep-logs
+    # still drop the team from state.teams; logs survive inside the
+    # archived directory.
+    archive_path, teams_remaining, new_active = _commit_shutdown_cleanup(
+        workspace, str(resolved_team_id or ""), session_name, event_log
+    )
+    return {
+        "ok": True,
+        "session_name": session_name,
+        "team": resolved_team_id,
+        "logs": captured,
+        "coordinator": coordinator,
+        "archive_path": archive_path,
+        "teams_remaining": teams_remaining,
+        "new_active_team_key": new_active,
+        "cleanup_mode": "synchronous_committed",
+    }
+
+
+def _commit_shutdown_cleanup(
+    workspace: Path,
+    team_key: str,
+    session_name: str | None,
+    event_log: EventLog,
+) -> tuple[str | None, list[str], str | None]:
+    import shutil as _shutil
+    from datetime import datetime as _dt, timezone as _tz
+    workspace_state = load_runtime_state(workspace)
+    teams = workspace_state.get("teams") if isinstance(workspace_state.get("teams"), dict) else {}
+    if team_key and team_key in teams:
+        teams.pop(team_key, None)
+    if workspace_state.get("active_team_key") == team_key:
+        workspace_state["active_team_key"] = None
+    workspace_state["teams"] = teams
+    archive_dest: Path | None = None
+    if session_name:
+        runtime_teams_dir = runtime_dir(workspace) / "teams"
+        from team_agent.restart.snapshot import safe_snapshot_name as _safe
+        snapshot_name = _safe(str(session_name))
+        snapshot_dir = runtime_teams_dir / snapshot_name
+        if snapshot_dir.exists():
+            ts = _dt.now(_tz.utc).strftime("%Y%m%dT%H%M%SZ")
+            archive_dest = runtime_teams_dir / f".archived-{snapshot_name}-{ts}"
+            try:
+                _shutil.move(str(snapshot_dir), str(archive_dest))
+            except OSError as exc:
+                event_log.write(
+                    "team.shutdown_blocked",
+                    reason="archive_move_failed",
+                    team_key=team_key,
+                    error=str(exc),
+                    hint="check filesystem permissions on .team/runtime/teams and rerun shutdown",
+                )
+                return None, sorted(teams.keys()), workspace_state.get("active_team_key")
+    save_runtime_state(workspace, workspace_state)
+    archive_path_str = str(archive_dest) if archive_dest is not None else None
+    new_active = workspace_state.get("active_team_key")
+    event_log.write(
+        "team.shutdown_completed",
+        team_key=team_key,
+        archive_path=archive_path_str,
+        teams_remaining=sorted(teams.keys()),
+        new_active_team_key=new_active,
+    )
+    return archive_path_str, sorted(teams.keys()), new_active
 
 
 
@@ -602,7 +672,44 @@ def acknowledge_idle(workspace: Path, agent_id: str | None = None, *, team: str
         EventLog(workspace).write("coordinator.idle_acknowledged", agent_id=agent_id, team=owner_team_id, acknowledged_at=now, expires_at=expires_at, ttl_seconds=ttl_seconds)
         return {"ok": True, "team": owner_team_id, "agent_id": agent_id, "acknowledged_at": now, "expires_at": expires_at, "ttl_seconds": ttl_seconds}
 
+_OWNER_IDENTITY_FIELDS = (
+    "pane_id",
+    "leader_session_uuid",
+    "machine_fingerprint",
+    "provider",
+    "os_user",
+)
+
+
+def _owner_identity_matches(existing: dict[str, Any], candidate: dict[str, Any]) -> bool:
+    for field in _OWNER_IDENTITY_FIELDS:
+        if str(existing.get(field) or "") != str(candidate.get(field) or ""):
+            return False
+    return True
+
+
+def _resolve_owner_team_id(state: dict[str, Any], team: str | None) -> str | None:
+    if team:
+        return str(team)
+    active = state.get("active_team_key")
+    if active:
+        return str(active)
+    teams = state.get("teams") or {}
+    if isinstance(teams, dict) and len(teams) == 1:
+        return next(iter(teams))
+    return None
+
+
 def takeover(workspace: Path, team: str | None = None, confirm: bool = False) -> dict[str, Any]:
+    """0.2.6 Family A: positive-source ownership rebind.
+
+    Identity is sourced exclusively from ``bind_owner_from_caller_pane``
+    (``$TMUX_PANE`` + one targeted ``tmux display-message``). The new
+    owner record force-writes every identity field into
+    ``state.teams[<team_id>].team_owner``; old fields are not merged,
+    migrated, or setdefaulted. Idempotent: re-running with the same
+    caller identity returns success without mutating state.
+    """
     if not confirm:
         return {
             "ok": False,
@@ -610,91 +717,151 @@ def takeover(workspace: Path, team: str | None = None, confirm: bool = False) ->
             "reason": "confirm_required",
             "action": "rerun with --confirm to claim ownership of this team",
         }
-    pane_id = os.environ.get("TEAM_AGENT_LEADER_PANE_ID")
-    if not pane_id:
-        return {
-            "ok": False,
-            "status": "refused",
-            "reason": "no_caller_identity",
-            "action": "set TEAM_AGENT_LEADER_PANE_ID/PROVIDER/MACHINE_FINGERPRINT or run from a tmux pane",
-        }
+    from team_agent.leader_binding import (
+        bind_owner_from_caller_pane,
+        emit_owner_bound_event,
+    )
     with _runtime_lock(workspace, LEADER_OWNERSHIP_LOCK):
-        try:
-            team_state = select_runtime_state(workspace, team)
-        except RuntimeError as exc:
+        state = load_runtime_state(workspace)
+        team_id = _resolve_owner_team_id(state, team)
+        if not team_id:
             return {
                 "ok": False,
                 "status": "refused",
                 "reason": "team_target_unresolved",
                 "team": team,
-                "error": str(exc),
+                "hint": "pass --team <name> or run quick-start first to register an active team.",
+            }
+        bind = bind_owner_from_caller_pane(workspace, team_id)
+        if not bind.get("ok"):
+            return {"ok": False, "status": "refused", **bind}
+        new_owner = bind["owner"]
+        teams = state.setdefault("teams", {})
+        team_entry = teams.get(team_id) or {}
+        existing_owner = team_entry.get("team_owner") if isinstance(team_entry.get("team_owner"), dict) else {}
+        if existing_owner and _owner_identity_matches(existing_owner, new_owner):
+            return {
+                "ok": True,
+                "status": "claimed",
+                "team": team_id,
+                "team_owner": existing_owner,
+                "idempotent": True,
             }
-        previous_owner = team_state.get("team_owner") if isinstance(team_state.get("team_owner"), dict) else {}
-        previous_receiver = team_state.get("leader_receiver") if isinstance(team_state.get("leader_receiver"), dict) else {}
-        from team_agent.leader import _lease_epoch, _receiver_from_claim_target
-        next_epoch = _lease_epoch(previous_owner, previous_receiver) + 1
-        leader_uuid = str(previous_owner.get("leader_session_uuid") or "")
-        new_owner = {
-            "pane_id": pane_id,
-            "provider": os.environ.get("TEAM_AGENT_LEADER_PROVIDER", ""),
-            "machine_fingerprint": os.environ.get("TEAM_AGENT_MACHINE_FINGERPRINT", ""),
-            "owner_epoch": next_epoch,
-            "claimed_at": datetime.now(timezone.utc).isoformat(),
-            "claimed_via": "takeover",
+        team_entry["team_owner"] = new_owner
+        teams[team_id] = team_entry
+        save_runtime_state(workspace, state)
+        emit_owner_bound_event(
+            workspace,
+            caller_pane_id=bind.get("caller_pane_id", ""),
+            caller_current_command=bind.get("caller_current_command", ""),
+            derived_leader_session_uuid=new_owner["leader_session_uuid"],
+            team_id=team_id,
+            old_leader_session_uuid=str(existing_owner.get("leader_session_uuid") or ""),
+        )
+        return {
+            "ok": True,
+            "status": "claimed",
+            "team": team_id,
+            "team_owner": new_owner,
+            "previous_owner": existing_owner or None,
         }
-        if leader_uuid:
-            new_owner["leader_session_uuid"] = leader_uuid
-        team_state["team_owner"] = new_owner
-        # C11/C17: takeover converges on the same lease mutation as claim-leader.
-        # Rebind the leader receiver to the caller pane and write owner + receiver
-        # to both state locations together, so takeover never leaves the receiver
-        # pointing at the old (often dead) pane.
-        targets_result = core_list_targets()
-        targets = targets_result.get("targets", []) if isinstance(targets_result, dict) and targets_result.get("ok") else []
-        caller_target = next((item for item in targets if isinstance(item, dict) and str(item.get("pane_id")) == str(pane_id)), None)
-        new_receiver = None
-        if caller_target:
-            new_receiver = _receiver_from_claim_target(
-                caller_target,
-                previous_receiver,
-                leader_uuid or None,
-                next_epoch,
-            )
-            new_receiver["discovery"] = "takeover"
-            team_state["leader_receiver"] = new_receiver
-        from team_agent.leader import _write_lease_dual_state
-        _write_lease_dual_state(workspace, team_state)
-        # C11: takeover converges on the same lease audit events as claim-leader
-        # instead of a divergent legacy team_owner.takeover record.
-        event_log = EventLog(workspace)
-        uuid_prefix = leader_uuid[:8]
-        old_pane_id = previous_receiver.get("pane_id") or (previous_owner or {}).get("pane_id")
-        if new_receiver is not None:
-            event_log.write(
-                "leader_receiver.rebind_applied",
-                reason="takeover_confirmed",
-                old_pane_id=old_pane_id,
-                new_pane_id=pane_id,
-                owner_epoch=next_epoch,
-                uuid_prefix=uuid_prefix,
-                team_id=team,
-            )
-        event_log.write(
-            "owner_epoch_advanced",
-            reason="takeover_confirmed",
-            old_pane_id=old_pane_id,
-            new_pane_id=pane_id,
-            owner_epoch=next_epoch,
-            uuid_prefix=uuid_prefix,
-            team_id=team,
-            previous_owner=previous_owner or None,
-            new_owner=new_owner,
-            receiver_rebound=bool(new_receiver),
+
+
+def claim_leader(workspace: Path, team: str | None = None, confirm: bool = False) -> dict[str, Any]:
+    """0.2.6 Family A: positive-source claim-leader.
+
+    Calls :func:`bind_owner_from_caller_pane` to confirm the caller is in
+    a leader-shaped tmux pane, then delegates to the legacy multi-
+    candidate lease arbiter for residual handling. The bind step is the
+    only source of caller identity; the legacy lease path no longer
+    re-derives it.
+    """
+    from team_agent.leader_binding import bind_owner_from_caller_pane
+    state = load_runtime_state(workspace)
+    team_id = _resolve_owner_team_id(state, team) or team_state_key(state)
+    bind = bind_owner_from_caller_pane(workspace, team_id)
+    if not bind.get("ok"):
+        return {"ok": False, "status": "refused", **bind}
+    return _legacy_claim_leader(workspace, team=team, confirm=confirm)
+
+
+def quick_start(
+    agents_dir: Path,
+    name: str | None = None,
+    yes: bool = False,
+    fresh: bool = False,
+    team_id: str | None = None,
+) -> dict[str, Any]:
+    """0.2.6 Family A: positive-source quick-start.
+
+    The caller-pane shape gate is owned by
+    :func:`bind_owner_from_caller_pane`. Quick-start binds the caller
+    pane BEFORE any team setup runs; ``$TMUX_PANE`` missing or the
+    caller pane not running a leader host short-circuits to a refusal
+    (no fallback to legacy reverse-scan). On success, the legacy
+    bootstrap brings up the workspace and the bind-derived
+    ``team_owner`` is force-written into
+    ``state.teams[team_id].team_owner`` so the runtime owner identity
+    matches the caller pane verbatim.
+    """
+    from team_agent.leader_binding import (
+        bind_owner_from_caller_pane,
+        emit_owner_bound_event,
+    )
+    from team_agent.diagnose.quick_start import prepare_quick_start_team
+
+    # Pre-resolve team_dir + workspace so the caller-pane bind can write
+    # its audit event before any worker is spawned. ``prepare_quick_start_team``
+    # is idempotent (mkdir + shutil.copy2 of role docs) and used inside
+    # ``_legacy_quick_start`` as the very first step anyway.
+    team_dir = prepare_quick_start_team(
+        Path(agents_dir).resolve(), Path.cwd().resolve(), name, team_id=team_id
+    )
+    workspace = team_workspace(team_dir)
+    ensure_workspace_dirs(workspace)
+    # Spark MED 1 (b1b17b1 review): the on-disk team_dir already passed
+    # through ``_safe_snapshot_name``; reusing ``team_dir.name`` here
+    # keeps the on-disk path and the state.teams key aligned. Using the
+    # raw ``team_id`` would have split the two writes whenever the
+    # caller-supplied id contained spaces or shell-unsafe characters.
+    resolved_team_id = team_dir.name or "current"
+    bind = bind_owner_from_caller_pane(workspace, resolved_team_id)
+    if not bind.get("ok"):
+        return {"ok": False, "status": "refused", **bind}
+    new_owner = bind["owner"]
+    result = _legacy_quick_start(
+        Path(agents_dir).resolve(), name=name, yes=yes, fresh=fresh, team_id=team_id
+    )
+    # Spark MED 2 (b1b17b1 review): only commit the owner force-write
+    # and emit ``owner.bound_from_caller_pane`` when the legacy bootstrap
+    # actually succeeded. Otherwise pass the refusal envelope back
+    # verbatim — ``existing_runtime_state`` / ``preflight`` failures
+    # must not leave a "team owner claimed" side effect behind.
+    if not result.get("ok"):
+        return result
+    state = load_runtime_state(workspace)
+    teams = state.setdefault("teams", {})
+    team_entry = teams.get(resolved_team_id) or {}
+    existing_owner = (
+        team_entry.get("team_owner")
+        if isinstance(team_entry.get("team_owner"), dict)
+        else {}
+    )
+    if not (existing_owner and _owner_identity_matches(existing_owner, new_owner)):
+        team_entry["team_owner"] = new_owner
+        teams[resolved_team_id] = team_entry
+        if not state.get("active_team_key"):
+            state["active_team_key"] = resolved_team_id
+        save_runtime_state(workspace, state)
+        emit_owner_bound_event(
+            workspace,
+            caller_pane_id=bind.get("caller_pane_id", ""),
+            caller_current_command=bind.get("caller_current_command", ""),
+            derived_leader_session_uuid=new_owner["leader_session_uuid"],
+            team_id=resolved_team_id,
+            old_leader_session_uuid=str(existing_owner.get("leader_session_uuid") or ""),
         )
-        response = {"ok": True, "status": "claimed", "team": team, "team_owner": new_owner, "previous_owner": previous_owner or None, "owner_epoch": next_epoch}
-        if new_receiver is not None:
-            response["leader_receiver"] = new_receiver
-        return response
+    return result
 
 
 def _running_agent_state(workspace: Path, agent: dict[str, Any], previous: dict[str, Any]) -> dict[str, Any]:

package/src/team_agent/state.py

@@ -51,14 +51,37 @@ def normalize_agent_session_state(state: dict[str, Any]) -> None:
 def load_runtime_state(workspace: Path) -> dict[str, Any]:
     path = runtime_state_path(workspace)
     if not path.exists():
-        return {"agents": {}, "tasks": [], "session_name": None}
+        return {"agents": {}, "tasks": [], "session_name": None, "active_team_key": None}
     state = json.loads(path.read_text(encoding="utf-8"))
     normalize_agent_session_state(state)
-    if _migrate_state_identity(state, workspace):
+    changed = _migrate_state_identity(state, workspace)
+    if _migrate_active_team_key(state):
+        changed = True
+    if changed:
         save_runtime_state(workspace, state)
     return state
 
 
+def _migrate_active_team_key(state: dict[str, Any]) -> bool:
+    """0.2.6 Family B (C6): legacy states with a top-level ``session_name``
+    but no ``active_team_key`` get the active pointer seeded once. After
+    this, ``active_team_key`` is the single explicit source of truth and
+    callers mutate it through CLI verbs (claim-leader / takeover /
+    shutdown / restart)."""
+    if "active_team_key" in state:
+        return False
+    teams = state.get("teams") if isinstance(state.get("teams"), dict) else {}
+    if state.get("session_name"):
+        seed = team_state_key(state)
+        state["active_team_key"] = seed if seed in teams or not teams else seed
+        return True
+    if isinstance(teams, dict) and len(teams) == 1:
+        state["active_team_key"] = next(iter(teams))
+        return True
+    state["active_team_key"] = None
+    return True
+
+
 def team_state_key(state: dict[str, Any]) -> str:
     for field in ("team_dir", "spec_path"):
         value = state.get(field)
@@ -98,58 +121,110 @@ def merge_workspace_team_state(existing: dict[str, Any], launched: dict[str, Any
 
 
 def team_state_candidates(state: dict[str, Any]) -> dict[str, dict[str, Any]]:
-    candidates: dict[str, dict[str, Any]] = {}
-    teams = state.get("teams")
-    if isinstance(teams, dict):
-        for key, value in teams.items():
-            if isinstance(value, dict):
-                candidates[str(key)] = value
-    if state.get("session_name"):
-        candidates.setdefault(team_state_key(state), compact_team_state(state))
-    return candidates
+    """0.2.6 Family B (C7): the only candidate source is ``state.teams``
+    filtered by ``status == "alive"``. Top-level ``session_name`` /
+    ``team_dir`` are a derived view of the active team and never count as
+    an independent candidate. Shutdown/legacy entries with non-alive
+    status are excluded."""
+    out: dict[str, dict[str, Any]] = {}
+    teams = state.get("teams") if isinstance(state.get("teams"), dict) else {}
+    for key, value in teams.items():
+        if not isinstance(value, dict):
+            continue
+        if str(value.get("status") or "alive").lower() != "alive":
+            continue
+        out[str(key)] = value
+    return out
 
 
-def format_team_candidates(candidates: dict[str, dict[str, Any]]) -> str:
-    if not candidates:
+def format_team_candidates(team_states: dict[str, dict[str, Any]]) -> str:
+    if not team_states:
         return "No team state was found."
     parts = []
-    for key, state in sorted(candidates.items()):
-        agents = ",".join(sorted(state.get("agents", {}).keys())) or "-"
-        parts.append(f"{key} session={state.get('session_name') or '-'} agents={agents}")
+    for key in sorted(team_states):
+        st = team_states[key]
+        agents = ",".join(sorted(st.get("agents", {}).keys())) or "-"
+        parts.append(f"{key} session={st.get('session_name') or '-'} agents={agents}")
     return "Candidates: " + "; ".join(parts)
 
 
+def _team_entry_from_state(state: dict[str, Any], team_key: str) -> dict[str, Any] | None:
+    teams = state.get("teams") if isinstance(state.get("teams"), dict) else {}
+    entry = teams.get(team_key)
+    if not isinstance(entry, dict):
+        return None
+    return entry
+
+
+def _project_top_level_view(state: dict[str, Any], team_key: str) -> dict[str, Any]:
+    """0.2.6 Family B (C8): when picking a team for use, the top-level
+    keys (``session_name`` / ``team_dir`` / ``agents`` / ``tasks``) are a
+    derived view of ``teams[team_key]``. We copy the team entry into a
+    flat dict and preserve any auxiliary state (``team_owner`` /
+    ``leader_receiver`` / ``coordinator`` already pinned to the team)."""
+    entry = _team_entry_from_state(state, team_key) or {}
+    projection = copy.deepcopy(entry)
+    projection.setdefault("session_name", entry.get("session_name"))
+    projection.setdefault("team_dir", entry.get("team_dir"))
+    projection["active_team_key"] = team_key
+    # Preserve the full teams dict so consumers can introspect siblings.
+    projection["teams"] = copy.deepcopy(state.get("teams") or {})
+    if "team_owner" in entry:
+        projection["team_owner"] = copy.deepcopy(entry["team_owner"])
+    elif state.get("team_owner") is not None:
+        projection["team_owner"] = copy.deepcopy(state["team_owner"])
+    if "leader_receiver" in entry:
+        projection["leader_receiver"] = copy.deepcopy(entry["leader_receiver"])
+    elif state.get("leader_receiver") is not None:
+        projection["leader_receiver"] = copy.deepcopy(state["leader_receiver"])
+    if "coordinator" in state:
+        projection.setdefault("coordinator", copy.deepcopy(state["coordinator"]))
+    return projection
+
+
 def select_runtime_state(workspace: Path, team: str | None = None) -> dict[str, Any]:
     state = load_runtime_state(workspace)
-    candidates = team_state_candidates(state)
+    alive = team_state_candidates(state)
     if team:
         matches = [
-            value
-            for key, value in candidates.items()
+            (key, value)
+            for key, value in alive.items()
             if team in {key, str(value.get("session_name") or ""), str(value.get("team_dir") or "")}
         ]
         if len(matches) == 1:
-            return copy.deepcopy(matches[0])
+            return _project_top_level_view(state, matches[0][0])
         from team_agent.errors import RuntimeError
         if len(matches) > 1:
-            raise RuntimeError("team selector is ambiguous. " + format_team_candidates(candidates))
-        raise RuntimeError(f"team {team!r} not found. " + format_team_candidates(candidates))
-    if len(candidates) > 1:
-        from team_agent.errors import RuntimeError
-        raise RuntimeError("multiple teams found in this workspace; pass --team <team> to choose. " + format_team_candidates(candidates))
-    return copy.deepcopy(state)
+            raise RuntimeError("team selector is ambiguous. " + format_team_candidates(alive))
+        raise RuntimeError(f"team {team!r} not found. " + format_team_candidates(alive))
+    active = state.get("active_team_key")
+    if active and active in alive:
+        return _project_top_level_view(state, str(active))
+    if len(alive) == 1:
+        return _project_top_level_view(state, next(iter(alive)))
+    if not alive:
+        return copy.deepcopy(state)
+    from team_agent.errors import RuntimeError
+    raise RuntimeError(
+        "multiple teams found in this workspace; pass --team <team> to choose. "
+        + format_team_candidates(alive)
+    )
 
 
 def ambiguous_team_target_result(state: dict[str, Any]) -> dict[str, Any] | None:
-    candidates = team_state_candidates(state)
-    if len(candidates) <= 1:
+    alive = team_state_candidates(state)
+    active = state.get("active_team_key")
+    if active and active in alive:
+        return None
+    if len(alive) <= 1:
         return None
     return {
         "ok": False,
         "status": "refused",
         "reason": "team_target_ambiguous",
-        "candidates": sorted(candidates),
-        "message": "multiple teams found in this workspace; pass --team <team> to choose. " + format_team_candidates(candidates),
+        "candidates": sorted(alive.keys()),
+        "message": "multiple teams found in this workspace; pass --team <team> to choose. "
+        + format_team_candidates(alive),
     }