agentwire-dev 1.64.0__tar.gz → 1.65.1__tar.gz

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.64.0
+Version: 1.65.1
 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

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/__init__.py

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

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/config.py

@@ -122,7 +122,6 @@ class ProjectsConfig:
 
     dir: Path = field(default_factory=lambda: Path.home() / "projects")
     worktrees: WorktreesConfig = field(default_factory=WorktreesConfig)
-    extra: list = field(default_factory=list)
 
     def __post_init__(self):
         self.dir = _expand_path(self.dir) or Path.home() / "projects"
@@ -636,7 +635,6 @@ def _dict_to_config(data: dict) -> Config:
     projects = ProjectsConfig(
         dir=projects_data.get("dir", "~/projects"),
         worktrees=worktrees,
-        extra=projects_data.get("extra", []),
     )
 
     # Worktree-session orchestration (`worktree:` key).

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/core.py

@@ -479,9 +479,21 @@ def resolve_default_created_by(caller: str | None, target_path: Path) -> str | N
     `{project}-{name}`, and would misjudge same/cross-project); if the
     caller's real cwd can't be confirmed, treat it as unknown (no inheritance)
     rather than risk a wrong guess.
+
+    A service session (agentwire-portal, -tts, -stt, -kokoro, ...) never
+    qualifies as a parent: it's infrastructure, not an agent that will ever
+    drain its msg inbox, so anything parented to it dead-letters forever. A
+    subprocess the portal shells out to inherits its TMUX_PANE and resolves
+    ``caller`` right back to "agentwire-portal" — this was the root cause of
+    a 147-message dead-letter storm (each mailing the owner individually,
+    2026-07-19).
     """
     if not caller:
         return None
+    from .services import is_service_session
+
+    if is_service_session(caller):
+        return None
     caller_path = _live_session_cwd(caller)
     if caller_path is None:
         return None
@@ -741,7 +753,7 @@ def _record_session_creator(session_name: str, created_by: str | None, via: str)
 
 
 def _record_session_role(session_name: str, role: str | None) -> None:
-    """Record the session's ROLE axis (orchestrator/worker) to disk (merge-preserving).
+    """Record the session's ROLE axis (orchestrator/worker/reviewer) to disk (merge-preserving).
 
     Distinct from the etiquette/persona ``roles:`` list in ``.agentwire.yml`` —
     this is the fundamental authority axis derived at creation time (``kind``

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/council/cli.py

@@ -164,11 +164,14 @@ def current_session() -> str | None:
     return pane_manager.get_current_session()
 
 
-def open_artifact_window(url: str, title: str) -> bool:
-    """Best-effort: open a rendered artifact as a portal window.
-
-    Returns True only when the portal accepted the open; a down or erroring
-    portal returns False — the artifact file exists on disk either way.
+def notify_artifact(url: str, title: str) -> bool:
+    """Best-effort: announce a rendered artifact via a portal notification.
+
+    Posts a click-to-open notice (toast + HUD entry, #817) rather than
+    force-opening a window — a background render must never steal focus from
+    whatever the human is working in. Returns True only when the portal
+    accepted the notification; a down or erroring portal returns False — the
+    artifact file exists on disk either way.
     """
     import os
 
@@ -184,8 +187,8 @@ def open_artifact_window(url: str, title: str) -> bool:
     try:
         resp = core.portal_request(
             "POST",
-            f"{portal}/api/desktop/window/open",
-            json={"type": "artifact", "url": url, "title": title},
+            f"{portal}/api/desktop/notification",
+            json={"artifact": {"url": url, "title": title}},
             timeout=5,
         )
         return resp.status_code == 200 and bool(resp.json().get("success"))
@@ -372,20 +375,20 @@ def _synthesis_text(value: str | None) -> str:
 def _render_minutes(
     name: str, prompt_ids: list[int] | None = None, synthesis: str = ""
 ) -> tuple[str | None, bool | None]:
-    """Write the minutes artifact and best-effort open it in the portal.
+    """Write the minutes artifact and best-effort announce it in the portal.
 
