@team-agent/installer 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",

package/src/team_agent/cli/commands.py

@@ -119,9 +119,10 @@ def cmd_peek(args: argparse.Namespace) -> dict[str, Any]:
 
 
 def cmd_inbox(args: argparse.Namespace) -> dict[str, Any]:
+    since = getattr(args, "since", None)
     if args.json:
-        return runtime.inbox(Path(args.workspace).resolve(), args.agent, limit=args.limit)
-    return runtime.format_inbox(Path(args.workspace).resolve(), args.agent, limit=args.limit)
+        return runtime.inbox(Path(args.workspace).resolve(), args.agent, limit=args.limit, since=since)
+    return runtime.format_inbox(Path(args.workspace).resolve(), args.agent, limit=args.limit, since=since)
 
 
 def cmd_sessions(args: argparse.Namespace) -> dict[str, Any]:
@@ -136,6 +137,14 @@ def cmd_takeover(args: argparse.Namespace) -> dict[str, Any]:
     return runtime.takeover(Path(args.workspace).resolve(), team=args.team, confirm=args.confirm)
 
 
+def cmd_claim_leader(args: argparse.Namespace) -> dict[str, Any]:
+    return runtime.claim_leader(Path(args.workspace).resolve(), team=args.team, confirm=args.confirm)
+
+
+def cmd_identity(args: argparse.Namespace) -> dict[str, Any]:
+    return runtime.leader_identity(Path(args.workspace).resolve(), team=args.team)
+
+
 def cmd_send(args: argparse.Namespace) -> dict[str, Any]:
     target = _send_target(args)
     return runtime.send_message(
@@ -190,7 +199,13 @@ def cmd_validate_result(args: argparse.Namespace) -> dict[str, Any]:
     return {"ok": True, "task_id": envelope["task_id"], "agent_id": envelope["agent_id"], "status": envelope["status"]}
 
 
-def cmd_doctor(args: argparse.Namespace) -> dict[str, Any]:
+def cmd_doctor(args: argparse.Namespace) -> dict[str, Any] | str:
+    if getattr(args, "cleanup_orphans", False):
+        from team_agent.diagnose.orphan_cleanup import cleanup_orphan_coordinators, format_cleanup_orphans
+        result = cleanup_orphan_coordinators(confirm=bool(getattr(args, "confirm", False)))
+        if args.json:
+            return result
+        return format_cleanup_orphans(result)
     spec = Path(args.spec).resolve() if args.spec else None
     return runtime.doctor(spec)
 

package/src/team_agent/cli/parser.py

@@ -30,6 +30,8 @@ from team_agent.cli.commands import (
     cmd_sessions,
     cmd_attach_leader,
     cmd_takeover,
+    cmd_claim_leader,
+    cmd_identity,
     cmd_send,
     cmd_collect,
     cmd_diagnose,
@@ -209,6 +211,12 @@ def main(argv: list[str] | None = None) -> None:
     p.add_argument("agent")
     p.add_argument("--workspace", default=".")
     p.add_argument("--limit", type=int, default=20)
+    p.add_argument(
+        "--since",
+        help="ISO 8601 timestamp; only show messages created at-or-after this time. "
+             "Use the timestamp from claim-leader's inbox_hint to retrieve messages "
+             "missed during a prior ambiguous-leader state.",
+    )
     add_json(p)
     p.set_defaults(func=cmd_inbox)
 
@@ -231,6 +239,19 @@ def main(argv: list[str] | None = None) -> None:
     add_json(p)
     p.set_defaults(func=cmd_takeover)
 
+    p = sub.add_parser("claim-leader", help="Claim this pane as leader after ambiguous leader recovery")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session selector when a workspace has multiple teams")
+    p.add_argument("--confirm", action="store_true", help="Apply the claim; without this, show a dry-run summary")
+    add_json(p)
+    p.set_defaults(func=cmd_claim_leader)
+
+    p = sub.add_parser("identity", help="Show leader identity diagnostics")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session selector when a workspace has multiple teams")
+    add_json(p)
+    p.set_defaults(func=cmd_identity)
+
     p = sub.add_parser(
         "send",
         help="Send a message to an agent, task assignee, or attached leader",
@@ -289,6 +310,17 @@ def main(argv: list[str] | None = None) -> None:
 
     p = sub.add_parser("doctor", help="Check local dependencies, providers, auth hints, tmux, and MCP")
     p.add_argument("spec", nargs="?")
+    p.add_argument(
+        "--cleanup-orphans",
+        action="store_true",
+        help="Scan for orphan team_agent.coordinator processes pointing at non-existent or "
+             "ephemeral-tempdir workspaces (dry-run unless --confirm is also passed).",
+    )
+    p.add_argument(
+        "--confirm",
+        action="store_true",
+        help="With --cleanup-orphans: send SIGTERM to each orphan (default is dry-run).",
+    )
     add_json(p)
     p.set_defaults(func=cmd_doctor)
 
@@ -429,7 +461,7 @@ def main(argv: list[str] | None = None) -> None:
     sub._choices_actions = [  # type: ignore[attr-defined]
         action for action in sub._choices_actions if action.help != argparse.SUPPRESS  # type: ignore[attr-defined]
     ]
-    sub.metavar = "{codex,claude,quick-start,send,status,approvals,inbox,shutdown,restart,start-agent,stop-agent,reset-agent,add-agent,fork-agent,remove-agent,stuck-list,stuck-cancel,acknowledge-idle,doctor}"
+    sub.metavar = "{codex,claude,quick-start,send,status,approvals,inbox,takeover,claim-leader,identity,shutdown,restart,start-agent,stop-agent,reset-agent,add-agent,fork-agent,remove-agent,stuck-list,stuck-cancel,acknowledge-idle,doctor}"
 
     args = parser.parse_args(raw_argv)
     try:

package/src/team_agent/coordinator/__main__.py

@@ -38,7 +38,23 @@ def main(argv: list[str] | None = None) -> None:
     signal.signal(signal.SIGINT, _stop)
 
     interval = args.tick_interval if args.tick_interval is not None else _tick_interval(workspace)
+    initial_ppid = os.getppid()
     while not STOP:
+        # Stage 14 (Gap 37b) — orphan self-detection. If our original parent (test harness,
+        # shell, or supervisor) died, our ppid is reparented to 1 (or to a launchd shim on
+        # macOS). When that happens AND the workspace no longer exists on disk, we are an
+        # orphan from a torn-down test environment and must self-terminate so we don't
+        # accumulate (today's evidence: 35 orphans pointing at /var/folders/...team-agent-
+        # watcher-dedupe-* paths long since cleaned up).
+        current_ppid = os.getppid()
+        if current_ppid != initial_ppid and current_ppid == 1 and not workspace.exists():
+            event_log.write(
+                "coordinator.orphan_self_terminate",
+                initial_ppid=initial_ppid,
+                current_ppid=current_ppid,
+                workspace=str(workspace),
+            )
+            break
         result = runtime.coordinator_tick(workspace)
         if result.get("stop") or args.once:
             break
@@ -46,18 +62,21 @@ def main(argv: list[str] | None = None) -> None:
     event_log.write("coordinator.exit", stop=STOP)
 
 
+DEFAULT_TICK_INTERVAL_SEC = 5.0  # Stage 14 (Gap 36c) — bumped from 2.0 (2.5x less CPU)
+
+
 def _tick_interval(workspace: Path) -> float:
     state = load_runtime_state(workspace)
     spec_path = Path(state.get("spec_path", workspace / "team.spec.yaml"))
     if spec_path.exists():
         try:
             spec = load_spec(spec_path)
-            return float(spec.get("runtime", {}).get("tick_interval_sec", 2))
+            return float(spec.get("runtime", {}).get("tick_interval_sec", DEFAULT_TICK_INTERVAL_SEC))
         except Exception:
             pass
     # Ensure schema exists even before launch; this makes doctor/tick diagnostics deterministic.
     MessageStore(workspace)
-    return 2.0
+    return DEFAULT_TICK_INTERVAL_SEC
 
 
 if __name__ == "__main__":

package/src/team_agent/coordinator/lifecycle.py

@@ -320,6 +320,14 @@ def coordinator_tick(workspace: Path) -> dict[str, Any]:
             drift_results.append(drift)
     save_runtime_state(workspace, state)
     results = _collect_results_and_notify_watchers(workspace, event_log)
+    # Stage 12: prune the dedupe log every tick — cheap O(n) delete bounded by 24h window.
+    from team_agent.message_store.leader_notification_log import prune_leader_notification_log
+    try:
+        pruned = prune_leader_notification_log(store, max_age_hours=24)
+        if pruned:
+            event_log.write("leader_notification.log_pruned", removed=pruned)
+    except Exception as exc:
+        event_log.write("leader_notification.prune_failed", error=str(exc))
     return {
         "ok": True,
         "stop": False,

package/src/team_agent/diagnose/orphan_cleanup.py

@@ -0,0 +1,193 @@
+"""Stage 14 (Gap 37a) — `team-agent doctor --cleanup-orphans` implementation.
+
+Scans `ps` for processes matching `team_agent.coordinator --workspace <path>` and
+classifies any whose workspace path no longer exists (or matches the test-tempdir
+pattern) as an orphan. Dry-run by default; --confirm sends SIGTERM.
+
+Mac mini 2026-05-26 evidence: 35 orphan coordinator processes alive simultaneously
+pointing at /var/folders/.../T/team-agent-watcher-dedupe-* paths that had been removed
+hours earlier. Each holds a long-lived Python interpreter + SQLite connection.
+"""
+from __future__ import annotations
+
+import os
+import re
+import signal
+import subprocess
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# Pattern: argv contains "team_agent.coordinator --workspace <path>" anywhere.
+_COORDINATOR_ARGV_RE = re.compile(
+    r"team_agent\.coordinator(?:\.__main__)?(?:\s+|.*?)\s--workspace\s+(\S+)"
+)
+# Test-tempdir patterns that indicate the workspace is ephemeral and almost certainly orphan.
+_EPHEMERAL_PATH_HINTS = (
+    "team-agent-watcher-dedupe-",
+    "team-agent-gap",
+    "team-agent-stage",
+    "team-agent-orchestrator-",
+    "team-agent-rm-",
+    "team-agent-claim-",
+    "team-agent-hotfix",
+    "team-agent-multi",
+    "team-agent-progress-",
+    "team-agent-fanout-",
+    "team-agent-in-flight-",
+    "team-agent-test-",
+)
+_SIGTERM_WAIT_SECONDS = 3.0
+
+
+def find_coordinator_processes(*, runner=subprocess.run) -> list[dict[str, Any]]:
+    """Return list of {pid, etime, cmdline, workspace} dicts for every running
+    team_agent.coordinator process visible to ps. workspace is None when the cmdline
+    doesn't parse — those are noted but not auto-classified as orphan."""
+    try:
+        proc = runner(
+            ["ps", "-Awwo", "pid=,etime=,command="],
+            text=True,
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return []
+    if proc.returncode != 0 or not proc.stdout:
+        return []
+    rows: list[dict[str, Any]] = []
+    for line in proc.stdout.splitlines():
+        parts = line.strip().split(None, 2)
+        if len(parts) < 3:
+            continue
+        pid_s, etime, cmdline = parts[0], parts[1], parts[2]
+        if "team_agent.coordinator" not in cmdline:
+            continue
+        if "ps -Awwo" in cmdline:
+            continue
+        try:
+            pid = int(pid_s)
+        except ValueError:
+            continue
+        if pid == os.getpid():
+            continue
+        match = _COORDINATOR_ARGV_RE.search(cmdline)
+        workspace = match.group(1) if match else None
+        rows.append({
+            "pid": pid,
+            "etime": etime,
+            "cmdline": cmdline,
+            "workspace": workspace,
+        })
+    return rows
+
+
+def classify_orphan(entry: dict[str, Any]) -> tuple[bool, str]:
+    """Return (is_orphan, reason). An entry is orphan when its workspace path no longer
+    exists on disk OR matches a known ephemeral-tempdir pattern (test workspaces should
+    NEVER spawn long-lived coordinators)."""
+    workspace = entry.get("workspace")
+    if not workspace:
+        return False, "cmdline_unparsed"
+    if not Path(workspace).exists():
+        return True, "workspace_path_missing"
+    for hint in _EPHEMERAL_PATH_HINTS:
+        if hint in workspace:
+            return True, f"ephemeral_tempdir_pattern:{hint}"
+    return False, "workspace_alive"
+
+
+def cleanup_orphan_coordinators(
+    *,
+    confirm: bool = False,
+    runner=subprocess.run,
+    killer=os.kill,
+    sleeper=time.sleep,
+) -> dict[str, Any]:
+    """Scan for orphan coordinators. Without confirm: dry-run (just classify and report).
+    With confirm: SIGTERM each orphan and wait up to _SIGTERM_WAIT_SECONDS for the
+    process to exit; report success/failure per pid."""
+    now = datetime.now(timezone.utc).isoformat()
+    entries = find_coordinator_processes(runner=runner)
+    classified: list[dict[str, Any]] = []
+    orphans: list[dict[str, Any]] = []
+    for entry in entries:
+        is_orphan, reason = classify_orphan(entry)
+        annotated = {**entry, "is_orphan": is_orphan, "reason": reason}
+        classified.append(annotated)
+        if is_orphan:
+            orphans.append(annotated)
+    if not confirm:
+        return {
+            "ok": True,
+            "scanned": len(classified),
+            "orphans": orphans,
+            "dry_run": True,
+            "scanned_at": now,
+            "action_required": "re-run with --confirm to send SIGTERM",
+        }
+    killed: list[dict[str, Any]] = []
+    failed: list[dict[str, Any]] = []
+    for entry in orphans:
+        pid = entry["pid"]
+        try:
+            killer(pid, signal.SIGTERM)
+        except (ProcessLookupError, PermissionError, OSError) as exc:
+            failed.append({**entry, "error": str(exc)})
+            continue
+        # Wait briefly; if the process is still alive after _SIGTERM_WAIT_SECONDS,
+        # mark as failed (caller may want to SIGKILL).
+        deadline = time.monotonic() + _SIGTERM_WAIT_SECONDS
+        gone = False
+        while time.monotonic() < deadline:
+            try:
+                killer(pid, 0)
+            except ProcessLookupError:
+                gone = True
+                break
+            except (PermissionError, OSError):
+                gone = True
+                break
+            sleeper(0.1)
+        if gone:
+            killed.append(entry)
+        else:
+            failed.append({**entry, "error": "still_alive_after_sigterm"})
+    return {
+        "ok": True,
+        "scanned": len(classified),
+        "orphans": orphans,
+        "killed": killed,
+        "failed": failed,
+        "dry_run": False,
+        "scanned_at": now,
+    }
+
+
+def format_cleanup_orphans(result: dict[str, Any]) -> str:
+    lines = [
+        f"Coordinator orphan scan @ {result.get('scanned_at')}",
+        f"  scanned: {result.get('scanned', 0)} coordinator processes",
+        f"  orphans: {len(result.get('orphans') or [])}",
+    ]
+    if result.get("dry_run"):
+        lines.append("  mode: DRY-RUN (no SIGTERM sent; re-run with --confirm)")
+    else:
+        lines.append(f"  killed: {len(result.get('killed') or [])}")
+        lines.append(f"  failed: {len(result.get('failed') or [])}")
+    for orphan in result.get("orphans") or []:
+        lines.append(
+            f"  PID {orphan['pid']} etime={orphan['etime']} "
+            f"workspace={orphan.get('workspace') or '?'} reason={orphan.get('reason')}"
+        )
+    return "\n".join(lines)
+
+
+__all__ = [
+    "cleanup_orphan_coordinators",
+    "classify_orphan",
+    "find_coordinator_processes",
+    "format_cleanup_orphans",
+]

package/src/team_agent/events.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import os
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -8,6 +9,15 @@ from typing import Any
 from team_agent.paths import logs_dir
 
 
+# Stage 14 (Gap 36a) — bounded retention. 5 MB cap × 5 archives = 25 MB worst-case.
+# Mac mini 2026-05-26 evidence: events.jsonl grew to 28 MB / 128k lines in one day with
+# unbounded retention; coordinator's tick-time scan over the file was a ~22% CPU hot path.
+# Rotation keeps the current segment small so reads are cheap; archives preserve forensic
+# history but are NOT consulted by hot-path scans.
+EVENT_LOG_ROTATE_BYTES = 5 * 1024 * 1024
+EVENT_LOG_ARCHIVE_KEEP = 5
+
+
 class EventLog:
     def __init__(self, workspace: Path):
         self.workspace = workspace
@@ -20,11 +30,14 @@ class EventLog:
             "event": event_type,
             **fields,
         }
+        self._maybe_rotate()
         with self.path.open("a", encoding="utf-8") as f:
             f.write(json.dumps(event, ensure_ascii=False, sort_keys=True) + "\n")
         return event
 
     def tail(self, limit: int = 20) -> list[dict[str, Any]]:
+        # Hot-path scan reads only the current segment. Archives are forensic; if a
+        # caller genuinely needs longer history it can iterate _archive_paths explicitly.
         if not self.path.exists():
             return []
         lines = self.path.read_text(encoding="utf-8").splitlines()[-limit:]
@@ -35,3 +48,37 @@ class EventLog:
             except json.JSONDecodeError:
                 out.append({"raw": line})
         return out
+
+    def _maybe_rotate(self) -> None:
+        try:
+            size = self.path.stat().st_size
+        except FileNotFoundError:
+            return
+        if size < EVENT_LOG_ROTATE_BYTES:
+            return
+        # Shift archives: events.jsonl.4 → .5, .3 → .4, …, .1 → .2, current → .1
+        # Drop the oldest if it would overflow the keep budget.
+        oldest = self._archive_path(EVENT_LOG_ARCHIVE_KEEP)
+        if oldest.exists():
+            try:
+                oldest.unlink()
+            except OSError:
+                pass
+        for idx in range(EVENT_LOG_ARCHIVE_KEEP - 1, 0, -1):
+            src = self._archive_path(idx)
+            dst = self._archive_path(idx + 1)
+            if src.exists():
+                try:
+                    os.replace(src, dst)
+                except OSError:
+                    pass
+        try:
+            os.replace(self.path, self._archive_path(1))
+        except OSError:
+            pass
+
+    def _archive_path(self, index: int) -> Path:
+        return self.path.with_name(f"{self.path.name}.{index}")
+
+    def _archive_paths(self) -> list[Path]:
+        return [self._archive_path(i) for i in range(1, EVENT_LOG_ARCHIVE_KEEP + 1)]