@team-agent/installer 0.2.0 → 0.2.2

package/src/team_agent/leader/__init__.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from typing import Any
 
 from team_agent.events import EventLog
-from team_agent.state import load_runtime_state, save_runtime_state
+from team_agent.state import apply_first_time_leader_binding, derive_leader_session_uuid, leader_env_exports, load_runtime_state, save_runtime_state, save_team_scoped_state, select_runtime_state, team_state_key, validate_leader_uuid_from_targets
 
 
 def attach_leader(workspace: Path, pane: str | None = None, provider: str = "codex") -> dict[str, Any]:
@@ -63,28 +63,16 @@ def start_leader(
     confirm_attach: bool = False,
     attach_session: str | None = None,
 ) -> None:
-    plan = leader_start_plan(
-        provider,
-        provider_args,
-        workspace,
-        attach_existing=attach_existing,
-        confirm_attach=confirm_attach,
-        attach_session=attach_session,
-    )
+    plan = leader_start_plan(provider, provider_args, workspace, attach_existing=attach_existing, confirm_attach=confirm_attach, attach_session=attach_session)
+    if plan.get("leader_session_uuid_source") == "override":
+        EventLog(workspace).write("leader_session_uuid.override", source="explicit-override", uuid_prefix=str(plan.get("leader_session_uuid") or "")[:12], team_id=plan.get("team_id"))
     if plan["mode"] == "new_tmux_session" and not sys.stdin.isatty():
         plan = dict(plan)
         argv = list(plan["argv"])
         argv.insert(2, "-d")
         plan["argv"] = argv
         plan["detached"] = True
-    EventLog(workspace).write(
-        "leader.start",
-        provider=provider,
-        workspace=str(workspace),
-        mode=plan["mode"],
-        session_name=plan.get("session_name"),
-        argv=plan["argv"],
-    )
+    EventLog(workspace).write("leader.start", provider=provider, workspace=str(workspace), mode=plan["mode"], session_name=plan.get("session_name"), argv=_leader_plan_log_argv(plan), leader_session_uuid_source=plan.get("leader_session_uuid_source"), uuid_prefix=str(plan.get("leader_session_uuid") or "")[:12] or None)
     _run_leader_plan(plan, workspace)
 
 
