agentwire-dev 1.65.3__tar.gz → 1.67.0__tar.gz

{agentwire_dev-1.65.3 → agentwire_dev-1.67.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.65.3
+Version: 1.67.0
 Summary: Multi-session voice web interface for AI coding agents
 Project-URL: Homepage, https://agentwire.dev
 Project-URL: Repository, https://github.com/dotdevdotdev/agentwire-dev
@@ -231,7 +231,7 @@ Requires-Dist: fastapi>=0.104.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: kokoro-onnx>=0.4.9; python_version < '3.14'
 Requires-Dist: markdown>=3.5
-Requires-Dist: mcp>=1.2.0
+Requires-Dist: mcp<2,>=1.2.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: python-multipart>=0.0.6

{agentwire_dev-1.65.3 → agentwire_dev-1.67.0}/agentwire/__init__.py

@@ -1,3 +1,3 @@
 """AgentWire - Multi-session voice web interface for AI coding agents."""
 
-__version__ = "1.65.3"
+__version__ = "1.67.0"

{agentwire_dev-1.65.3 → agentwire_dev-1.67.0}/agentwire/__main__.py

@@ -37,7 +37,6 @@ from .core import (  # noqa: E402,F401  # E402: must follow load_dotenv(); F401:
     _parse_session_target,
     _portal_auth_headers,
     _post_desktop_notification,
-    _record_session_creator,
     _resolve_posture_from_args,
     _run_remote,
     _set_session_name_env,
@@ -58,6 +57,7 @@ from .core import (  # noqa: E402,F401  # E402: must follow load_dotenv(); F401:
     load_config,
     load_session_metadata,
     parse_env_args,
+    record_session_launch,
     store_session_metadata,
     tmux_session_exists,
     tmux_session_has_agent,
@@ -190,7 +190,7 @@ Command Categories:
     from . import doctor_cli, history_cli, machine_cli, safety_cli
     from . import handoff_cli, hooks_cli, mcp_cli, roles_cli, tunnels_cli
     from . import notify_cli, palette_cli, push_cli, repo_cli, system_cli, wiki_cli
-    from . import tabs_cli
+    from . import tabs_cli, wait_cli, worktree_cli
     from .council import cli as council_cli
 
     _REGISTRARS = [  # noqa: N806  # registry constant; Phase 1 of #495 appends here
@@ -225,6 +225,8 @@ Command Categories:
         config_cli.register_config_parser,
         palette_cli.register_palette_parser,
         tabs_cli.register_tabs_parser,
+        wait_cli.register_wait_parser,
+        worktree_cli.register_helper_parser,
     ]
     for _reg in _REGISTRARS:
         _reg(subparsers)

agentwire_dev-1.67.0/agentwire/cohort.py

@@ -0,0 +1,505 @@
+"""Fan-out cohort ledger — a parent's outstanding children (#852).
+
+A scheduled task that fans out child sessions had no way to wait for them.
+The parent went idle while *waiting*, the idle handler read idle as done, and
+the task was reaped — killing the roll-up the parent existed to write and
+orphaning the children's report-backs into dead-letter (which, for
+load-bearing kinds, also emails the owner about work that succeeded). The
+children themselves were full ``agentwire new`` sessions, so nothing reaped
+them either: a nightly fan-out leaked N sessions per run.
+
+**idle != done for a session with outstanding children.** This module is the
+one artifact that makes that knowable, with three consumers:
+
+1. ``agentwire wait --children`` (:func:`wait`) — the join primitive. Blocking
+   inside a tool call is not idle, so the hook never fires and the agent
+   resumes naturally to write its roll-up.
+2. The idle-handler guard — a file-existence + ``jq`` check in the same shape
+   as the usage-limit park guard and the #276 prompt-router guard. It reads
+   ``state == "pending"`` and ``deadline`` directly out of the JSON, so those
+   two field names are load-bearing across the language boundary.
+3. The watchdog sweeper (:func:`tick`) — the anti-leak backstop. It reaps a
+   cohort whose parent died mid-wait, and reconciles a live parent's ledger so
+   the guard self-clears as children exit.
+
+**Cohort is not rooting.** ``created_by`` (#715) answers "who has authority /
+where do prompts route", and deliberately returns nothing for a *cross-project*
+spawn. The 2026-08-01 fan-out was three cross-project children and one
+same-project one, so a ``created_by``-derived guard would have protected
+exactly one child and reaped the parent out from under the other three. A
+half-linked fan-out is worse than an unlinked one, so cohort membership is
+keyed off the CALLER, independent of the rooting decision.
+
+**Ordering is load-bearing.** ``agentwire kill`` runs ``inbox.gc_sender()``,
+which dead-letters the killed session's still-pending load-bearing outbound
+**and emails the owner**. Kill-before-collect turns every child's ``done``
+report into owner email. So: collect the report, consume it, THEN kill.
+
+Everything here fails OPEN: a missing, corrupt, or expired ledger must never be
+able to wedge a task alive forever.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+from .utils.event_log import append_event
+
+COHORT_ROOT = Path.home() / ".agentwire" / "cohorts"
+EVENTS_FILE = Path.home() / ".agentwire" / "cohort-events.jsonl"
+
+# How long a cohort may suppress its parent's idle handling. Past this the
+# guard stops firing, `wait` stops blocking, and outstanding children are
+# killed and reported as failures — a wedged child must not pin a task forever.
+DEFAULT_TTL = 3600
+
+# How long past its deadline a ledger survives when the parent is still alive.
+# Covers a parent that fanned out and never called `wait --children`: the guard
+# has already stopped protecting it, and the children get reaped rather than
+# leaked. Generous, because a parent that IS about to call `wait` should find
+# its ledger intact.
+STALE_GRACE = 3600
+
+# Child states. `pending` is read by the idle-handler guard's jq — renaming it
+# silently disarms the guard.
+PENDING = "pending"
+REPORTED = "reported"  # report collected, child killed
+TIMEOUT = "timeout"    # deadline hit with no report; child killed anyway
+GONE = "gone"          # child's session vanished before it reported
+
+RESOLVED_STATES = (REPORTED, TIMEOUT, GONE)
+
+# Topologies, which decide whether resolving a child also tears its session
+# down. A `main`-topology child (`agentwire new`) is the leak this issue is
+# about: nothing reaps it, so the cohort does. A `worktree` child is NOT torn
+# down — it holds a branch and possibly an open PR, whose teardown must follow
+# merge verification (#756), and its session is where a reviewer sends fix-ups.
+# It is still tracked, still reported, and still surfaced when it goes silent;
+# an abandoned one is what `worktree --dangling` / `--list` already flag.
+MAIN = "main"
+WORKTREE = "worktree"
+
+# Kinds a child's report-back can arrive as. `note` is included because a child
+# that fails mid-task may downgrade its report; `ingest` is not, since passive
+# messages are pull-only pointers the parent reads separately.
+REPORT_KINDS = ("done", "request", "escalation", "note")
+
+_POLL_INTERVAL = 2.0
+
+
+# =============================================================================
+# Ledger I/O
+# =============================================================================
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+def log_event(event: str, **fields) -> None:
+    append_event(EVENTS_FILE, {"ts": _now(), "event": event, **fields})
+
+
+def ledger_path(parent: str) -> Path:
+    """Ledger file for *parent*. Worktree names contain ``/`` and nest a dir."""
+    if not parent or parent.startswith("/") or ".." in parent.split("/"):
+        raise ValueError(f"invalid session name: {parent!r}")
+    path = COHORT_ROOT / f"{parent}.json"
+    if not path.resolve().is_relative_to(COHORT_ROOT.resolve()):
+        raise ValueError(f"invalid session name: {parent!r}")
+    return path
+
+
+def load(parent: str) -> dict | None:
+    """The parent's ledger, or None when absent/unreadable/malformed.
+
+    Fails open on purpose: a corrupt ledger reads as "no cohort", so the guard
+    stops suppressing and the parent resumes normal idle handling.
+    """
+    try:
+        data = json.loads(ledger_path(parent).read_text())
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict) or not isinstance(data.get("children"), list):
+        return None
+    return data
+
+
+def _save(parent: str, data: dict) -> None:
+    path = ledger_path(parent)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=path.name + ".", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+@contextmanager
+def _locked(parent: str):
+    """Serialize a read-modify-write on one parent's ledger.
+
+    An orchestrator can fire several spawns in a single turn (parallel tool
+    calls), and a lost update there means a child is never enrolled — i.e. a
+    session that leaks. Same mkdir-based lock the inbox uses; best-effort, so a
+    stuck lock degrades to the unsynchronized write rather than blocking a
+    spawn.
+    """
+    lock = ledger_path(parent).with_suffix(".lock")
+    held = False
+    for _ in range(50):
+        try:
+            lock.parent.mkdir(parents=True, exist_ok=True)
+            os.mkdir(lock)
+            held = True
+            break
+        except FileExistsError:
+            time.sleep(0.1)
+        except OSError:
+            break
+    try:
+        yield
+    finally:
+        if held:
+            try:
+                os.rmdir(lock)
+            except OSError:
+                pass
+
+
+def discard(parent: str) -> bool:
+    """Delete the parent's ledger. True if one was there."""
+    try:
+        ledger_path(parent).unlink()
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def enroll(parent: str, child: str, task: str | None = None,
+           ttl: int = DEFAULT_TTL, topology: str = MAIN) -> bool:
+    """Record *child* as an outstanding member of *parent*'s cohort.
+
+    Called automatically by ``agentwire new`` (and therefore ``worktree``)
+    whenever there is a caller, so a fan-out author has no bookkeeping to
+    forget. Re-enrolling a session already in the ledger is a no-op; a fresh
+    fan-out after the previous cohort resolved extends the deadline so the
+    second wave gets its own full TTL.
+
+    *topology* decides whether resolving this child also tears its session
+    down — see :data:`WORKTREE`.
+    """
+    if not parent or not child or parent == child:
+        return False
+    try:
+        with _locked(parent):
+            data = load(parent) or {
+                "parent": parent, "task": task, "created_at": _now(), "children": [],
+            }
+            if any(c.get("session") == child for c in data["children"]):
+                return False
+            data["children"].append({
+                "session": child, "state": PENDING, "report": None,
+                "topology": topology, "enrolled_at": _now(),
+            })
+            data["deadline"] = _now() + ttl
+            if task and not data.get("task"):
+                data["task"] = task
+            _save(parent, data)
+    except (OSError, ValueError):
+        return False
+    log_event("enrolled", parent=parent, child=child, task=task)
+    return True
+
+
+def pending(parent: str) -> list[str]:
+    """Sessions in *parent*'s cohort that haven't been resolved yet."""
+    data = load(parent)
+    if not data:
+        return []
+    return [c["session"] for c in data["children"]
+            if c.get("state") == PENDING and c.get("session")]
+
+
+def blocking(parent: str, now: int | None = None) -> bool:
+    """Should *parent*'s idle handling be suppressed right now?
+
+    The Python mirror of the idle-handler's jq guard: pending children AND the
+    deadline not yet passed. Both halves matter — the deadline is what stops a
+    wedged child from pinning a task alive forever.
+    """
+    data = load(parent)
+    if not data:
+        return False
+    if not any(c.get("state") == PENDING for c in data["children"]):
+        return False
+    return (now if now is not None else _now()) < int(data.get("deadline") or 0)
+
+
+def _mark(data: dict, child: str, state: str, report: str | None = None) -> None:
+    for entry in data["children"]:
+        if entry.get("session") == child:
+            entry["state"] = state
+            if report is not None:
+                entry["report"] = report
+
+
+# =============================================================================
+# Session liveness / teardown
+# =============================================================================
+
+
+def session_exists(session: str) -> bool:
+    try:
+        return subprocess.run(
+            ["tmux", "has-session", "-t", f"={session}"],
+            capture_output=True, timeout=5,
+        ).returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def _kill(session: str) -> bool:
+    """Tear a child session down through the CLI's own kill path.
+
+    Never the child's own job (a wedged child never goes idle, so child-side
+    teardown structurally can't cover the failure path), and never raw tmux —
+    the shared path also drops session metadata and GCs the child's leftover
+    outbound.
+    """
+    try:
+        from .pane_cli import kill_local_session
+
+        return bool(kill_local_session(session).get("success"))
+    except Exception:
+        return False
+
+
+# =============================================================================
+# Collection + join
+# =============================================================================
+
+
+def _harvest(parent: str) -> dict[str, list]:
+    """Pending inbox messages to *parent*, grouped by sender.
+
+    Read straight off disk rather than waiting for the drain to paste them:
+    the parent is mid-tool-call, and a paste into its box is exactly what
+    #851 makes unreliable for long reports.
+    """
+    try:
+        from . import inbox
+
+        out: dict[str, list] = {}
+        for msg in inbox.list_messages(parent):
+            if msg.kind in REPORT_KINDS:
+                out.setdefault(msg.sender, []).append(msg)
+        return out
+    except Exception:
+        return {}
+
+
+def _consume(messages: list) -> str:
+    """Take these messages out of the inbox and return their text.
+
+    Consuming BEFORE the kill is what keeps ``gc_sender`` from dead-lettering
+    the report (and emailing the owner) for a child that reported perfectly.
+    """
+    texts = []
+    for msg in messages:
+        texts.append(msg.text)
+        try:
+            if msg.path:
+                msg.path.unlink()
+        except OSError:
+            pass
+    return "\n".join(texts)
+
+
+def collect(parent: str) -> dict | None:
+    """One resolution pass over *parent*'s cohort. Returns the ledger, or None.
+
+    Per pending child: a report waiting in the parent's inbox is consumed and
+    the child torn down (collect → consume → kill, in that order); a child
+    whose session has already vanished is marked ``gone``. Past the deadline
+    every remaining child is torn down and marked ``timeout`` so the parent's
+    summary can name it as a failure instead of the run silently leaking a live
+    session. Teardown skips worktree children — see :func:`_teardown`.
+    """
+    data = load(parent)
+    if not data:
+        return None
+    outstanding = [c["session"] for c in data["children"]
+                   if c.get("state") == PENDING and c.get("session")]
+    if not outstanding:
+        return data
+
+    expired = _now() >= int(data.get("deadline") or 0)
+    reports = _harvest(parent)
+    for child in outstanding:
+        msgs = reports.get(child)
+        if msgs:
+            _mark(data, child, REPORTED, _consume(msgs))
+            _teardown(data, child)
+            log_event("collected", parent=parent, child=child)
+        elif not session_exists(child):
+            _mark(data, child, GONE)
+            log_event("child_gone", parent=parent, child=child)
+        elif expired:
+            _mark(data, child, TIMEOUT)
+            _teardown(data, child)
+            log_event("child_timeout", parent=parent, child=child)
+    _save(parent, data)
+    return data
+
+
+def _teardown(data: dict, child: str) -> bool:
+    """Kill a resolved child's session — unless it's on worktree topology.
+
+    The leak #852 is about is a ``main``-topology child: a full session nothing
+    reaps. A worktree child is deliberately left running: its branch and any
+    open PR are torn down only after merge verification (#756), a reviewer may
+    still need to send it fix-ups, and an abandoned one is already surfaced by
+    ``worktree --dangling``. Killing it would trade a visible leak for a
+    silently destroyed working tree.
+    """
+    entry = next((c for c in data["children"] if c.get("session") == child), None)
+    if entry is not None and entry.get("topology") == WORKTREE:
+        entry["torn_down"] = False
+        return False
+    killed = _kill(child)
+    if entry is not None:
+        entry["torn_down"] = killed
+    return killed
+
+
+def summarize(data: dict) -> dict:
+    """Caller-facing view of a ledger."""
+    children = data.get("children") or []
+    return {
+        "parent": data.get("parent"),
+        "task": data.get("task"),
+        "deadline": data.get("deadline"),
+        "pending": [c["session"] for c in children if c.get("state") == PENDING],
+        "reports": [{"session": c["session"], "report": c.get("report")}
+                    for c in children if c.get("state") == REPORTED],
+        "failed": [{"session": c["session"], "state": c.get("state")}
+                   for c in children if c.get("state") in (TIMEOUT, GONE)],
+        # Resolved but deliberately still running: worktree children, whose
+        # branch/PR teardown follows merge verification (#756).
+        "left_alive": [c["session"] for c in children
+                       if c.get("state") in (REPORTED, TIMEOUT)
+                       and c.get("torn_down") is False],
+        "children": children,
+    }
+
+
+def wait(parent: str, timeout: float = 600.0,
+         poll: float = _POLL_INTERVAL) -> dict:
+    """Block until *parent*'s cohort resolves, this call's *timeout* elapses,
+    or the cohort deadline passes.
+
+    Blocking here happens inside a tool call, which is not idle — so the idle
+    hook never fires, the parent is never prompted for a roll-up it can't
+    write, and it resumes naturally with every child's report in hand.
+
+    Bounded and re-callable: a fan-out longer than the calling harness's tool
+    timeout just loops. The ledger is deleted once nothing is pending, so the
+    idle guard stops suppressing the moment the cohort is done.
+    """
+    data = load(parent)
+    if not data:
+        return {"parent": parent, "cohort": False, "resolved": True,
+                "pending": [], "reports": [], "failed": [], "left_alive": [],
+                "children": []}
+
+    deadline = time.time() + max(timeout, 0)
+    while True:
+        data = collect(parent) or data
+        result = summarize(data)
+        if not result["pending"]:
+            discard(parent)
+            log_event("resolved", parent=parent,
+                      reported=len(result["reports"]), failed=len(result["failed"]))
+            return {**result, "cohort": True, "resolved": True}
+        if time.time() >= deadline:
+            return {**result, "cohort": True, "resolved": False}
+        time.sleep(poll)
+
+
+# =============================================================================
+# Watchdog sweep
+# =============================================================================
+
+
+def sweep() -> dict:
+    """Reconcile every ledger on disk. The anti-leak backstop.
+
+    - **Parent gone** → kill whatever is still pending and delete the ledger.
+      This is the crash path (usage limit, guard deadline, ``/exit``) that
+      leaks children under every other mechanism, including a child-side
+      self-kill: a wedged child never goes idle, so it never self-kills.
+    - **Parent alive** → mark pending children whose session has vanished, so
+      the idle guard self-clears as the cohort empties.
+    - **Past deadline + grace** → the parent fanned out and never joined; kill
+      the stragglers and drop the ledger rather than leaving it to suppress
+      nothing forever.
+
+    Teardown here is deliberately session-only: killing a tmux session never
+    touches a worktree's branch or its open PR, whose removal must follow merge
+    verification (#756) and stays with ``worktree --remove``.
+    """
+    reaped: list[dict] = []
+    swept: list[str] = []
+    if not COHORT_ROOT.exists():
+        return {"reaped": reaped, "swept": swept}
+
+    for path in sorted(p for p in COHORT_ROOT.rglob("*.json") if p.is_file()):
+        try:
+            parent = str(path.relative_to(COHORT_ROOT))[: -len(".json")]
+        except ValueError:
+            continue
+        data = load(parent)
+        if not data:
+            continue
+        outstanding = [c["session"] for c in data["children"]
+                       if c.get("state") == PENDING and c.get("session")]
+        parent_live = session_exists(parent)
+        expired = _now() >= int(data.get("deadline") or 0) + STALE_GRACE
+
+        if parent_live and not expired:
+            changed = False
+            for child in outstanding:
+                if not session_exists(child):
+                    _mark(data, child, GONE)
+                    changed = True
+            if changed:
+                _save(parent, data)
+                swept.append(parent)
+            continue
+
+        for child in outstanding:
+            if session_exists(child) and _teardown(data, child):
+                reaped.append({"parent": parent, "child": child})
+                log_event("orphan_reaped", parent=parent, child=child,
+                          parent_live=parent_live, expired=expired)
+        discard(parent)
+        swept.append(parent)
+    return {"reaped": reaped, "swept": swept}
+
+
+def tick() -> dict:
+    """Watchdog stage entry point — same shape as :func:`sweep`."""
+    return sweep()

{agentwire_dev-1.65.3 → agentwire_dev-1.67.0}/agentwire/completion.py

@@ -187,25 +187,38 @@ def wait_for_completion_signal(
     session: str,
     poll_interval: float = 10.0,
     summary_path: Path | None = None,
+    max_duration: int = 0,
 ) -> dict:
     """Wait for task completion by polling the summary file directly.
 
     Exits when:
     1. Summary file appears (task completed normally)
     2. Session dies (agent crashed, tmux killed)
+    3. ``max_duration`` elapses, when the task sets one
 
-    There is no wall-clock timeout. Tasks run until one of these conditions.
+    Completion is otherwise agent-driven: the idle hook fires, the agent writes
+    a summary, and this returns. An agent that never goes idle never produces
+    either exit — wedged on an unrecognized dialog, or blocked inside a tool
+    call — and before ``max_duration`` existed the wait was unbounded, so that
+    read as a silent multi-hour hang whose only visible end was the scheduler's
+    4h process-group watchdog (#867).
+
+    ``max_duration`` is a per-attempt wall clock, not an idle timer: it can't
+    tell a wedged agent from a slow one, so a task that legitimately runs long
+    should set it high or leave it at 0 rather than get killed mid-work.
 
     Args:
         session: tmux session name
         poll_interval: Seconds between checks
         summary_path: Path to the summary .md file the agent will write
+        max_duration: Seconds before giving up (0 = unbounded)
 
     Returns:
         Dict with 'status', 'summary', 'summary_file' keys
 
     Raises:
-        CompletionTimeout: If session dies before task completed
+        CompletionTimeout: If the session dies, or max_duration elapses, before
+            the task completed. The message names which.
     """
     # Build glob pattern for fuzzy summary detection (agents sometimes
     # invent their own timestamp instead of using the provided filename).
@@ -217,6 +230,8 @@ def wait_for_completion_signal(
         prefix = stem[:-19] if len(stem) > 19 else stem
         summary_glob = f"{prefix}*.md"
 
+    started = time.time()
+
     while True:
         # Primary: check if the agent has written the summary file AND
         # the hook has deleted the context file (signals cleanup complete).
@@ -274,6 +289,14 @@ def wait_for_completion_signal(
                 f"Session '{session}' died or agent exited before task completed"
             )
 
+        if max_duration > 0:
+            elapsed = time.time() - started
+            if elapsed >= max_duration:
+                raise CompletionTimeout(
+                    f"Task exceeded max_duration ({max_duration}s) after "
+                    f"{int(elapsed)}s — the agent never signalled completion"
+                )
+
         time.sleep(poll_interval)