-    Returns ``(path, opened)`` — both None when the sitting has no matching
-    prompt history (nothing rendered, nothing opened).
+    Returns ``(path, notified)`` — both None when the sitting has no matching
+    prompt history (nothing rendered, nothing announced).
     """
     from agentwire.council import minutes
 
     path = minutes.write_minutes(name, prompt_ids, synthesis=synthesis)
     if path is None:
         return None, None
-    opened = open_artifact_window(
+    notified = notify_artifact(
         minutes.artifact_url(name), f"Council minutes — {name}"
     )
-    return str(path), opened
+    return str(path), notified
 
 
 def cmd_council_stop(args) -> int:
@@ -399,9 +402,9 @@ def cmd_council_stop(args) -> int:
     # Minutes before teardown (#708): tri-state --minutes/--no-minutes,
     # default (None) renders exactly when any prompt history exists.
     minutes_path: str | None = None
-    minutes_opened: bool | None = None
+    minutes_notified: bool | None = None
     if getattr(args, "minutes", None) is not False:
-        minutes_path, minutes_opened = _render_minutes(
+        minutes_path, minutes_notified = _render_minutes(
             name, synthesis=_synthesis_text(getattr(args, "synthesis", None))
         )
 
@@ -420,7 +423,7 @@ def cmd_council_stop(args) -> int:
         "killed": killed,
         "not_running": not_running,
         "minutes": minutes_path,
-        "minutes_opened": minutes_opened,
+        "minutes_notified": minutes_notified,
     }
     human = (
         f"Council '{name}' stopped ({len(killed)} sessions killed). "
@@ -456,14 +459,14 @@ def cmd_council_minutes(args) -> int:
                 f"(available: {', '.join(map(str, available))})",
             )
 
-    path, opened = _render_minutes(
+    path, notified = _render_minutes(
         name, prompt_ids, synthesis=_synthesis_text(getattr(args, "synthesis", None))
     )
 
-    payload = {"success": True, "path": path, "opened": opened}
+    payload = {"success": True, "path": path, "notified": notified}
     human = f"Minutes: {path}"
-    if opened:
-        human += "\nOpened as a portal artifact window."
+    if notified:
+        human += "\nAnnounced in the portal — click the notification to open."
     return _emit(args, payload, human, council=name)
 
 

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/inbox.py

@@ -453,6 +453,7 @@ def gc_sender(sender: str) -> dict:
             # delivered, not lost. Skip GC for this recipient this round.
             continue
         try:
+            newly_dead: list[Message] = []
             for path in paths:
                 if not path.exists():
                     continue  # delivered + unlinked just before we locked
@@ -472,7 +473,7 @@ def gc_sender(sender: str) -> dict:
                             attempts=msg.attempts, reason="sender_exited",
                         )
                         dead += 1
-                        _escalate_dead_letter(msg, "sender_exited")
+                        newly_dead.append(msg)
                     except OSError:
                         pass
                 else:
@@ -481,6 +482,8 @@ def gc_sender(sender: str) -> dict:
                         dropped += 1
                     except OSError:
                         pass
+            # One digest per recipient, not one email per message (#836).
+            _escalate_dead_letters(newly_dead, "sender_exited")
         finally:
             _release_lock(lock)
 
@@ -608,17 +611,32 @@ def _fmt_ts(ms: int) -> str:
     return time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(ms / 1000))
 
 
-def _escalate_dead_letter(msg: Message, reason: str) -> None:
-    """Email the owner when a load-bearing report-back dead-letters.
+# A single stuck recipient (e.g. a session wrongly parented to a service
+# session that can never drain its inbox) can dead-letter dozens of messages
+# in one drain pass — cap the per-message detail in the digest so the email
+# stays readable instead of dumping an unbounded wall of text.
+_ESCALATE_DIGEST_DETAIL_CAP = 10
+
+
+def _escalate_dead_letters(messages: list[Message], reason: str) -> None:
+    """Email the owner once per batch when load-bearing report-backs dead-letter.
 
     ``done`` / ``request`` / ``escalation`` are load-bearing — a silently-dropped
     one is a real loss, so we surface it out-of-band via the shared Resend wiring
     (the same owner-escalation channel usage-limit parking uses). ``note`` and
-    ``ingest`` are not escalated. Best-effort: a missing key or send failure must
-    never break the drain — the corpse already sits in ``dead/`` for
-    ``agentwire msg dead``.
+    ``ingest`` are not escalated.
+
+    *messages* is everything dead-lettered by one caller's batch (one drain
+    pass for one recipient, or one sender's GC sweep) — a single digest email
+    covers the whole batch instead of one email per message, so a recipient
+    that's been permanently undeliverable for a while (e.g. parented to a
+    service session that never drains) can't spam the owner's inbox one email
+    per stuck message (147 individual emails in ~2s, 2026-07-19). Best-effort:
+    a missing key or send failure must never break the drain — each corpse
+    already sits in ``dead/`` for ``agentwire msg dead``.
     """
