agentwire-dev 1.63.0__tar.gz → 1.65.0__tar.gz

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/PKG-INFO

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

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/agentwire/__init__.py

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

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/agentwire/config.py

@@ -13,6 +13,14 @@ from typing import Optional
 
 import yaml
 
+# Gitignored files a fresh git worktree needs seeded — a worktree can't load
+# its session/task config without them. Single source of truth: referenced
+# by WorktreesConfig's default below, the config-loading fallback further
+# down, AND worktree.py's mandatory (never-omittable) seed set (#803) — a
+# stale `copy_files:` in a user's config.yaml that predates one of these
+# being added here must not silently drop it from every fresh worktree.
+DEFAULT_WORKTREE_COPY_FILES = [".env", ".agentwire.yml", ".agentwire.tasks.yml"]
+
 
 def _get_default_agent_command() -> str:
     """Get the default agent command.
@@ -105,7 +113,7 @@ class WorktreesConfig:
     # tasks can't load their session/task config without them when the project
     # gitignores them (the latter is the protected, host-authored task-exec file —
     # #720).
-    copy_files: list = field(default_factory=lambda: [".env", ".agentwire.yml", ".agentwire.tasks.yml"])
+    copy_files: list = field(default_factory=lambda: list(DEFAULT_WORKTREE_COPY_FILES))
 
 
 @dataclass
@@ -114,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"
@@ -623,12 +630,11 @@ def _dict_to_config(data: dict) -> Config:
         enabled=worktrees_data.get("enabled", True),
         suffix=worktrees_data.get("suffix", "-worktrees"),
         auto_create_branch=worktrees_data.get("auto_create_branch", True),
-        copy_files=worktrees_data.get("copy_files", [".env", ".agentwire.yml", ".agentwire.tasks.yml"]),
+        copy_files=worktrees_data.get("copy_files", list(DEFAULT_WORKTREE_COPY_FILES)),
     )
     projects = ProjectsConfig(
         dir=projects_data.get("dir", "~/projects"),
         worktrees=worktrees,
-        extra=projects_data.get("extra", []),
     )
 
     # Worktree-session orchestration (`worktree:` key).

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/agentwire/core.py

@@ -741,7 +741,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.63.0 → agentwire_dev-1.65.0}/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.63.0 → agentwire_dev-1.65.0}/agentwire/doctor_cli.py

@@ -19,6 +19,7 @@ import shutil
 import socket
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 from .core import (
@@ -475,6 +476,75 @@ def _render_shim_liveness_section() -> int:
     return len(dead)
 
 
+def _scheduler_daemon_started_at() -> float | None:
+    """Epoch seconds the scheduler daemon process started, or ``None`` if not running.
+
+    Reads the daemon's own self-reported ``started_at`` from the live-state
+    file it already writes every loop tick (``scheduler/loop.py`` ->
+    ``_write_live_state`` -> ``read_live_state()``) rather than reimplementing
+    process-start-time discovery via ``ps``/``pgrep`` PID matching, which is
+    both platform-fragile (``ps`` elapsed-time output format varies) and
+    ambiguous if a stray/duplicate daemon process happens to be running.
+    ``tmux_session_exists`` confirms the daemon is actually alive, so a
+    leftover live-state file from a since-stopped daemon doesn't produce a
+    false "stale" reading.
+    """
+    from .scheduler import SCHEDULER_SESSION, read_live_state
+
+    if not tmux_session_exists(SCHEDULER_SESSION):
+        return None
+    state = read_live_state()
+    if not state:
+        return None
+    started_at = state.get("started_at")
+    if not started_at:
+        return None
+    try:
+        from datetime import datetime
+        return datetime.fromisoformat(started_at).timestamp()
+    except (ValueError, TypeError):
+        return None
+
+
+def _newest_installed_source_mtime(pkg_dir: Path | None = None) -> float:
+    """Newest mtime among the installed ``agentwire`` package's ``.py`` files."""
+    if pkg_dir is None:
+        pkg_dir = Path(__file__).resolve().parent
+    try:
+        return max((f.stat().st_mtime for f in pkg_dir.rglob("*.py")), default=0.0)
+    except Exception:
+        return 0.0
+
+
+def _render_scheduler_staleness_section() -> int:
+    """Doctor section: flag a scheduler daemon older than the installed code (#803).
+
+    ``agentwire scheduler serve`` is a long-running Python process — like the
+    MCP server, it imports its modules once at start and never re-reads them.
+    ``agentwire rebuild`` updates the on-disk package but can't touch an
+    already-running interpreter's loaded bytecode, so a daemon that has been
+    up since before the last rebuild is silently executing stale dispatch
+    logic: any bug fixed since then stays live in production until the
+    daemon is restarted.
+    """
+    started_at = _scheduler_daemon_started_at()
+    if started_at is None:
+        print("  [..] Scheduler daemon not running — skipping staleness check")
+        return 0
+
+    newest_src = _newest_installed_source_mtime()
+    if not newest_src or newest_src <= started_at:
+        print("  [ok] Scheduler daemon is current with the installed package")
+        return 0
+
+    age_days = (time.time() - started_at) / 86400
+    print(f"  [!!] Scheduler daemon has been running {age_days:.1f}d — "
+          "predates the most recent `agentwire rebuild`")
+    print("       Any dispatch bug fixed since then is still live in the running daemon.")
+    print("       Fix: agentwire scheduler stop && agentwire scheduler start")
+    return 1
+
+
 def cmd_doctor(args) -> int:
     """Auto-diagnose and fix common issues."""
     from .hooks_cli import _managed_file_state, _managed_hook_files, get_hooks_source
