@team-agent/installer 0.1.11 → 0.2.1

package/src/team_agent/messaging/leader_panes.py

@@ -0,0 +1,343 @@
+from __future__ import annotations
+
+from team_agent.messaging.deps import (
+    EventLog,
+    RuntimeError,
+    TMUX_PANE_FORMAT,
+    _infer_active_tmux_pane as _runtime_infer_active_tmux_pane,
+    _infer_workspace_tmux_pane as _runtime_infer_workspace_tmux_pane,
+    _tmux_current_client_pane_info as _runtime_tmux_current_client_pane_info,
+    _tmux_list_panes as _runtime_tmux_list_panes,
+    _tmux_pane_info as _runtime_tmux_pane_info,
+    core_list_targets,
+    datetime,
+    os,
+    re,
+    run_cmd,
+    timezone,
+)
+
+from pathlib import Path
+from typing import Any
+
+def _resolve_leader_pane(
+    pane: str | None,
+    provider: str,
+    workspace: Path | None = None,
+    require_current: bool = False,
+) -> tuple[dict[str, str], str]:
+    if pane:
+        pane_info = _tmux_pane_info(pane)
+        if not pane_info:
+            raise RuntimeError(f"tmux pane not found: {pane}")
+        return pane_info, "explicit_pane"
+    pane_info = _runtime_tmux_current_client_pane_info()
+    if pane_info and _pane_is_usable_leader(pane_info, provider, workspace):
+        return pane_info, "current_client"
+    if workspace is not None:
+        workspace_match = _runtime_infer_workspace_tmux_pane(provider, workspace)
+        if workspace_match["status"] == "ok":
+            return workspace_match["pane"], "workspace_pane_scan"
+        if workspace_match["status"] == "ambiguous":
+            raise RuntimeError(
+                "multiple tmux leader panes match this workspace; pass --pane explicitly. "
+                + _format_leader_pane_candidates(workspace_match["candidates"])
+            )
+    if require_current:
+        details = ""
+        if pane_info:
+            details = (
+                f" Current tmux client points at pane {pane_info.get('pane_id')} "
+                f"command={pane_info.get('pane_current_command')!r} "
+                f"cwd={pane_info.get('pane_current_path')!r}, not a usable pane for this workspace."
+            )
+        raise RuntimeError(
+            "Team Agent could not locate a tmux-managed leader pane for this workspace. "
+            "Run quick-start from the visible tmux-managed leader pane, pass --pane explicitly, "
+            "or use `team-agent codex`/`team-agent claude` as a convenience fallback."
+            + details
+        )
+    if pane_info and workspace is None:
+        return pane_info, "current_client"
+    pane_info = _runtime_infer_active_tmux_pane(provider)
+    if pane_info:
+        return pane_info, "active_pane_scan"
+    raise RuntimeError("could not infer a tmux leader pane; pass --pane <pane_id>")
+
+
+def _tmux_current_client_pane_info() -> dict[str, str] | None:
+    proc = run_cmd(["tmux", "display-message", "-p", "-F", TMUX_PANE_FORMAT], timeout=5)
+    if proc.returncode != 0:
+        return None
+    return _parse_tmux_pane_info(proc.stdout.strip())
+
+
+def _tmux_list_panes() -> list[dict[str, str]]:
+    proc = run_cmd(["tmux", "list-panes", "-a", "-F", TMUX_PANE_FORMAT], timeout=5)
+    if proc.returncode != 0:
+        return []
+    return [pane for line in proc.stdout.splitlines() if (pane := _parse_tmux_pane_info(line))]
+
+
+def _infer_active_tmux_pane(provider: str) -> dict[str, str] | None:
+    panes = _runtime_tmux_list_panes()
+    active = [pane for pane in panes if pane.get("pane_active") == "1"]
+    preferred = [pane for pane in active if _leader_command_looks_usable(pane.get("pane_current_command", ""), provider)]
+    if len(preferred) == 1:
+        return preferred[0]
+    if len(active) == 1:
+        return active[0]
+    if preferred:
+        return preferred[0]
+    return active[0] if active else None
+
+
+def _tmux_pane_info(target: str | None) -> dict[str, str] | None:
+    if not target:
+        return None
+    proc = run_cmd(["tmux", "display-message", "-p", "-t", target, "-F", TMUX_PANE_FORMAT], timeout=5)
+    if proc.returncode != 0:
+        return None
+    return _parse_tmux_pane_info(proc.stdout.strip())
+
+
+def _parse_tmux_pane_info(line: str) -> dict[str, str] | None:
+    parts = line.split("\t")
+    if len(parts) not in {8, 10, 11}:
+        return None
+    keys = [
+        "pane_id",
+        "session_name",
+        "window_index",
+        "window_name",
+        "pane_index",
+        "pane_tty",
+        "pane_current_command",
+        "pane_active",
+    ]
+    if len(parts) >= 10:
+        keys.extend(["pane_current_path", "session_attached"])
+    if len(parts) == 11:
+        keys.append("pane_in_mode")
+    return dict(zip(keys, parts))
+
+
+def _infer_workspace_tmux_pane(provider: str, workspace: Path) -> dict[str, Any]:
+    panes = _runtime_tmux_list_panes()
+    workspace_panes = [pane for pane in panes if _pane_path_matches_workspace(pane, workspace)]
+    candidates = [
+        pane
+        for pane in workspace_panes
+        if _leader_command_looks_usable(pane.get("pane_current_command", ""), provider)
+        or _leader_command_provider(pane.get("pane_current_command", "")) is not None
+    ]
+    if not candidates:
+        return {"status": "missing", "workspace_panes": workspace_panes}
+    ranked = sorted(candidates, key=lambda item: _leader_pane_rank(item, provider), reverse=True)
+    best_rank = _leader_pane_rank(ranked[0], provider)
+    best = [pane for pane in ranked if _leader_pane_rank(pane, provider) == best_rank]
+    if len(best) == 1:
+        return {"status": "ok", "pane": best[0], "candidates": candidates}
+    return {"status": "ambiguous", "candidates": best}
+
+
+def _pane_is_usable_leader(pane: dict[str, str], provider: str, workspace: Path | None) -> bool:
+    command = pane.get("pane_current_command", "")
+    if not _leader_command_looks_usable(command, provider) and _leader_command_provider(command) is None:
+        return False
+    if workspace is not None and not _pane_path_matches_workspace(pane, workspace):
+        return False
+    return True
+
+
+def _pane_path_matches_workspace(pane: dict[str, str], workspace: Path) -> bool:
+    current_path = pane.get("pane_current_path")
+    if not current_path:
+        return False
+    return os.path.realpath(current_path) == os.path.realpath(str(workspace.resolve()))
+
+
+def _leader_pane_rank(pane: dict[str, str], provider: str) -> tuple[int, int, int]:
+    return (
+        _tmux_truthy(pane.get("session_attached", "")),
+        1 if pane.get("pane_active") == "1" else 0,
+        1 if _leader_command_is_exact(pane.get("pane_current_command", ""), provider) else 0,
+    )
+
+
+def _tmux_truthy(value: str) -> int:
+    try:
+        return 1 if int(value) > 0 else 0
+    except (TypeError, ValueError):
+        return 1 if value and value != "0" else 0
+
+
+def _leader_command_is_exact(command: str, provider: str) -> bool:
+    command_name = Path(command).name
+    if provider == "codex":
+        return command_name == "codex"
+    if provider in {"claude", "claude_code"}:
+        return command_name in {"claude", "claude.exe"}
+    return provider == "fake"
+
+
+def _leader_command_provider(command: str) -> str | None:
+    command_name = Path(command).name
+    if command_name in {"codex", "node", "nodejs"}:
+        return "codex"
+    if command_name in {"claude", "claude.exe"}:
+        return "claude_code"
+    return None
+
+
+def _format_leader_pane_candidates(candidates: list[dict[str, str]]) -> str:
+    compact = []
+    for pane in candidates[:5]:
+        compact.append(
+            "{pane_id} session={session_name} pane={window_index}.{pane_index} "
+            "cmd={pane_current_command} cwd={pane_current_path} active={pane_active}".format(**pane)
+        )
+    suffix = "" if len(candidates) <= 5 else f" ... +{len(candidates) - 5} more"
+    return "candidates: " + "; ".join(compact) + suffix
+
+
+def _target_fingerprint(pane_info: dict[str, Any]) -> str:
+    return "|".join(
+        str(pane_info.get(key, ""))
+        for key in ["session_name", "window_index", "pane_index", "pane_tty"]
+    )
+
+
+def _rediscover_leader_receiver(
+    receiver: dict[str, Any],
+    event_log: EventLog,
+    owner_identity: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    provider = str(receiver.get("provider") or "codex")
+    if provider != "codex":
+        return {"status": "missing", "reason": "rediscovery_only_for_codex"}
+    targets = core_list_targets()
+    if not targets.get("ok"):
+        event_log.write("leader_receiver.rediscover_failed", provider=provider, error=targets.get("error"))
+        return {"status": "failed", "error": targets.get("error")}
+    candidates = [
+        target
+        for target in targets.get("targets", [])
+        if _leader_command_looks_usable(str(target.get("pane_current_command", "")), provider)
+    ]
+    if owner_identity:
+        owner_candidates = [target for target in candidates if _target_matches_owner_identity(target, owner_identity)]
+        if len(owner_candidates) == 1:
+            return _rediscovered_receiver(receiver, provider, owner_candidates[0], event_log, owner_identity)
+        if len(owner_candidates) > 1:
+            event_log.write(
+                "leader_receiver.rediscover_ambiguous",
+                provider=provider,
+                old_target=receiver.get("pane_id"),
+                candidates=[target.get("pane_id") for target in owner_candidates],
+                owner_identity=owner_identity,
+            )
+            return {"status": "ambiguous", "candidates": owner_candidates, "owner_identity": owner_identity}
+        event_log.write(
+            "leader_receiver.rediscover_missing",
+            provider=provider,
+            old_target=receiver.get("pane_id"),
+            owner_identity=owner_identity,
+            candidate_count=len(candidates),
+        )
+        return {"status": "missing", "owner_identity": owner_identity}
+    if len(candidates) == 1:
+        return _rediscovered_receiver(receiver, provider, candidates[0], event_log, None)
+    if len(candidates) > 1:
+        event_log.write(
+            "leader_receiver.rediscover_ambiguous",
+            provider=provider,
+            old_target=receiver.get("pane_id"),
+            candidates=[target.get("pane_id") for target in candidates],
+        )
+        return {"status": "ambiguous", "candidates": candidates}
+    event_log.write("leader_receiver.rediscover_missing", provider=provider, old_target=receiver.get("pane_id"))
+    return {"status": "missing"}
+
+
+def _target_matches_owner_identity(target: dict[str, Any], owner_identity: dict[str, Any]) -> bool:
+    env = target.get("leader_env") if isinstance(target.get("leader_env"), dict) else {}
+    return (
+        env.get("TEAM_AGENT_LEADER_PANE_ID") == (owner_identity.get("pane_id") or "")
+        and env.get("TEAM_AGENT_LEADER_PROVIDER") == (owner_identity.get("provider") or "")
+        and env.get("TEAM_AGENT_MACHINE_FINGERPRINT") == (owner_identity.get("machine_fingerprint") or "")
+    )
+
+
+def _rediscovered_receiver(
+    receiver: dict[str, Any],
+    provider: str,
+    target: dict[str, Any],
+    event_log: EventLog,
+    owner_identity: dict[str, Any] | None,
+) -> dict[str, Any]:
+    updated = {
+        "mode": "direct_tmux",
+        "status": "attached",
+        "provider": provider,
+        "pane_id": target["pane_id"],
+        "session_name": target["session_name"],
+        "window_index": str(target["window_index"]),
+        "window_name": target["window_name"],
+        "pane_index": str(target["pane_index"]),
+        "pane_tty": target["pane_tty"],
+        "pane_current_command": target["pane_current_command"],
+        "fingerprint": target.get("fingerprint") or _target_fingerprint(target),
+        "attached_at": datetime.now(timezone.utc).isoformat(),
+        "discovery": "stale_rediscovery_owner_identity" if owner_identity else "stale_rediscovery_unique_candidate",
+    }
+    event_log.write(
+        "leader_receiver.rediscovered",
+        provider=provider,
+        old_target=receiver.get("pane_id"),
+        new_target=updated["pane_id"],
+        candidate_count=1,
+        owner_identity=owner_identity,
+    )
+    return {"status": "updated", "receiver": updated, "owner_identity": owner_identity}
+
+
+def _validate_leader_receiver(receiver: dict[str, Any]) -> dict[str, Any]:
+    pane_info = _runtime_tmux_pane_info(receiver.get("pane_id"))
+    if not pane_info:
+        return {"ok": False, "reason": "leader_pane_missing", "error": "tmux pane does not exist"}
+    capture = run_cmd(["tmux", "capture-pane", "-p", "-S", "-40", "-t", pane_info["pane_id"]], timeout=5)
+    if capture.returncode != 0:
+        return {
+            "ok": False,
+            "reason": "leader_capture_failed",
+            "error": capture.stderr.strip() or "tmux capture-pane failed",
+            "pane": pane_info,
+        }
+    warning = None
+    provider = str(receiver.get("provider") or "codex")
+    if not _leader_command_looks_usable(pane_info.get("pane_current_command", ""), provider):
+        warning = (
+            f"pane command {pane_info.get('pane_current_command')!r} is not a typical {provider} host; "
+            "continuing because tmux capture works"
+        )
+    return {"ok": True, "pane": pane_info, "capture": capture.stdout, "warning": warning}
+
+
+def _leader_command_looks_usable(command: str, provider: str) -> bool:
+    if provider == "fake":
+        return True
+    command_name = Path(command).name
+    if provider == "codex":
+        return command_name in {"codex", "node", "nodejs"}
+    return bool(command_name)
+
+
+def _choose_leader_submit_key(provider: str, capture_text: str) -> tuple[str, str]:
+    if provider != "codex":
+        return "Enter", "non_codex_provider"
+    if re.search(r"esc to interrupt|working|running", capture_text, re.IGNORECASE):
+        return "Enter", "codex_busy_submit_followup"
+    if re.search(r"(›|❯|codex>)", capture_text):
+        return "Enter", "codex_idle_prompt"
+    return "Enter", "codex_state_unknown_submit"

package/src/team_agent/messaging/owner_bypass.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any
+
+from team_agent.events import EventLog
+from team_agent.state import worker_sender_bypasses_owner_gate
+
+
+def apply_worker_sender_bypass(
+    state: dict[str, Any],
+    sender: str | None,
+    target: Any,
+    task_id: str | None,
+    event_log: EventLog,
+) -> bool:
+    via = worker_sender_bypasses_owner_gate(state, sender)
+    if not via:
+        return False
+    event_log.write(
+        "send.bypassed_owner_gate_worker_sender",
+        sender=sender,
+        env_team_agent_id=via,
+        target=target if isinstance(target, str) else None,
+        task_id=task_id,
+    )
+    return True
+
+
+__all__ = ["apply_worker_sender_bypass"]

package/src/team_agent/messaging/result_delivery.py

@@ -0,0 +1,300 @@
+from __future__ import annotations
+
+import json
+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 send_message
+from team_agent.messaging.internal_delivery import deliver_stored_message
+
+_RESULT_DELIVERY_MAX_ATTEMPTS = 5
+_DELIVERED_RESULT_MESSAGE_STATUSES = {"visible", "submitted", "submitted_unverified", "delivered", "acknowledged"}
+
+
+def retry_result_deliveries(workspace: Path, event_log: EventLog) -> list[dict[str, Any]]:
+    store = MessageStore(workspace)
+    notified: list[dict[str, Any]] = []
+    for watcher in store.retryable_result_watchers():
+        if watcher.get("status") != "notify_failed" or not watcher.get("result_id"):
+            continue
+        row = store.result_by_id(str(watcher["result_id"]))
+        if not row:
+            continue
+        notified.extend(notify_result_watchers(workspace, _result_entry_from_row(row), event_log, watchers=[watcher]))
+    return notified
+
+
+def notify_result_watchers(
+    workspace: Path,
+    result: dict[str, Any],
+    event_log: EventLog,
+    watchers: list[dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
+    store = MessageStore(workspace)
+    candidates = [
+        watcher
+        for watcher in (watchers if watchers is not None else store.pending_result_watchers())
+        if watcher_matches_result(watcher, result)
+    ]
+    if not candidates:
+        return []
+    primary, superseded = _dedupe_watchers_for_result(candidates)
+    notified: list[dict[str, Any]] = []
+    for stale in superseded:
+        store.mark_result_watcher(
+            stale["watcher_id"],
+            "superseded",
+            result_id=result.get("result_id"),
+            error="superseded by earlier watcher for same (task_id, agent_id, result_id)",
+        )
+        event_log.write(
+            "result_watcher.superseded",
+            watcher_id=stale["watcher_id"],
+            result_id=result.get("result_id"),
+            task_id=result.get("task_id"),
+            agent_id=result.get("agent_id"),
+            primary_watcher_id=primary["watcher_id"],
+        )
+        notified.append(
+            {
+                "watcher_id": stale["watcher_id"],
+                "result_id": result.get("result_id"),
+                "ok": False,
+                "status": "superseded",
+                "primary_watcher_id": primary["watcher_id"],
+            }
+        )
+    attempts = result_delivery_attempts(event_log, primary["watcher_id"], str(result.get("result_id") or ""))
+    existing = delivered_result_message(
+        store,
+        str(result.get("result_id") or ""),
+        task_id=result.get("task_id"),
+        owner_team_id=primary.get("owner_team_id"),
+    )
+    if existing:
+        notified.append(_mark_watcher_already_delivered(store, event_log, primary, result, attempts, existing))
+        return notified
+    if attempts >= _RESULT_DELIVERY_MAX_ATTEMPTS:
+        notified.append(_mark_delivery_exhausted(store, event_log, primary, result, attempts))
+    else:
+        notified.append(_deliver_result_to_watcher(workspace, store, event_log, primary, result, attempts))
+    return notified
+
+
+def _dedupe_watchers_for_result(
+    watchers: list[dict[str, Any]],
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    ordered = sorted(watchers, key=lambda w: (str(w.get("created_at") or ""), str(w.get("watcher_id") or "")))
+    return ordered[0], ordered[1:]
+
+
+def _deliver_result_to_watcher(
+    workspace: Path,
+    store: MessageStore,
+    event_log: EventLog,
+    watcher: dict[str, Any],
+    result: dict[str, Any],
+    attempts: int,
+) -> dict[str, Any]:
+    try:
+        deliver = deliver_stored_message if watcher.get("owner_team_id") else send_message
+        delivery = deliver(
+            workspace,
+            watcher.get("leader_id") or "leader",
+            format_result_watcher_notification(result),
+            task_id=result.get("task_id"),
+            sender="coordinator",
+            requires_ack=False,
+            wait_visible=False,
+            team=watcher.get("owner_team_id"),
+        )
+    except Exception as exc:
+        return _mark_delivery_failed(store, event_log, watcher, result, attempts, str(exc))
+    status = "notified" if delivery.get("ok") else "notify_failed"
+    error = delivery.get("reason") or delivery.get("error")
+    store.mark_result_watcher(
+        watcher["watcher_id"],
+        status,
+        result_id=result.get("result_id"),
+        notified_message_id=delivery.get("message_id"),
+        error=error,
+    )
+    event_log.write(
+        "result_watcher.notified",
+        watcher_id=watcher["watcher_id"],
+        result_id=result.get("result_id"),
+        task_id=result.get("task_id"),
+        agent_id=result.get("agent_id"),
+        ok=bool(delivery.get("ok")),
+        delivery_status=delivery.get("status"),
+        message_id=delivery.get("message_id"),
+        error=error,
+        attempt=attempts + 1,
+    )
+    return {
+        "watcher_id": watcher["watcher_id"],
+        "result_id": result.get("result_id"),
+        "ok": bool(delivery.get("ok")),
+        "message_id": delivery.get("message_id"),
+    }
+
+
+def _mark_delivery_failed(
+    store: MessageStore,
+    event_log: EventLog,
+    watcher: dict[str, Any],
+    result: dict[str, Any],
+    attempts: int,
+    error: str,
+) -> dict[str, Any]:
+    store.mark_result_watcher(watcher["watcher_id"], "notify_failed", result_id=result.get("result_id"), error=error)
+    event_log.write(
+        "result_watcher.notify_failed",
+        watcher_id=watcher["watcher_id"],
+        result_id=result.get("result_id"),
+        attempt=attempts + 1,
+        error=error,
+    )
+    return {"watcher_id": watcher["watcher_id"], "result_id": result.get("result_id"), "ok": False, "error": error}
+
+
+def _mark_watcher_already_delivered(
+    store: MessageStore,
+    event_log: EventLog,
+    watcher: dict[str, Any],
+    result: dict[str, Any],
+    attempts: int,
+    message: dict[str, Any],
+) -> dict[str, Any]:
+    store.mark_result_watcher(
+        watcher["watcher_id"],
+        "notified",
+        result_id=result.get("result_id"),
+        notified_message_id=message.get("message_id"),
+    )
+    event_log.write(
+        "result_watcher.notified",
+        watcher_id=watcher["watcher_id"],
+        result_id=result.get("result_id"),
+        task_id=result.get("task_id"),
+        agent_id=result.get("agent_id"),
+        ok=True,
+        delivery_status="already_delivered",
+        message_id=message.get("message_id"),
+        deduped=True,
+        attempt=attempts,
+    )
+    return {
+        "watcher_id": watcher["watcher_id"],
+        "result_id": result.get("result_id"),
+        "ok": True,
+        "message_id": message.get("message_id"),
+        "deduped": True,
+    }
+
+
+def _mark_delivery_exhausted(
+    store: MessageStore,
+    event_log: EventLog,
+    watcher: dict[str, Any],
+    result: dict[str, Any],
+    attempts: int,
+) -> dict[str, Any]:
+    error = "result delivery retry budget exhausted"
+    store.mark_result_watcher(watcher["watcher_id"], "delivery_exhausted", result_id=result.get("result_id"), error=error)
+    event_log.write(
+        "result_delivery_exhausted",
+        watcher_id=watcher["watcher_id"],
+        result_id=result.get("result_id"),
+        task_id=result.get("task_id"),
+        agent_id=result.get("agent_id"),
+        attempts=attempts,
+        last_error=watcher.get("error"),
+    )
+    return {"watcher_id": watcher["watcher_id"], "result_id": result.get("result_id"), "ok": False, "error": error}
+
+
+def _result_entry_from_row(row: dict[str, Any]) -> dict[str, Any]:
+    envelope = json.loads(row["envelope"])
+    return {
+        "result_id": row["result_id"],
+        "task_id": envelope.get("task_id"),
+        "agent_id": envelope.get("agent_id"),
+        "status": envelope.get("status"),
+        "summary": envelope.get("summary"),
+        "tests": envelope.get("tests", []),
+        "created_at": row.get("created_at"),
+        "scope": "task",
+    }
+
+
+def result_delivery_attempts(event_log: EventLog, watcher_id: str, result_id: str) -> int:
+    attempts = 0
+    for event in event_log.tail(500):
+        if event.get("watcher_id") != watcher_id:
+            continue
+        if event.get("event") == "result_watcher.requeued":
+            attempts = 0
+            continue
+        if event.get("result_id") != result_id:
+            continue
+        if event.get("event") in {"result_watcher.notified", "result_watcher.notify_failed"}:
+            attempts += 1
+    return attempts
+
+
+def delivered_result_message(
+    store: MessageStore,
+    result_id: str,
+    *,
+    task_id: str | None = None,
+    owner_team_id: str | None = None,
+) -> dict[str, Any] | None:
+    if not result_id:
+        return None
+    for message in reversed(store.messages(owner_team_id=owner_team_id)):
+        if message.get("recipient") != "leader":
+            continue
+        if task_id and message.get("task_id") != task_id:
+            continue
+        if message.get("status") not in _DELIVERED_RESULT_MESSAGE_STATUSES:
+            continue
+        if f"Result id: {result_id}" in str(message.get("content") or ""):
+            return message
+    return None
+
+
+def result_id_from_text(content: str) -> str | None:
+    for line in content.splitlines():
+        if line.startswith("Result id: "):
+            return line.removeprefix("Result id: ").strip() or None
+    return None
+
+
+def watcher_matches_result(watcher: dict[str, Any], result: dict[str, Any]) -> bool:
+    task_id = watcher.get("task_id")
+    agent_id = watcher.get("agent_id")
+    return (not task_id or task_id == result.get("task_id")) and (not agent_id or agent_id == result.get("agent_id"))
+
+
+def format_result_watcher_notification(result: dict[str, Any]) -> str:
+    task_id = result.get("task_id") or "unknown task"
+    agent_id = result.get("agent_id") or "unknown agent"
+    status = result.get("status") or "unknown"
+    summary = result.get("summary") or "completed"
+    lines = [
+        f"Task {task_id} reported {status} from {agent_id}: {summary}",
+        "Team Agent has collected this result and updated team_state.md. No manual polling is needed.",
+    ]
+    if result.get("result_id"):
+        lines.insert(1, f"Result id: {result['result_id']}")
+    rendered_tests = [
+        f"{test.get('command') or 'test'}={test.get('status') or 'unknown'}"
+        for test in (result.get("tests") or [])[:3]
+        if isinstance(test, dict)
+    ]
+    if rendered_tests:
+        lines.insert(1, "Tests: " + "; ".join(rendered_tests))
+    return "\n".join(lines)