-    if msg.kind not in ESCALATE_KINDS:
+    batch = [m for m in messages if m.kind in ESCALATE_KINDS]
+    if not batch:
         return
     try:
         import socket
@@ -626,36 +644,47 @@ def _escalate_dead_letter(msg: Message, reason: str) -> None:
         from .channels.email import send_email
 
         host = socket.gethostname()
-        subject = (
-            f"[agentwire] undelivered {msg.kind}: {msg.sender} → {msg.to} (dead-lettered)"
-        )
-        body = "\n".join([
-            f"A **{msg.kind}** message from **{msg.sender}** to **{msg.to}** on "
-            f"`{host}` was never delivered after {msg.attempts} attempts and has "
-            f"been dead-lettered.",
-            "",
-            f"- **Kind:** {msg.kind}",
-            f"- **From:** {msg.sender}",
-            f"- **To:** {msg.to}",
-            f"- **Last defer reason:** {reason}",
-            f"- **Sent:** {_fmt_ts(msg.ts)}",
-            f"- **Dead-lettered:** {_fmt_ts(msg.dead_ts)}",
-            "",
-            "Message text:",
+        if len(batch) == 1:
+            msg = batch[0]
+            subject = (
+                f"[agentwire] undelivered {msg.kind}: {msg.sender} → {msg.to} (dead-lettered)"
+            )
+        else:
+            to = batch[0].to
+            subject = (
+                f"[agentwire] {len(batch)} undelivered messages → {to} (dead-lettered)"
+            )
+        noun = "message" if len(batch) == 1 else "messages"
+        verb = "was" if len(batch) == 1 else "were"
+        lines = [
+            f"{len(batch)} load-bearing {noun} on `{host}` {verb} never delivered "
+            f"and {'has' if len(batch) == 1 else 'have'} been dead-lettered "
+            f"(last defer reason: {reason}).",
             "",
-            "```",
-            msg.text,
-            "```",
+        ]
+        for msg in batch[:_ESCALATE_DIGEST_DETAIL_CAP]:
+            lines += [
+                f"- **{msg.kind}** {msg.sender} → {msg.to}, sent {_fmt_ts(msg.ts)}, "
+                f"dead-lettered {_fmt_ts(msg.dead_ts)}, {msg.attempts} attempts:",
+                "  ```",
+                f"  {msg.text}",
+                "  ```",
+            ]
+        remaining = len(batch) - _ESCALATE_DIGEST_DETAIL_CAP
+        if remaining > 0:
+            lines.append(f"- ...and {remaining} more.")
+        lines += [
             "",
-            f"Saved in the dead-letter store — review with `agentwire msg dead -s {msg.to}`.",
-        ])
-        result = send_email(subject=subject, body=body)
+            f"Saved in the dead-letter store — review with "
+            f"`agentwire msg dead -s {batch[0].to}`.",
+        ]
+        result = send_email(subject=subject, body="\n".join(lines))
         _log_event(
-            "dead_letter_escalated", id=msg.id, to=msg.to, kind=msg.kind,
+            "dead_letter_escalated", to=batch[0].to, count=len(batch), reason=reason,
             ok=bool(getattr(result, "success", False)),
         )
     except Exception as exc:  # escalation is best-effort; never break the drain