@@ -653,6 +723,14 @@ def cmd_doctor(args) -> int:
         else:
             print("  [ok] Local main up to date with origin/main")
 
+    # 4d. Scheduler daemon staleness — the daemon is a long-running process
+    # that never re-imports its code, so it can silently run a dispatch bug
+    # that's since been fixed on disk (#803). Distinct from the git-drift
+    # check above: that flags an out-of-date CHECKOUT, this flags a
+    # currently-running PROCESS that predates the last install.
+    print("\nChecking scheduler daemon freshness...")
+    issues_found += _render_scheduler_staleness_section()
+
     # Check custom services (registry-driven: built-in notifications bridge
     # + user-defined services from services.custom)
     print("\nChecking custom services...")

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/agentwire/hooks/damage-control/bash-tool-damage-control.py

@@ -613,8 +613,8 @@ def load_config(
 # dispatch by the scheduler), the hook resolves ``ask`` by FAILING CLOSED:
 # block + notify the owner, UNLESS the matched rule's stable ID is on the
 # allowlist. The allowlist is the union of:
-#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (tight — work + open a PR, nothing
-#      irreversible or outward-facing),
+#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (work + open a PR + notify the owner
+#      by email — nothing else irreversible or outward-facing),
 #   2. ``safety.unattended_allow`` from global / project config,
 #   3. ``AGENTWIRE_UNATTENDED_ALLOW`` (comma-separated) — the per-task
 #      extension the scheduler stamps from a task's ``unattended_allow``.
@@ -629,6 +629,7 @@ DEFAULT_UNATTENDED_ALLOW = {
     "git.commit",    # commit
     "git.push",      # push (force/delete are SEPARATE hard-block/ask rules)
     "gh.pr-create",  # open a PR — the human-reviewed gate
+    "outbound.agentwire-email",  # blanket allow, any recipient (#804)
 }
 
 

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/agentwire/hooks/damage-control/edit-tool-damage-control.py

@@ -609,8 +609,8 @@ def load_config(
 # dispatch by the scheduler), the hook resolves ``ask`` by FAILING CLOSED:
 # block + notify the owner, UNLESS the matched rule's stable ID is on the
 # allowlist. The allowlist is the union of:
-#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (tight — work + open a PR, nothing
-#      irreversible or outward-facing),
+#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (work + open a PR + notify the owner
+#      by email — nothing else irreversible or outward-facing),
 #   2. ``safety.unattended_allow`` from global / project config,
 #   3. ``AGENTWIRE_UNATTENDED_ALLOW`` (comma-separated) — the per-task
 #      extension the scheduler stamps from a task's ``unattended_allow``.
@@ -625,6 +625,7 @@ DEFAULT_UNATTENDED_ALLOW = {
     "git.commit",    # commit
     "git.push",      # push (force/delete are SEPARATE hard-block/ask rules)
     "gh.pr-create",  # open a PR — the human-reviewed gate
+    "outbound.agentwire-email",  # blanket allow, any recipient (#804)
 }
 
 

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/agentwire/hooks/damage-control/mcp-tool-damage-control.py

@@ -621,8 +621,8 @@ def load_config(
 # dispatch by the scheduler), the hook resolves ``ask`` by FAILING CLOSED:
 # block + notify the owner, UNLESS the matched rule's stable ID is on the
 # allowlist. The allowlist is the union of:
-#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (tight — work + open a PR, nothing
-#      irreversible or outward-facing),
+#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (work + open a PR + notify the owner
+#      by email — nothing else irreversible or outward-facing),
 #   2. ``safety.unattended_allow`` from global / project config,
 #   3. ``AGENTWIRE_UNATTENDED_ALLOW`` (comma-separated) — the per-task
 #      extension the scheduler stamps from a task's ``unattended_allow``.
@@ -637,6 +637,7 @@ DEFAULT_UNATTENDED_ALLOW = {
     "git.commit",    # commit
     "git.push",      # push (force/delete are SEPARATE hard-block/ask rules)
     "gh.pr-create",  # open a PR — the human-reviewed gate
+    "outbound.agentwire-email",  # blanket allow, any recipient (#804)
 }
 
 

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/agentwire/hooks/damage-control/read-tool-damage-control.py

@@ -615,8 +615,8 @@ def load_config(
 # dispatch by the scheduler), the hook resolves ``ask`` by FAILING CLOSED:
 # block + notify the owner, UNLESS the matched rule's stable ID is on the
 # allowlist. The allowlist is the union of:
-#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (tight — work + open a PR, nothing
-#      irreversible or outward-facing),
+#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (work + open a PR + notify the owner
+#      by email — nothing else irreversible or outward-facing),
 #   2. ``safety.unattended_allow`` from global / project config,
 #   3. ``AGENTWIRE_UNATTENDED_ALLOW`` (comma-separated) — the per-task
 #      extension the scheduler stamps from a task's ``unattended_allow``.
@@ -631,6 +631,7 @@ DEFAULT_UNATTENDED_ALLOW = {
     "git.commit",    # commit
     "git.push",      # push (force/delete are SEPARATE hard-block/ask rules)
     "gh.pr-create",  # open a PR — the human-reviewed gate
+    "outbound.agentwire-email",  # blanket allow, any recipient (#804)
 }
 
 

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/agentwire/hooks/damage-control/write-tool-damage-control.py

@@ -608,8 +608,8 @@ def load_config(
 # dispatch by the scheduler), the hook resolves ``ask`` by FAILING CLOSED:
 # block + notify the owner, UNLESS the matched rule's stable ID is on the
 # allowlist. The allowlist is the union of:
-#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (tight — work + open a PR, nothing
-#      irreversible or outward-facing),
+#   1. ``DEFAULT_UNATTENDED_ALLOW`` below (work + open a PR + notify the owner
+#      by email — nothing else irreversible or outward-facing),
 #   2. ``safety.unattended_allow`` from global / project config,
 #   3. ``AGENTWIRE_UNATTENDED_ALLOW`` (comma-separated) — the per-task
 #      extension the scheduler stamps from a task's ``unattended_allow``.
@@ -624,6 +624,7 @@ DEFAULT_UNATTENDED_ALLOW = {
     "git.commit",    # commit
     "git.push",      # push (force/delete are SEPARATE hard-block/ask rules)
     "gh.pr-create",  # open a PR — the human-reviewed gate
+    "outbound.agentwire-email",  # blanket allow, any recipient (#804)
 }
 
 

{agentwire_dev-1.63.0 → agentwire_dev-1.65.0}/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.63.0 → agentwire_dev-1.65.0}/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.63.0 → agentwire_dev-1.65.0}/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.63.0 → agentwire_dev-1.65.0}/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.63.0 → agentwire_dev-1.65.0}/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.63.0 → agentwire_dev-1.65.0}/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.