@@ -110,33 +98,23 @@ def leader_start_plan(
     if not adapter.is_installed():
         raise RuntimeError(f"Provider {provider} command {adapter.command_name!r} not found")
     argv = [adapter.command_name, *provider_args]
+    identity = _leader_identity_context(workspace)
+    leader_env = _leader_provider_env(provider, identity)
     if attach_session:
         if not confirm_attach:
             raise RuntimeError("--attach-session requires --confirm")
-        return {
-            "mode": "attach_existing",
-            "provider": provider,
-            "workspace": str(workspace),
-            "session_name": attach_session,
-            "argv": ["tmux", "attach-session", "-t", attach_session],
-        }
+        return {"mode": "attach_existing", "provider": provider, "workspace": str(workspace), "session_name": attach_session, "argv": ["tmux", "attach-session", "-t", attach_session]}
     if os.environ.get("TMUX"):
-        return {"mode": "exec_provider", "provider": provider, "workspace": str(workspace), "argv": argv}
+        return {"mode": "exec_provider", "provider": provider, "workspace": str(workspace), "argv": argv, "env": {**os.environ, **leader_env}, **identity}
     if not shutil_which("tmux"):
         raise RuntimeError("tmux is not installed; install tmux 3.3+ or start the leader from an existing tmux pane")
     session_name = leader_session_name(provider, workspace)
     if _tmux_session_exists(session_name):
-        return {
-            "mode": "attach_existing",
-            "provider": provider,
-            "workspace": str(workspace),
-            "session_name": session_name,
-            "argv": ["tmux", "attach-session", "-t", session_name],
-        }
-    exports = ""
+        return {"mode": "attach_existing", "provider": provider, "workspace": str(workspace), "session_name": session_name, "argv": ["tmux", "attach-session", "-t", session_name]}
+    exports = " ".join(f"{key}={shlex.quote(value)}" for key, value in leader_env.items())
     if os.environ.get("PATH"):
-        exports = f"PATH={shlex.quote(os.environ['PATH'])} "
-    shell = f"cd {shlex.quote(str(workspace))} && {exports}exec {shlex.join(argv)}"
+        exports = f"{exports} PATH={shlex.quote(os.environ['PATH'])}"
+    shell = f"cd {shlex.quote(str(workspace))} && export {exports} && exec {shlex.join(argv)}"
     tmux_args = ["tmux", "new-session", "-s", session_name, "-n", provider, "-c", str(workspace)]
     return {
         "mode": "new_tmux_session",
@@ -144,6 +122,8 @@ def leader_start_plan(
         "workspace": str(workspace),
         "session_name": session_name,
         "argv": [*tmux_args, "sh", "-lc", shell],
+        "leader_env": leader_env,
+        **identity,
         "detached": False,
     }
 
@@ -174,7 +154,7 @@ def _run_leader_plan(plan: dict[str, Any], workspace: Path) -> None:
     try:
         if plan["mode"] == "exec_provider":
             os.chdir(workspace)
-        proc = subprocess.Popen(plan["argv"])
+        proc = subprocess.Popen(plan["argv"], env=plan.get("env"))
         if plan.get("detached") and session_name:
             proc.wait()
             while _tmux_session_exists_local(str(session_name)):
@@ -206,6 +186,70 @@ def leader_session_name(provider: str, workspace: Path) -> str:
     return f"team-agent-leader-{provider}-{folder}-{digest}"
 
 
+def _leader_identity_context(workspace: Path, team: str | None = None, state: dict[str, Any] | None = None) -> dict[str, Any]:
+    state = state or _load_identity_state(workspace, team)
+    team_id = team_state_key(state)
+    machine = _identity_machine_fingerprint(state)
+    user = _identity_os_user()
+    override = os.environ.get("TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE") or ""
+    leader_uuid = override or _state_leader_session_uuid(state) or derive_leader_session_uuid(
+        machine,
+        str(workspace.resolve()),
+        user,
+        team_id,
+    )
+    return {
+        "leader_session_uuid": leader_uuid,
+        "leader_session_uuid_source": "override" if override else "derived",
+        "machine_fingerprint": machine,
+        "workspace_abspath": str(workspace.resolve()),
+        "os_user": user,
+        "team_id": team_id,
+    }
+
+
+def _load_identity_state(workspace: Path, team: str | None) -> dict[str, Any]:
+    try:
+        return select_runtime_state(workspace, team)
+    except Exception:
+        return load_runtime_state(workspace)
+
+
+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 os.uname().nodename
+
+
+def _identity_os_user() -> str:
+    return os.environ.get("USER") or os.environ.get("USERNAME") or ""
+
+
+def _state_leader_session_uuid(state: dict[str, Any]) -> str:
+    for record in (state.get("team_owner"), state.get("leader_receiver")):
+        if isinstance(record, dict) and record.get("leader_session_uuid"):
+            return str(record["leader_session_uuid"])
+    return ""
+
+
+def _leader_provider_env(provider: str, identity: dict[str, Any]) -> dict[str, str]:
+    return {
+        "TEAM_AGENT_LEADER_PROVIDER": provider,
+        "TEAM_AGENT_LEADER_SESSION_UUID": str(identity["leader_session_uuid"]),
+        "TEAM_AGENT_MACHINE_FINGERPRINT": str(identity["machine_fingerprint"]),
+        "TEAM_AGENT_WORKSPACE": str(identity["workspace_abspath"]),
+        "TEAM_AGENT_TEAM_ID": str(identity["team_id"]),
+    }
+
+
+def _leader_plan_log_argv(plan: dict[str, Any]) -> list[str]:
+    uuid_value = str(plan.get("leader_session_uuid") or "")
+    if not uuid_value:
+        return plan["argv"]
+    return [str(part).replace(uuid_value, f"{uuid_value[:12]}...") for part in plan["argv"]]
+
+
 def attach_leader_to_state(
     workspace: Path,
     state: dict[str, Any],
@@ -221,12 +265,17 @@ def attach_leader_to_state(
         _resolve_leader_pane,
         _target_fingerprint,
         _validate_leader_receiver,
+        core_list_targets,
         get_adapter,
+        run_cmd,
     )
     get_adapter(provider)
     pane_info, discovery = _resolve_leader_pane(pane, provider, workspace=workspace, require_current=require_current)
     inferred_provider = _leader_command_provider(pane_info.get("pane_current_command", ""))
     receiver_provider = inferred_provider or provider
+    identity = _leader_identity_context(workspace, state=state)
+    if identity.get("leader_session_uuid_source") == "override":
+        event_log.write("leader_session_uuid.override", source="explicit-override", uuid_prefix=str(identity.get("leader_session_uuid") or "")[:12], team_id=identity.get("team_id"))
     receiver = {
         "mode": "direct_tmux",
         "status": "attached",
@@ -242,38 +291,200 @@ def attach_leader_to_state(
         "attached_at": datetime.now(timezone.utc).isoformat(),
         "discovery": discovery,
     }
+    if not state.get("team_owner") and source in {"launch", "quick_start"}:
+        validation = apply_first_time_leader_binding(workspace, state, receiver, pane_info, identity, source)
+        if not validation["ok"]:
+            event_log.write("leader_receiver.attach_failed", target=pane or pane_info.get("pane_id"), discovery=discovery, provider=provider, reason=validation["reason"], error=validation.get("error"), source=source, first_time=True, uuid_prefix=str(identity.get("leader_session_uuid") or "")[:12])
+            raise RuntimeError(f"leader pane validation failed: {validation['reason']}")
+        _set_tmux_leader_environment(receiver, identity, event_log, run_cmd)
+        event_log.write("leader_receiver.attached", target=receiver["pane_id"], session_name=receiver["session_name"], window_index=receiver["window_index"], window_name=receiver["window_name"], pane_index=receiver["pane_index"], pane_tty=receiver["pane_tty"], pane_current_command=receiver["pane_current_command"], provider=receiver_provider, requested_provider=provider if receiver_provider != provider else None, discovery=discovery, source=source, first_time=True, uuid_prefix=str(identity.get("leader_session_uuid") or "")[:12], leader_session_uuid_source=identity.get("leader_session_uuid_source"))
+        return receiver, validation
+    if receiver_provider != "fake":
+        receiver["leader_session_uuid"] = identity["leader_session_uuid"]
     if receiver_provider != provider:
         receiver["requested_provider"] = provider
-    validation = _validate_leader_receiver(receiver)
+    validation = validate_leader_uuid_from_targets(receiver, core_list_targets())
+    if validation["ok"]:
+        validation = _validate_leader_receiver(receiver)
     if not validation["ok"]:
-        event_log.write(
-            "leader_receiver.attach_failed",
-            target=pane or pane_info.get("pane_id"),
-            discovery=discovery,
-            provider=provider,
-            reason=validation["reason"],
-            error=validation.get("error"),
-            source=source,
-        )
-        raise RuntimeError(f"leader pane validation failed: {validation['reason']}")
+        event_log.write("leader_receiver.attach_failed", target=pane or pane_info.get("pane_id"), discovery=discovery, provider=provider, reason=validation["reason"], error=validation.get("error"), source=source, uuid_prefix=str(identity.get("leader_session_uuid") or "")[:12])
+        raise RuntimeError(_strict_leader_validation_error(validation))
     if validation.get("warning"):
         receiver["warning"] = validation["warning"]
     state["leader_receiver"] = receiver
+    event_log.write("leader_receiver.attached", target=receiver["pane_id"], session_name=receiver["session_name"], window_index=receiver["window_index"], window_name=receiver["window_name"], pane_index=receiver["pane_index"], pane_tty=receiver["pane_tty"], pane_current_command=receiver["pane_current_command"], provider=receiver_provider, requested_provider=provider if receiver_provider != provider else None, discovery=discovery, source=source, uuid_prefix=str(identity.get("leader_session_uuid") or "")[:12], leader_session_uuid_source=identity.get("leader_session_uuid_source"))
+    return receiver, validation
+
+
+def _set_tmux_leader_environment(receiver: dict[str, Any], identity: dict[str, Any], event_log: EventLog, run_cmd: Any) -> None:
+    session_name = receiver.get("session_name")
+    if not session_name:
+        return
+    failures: dict[str, str] = {}
+    for key, value in leader_env_exports(receiver, identity).items():
+        proc = run_cmd(["tmux", "set-environment", "-t", str(session_name), key, value], timeout=5)
+        if proc.returncode != 0:
+            failures[key] = proc.stderr.strip() or "tmux set-environment failed"
     event_log.write(
-        "leader_receiver.attached",
-        target=receiver["pane_id"],
-        session_name=receiver["session_name"],
-        window_index=receiver["window_index"],
-        window_name=receiver["window_name"],
-        pane_index=receiver["pane_index"],
-        pane_tty=receiver["pane_tty"],
-        pane_current_command=receiver["pane_current_command"],
-        provider=receiver_provider,
-        requested_provider=provider if receiver_provider != provider else None,
-        discovery=discovery,
-        source=source,
+        "leader_receiver.first_time_env_seeded",
+        pane_id=receiver.get("pane_id"),
+        session_name=session_name,
+        ok=not failures,
+        failed_keys=sorted(failures),
     )
-    return receiver, validation
+
+def _strict_leader_validation_error(validation: dict[str, Any]) -> str:
+    return (
+        f"leader pane validation failed: {validation['reason']}. "
+        "first quick-start uses cwd+command match only; this team already has team_owner "
+        "so strict UUID gate applies; use team-agent takeover --confirm if you intend to take over"
+    )
+
+
+def leader_identity(workspace: Path, team: str | None = None) -> dict[str, Any]:
+    state = _load_identity_state(workspace, team)
+    identity = _leader_identity_context(workspace, team=team, state=state)
+    receiver = state.get("leader_receiver") if isinstance(state.get("leader_receiver"), dict) else {}
+    return {
+        "ok": True,
+        "uuid_prefix": str(identity["leader_session_uuid"])[:12],
+        "machine_fingerprint": identity["machine_fingerprint"],
+        "workspace_abspath": identity["workspace_abspath"],
+        "os_user": identity["os_user"],
+        "team_id": identity["team_id"],
+        "current_pane_id": os.environ.get("TEAM_AGENT_LEADER_PANE_ID") or os.environ.get("TMUX_PANE") or None,
+        "last_seen_at": receiver.get("attached_at") or receiver.get("last_seen_at"),
+        "source": identity["leader_session_uuid_source"],
+    }
+
+
+def claim_leader(workspace: Path, team: str | None = None, confirm: bool = False) -> dict[str, Any]:
+    from team_agent.runtime import RuntimeError, _runtime_lock, core_list_targets
+    current_pane = os.environ.get("TEAM_AGENT_LEADER_PANE_ID") or os.environ.get("TMUX_PANE")
+    if not current_pane:
+        return {"ok": False, "status": "refused", "reason": "no_caller_pane", "action": "run from a tmux leader pane"}
+    with _runtime_lock(workspace, "leader_receiver"):
+        state = select_runtime_state(workspace, team)
+        event_log = EventLog(workspace)
+        incident = _latest_ambiguous_incident(event_log, team_state_key(state))
+        if not incident:
+            return {"ok": False, "status": "refused", "reason": "no_ambiguous_candidates"}
+        candidates = [str(item) for item in incident.get("candidates", [])]
+        if current_pane not in candidates:
+            return {"ok": False, "status": "refused", "reason": "caller_not_candidate", "candidates": candidates}
+        receiver = state.get("leader_receiver") or {}
+        if receiver.get("pane_id") == current_pane:
+            return {"ok": True, "status": "already_bound", "leader_receiver": receiver}
+        if _incident_already_claimed(event_log, str(incident.get("incident_id"))):
+            return _claim_lost_race(receiver)
+        if receiver.get("pane_id") in candidates and receiver.get("pane_id") != incident.get("old_pane_id"):
+            return _claim_lost_race(receiver)
+        if not confirm:
+            return {"ok": True, "status": "dry_run", "would_bind_pane_id": current_pane, "candidates": candidates}
+        targets = core_list_targets()
+        if not targets.get("ok"):
+            raise RuntimeError(str(targets.get("error") or "tmux target scan failed"))
+        target = next((item for item in targets.get("targets", []) if item.get("pane_id") == current_pane), None)
+        if not target:
+            return {"ok": False, "status": "refused", "reason": "candidate_pane_missing", "pane_id": current_pane}
+        owner = state.setdefault("team_owner", {})
+        expected_uuid = str(owner.get("leader_session_uuid") or _leader_identity_context(workspace, team=team, state=state)["leader_session_uuid"])
+        target_uuid = _target_leader_session_uuid(target)
+        if target_uuid != expected_uuid:
+            return {"ok": False, "status": "refused", "reason": "leader_session_uuid_mismatch", "uuid_prefix": expected_uuid[:12]}
+        epoch = int(owner.get("owner_epoch") or receiver.get("owner_epoch") or 0) + 1
+        owner.update({"pane_id": current_pane, "owner_epoch": epoch, "claimed_at": datetime.now(timezone.utc).isoformat(), "claimed_via": "claim-leader"})
+        state["leader_receiver"] = _receiver_from_claim_target(target, receiver, expected_uuid, epoch)
+        save_team_scoped_state(workspace, state)
+        losers = [pane for pane in candidates if pane != current_pane]
+        event_log.write(
+            "leader_receiver.claim_applied",
+            incident_id=incident.get("incident_id"),
+            winner_pane_id=current_pane,
+            losers=losers,
+            owner_epoch=epoch,
+            uuid_prefix=expected_uuid[:12],
+        )
+        # Stage 11.9 (Gap 26 Mac mini Scenario 3): result watchers that stalled while the
+        # broadcast was waiting for a human claim need fresh budget against the newly bound
+        # pane. Per-watcher leader_receiver.claim_requeue events + immediate retry.
+        from team_agent.message_store import MessageStore
+        from team_agent.messaging.result_delivery import requeue_after_claim_leader
+        requeued = requeue_after_claim_leader(
+            workspace,
+            MessageStore(workspace),
+            event_log,
+            team_state_key(state),
+            current_pane,
+            incident_ts=incident.get("ts"),
+        )
+        response: dict[str, Any] = {
+            "ok": True,
+            "status": "claimed",
+            "leader_receiver": state["leader_receiver"],
+            "owner_epoch": epoch,
+            "losers": losers,
+            "requeued_watchers": [item["watcher_id"] for item in requeued],
+        }
+        # Stage 13 (silent-loss arm mailbox-hint route, 2026-05-26 second roundtable):
+        # the framework cannot guarantee every worker message reached the leader pane during
+        # the ambiguous-state window (retry budgets may have exhausted before the human
+        # claimed). Pointing the leader agent at the inbox lets it self-recover by reading
+        # the messages that landed in storage but never injected to a pane.
+        incident_ts = incident.get("ts")
+        if incident_ts:
+            response["inbox_hint"] = {
+                "message": (
+                    "During the previous ambiguous-leader state, some worker messages may "
+                    "not have been auto-delivered to this pane. Run the command below to "
+                    "retrieve them."
+                ),
+                "command": f"team-agent inbox leader --since {incident_ts}",
+                "since": incident_ts,
+                "incident_id": incident.get("incident_id"),
+            }
+        return response
+
+
+def _latest_ambiguous_incident(event_log: EventLog, team_id: str) -> dict[str, Any] | None:
+    for event in reversed(event_log.tail(200)):
+        if event.get("event") != "leader_receiver.ambiguous_candidates":
+            continue
+        if event.get("team_id") in {None, team_id}:
+            return event
+    return None
+
+
+def _incident_already_claimed(event_log: EventLog, incident_id: str) -> bool:
+    return any(event.get("event") == "leader_receiver.claim_applied" and event.get("incident_id") == incident_id for event in event_log.tail(200))
+
+
+def _claim_lost_race(receiver: dict[str, Any]) -> dict[str, Any]:
+    return {"ok": False, "status": "refused", "reason": "owner_epoch_advanced", "error": f"team already bound to pane {receiver.get('pane_id')}; you lost the race", "bound_pane_id": receiver.get("pane_id"), "owner_epoch": receiver.get("owner_epoch")}
+
+
+def _target_leader_session_uuid(target: dict[str, Any]) -> str:
+    env = target.get("leader_env") if isinstance(target.get("leader_env"), dict) else {}
+    return str(target.get("leader_session_uuid") or env.get("TEAM_AGENT_LEADER_SESSION_UUID") or "")
+
+
+def _receiver_from_claim_target(target: dict[str, Any], previous: dict[str, Any], leader_uuid: str, owner_epoch: int) -> dict[str, Any]:
+    return {
+        "mode": "direct_tmux",
+        "status": "attached",
+        "provider": previous.get("provider") or "codex",
+        "pane_id": target["pane_id"],
+        "session_name": target.get("session_name"),
+        "window_index": str(target.get("window_index")),
+        "window_name": target.get("window_name"),
+        "pane_index": str(target.get("pane_index")),
+        "pane_tty": target.get("pane_tty"),
+        "pane_current_command": target.get("pane_current_command"),
+        "leader_session_uuid": leader_uuid,
+        "owner_epoch": owner_epoch,
+        "attached_at": datetime.now(timezone.utc).isoformat(),
+        "discovery": "claim_leader",
+    }
 
 
 def autobind_leader_receiver_from_env(
@@ -314,6 +525,8 @@ __all__ = [
     "attach_leader",
     "attach_leader_to_state",
     "autobind_leader_receiver_from_env",
+    "claim_leader",
+    "leader_identity",
     "leader_session_name",
     "leader_start_plan",
     "start_leader",

package/src/team_agent/lifecycle/agents.py

@@ -57,30 +57,80 @@ def remove_agent(
 
     rollback = _RemoveRollback(workspace, spec_path, spec, state, dynamic_role_file, store, agent_id, False)
     stopped: dict[str, Any] | None = None
+    cleared_locations: list[str] = []
+    current_step = "init"
+    current_resource: str | None = None
+
+    def _step_done(name: str, resource: str | None = None, **extra: Any) -> None:
+        cleared_locations.append(name)
+        event_log.write(
+            "lifecycle.remove_step_completed",
+            agent_id=agent_id,
+            step=name,
+            resource=resource,
+            **extra,
+        )
+
     try:
         if running and force:
+            current_step, current_resource = "stop_agent", agent_id
             stopped = runtime.stop_agent(workspace, agent_id, team=team)
             rollback.restore_running = True
             state, _refusal_after = resolve_team_scoped_state(workspace, team)
+            _step_done("stop_agent", resource=agent_id, stopped=stopped)
+
+        current_step, current_resource = "workspace_state", "state.json:agents"
         removed_state = copy.deepcopy(state)
         removed_state.get("agents", {}).pop(agent_id, None)
         save_team_scoped_state(workspace, removed_state)
+        _step_done("workspace_state", resource=current_resource)
 
+        current_step, current_resource = "spec_yaml", str(spec_path)
         removed_spec = copy.deepcopy(spec)
         removed_spec["agents"] = [item for item in removed_spec.get("agents", []) if item.get("id") != agent_id]
         startup_order = removed_spec.get("runtime", {}).get("startup_order")
         if isinstance(startup_order, list):
             removed_spec["runtime"]["startup_order"] = [item for item in startup_order if item != agent_id]
         validate_spec(removed_spec, base_dir=spec_path.parent)
+        current_step, current_resource = "team_state_md", "team_state.md"
         team_state_path = write_team_state(workspace, removed_spec, removed_state)
+        _step_done("team_state_md", resource=str(team_state_path))
+        current_step, current_resource = "spec_yaml", str(spec_path)
         write_spec(spec_path, removed_spec)
+        _step_done("spec_yaml", resource=str(spec_path))
 
+        current_step, current_resource = "role_file", str(dynamic_role_file)
         role_file_removed = _remove_dynamic_role_file(dynamic_role_file, bool(agent_state.get("dynamic_role_file")))
+        if role_file_removed:
+            _step_done("role_file", resource=str(dynamic_role_file))
+
+        current_step, current_resource = "agent_health", agent_id
         _delete_agent_health(store, agent_id)
+        _step_done("agent_health", resource=agent_id)
     except Exception as exc:
         rollback_result = rollback.restore(runtime, event_log)
-        event_log.write("remove_agent.rollback", agent_id=agent_id, ok=rollback_result["ok"], error=str(exc), rollback=rollback_result)
-        raise RuntimeError(f"remove-agent failed for {agent_id}: {exc}; rollback_ok={rollback_result['ok']}") from exc
+        event_log.write(
+            "remove_agent.rollback",
+            agent_id=agent_id,
+            ok=rollback_result["ok"],
+            error=str(exc),
+            failed_step=current_step,
+            resource=current_resource,
+            cleared_before_failure=cleared_locations,
+            rollback=rollback_result,
+        )
+        event_log.write(
+            "lifecycle.remove_rolled_back",
+            agent_id=agent_id,
+            ok=rollback_result["ok"],
+            failed_step=current_step,
+            resource=current_resource,
+            rollback_errors=rollback_result.get("errors", []),
+        )
+        raise RuntimeError(
+            f"remove-agent failed for {agent_id} at step={current_step} "
+            f"resource={current_resource}: {exc}; rollback_ok={rollback_result['ok']}"
+        ) from exc
 
     runtime._save_team_runtime_snapshot(workspace, removed_state)
     warning = None
@@ -93,6 +143,7 @@ def remove_agent(
             force=force,
             stopped=stopped,
             role_file_removed=role_file_removed,
+            cleared_locations=cleared_locations,
         )
     except Exception as exc:
         warning = f"remove-agent completed but success event logging failed: {exc}"
@@ -105,6 +156,7 @@ def remove_agent(
         "stopped": stopped,
         "state_file": str(team_state_path),
         "role_file_removed": role_file_removed,
+        "cleared_locations": cleared_locations,
         **({"warning": warning} if warning else {}),
     }
 

package/src/team_agent/lifecycle/operations.py

@@ -154,32 +154,109 @@ def add_agent(workspace: Path, agent_id: str, *, role_file_path: str, open_displ
     old_spec_text = spec_path.read_text(encoding="utf-8")
     old_state = copy.deepcopy(state)
     old_dynamic = dynamic_path.read_bytes() if dynamic_path.exists() else None
+    # Stage 11.11 (Gap 15 follow-up): snapshot team_state.md BEFORE any write so the rollback
+    # path can restore it byte-equal. Pre-Stage-11.11 the rollback handler omitted this file
+    # and Mac mini Scenario 6 left orphan entries after induced add-agent failures.
+    team_state_path = workspace / spec.get("context", {}).get("state_file", "team_state.md")
+    old_team_state = team_state_path.read_bytes() if team_state_path.exists() else None
     event_log = EventLog(workspace)
+    cleared_locations: list[str] = []
+    current_step = "init"
+    current_resource: str | None = None
+
+    def _step_done(name: str, resource: str | None = None, **extra: Any) -> None:
+        cleared_locations.append(name)
+        event_log.write(
+            "lifecycle.add_step_completed",
+            agent_id=agent_id,
+            step=name,
+            resource=resource,
+            **extra,
+        )
+
     try:
+        current_step, current_resource = "role_file", str(dynamic_path)
         dynamic_dir.mkdir(parents=True, exist_ok=True)
         dynamic_path.write_bytes(role_bytes)
+        _step_done("role_file", resource=str(dynamic_path))
+
+        current_step, current_resource = "compile_role_doc", str(dynamic_path)
         agent = compile_role_doc_agent(dynamic_path, team_dir, agent_id)
+        _step_done("compile_role_doc", resource=str(dynamic_path))
+
+        current_step, current_resource = "spec_yaml", str(spec_path)
         spec.setdefault("agents", []).append(agent)
         spec.setdefault("runtime", {}).setdefault("startup_order", []).append(agent_id)
         validate_spec(spec, base_dir=spec_path.parent)
         write_spec(spec_path, spec)
+        _step_done("spec_yaml", resource=str(spec_path))
+
+        current_step, current_resource = "team_state_md", "team_state.md"
         write_team_state(workspace, spec, state)
+        _step_done("team_state_md", resource="team_state.md")
+
+        current_step, current_resource = "start_agent", agent_id
         started = start_agent(workspace, agent_id, open_display=open_display, allow_fresh=True, team=team)
+        _step_done("start_agent", resource=agent_id, started=started)
+
+        current_step, current_resource = "workspace_state", "state.json:agents"
         state, _refusal_after = resolve_team_scoped_state(workspace, team)
         state["agents"][agent_id]["dynamic_role_file"] = str(dynamic_path.relative_to(workspace))
         state["agents"][agent_id]["role_file_sha"] = role_sha
         save_team_scoped_state(workspace, state)
         state_path = write_team_state(workspace, spec, state)
-    except Exception:
-        spec_path.write_text(old_spec_text, encoding="utf-8")
-        save_team_scoped_state(workspace, old_state)
-        if old_dynamic is None:
-            dynamic_path.unlink(missing_ok=True)
-        else:
-            dynamic_path.parent.mkdir(parents=True, exist_ok=True)
-            dynamic_path.write_bytes(old_dynamic)
+        _step_done("workspace_state", resource="state.json:agents")
+    except Exception as exc:
+        rolled_back: list[str] = []
+        rollback_errors: list[str] = []
+        try:
+            spec_path.write_text(old_spec_text, encoding="utf-8")
+            rolled_back.append("spec_yaml")
+            event_log.write("lifecycle.add_step_rolled_back", agent_id=agent_id,
+                            step="spec_yaml", resource=str(spec_path))
+        except Exception as restore_exc:
+            rollback_errors.append(f"spec_yaml:{restore_exc}")
+        try:
+            save_team_scoped_state(workspace, old_state)
+            rolled_back.append("workspace_state")
+            event_log.write("lifecycle.add_step_rolled_back", agent_id=agent_id,
+                            step="workspace_state", resource="state.json:agents")
+        except Exception as restore_exc:
+            rollback_errors.append(f"workspace_state:{restore_exc}")
+        try:
+            if old_team_state is None:
+                team_state_path.unlink(missing_ok=True)
+            else:
+                team_state_path.parent.mkdir(parents=True, exist_ok=True)
+                team_state_path.write_bytes(old_team_state)
+            rolled_back.append("team_state_md")
+            event_log.write("lifecycle.add_step_rolled_back", agent_id=agent_id,
+                            step="team_state_md", resource=str(team_state_path))
+        except Exception as restore_exc:
+            rollback_errors.append(f"team_state_md:{restore_exc}")
+        try:
+            if old_dynamic is None:
+                dynamic_path.unlink(missing_ok=True)
+            else:
+                dynamic_path.parent.mkdir(parents=True, exist_ok=True)
+                dynamic_path.write_bytes(old_dynamic)
+            rolled_back.append("role_file")
+            event_log.write("lifecycle.add_step_rolled_back", agent_id=agent_id,
+                            step="role_file", resource=str(dynamic_path))
+        except Exception as restore_exc:
+            rollback_errors.append(f"role_file:{restore_exc}")
+        event_log.write(
+            "lifecycle.add_failed",
+            agent_id=agent_id,
+            failed_step=current_step,
+            failed_resource=current_resource,
+            cleared_locations=cleared_locations,
+            rolled_back=rolled_back,
+            rollback_errors=rollback_errors,
+            reason=str(exc),
+        )
         raise
-    event_log.write("add_agent.complete", agent_id=agent_id, role_file=str(dynamic_path), role_file_sha=role_sha, started=started)
+    event_log.write("add_agent.complete", agent_id=agent_id, role_file=str(dynamic_path), role_file_sha=role_sha, started=started, cleared_locations=cleared_locations)
     return {
         "ok": True,
         "agent_id": agent_id,