@team-agent/installer 0.2.0 → 0.2.2

package/src/team_agent/messaging/idle_alerts.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, 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.messaging.deps import load_spec, save_runtime_state, team_state_key
+from team_agent.messaging.deps import load_runtime_state, load_spec, save_runtime_state, team_state_key
 from team_agent.messaging.internal_delivery import deliver_stored_message
 
 
@@ -23,33 +23,212 @@ _UNDELIVERED_MESSAGE_STATUSES = {
 }
 
 
+STABLE_IDLE_SECONDS = 120
+FIRE_DEBOUNCE_SECONDS = 300
+OBLIGATION_PENDING_MIN_AGE_SECONDS = 60
+
+# Event-log progress signal (Gap 32 §"Idle-Detector False Positive Continues Post Phase G hotfix-3"):
+# the team_last_progress_at calculation must also count leader-side sends and worker MCP calls
+# as recent team activity, not only agent_health.last_output_at. Without this, a worker that has
+# called MCP but not yet emitted a visible turn shows up as idle and the idle reminder fires
+# spuriously inside the stable-idle window.
+_PROGRESS_EVENT_TYPES = frozenset({
+    "send.deliver_attempt",
+    "leader_receiver.deliver_attempt",
+    "mcp.report_result",
+    "mcp.send_message",
+})
+_PROGRESS_EVENT_PREFIXES = ("mcp.read_",)
+_PROGRESS_EVENT_WINDOW_SECONDS = 300
+_PROGRESS_EVENT_TAIL_LIMIT = 1000
+
+
+def _parse_iso(text: Any) -> datetime | None:
+    if not isinstance(text, str) or not text:
+        return None
+    try:
+        dt = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def record_team_progress(
+    state: dict[str, Any],
+    now: datetime | None = None,
+    *,
+    source: str = "",
+    owner_team_id: str | None = None,
+) -> None:
+    coordinator = state.setdefault("coordinator", {})
+    progress = coordinator.setdefault("team_last_progress_at", {})
+    key = owner_team_id or team_state_key(state)
+    if not key:
+        return
+    progress[key] = {
+        "at": (now or datetime.now(timezone.utc)).isoformat(),
+        "source": source,
+    }
+
+
+def _team_last_progress_at(
+    state: dict[str, Any],
+    store: MessageStore,
+    owner_team_id: str,
+    event_log: EventLog | None = None,
+    now: datetime | None = None,
+    workspace: Path | None = None,
+) -> tuple[datetime | None, str | None]:
+    sources: list[tuple[datetime, str]] = []
+    coordinator = state.get("coordinator") or {}
+    explicit = (coordinator.get("team_last_progress_at") or {}).get(owner_team_id)
+    if isinstance(explicit, dict):
+        ts = _parse_iso(explicit.get("at"))
+        if ts:
+            sources.append((ts, "explicit_marker"))
+    elif isinstance(explicit, str):
+        ts = _parse_iso(explicit)
+        if ts:
+            sources.append((ts, "explicit_marker"))
+    health = store.agent_health(owner_team_id=owner_team_id)
+    for row in health.values():
+        ts = _parse_iso(row.get("last_output_at"))
+        if ts:
+            sources.append((ts, "agent_health.last_output_at"))
+    if event_log is not None:
+        # Spark MEDIUM #3 (d9f740d): in multi-team workspaces an unscoped progress event in
+        # team A's activity must NOT suppress team B's idle_fallback. require_team_scope=True
+        # when the workspace has more than one team so unscoped events are ignored. The
+        # team-scoped state passed in here does not carry the workspace-level `teams` dict, so
+        # we re-read the workspace state from disk to detect multi-team shape.
+        require_team_scope = False
+        teams = state.get("teams")
+        if isinstance(teams, dict) and len(teams) > 1:
+            require_team_scope = True
+        elif workspace is not None:
+            try:
+                ws_teams = (load_runtime_state(workspace).get("teams") or {})
+            except Exception:
+                ws_teams = {}
+            if isinstance(ws_teams, dict) and len(ws_teams) > 1:
+                require_team_scope = True
+        event_ts = _scan_event_progress_signals(
+            event_log, owner_team_id, now or datetime.now(timezone.utc),
+            require_team_scope=require_team_scope,
+        )
+        if event_ts:
+            sources.append((event_ts, "event_log"))
+    if not sources:
+        return None, None
+    sources.sort(key=lambda item: item[0], reverse=True)
+    return sources[0]
+
+
+# Stage 14 (Gap 36b) — mtime cache per (workspace_path, owner_team_id, require_team_scope).
+# Mac mini 2026-05-26 evidence: _scan_event_progress_signals was a 22% CPU hot path because
+# every 2-second coordinator tick parsed up to 1000 events from a 28 MB events.jsonl. With
+# the cache, the parse only re-runs when the file changes; quiet workspaces pay zero file
+# I/O between writes.
+_PROGRESS_SCAN_CACHE: dict[tuple[str, str, bool], tuple[float, datetime | None]] = {}
+
+
+def _scan_event_progress_signals(
+    event_log: EventLog,
+    owner_team_id: str,
+    now: datetime,
+    *,
+    require_team_scope: bool = False,
+) -> datetime | None:
+    cache_key = (str(event_log.path), owner_team_id, require_team_scope)
+    try:
+        current_mtime = event_log.path.stat().st_mtime
+    except FileNotFoundError:
+        _PROGRESS_SCAN_CACHE.pop(cache_key, None)
+        return None
+    cached = _PROGRESS_SCAN_CACHE.get(cache_key)
+    if cached is not None and cached[0] == current_mtime:
+        return cached[1]
+    window_start = now - timedelta(seconds=_PROGRESS_EVENT_WINDOW_SECONDS)
+    latest: datetime | None = None
+    for event in event_log.tail(_PROGRESS_EVENT_TAIL_LIMIT):
+        event_type = str(event.get("event") or "")
+        if event_type not in _PROGRESS_EVENT_TYPES and not any(
+            event_type.startswith(prefix) for prefix in _PROGRESS_EVENT_PREFIXES
+        ):
+            continue
+        event_team = event.get("team") or event.get("owner_team_id")
+        if event_team is None:
+            if require_team_scope:
+                continue
+        elif event_team != owner_team_id:
+            continue
+        ts = _parse_iso(event.get("ts"))
+        if not ts or ts < window_start:
+            continue
+        if latest is None or ts > latest:
+            latest = ts
+    _PROGRESS_SCAN_CACHE[cache_key] = (current_mtime, latest)
+    return latest
+
+
+def _reset_progress_scan_cache() -> None:
+    """Test-only hook to force re-scan."""
+    _PROGRESS_SCAN_CACHE.clear()
+
+
+def _team_last_idle_fallback_fire_at(state: dict[str, Any], owner_team_id: str) -> datetime | None:
+    coordinator = state.get("coordinator") or {}
+    fires = coordinator.get("team_last_idle_fallback_fire_at") or {}
+    return _parse_iso(fires.get(owner_team_id))
+
+
+def _record_idle_fallback_fire(state: dict[str, Any], owner_team_id: str, now: datetime) -> None:
+    coordinator = state.setdefault("coordinator", {})
+    fires = coordinator.setdefault("team_last_idle_fallback_fire_at", {})
+    fires[owner_team_id] = now.isoformat()
+
+
 def _team_undelivered_obligations(
     state: dict[str, Any],
     store: MessageStore,
     owner_team_id: str,
     active_task_statuses: set[str],
+    *,
+    now: datetime | None = None,
 ) -> list[dict[str, Any]]:
+    now = now or datetime.now(timezone.utc)
+    min_age = timedelta(seconds=OBLIGATION_PENDING_MIN_AGE_SECONDS)
     obligations: list[dict[str, Any]] = []
     for message in store.messages(owner_team_id=owner_team_id):
-        if message.get("status") in _UNDELIVERED_MESSAGE_STATUSES:
-            obligations.append(
-                {
-                    "kind": "undelivered_message",
-                    "message_id": message.get("message_id"),
-                    "recipient": message.get("recipient"),
-                    "status": message.get("status"),
-                }
-            )
+        if message.get("status") not in _UNDELIVERED_MESSAGE_STATUSES:
+            continue
+        created_at = _parse_iso(message.get("created_at"))
+        if created_at and (now - created_at) < min_age:
+            continue
+        obligations.append(
+            {
+                "kind": "undelivered_message",
+                "message_id": message.get("message_id"),
+                "recipient": message.get("recipient"),
+                "status": message.get("status"),
+            }
+        )
     for watcher in store.retryable_result_watchers():
-        if watcher.get("status") in {"pending", "notify_failed"}:
-            obligations.append(
-                {
-                    "kind": "pending_result_watcher",
-                    "watcher_id": watcher.get("watcher_id"),
-                    "task_id": watcher.get("task_id"),
-                    "agent_id": watcher.get("agent_id"),
-                }
-            )
+        if watcher.get("status") not in {"pending", "notify_failed"}:
+            continue
+        created_at = _parse_iso(watcher.get("created_at"))
+        if created_at and (now - created_at) < min_age:
+            continue
+        obligations.append(
+            {
+                "kind": "pending_result_watcher",
+                "watcher_id": watcher.get("watcher_id"),
+                "task_id": watcher.get("task_id"),
+                "agent_id": watcher.get("agent_id"),
+            }
+        )
     for task in state.get("tasks", []):
         if task.get("status", "pending") in active_task_statuses and task.get("assignee"):
             obligations.append(
@@ -118,11 +297,37 @@ def detect_idle_fallbacks(
     )
     now = now or datetime.now(timezone.utc)
     owner_team_id = team_state_key(state)
-    obligations = _team_undelivered_obligations(state, store, owner_team_id, _ACTIVE_TASK_STATUSES)
+    obligations = _team_undelivered_obligations(state, store, owner_team_id, _ACTIVE_TASK_STATUSES, now=now)
     if not obligations:
         return []
     all_idle, idle_workers = _all_workers_idle(state, store, owner_team_id)
     if not all_idle:
+        record_team_progress(state, now, source="all_workers_idle:false", owner_team_id=owner_team_id)
+        save_runtime_state(workspace, state)
+        return []
+    last_progress, progress_source = _team_last_progress_at(
+        state, store, owner_team_id, event_log=event_log, now=now, workspace=workspace,
+    )
+    if last_progress and (now - last_progress) < timedelta(seconds=STABLE_IDLE_SECONDS):
+        reason = "recent_team_progress" if progress_source == "event_log" else "stable_idle_window"
+        event_log.write(
+            "coordinator.idle_fallback_skipped",
+            reason=reason,
+            team=owner_team_id,
+            stable_idle_seconds=STABLE_IDLE_SECONDS,
+            elapsed_seconds=int((now - last_progress).total_seconds()),
+            progress_source=progress_source,
+        )
+        return []
+    last_fire = _team_last_idle_fallback_fire_at(state, owner_team_id)
+    if last_fire and (now - last_fire) < timedelta(seconds=FIRE_DEBOUNCE_SECONDS):
+        event_log.write(
+            "coordinator.idle_fallback_skipped",
+            reason="fire_debounce",
+            team=owner_team_id,
+            fire_debounce_seconds=FIRE_DEBOUNCE_SECONDS,
+            elapsed_seconds=int((now - last_fire).total_seconds()),
+        )
         return []
     spec_path = Path(state.get("spec_path", workspace / "team.spec.yaml"))
     spec = load_spec(spec_path) if spec_path.exists() else {}
@@ -137,6 +342,7 @@ def detect_idle_fallbacks(
         alerts.append({"agent_id": agent_id, "alert_type": "idle_fallback", "obligations": obligations})
     if not alerts:
         return []
+    _record_idle_fallback_fire(state, owner_team_id, now)
     save_runtime_state(workspace, state)
     content = (
         "There is still unfinished work. Continue coordinating, deliver a result, "

package/src/team_agent/messaging/leader.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import hashlib
+
 from team_agent.messaging.deps import (
     EventLog,
     MessageStore,
@@ -10,8 +12,10 @@ from team_agent.messaging.deps import (
     _validate_leader_receiver,
     core_render_message,
     json,
+    os,
     runtime_dir,
     save_runtime_state,
+    team_state_key,
     time,
 )
 
@@ -49,6 +53,19 @@ def _leader_inbox_path(workspace: Path) -> Path:
     return runtime_dir(workspace) / "leader-inbox.log"
 
 
+def _extract_result_id_from_content(content: str) -> str | None:
+    """Stage 12: result-notification messages embed a `Result id: <id>` line; the gate
+    parses it from content so callers that did NOT plumb the result_id kwarg through
+    still consult the dedupe gate. Format mirrors _format_report_result_notification and
+    format_result_watcher_notification."""
+    if not content:
+        return None
+    for line in content.splitlines():
+        if line.startswith("Result id: "):
+            return line.removeprefix("Result id: ").strip() or None
+    return None
+
+
 def _send_to_leader_receiver(
     workspace: Path,
     state: dict[str, Any],
@@ -58,6 +75,8 @@ def _send_to_leader_receiver(
     sender: str,
     requires_ack: bool,
     event_log: EventLog,
+    *,
+    result_id: str | None = None,
 ) -> dict[str, Any]:
     store = MessageStore(workspace)
     message_id = store.create_message(task_id, sender, leader_id, content, requires_ack=False)
@@ -94,10 +113,30 @@ def _send_to_leader_receiver(
             error="No direct leader tmux pane is attached. Run team-agent attach-leader.",
         )
 
-    validation = _validate_leader_receiver(receiver)
+    owner_identity = state.get("team_owner") or None
+    side_pane_refusal = _side_pane_owner_refusal(state, owner_identity)
+    if side_pane_refusal:
+        event_log.write("leader_receiver.side_pane_refused", **side_pane_refusal)
+        return {
+            "ok": False,
+            "message_id": message_id,
+            "status": "refused",
+            "to": leader_id,
+            "channel": "direct_tmux",
+            **side_pane_refusal,
+        }
+    receiver_for_validation = dict(receiver)
+    if owner_identity and owner_identity.get("leader_session_uuid") and not receiver_for_validation.get("leader_session_uuid"):
+        receiver_for_validation["leader_session_uuid"] = owner_identity["leader_session_uuid"]
+    validation = _validate_leader_receiver(receiver_for_validation)
     if not validation["ok"]:
-        owner_identity = state.get("team_owner") or None
-        rediscovery = _rediscover_leader_receiver(receiver, event_log, owner_identity)
+        rediscovery = _rediscover_leader_receiver(
+            receiver_for_validation,
+            event_log,
+            owner_identity,
+            invalidation_reason=validation.get("reason"),
+            team_id=team_state_key(state),
+        )
         if rediscovery.get("status") == "updated":
             state["leader_receiver"].update(rediscovery["receiver"])
             receiver = state["leader_receiver"]
@@ -111,7 +150,7 @@ def _send_to_leader_receiver(
                 payload,
                 event_log,
                 reason="ambiguous",
-                error="multiple possible leader panes found; rerun team-agent attach-leader --pane <pane_id>",
+                error="multiple possible leader panes found; run team-agent claim-leader --confirm from the intended pane",
                 message_status="ambiguous",
             )
     if not validation["ok"]:
@@ -128,6 +167,69 @@ def _send_to_leader_receiver(
     state["leader_receiver"].update(validation["pane"])
     submit_key, submit_reason = _choose_leader_submit_key(receiver.get("provider", "codex"), validation.get("capture", ""))
     target = receiver["pane_id"]
+    # Stage 12 (Gap 26 ∩ Gap 32 roundtable 2026-05-26) — injection-boundary dedupe gate.
+    # Result-notification injections route through claim_leader_notification_delivery; the
+    # gate suppresses a second inject for the same (result_id, leader_session_uuid).
+    # Non-result messages (peer mirror, idle reminder, ambiguous-prompt) lack a "Result id:"
+    # line in their text and bypass the gate.
+    effective_result_id = result_id or _extract_result_id_from_content(content)
+    leader_uuid_for_gate = str(
+        (state.get("team_owner") or {}).get("leader_session_uuid")
+        or (state.get("leader_receiver") or {}).get("leader_session_uuid")
+        or ""
+    )
+    if effective_result_id and leader_uuid_for_gate:
+        from team_agent.message_store.leader_notification_log import claim_leader_notification_delivery
+        envelope_hash = hashlib.sha256(content.encode("utf-8", errors="ignore")).hexdigest()[:16]
+        claim = claim_leader_notification_delivery(
+            store,
+            result_id=effective_result_id,
+            leader_session_uuid=leader_uuid_for_gate,
+            proposed_message_id=message_id,
+            envelope_hash=envelope_hash,
+            owner_team_id=team_state_key(state),
+            pane_id=target,
+        )
+        if claim["status"] == "already_notified_by":
+            prev_msg = claim.get("notified_message_id")
+            prev_hash = claim.get("envelope_content_hash")
+            if envelope_hash == prev_hash:
+                event_log.write(
+                    "leader_notification.dedupe_skip",
+                    result_id=effective_result_id,
+                    leader_session_uuid=leader_uuid_for_gate,
+                    prev_message_id=prev_msg,
+                    this_message_id=message_id,
+                    prev_ts=claim.get("notified_at"),
+                    pane_id=target,
+                    team_id=team_state_key(state),
+                )
+            else:
+                event_log.write(
+                    "leader_notification.legitimate_duplicate_suspected",
+                    result_id=effective_result_id,
+                    leader_session_uuid=leader_uuid_for_gate,
+                    prev_message_id=prev_msg,
+                    this_message_id=message_id,
+                    prev_envelope_hash=prev_hash,
+                    this_envelope_hash=envelope_hash,
+                    pane_id=target,
+                    team_id=team_state_key(state),
+                )
+            store.mark(message_id, "submitted", "dedupe_suppressed_by_leader_notification_log")
+            save_runtime_state(workspace, state)
+            return {
+                "ok": True,
+                "message_id": message_id,
+                "status": "submitted",
+                "to": leader_id,
+                "channel": "direct_tmux",
+                "leader_receiver": state["leader_receiver"],
+                "visible": False,
+                "submitted": False,
+                "deduped": True,
+                "canonical_message_id": prev_msg,
+            }
     event_log.write(
         "leader_receiver.deliver_attempt",
         message_id=message_id,
@@ -139,6 +241,8 @@ def _send_to_leader_receiver(
         visible_token=rendered.get("token"),
         payload=payload,
         warning=validation.get("warning"),
+        result_id=effective_result_id,
+        leader_session_uuid=leader_uuid_for_gate or None,
     )
     injection = _tmux_inject_text(
         target,
@@ -201,6 +305,64 @@ def _send_to_leader_receiver(
     )
 
 
+def _side_pane_owner_refusal(state: dict[str, Any], owner_identity: dict[str, Any] | None) -> dict[str, Any] | None:
+    owner_uuid = str((owner_identity or {}).get("leader_session_uuid") or "")
+    caller_uuid = os.environ.get("TEAM_AGENT_LEADER_SESSION_UUID") or os.environ.get("TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE") or ""
+    if not owner_uuid or not caller_uuid or caller_uuid == owner_uuid:
+        return None
+    bound_pane = (state.get("leader_receiver") or {}).get("pane_id") or (owner_identity or {}).get("pane_id")
+    team_id = team_state_key(state)
+    return {
+        "reason": "team_owner_mismatch",
+        "error": (
+            f"This workspace's team `{team_id}` is already bound to pane `{bound_pane}`. "
+            "To work in this window either start a new team with a different team_id, operate through the bound pane, "
+            "or run `team-agent claim-leader --confirm` only if you intend to forcibly take over."
+        ),
+        "bound_pane_id": bound_pane,
+        "caller_uuid_prefix": caller_uuid[:8],
+        "uuid_prefix": owner_uuid[:8],
+        "action": "team-agent claim-leader --confirm",
+    }
+
+
+def claim_leader_receiver(
+    workspace: Path,
+    state: dict[str, Any],
+    candidate: dict[str, Any],
+    event_log: EventLog,
+    *,
+    confirm: bool,
+    expected_epoch: int | None = None,
+) -> dict[str, Any]:
+    from team_agent.messaging.leader_panes import _leader_command_looks_usable, _receiver_from_target, _target_matches_owner_identity, _uuid_prefix
+    if not confirm:
+        return {"ok": False, "status": "refused", "reason": "confirm_required", "action": "team-agent claim-leader --confirm"}
+    owner = state.setdefault("team_owner", {})
+    receiver = state.get("leader_receiver") or {}
+    current_epoch = int(owner.get("owner_epoch") or receiver.get("owner_epoch") or 0)
+    if expected_epoch is not None and current_epoch != expected_epoch:
+        event_log.write("leader_receiver.claim_refused", reason="owner_epoch_advanced", owner_epoch=current_epoch, bound_pane_id=receiver.get("pane_id"))
+        return {"ok": False, "status": "refused", "reason": "owner_epoch_advanced", "owner_epoch": current_epoch, "bound_pane_id": receiver.get("pane_id")}
+    if receiver.get("pane_id") == candidate.get("pane_id"):
+        return {"ok": True, "status": "already_bound", "leader_receiver": receiver, "owner_epoch": current_epoch}
+    if not _target_matches_owner_identity(candidate, owner):
+        event_log.write("leader_receiver.claim_refused", reason="uuid_mismatch", candidate_pane_id=candidate.get("pane_id"))
+        return {"ok": False, "status": "refused", "reason": "uuid_mismatch"}
+    provider = str(candidate.get("provider") or receiver.get("provider") or "codex")
+    if not _leader_command_looks_usable(str(candidate.get("pane_current_command", "")), provider):
+        return {"ok": False, "status": "refused", "reason": "wrong_command", "candidate_pane_id": candidate.get("pane_id")}
+    next_epoch = current_epoch + 1
+    new_receiver = _receiver_from_target(candidate, provider, owner.get("leader_session_uuid"), next_epoch)
+    owner["owner_epoch"] = next_epoch
+    state["leader_receiver"] = new_receiver
+    from team_agent.runtime import _runtime_lock, save_runtime_state
+    with _runtime_lock(workspace, "leader_receiver"):
+        save_runtime_state(workspace, state)
+    event_log.write("leader_receiver.claimed", pane_id=new_receiver["pane_id"], owner_epoch=next_epoch, uuid_prefix=_uuid_prefix(owner))
+    return {"ok": True, "status": "claimed", "leader_receiver": new_receiver, "owner_epoch": next_epoch}
+
+
 def _fail_leader_delivery(
     workspace: Path,
     state: dict[str, Any],
@@ -310,8 +472,6 @@ def _format_team_agent_message(payload: dict[str, Any]) -> str:
 
 
 
-
-