-        _log_event("dead_letter_escalate_failed", id=msg.id, to=msg.to, error=str(exc))
+        _log_event("dead_letter_escalate_failed", to=batch[0].to, count=len(batch), error=str(exc))
 
 
 def _bump_attempts(messages: list[Message], reason: str = "") -> int:
@@ -675,6 +704,7 @@ def _bump_attempts(messages: list[Message], reason: str = "") -> int:
     burns out on schedule.
     """
     dead = 0
+    newly_dead: list[Message] = []
     for msg in messages:
         if msg.path is None:
             continue
@@ -705,7 +735,7 @@ def _bump_attempts(messages: list[Message], reason: str = "") -> int:
                     attempts=msg.attempts, reason=reason,
                 )
                 dead += 1
-                _escalate_dead_letter(msg, reason)
+                newly_dead.append(msg)
             except OSError:
                 pass
         else:
@@ -713,6 +743,9 @@ def _bump_attempts(messages: list[Message], reason: str = "") -> int:
                 _write_message(msg.path, msg)
             except OSError:
                 pass
+    # One digest email for the whole batch (all share the same recipient —
+    # `messages` is always one session's inbox), not one per message (#836).
+    _escalate_dead_letters(newly_dead, reason)
     return dead
 
 

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/mcp_council.py

@@ -212,9 +212,10 @@ def council_minutes(name: str = "", prompt: str = "", synthesis: str = "") -> st
     Deterministically renders the sitting's persisted prompt history
     (question + attributed take/ack/pass replies) plus your optional
     synthesis into a self-contained HTML artifact at
-    ``~/.agentwire/artifacts/council-<name>-minutes/index.html``, and opens
-    it as a portal artifact window when the portal is up. Works for live and
-    dismissed sittings alike — prompt history survives ``council_stop``.
+    ``~/.agentwire/artifacts/council-<name>-minutes/index.html``, and
+    announces it as a click-to-open portal notification when the portal is
+    up (#817 — never steals focus). Works for live and dismissed sittings
+    alike — prompt history survives ``council_stop``.
 
     Args:
         prompt: Prompt id to render, or 'all' (empty = all)
@@ -222,7 +223,7 @@ def council_minutes(name: str = "", prompt: str = "", synthesis: str = "") -> st
         name: Sitting name (empty = cwd-repo-slug / sole live sitting)
 
     Returns:
-        The rendered artifact's path, and whether a portal window opened.
+        The rendered artifact's path, and whether the portal was notified.
     """
     args = ["council", "minutes"]
     if name:
@@ -235,6 +236,6 @@ def council_minutes(name: str = "", prompt: str = "", synthesis: str = "") -> st
     if not data.get("success"):
         return f"Failed to render minutes: {data.get('error') or data}"
     out = f"{_council_tag(data)}Minutes: {data.get('path')}"
-    if data.get("opened"):
-        out += "\nOpened as a portal artifact window."
+    if data.get("notified"):
+        out += "\nAnnounced in the portal — the human clicks the notification to open."
     return out

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/mcp_desktop.py

@@ -106,9 +106,23 @@ def desktop_open_panel(panel_type: str) -> str:
     return f"Failed to open panel: {data.get('error', 'Unknown error')}"
 
 
+def _announce_artifact(url: str, title: str, artifact_id: str | None) -> dict:
+    """POST the click-to-open artifact notification (#817) — the single
+    portal-side path for surfacing an artifact; there is no force-open."""
+    artifact = {"url": url, "title": title}
+    if artifact_id:
+        artifact["artifact_id"] = artifact_id
+    return _portal_request("POST", "/api/desktop/notification", {"artifact": artifact})
+
+
 @mcp.tool()
 def desktop_open_artifact(url: str, title: str = "Artifact", artifact_id: str | None = None) -> str:
-    """Open a URL or local artifact file in an iframe window on the portal desktop.
+    """Announce a URL or local artifact file on the portal desktop (click-to-open).
+
+    Posts a notification (toast + Session HUD entry) carrying the artifact
+    target instead of force-opening a window (#817) — a background-produced
+    artifact must never steal focus. The human clicks the notice to open the
+    artifact window, focused.
 
     For local files, use a filename from ~/.agentwire/artifacts/ (e.g., "dashboard.html").
     For external sites, use a full URL (e.g., "https://example.com").
@@ -119,21 +133,12 @@ def desktop_open_artifact(url: str, title: str = "Artifact", artifact_id: str |
         artifact_id: Optional unique window ID. If omitted, derived from URL.
 
     Returns:
-        Window ID of the opened window or error.
+        Notification ID or error description.
     """
-    body = {
-        "type": "artifact",
-        "url": url,
-        "title": title,
-    }
-    if artifact_id:
-        body["artifact_id"] = artifact_id
-
-    data = _portal_request("POST", "/api/desktop/window/open", body)
+    data = _announce_artifact(url, title, artifact_id)
     if data.get("success"):
-        wid = data.get("window_id", "unknown")
-        return f"Opened artifact window '{title}' (id: {wid})."
-    return f"Failed to open artifact window: {data.get('error', 'Unknown error')}"
+        return f"Artifact '{title}' announced (notification id: {data.get('id', 'unknown')}) — the human clicks to open."
+    return f"Failed to announce artifact: {data.get('error', 'Unknown error')}"
 
 
 @mcp.tool()
@@ -143,11 +148,12 @@ def desktop_write_artifact(
     title: str = "Artifact",
     artifact_id: str | None = None,
 ) -> str:
-    """Write HTML content to a file and open it as an artifact window.
+    """Write HTML content to a file and announce it as a click-to-open artifact.
 
-    Atomically writes content to ~/.agentwire/artifacts/<filename>, then opens
-    it in an iframe window on the portal desktop. Use this to display
-    dashboards, diagrams, reports, or any HTML content.
+    Atomically writes content to ~/.agentwire/artifacts/<filename>, then posts
+    a click-to-open notification (toast + Session HUD entry, #817) — the human
+    clicks to open the artifact window; it never steals focus. Use this to
+    deliver dashboards, diagrams, reports, or any HTML content.
 
     Args:
         filename: Output filename (must end in .html, e.g., "dashboard.html")
@@ -156,9 +162,8 @@ def desktop_write_artifact(
         artifact_id: Optional unique window ID. If omitted, derived from filename.
 
     Returns:
-        Window ID of the opened window or error.
+        Notification ID or error description.
     """
-    # Step 1: Upload the file
     upload_data = _portal_request("POST", "/api/artifacts/upload", {
         "filename": filename,
         "content": html_content,
@@ -166,20 +171,10 @@ def desktop_write_artifact(
     if not upload_data.get("success"):
         return f"Failed to write artifact: {upload_data.get('error', 'Unknown error')}"
 
-    # Step 2: Open it as a window
-    body = {
-        "type": "artifact",
-        "url": filename,
-        "title": title,
-    }
-    if artifact_id:
-        body["artifact_id"] = artifact_id
-
-    open_data = _portal_request("POST", "/api/desktop/window/open", body)
+    open_data = _announce_artifact(filename, title, artifact_id)
     if open_data.get("success"):
-        wid = open_data.get("window_id", "unknown")
-        return f"Artifact '{filename}' written and opened (id: {wid})."
-    return f"File written but failed to open window: {open_data.get('error', 'Unknown error')}"
+        return f"Artifact '{filename}' written and announced (notification id: {open_data.get('id', 'unknown')})."
+    return f"File written but failed to announce it: {open_data.get('error', 'Unknown error')}"
 
 
 @mcp.tool()

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/mcp_notify.py

@@ -65,7 +65,8 @@ def notify_event(event: str, session: str | None = None) -> str:
 
 
 @mcp.tool()
-def notify_user(text: str, session: str | None = None, priority: str = "normal") -> str:
+def notify_user(text: str, session: str | None = None, priority: str = "normal",
+                artifact_url: str | None = None, artifact_title: str | None = None) -> str:
     """Show the HUMAN a desktop toast on the portal (persistent, visual).
 
     The human-screen channel — the asymmetric text partner to `say` (audio).
@@ -74,11 +75,18 @@ def notify_user(text: str, session: str | None = None, priority: str = "normal")
     (portal lifecycle). Clicking the toast opens the session that generated the
     notification (the `session` below); a toast with no session is non-clickable.
 
+    With `artifact_url` set, the toast instead becomes a click-to-open artifact
+    notice (#817): it sticks until dismissed, also appears in the Session HUD,
+    and clicking it opens that artifact window — use this to hand the human a
+    rendered deliverable without stealing focus.
+
     Args:
         text: Notification text. Bold (**x**), line breaks, and [links](https://…)
             render; everything else is escaped.
         session: Session this relates to (shown as a badge).
         priority: 'normal' or 'high' (high gets an accent border).
+        artifact_url: URL or ~/.agentwire/artifacts/ filename to open on click.
+        artifact_title: Window title for the artifact (default: "Artifact").
 
     Returns:
         Notification ID or error description.
@@ -86,6 +94,8 @@ def notify_user(text: str, session: str | None = None, priority: str = "normal")
     body = {"text": text, "priority": priority}
     if session:
         body["session"] = session
+    if artifact_url:
+        body["artifact"] = {"url": artifact_url, "title": artifact_title or "Artifact"}
     data = _portal_request("POST", "/api/desktop/notification", body)
     if not data.get("success"):
         return f"Failed to post notification: {data.get('error', 'Unknown error')}"

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/mcp_scheduler.py

@@ -258,7 +258,7 @@ def scheduler_report(since: str = "8h", artifact: bool = False) -> str:
 
     Args:
         since: Time window to cover (e.g. '8h', '12h', '1d') default: '8h'
-        artifact: If True, open the report as a portal artifact window
+        artifact: If True, announce the report as a click-to-open portal notification
 
     Returns:
         Path to generated HTML report and summary statistics.

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/mcp_session.py

@@ -151,12 +151,16 @@ def session_create(
             spawns already auto-root (#715), so this is mainly for a
             same-project session you want detached, or to force standalone
             explicitly. Ignored when `created_by` is set (that wins).
-        kind: Session role — "worker" or "orchestrator". A flat name (no
-            branch) already defaults to orchestrator; a project/branch name
-            defaults to worker (safety-railed: isolation/verify/draft-PR/
-            notify). Pass "orchestrator" to override that default for a
-            project/branch name — e.g. a durable branch-pinned project
-            window. Leave empty for the derived default.
+        kind: Session role — "worker", "orchestrator", or "reviewer". A flat
+            name (no branch) already defaults to orchestrator; a
+            project/branch name defaults to worker (safety-railed:
+            isolation/verify/draft-PR/notify). Pass "orchestrator" to
+            override that default for a project/branch name — e.g. a durable
+            branch-pinned project window. Pass "reviewer" for a PR-review
+            station that adversarially reviews a sibling session's PR and
+            never opens/merges one of its own (safety-railed the other way —
+            non-overridable, parented rooting like worker, not rooted like
+            orchestrator). Leave empty for the derived default.
 
     Returns:
         Success message or error description.

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/mcp_worktree.py

@@ -33,9 +33,10 @@ def worktree_create(
     Args:
         name: Worktree/branch name (becomes the branch + session suffix).
         project_dir: Path to the git repo (default: server cwd).
-        roles: Comma-separated roles STACKED on the intrinsic worker etiquette
-            (e.g. "correspondent"). Never replaces the safety rail (kind=worker;
-            for kind="orchestrator" these REPLACE the default persona instead).
+        roles: Comma-separated roles STACKED on the intrinsic worker/reviewer
+            etiquette (e.g. "correspondent"). Never replaces the safety rail
+            (kind=worker or kind=reviewer; for kind="orchestrator" these
+            REPLACE the default persona instead).
         base: Base branch to fork from (default: the repo's origin/HEAD).
         prompt: Optional first message — delivered once the agent is booted and
             ready (verified paste). Lets you spawn AND seed the task in one call
@@ -50,9 +51,13 @@ def worktree_create(
             roots by default (a durable orchestrator shouldn't inherit
             whoever spawned it).
         kind: Session role — "worker" (default: safety-railed, isolation/
-            verify/draft-PR/notify, non-overridable) or "orchestrator" (a
+            verify/draft-PR/notify, non-overridable), "orchestrator" (a
             durable, replaceable-persona project window instead of a
-            subordinate). Leave empty for the default.
+            subordinate), or "reviewer" (safety-railed the other way:
+            adversarially reviews a sibling session's PR, never opens or
+            merges one of its own; stays parented like worker, not rooted
+            like orchestrator — for anyone who needs a local checkout to e2e
+            a sibling's branch). Leave empty for the default.
 
     Returns:
         Success message with the session name + worktree path, or an error.

{agentwire_dev-1.64.0 → agentwire_dev-1.65.1}/agentwire/notify_cli.py

@@ -149,7 +149,11 @@ def cmd_notify_parent(args) -> int:
 
 
 def cmd_open(args) -> int:
-    """Open a URL or local file as an artifact window in the portal.
+    """Announce a URL or local file as a click-to-open artifact notification.
+
+    Posts a portal notification (toast + Session HUD entry) carrying the
+    artifact target instead of force-opening a window (#817) — the window
+    opens, focused, only when the human clicks the notice.
 
     Examples:
         agentwire open dashboard.html --title "Dashboard"
@@ -167,26 +171,23 @@ def cmd_open(args) -> int:
 
     portal_url = _get_portal_url()
 
-    body = {
-        "type": "artifact",
-        "url": url,
-        "title": title,
-    }
+    artifact = {"url": url, "title": title}
     if artifact_id:
-        body["artifact_id"] = artifact_id
+        artifact["artifact_id"] = artifact_id
 
     try:
         resp = portal_request(
             "POST",
-            f"{portal_url}/api/desktop/window/open",
-            json=body,
+            f"{portal_url}/api/desktop/notification",
+            json={"artifact": artifact},
         )
         data = resp.json()
 
         if json_output:
             print(json.dumps(data))
         elif data.get("success"):
-            print(f"Opened artifact window: {title} (id: {data.get('window_id', 'unknown')})")
+            print(f"Artifact announced: {title} (notification id: {data.get('id', 'unknown')}) "
+                  "— click the toast or HUD entry to open")
         else:
             print(f"Failed: {data.get('error', 'Unknown error')}", file=sys.stderr)
             return 1
@@ -311,11 +312,11 @@ def register_notify_parser(subparsers) -> None:
     notify_cmd_parser.add_argument("--json", action="store_true", help="Output as JSON")
     notify_cmd_parser.set_defaults(func=cmd_notify_parent)
 
-    # === open command (artifact windows) ===
-    open_parser = subparsers.add_parser("open", help="Open a URL or local file as an artifact window in the portal")
-    open_parser.add_argument("url", help="URL or filename to open (filenames served from ~/.agentwire/artifacts/)")
+    # === open command (artifact notifications) ===
+    open_parser = subparsers.add_parser("open", help="Announce a URL or local file as a click-to-open artifact notification in the portal")
+    open_parser.add_argument("url", help="URL or filename to announce (filenames served from ~/.agentwire/artifacts/)")
     open_parser.add_argument("--title", "-t", type=str, default="Artifact", help="Window title")
-    open_parser.add_argument("--artifact-id", type=str, help="Unique window ID (auto-generated if omitted)")
+    open_parser.add_argument("--artifact-id", type=str, help="Unique window ID for the opened artifact (auto-generated if omitted)")
     open_parser.add_argument("--json", action="store_true", help="Output JSON")
     open_parser.set_defaults(func=cmd_open)