agentwire-dev 1.60.0__tar.gz → 1.62.0__tar.gz

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.60.0
+Version: 1.62.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.60.0 → agentwire_dev-1.62.0}/agentwire/__init__.py

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

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/agentwire/core.py

@@ -148,15 +148,25 @@ def _build_tmux_env_flags_shell(env: dict[str, str]) -> str:
     return " ".join(parts) + " "
 
 
-def _set_session_name_env(agent: "AgentCommand", session_name: str) -> None:
-    """Stamp ``AGENTWIRE_SESSION_NAME`` onto an ``AgentCommand.env``.
+def _set_session_name_env(agent: "AgentCommand", session_name: str, created_by: str | None = None) -> None:
+    """Stamp ``AGENTWIRE_SESSION_NAME`` (and, when there's a real parent,
+    ``AGENTWIRE_CREATED_BY``) onto an ``AgentCommand.env``.
 
     Every session created via ``cmd_new`` / ``cmd_spawn`` / ``cmd_recreate``
-    / ``cmd_fork`` / scheduler-spawn paths gets this so downstream tooling
-    (notably the worker damage-control rules in ``safety/_core.py``)
-    can identify which agentwire session the running tool is part of.
+    / ``cmd_fork`` / scheduler-spawn paths gets ``AGENTWIRE_SESSION_NAME`` so
+    downstream tooling (notably the worker damage-control rules in
+    ``safety/_core.py``) can identify which agentwire session the running
+    tool is part of.
+
+    ``created_by`` of ``''`` (root/orchestrator) or ``None`` means no
+    parent — ``AGENTWIRE_CREATED_BY`` is deliberately left UNSET rather than
+    set to an empty string, so the bare pre-agent shell's launch-crash guard
+    (``_guarded_launch_command``) can tell "has a parent to escalate to"
+    apart from "root session, email the owner" with a plain ``-n`` test (#743).
     """
     agent.env["AGENTWIRE_SESSION_NAME"] = session_name
+    if created_by:
+        agent.env["AGENTWIRE_CREATED_BY"] = created_by
 
 
 def inject_session_env(session: str, env: dict[str, str], remote_host: str | None = None) -> None:
@@ -730,6 +740,54 @@ def _record_session_creator(session_name: str, created_by: str | None, via: str)
     store_session_metadata(session_name, metadata)
 
 
+def _record_session_role(session_name: str, role: str | None) -> None:
+    """Record the session's ROLE axis (orchestrator/worker) 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``
+    in cmd_new, ``effective_kind`` in cmd_worktree, "worker" for cmd_spawn).
+    Read back by list_local_sessions() and the session_created notify lookup.
+    """
+    if not role:
+        return
+    metadata = load_session_metadata(session_name)
+    metadata["role"] = role
+    store_session_metadata(session_name, metadata)
+
+
+def notify_portal_session_created(session_name: str, parent: str | None, role: str | None) -> None:
+    """Tell the portal a session was just created, with topology context (#747).
+
+    Fires immediately from the creating process instead of relying solely on
+    the global tmux ``session-created`` hook, which only knows the bare
+    session name (no parent/role) and can race a slow first-message delivery
+    before metadata is written. Fire-and-forget — failures are silently
+    ignored since the portal may not be running.
+    """
+    import ssl
+
+    payload: dict = {"event": "session_created", "session": session_name}
+    if parent:
+        payload["parent"] = parent
+    if role:
+        payload["role"] = role
+
+    try:
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+
+        req = urllib.request.Request(
+            f"{_default_portal_url()}/api/notify",
+            data=json.dumps(payload).encode(),
+            headers={"Content-Type": "application/json", **_portal_auth_headers()},
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=3, context=ctx)
+    except Exception:
+        pass
+
+
 def _display_parent(session_name: str, path: str = "") -> "str | None":
     """The session that should visually own this one in the sidebar.
 
@@ -847,6 +905,52 @@ def _run_remote(machine_id: str, command: str) -> subprocess.CompletedProcess:
         )
 
 
+def _guarded_launch_command(path_str: str, agent_cmd: str | None) -> str:
+    """Build the pane's ``cd <path> && <agent_cmd>`` line with a missing-dir guard (#739).
+
+    A crashed worktree create can leave ``path_str`` absent by the time the
+    pane actually runs its ``cd`` (race between ``agentwire new`` reporting
+    success and the async pane launch, or an external actor removing the
+    dir). Without a guard, ``cd`` fails, the shell prints an error and
+    carries on, and ``agent_cmd`` (e.g. ``claude``) then launches from the
+    WRONG cwd and crashes — dropping the pane to a bare shell that the
+    idle-reaper never touches (it only reaps a *running* agent going idle),
+    so it lingers forever.
+
+    On a missing dir this instead alerts and exits the shell, which tears the
+    tmux session down instead of leaving a zombie. ``agent_cmd`` never runs.
+
+    Two alert routes, both shell-runtime-gated on env vars stamped at launch
+    (``_set_session_name_env``), so this function stays a pure string builder
+    with no Python-level knowledge of the session's parent (#743):
+    - A real recorded parent (``$AGENTWIRE_CREATED_BY`` set) gets the crash
+      escalated to its msg inbox — in-band, not just an email the human has
+      to forward.
+    - No parent (root/orchestrator sessions, the genuine scheduler-dispatch
+      case) falls back to the original owner email, still gated on
+      ``$AGENTWIRE_UNATTENDED=1`` (see ``_with_unattended_env``).
+    """
+    quoted_path = shlex.quote(path_str)
+    session_ref = "${AGENTWIRE_SESSION_NAME:-unknown session}"
+    missing_body = f"cd failed at launch: {path_str}"
+    notify_parent = (
+        '[ -n "$AGENTWIRE_CREATED_BY" ] && agentwire msg send --to "$AGENTWIRE_CREATED_BY" '
+        f'--kind escalation --subject "agentwire: worktree missing at launch — {session_ref}" '
+        f'--body "{missing_body}" >/dev/null 2>&1'
+    )
+    notify_owner = (
+        '[ -z "$AGENTWIRE_CREATED_BY" ] && [ "$AGENTWIRE_UNATTENDED" = "1" ] && agentwire email '
+        f'--subject "agentwire: worktree missing — {session_ref}" '
+        f'--body "{missing_body}" >/dev/null 2>&1'
+    )
+    alert = (
+        f"echo \"agentwire: worktree missing at launch, aborting: {path_str}\" >&2; "
+        f"{notify_parent}; {notify_owner}"
+    )
+    guard = f"cd {quoted_path} || {{ {alert}; exit 1; }}"
+    return f"{guard} && {agent_cmd}" if agent_cmd else guard
+
+
 def _launch_tmux_session(
     session_name: str,
     session_path,
@@ -859,8 +963,9 @@ def _launch_tmux_session(
     The one launch sequence shared by ``new`` / ``recreate`` / ``fork`` (#630):
     `tmux new-session -e K=V` injects *env* into the session environment
     BEFORE the initial shell starts (post-hoc `set-environment` never reaches
-    it), then `send-keys` cd's into place and, if *agent_cmd* is non-empty,
-    starts the agent after a short settle.
+    it), then `send-keys` cd's into place (guarded — see
+    ``_guarded_launch_command``) and, if *agent_cmd* is non-empty, starts the
+    agent after a short settle.
 
     Local (machine_id None): runs subprocess calls with check=True (raises on
     tmux failure) and returns None. Remote: runs one composite shell command
@@ -869,17 +974,14 @@ def _launch_tmux_session(
     import time
 
     path_str = str(session_path)
+    launch_cmd = _guarded_launch_command(path_str, agent_cmd)
     if machine_id:
         env_flags = _build_tmux_env_flags_shell(env)
         create_cmd = (
             f"tmux new-session -d -s {shlex.quote(session_name)} -c {shlex.quote(path_str)} {env_flags}&& "
-            f"tmux send-keys -t {shlex.quote(session_name)} 'cd {shlex.quote(path_str)}' Enter"
+            f"sleep 0.1 && "
+            f"tmux send-keys -t {shlex.quote(session_name)} {shlex.quote(launch_cmd)} Enter"
         )
-        if agent_cmd:
-            create_cmd += (
-                f" && sleep 0.1 && "
-                f"tmux send-keys -t {shlex.quote(session_name)} {shlex.quote(agent_cmd)} Enter"
-            )
         return _run_remote(machine_id, create_cmd)
 
     subprocess.run(
@@ -887,16 +989,11 @@ def _launch_tmux_session(
          *_build_tmux_env_flags(env)],
         check=True,
     )
+    time.sleep(0.1)
     subprocess.run(
-        ["tmux", "send-keys", "-t", session_name, f"cd {shlex.quote(path_str)}", "Enter"],
+        ["tmux", "send-keys", "-t", session_name, launch_cmd, "Enter"],
         check=True,
     )
-    time.sleep(0.1)
-    if agent_cmd:
-        subprocess.run(
-            ["tmux", "send-keys", "-t", session_name, agent_cmd, "Enter"],
-            check=True,
-        )
     return None
 
 

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/agentwire/doctor_cli.py

@@ -1008,6 +1008,30 @@ def cmd_doctor(args) -> int:
     except Exception as e:
         print(f"  [..] Could not check managed voice shim liveness: {e}")
 
+    # 14. Zombie scheduler sessions (#739): a worktree dispatch whose launch
+    # crashed before the agent started (e.g. the worktree dir went missing
+    # between `agentwire new` reporting success and the pane's `cd`) drops to
+    # a bare shell the idle-reaper never touches. `agentwire limits tick`
+    # self-heals these every minute, so a live one here means the watchdog
+    # isn't installed/running, not that reaping is broken.
+    print("\nChecking for zombie scheduler sessions (#739)...")
+    try:
+        from .scheduler import scan_zombie_sessions
+
+        zombie_sessions = scan_zombie_sessions()
+        if not zombie_sessions:
+            print("  [ok] No zombie scheduler sessions found")
+        else:
+            issues_found += 1
+            print(f"  [!!] {len(zombie_sessions)} scheduler session(s) stuck at a bare shell:")
+            for z in zombie_sessions:
+                print(f"       - {z['session']} ({z['command']}, {z['age_seconds']}s old)")
+            print("       `agentwire limits tick` reaps these automatically — "
+                  "run it now, or check the usage-limit watchdog is installed "
+                  "(`agentwire limits install`).")
+    except Exception as e:
+        print(f"  [..] Could not check for zombie scheduler sessions: {e}")
+
     # Summary
     print()
     print("-" * 60)

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/agentwire/limits_cli.py

@@ -177,16 +177,20 @@ def cmd_limits_tick(args) -> int:
     """One watchdog pass (called by launchd every minute).
 
     Runs the usage-limit sweep FIRST, then prompt routing (#276), then the
-    polite-message inbox drain (#296), then context auto-management (#442) —
-    the ordering guarantees a usage-limit dialog is parked before any sweep
-    looks at the pane, that the inbox only ever delivers to panes the prompt
-    sweep already cleared, and that auto-``/clear`` runs LAST so it never fights
-    a pending paste/prompt for the same idle, empty box.
+    polite-message inbox drain (#296), then context auto-management (#442),
+    then the zombie-scheduler-session reap (#739) — the ordering guarantees a
+    usage-limit dialog is parked before any sweep looks at the pane, that the
+    inbox only ever delivers to panes the prompt sweep already cleared, that
+    auto-``/clear`` runs before the reap so it never fights a pending
+    paste/prompt for the same idle, empty box, and that the reap runs LAST
+    since it kills sessions outright (nothing later should still be acting on
+    one).
 
     Each stage runs inside :func:`_run_stage` so an exception in one subsystem
     is logged and skipped rather than aborting the whole cycle (#490).
     """
     from agentwire import inbox, prompt_router, session_context
+    from agentwire.scheduler import zombie as scheduler_zombie
 
     result = _run_stage(
         "usage_limit", usage_limit.tick,
@@ -197,9 +201,12 @@ def cmd_limits_tick(args) -> int:
         "inbox", inbox.tick, {"flushed": [], "deferred": []})
     context = _run_stage(
         "session_context", session_context.tick, {"acted": [], "deferred": []})
+    zombies = _run_stage(
+        "scheduler_zombie", scheduler_zombie.tick, {"killed": []})
     if getattr(args, "json", False):
         print(json.dumps({
-            **result, "prompts": prompts, "messages": messages, "context": context,
+            **result, "prompts": prompts, "messages": messages,
+            "context": context, "zombies": zombies,
         }))
         return 0
     if result.get("skipped"):
@@ -237,6 +244,9 @@ def cmd_limits_tick(args) -> int:
     if ctx_deferred:
         print("context deferred: " + ", ".join(
             f"{e['session']}({e['deferred']})" for e in ctx_deferred))
+    killed = zombies.get("killed") or []
+    if killed:
+        print("zombie scheduler sessions reaped: " + ", ".join(killed))
     return 0
 
 

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/agentwire/mcp_worktree.py

@@ -225,6 +225,7 @@ def worktree_remove(
     project_dir: str = "",
     keep_branch: bool = False,
     force_delete_branch: bool = False,
+    close_pr_branch: bool = False,
 ) -> str:
     """Tear down a worktree session: kill the session, remove the worktree + branch, unregister.
 
@@ -245,7 +246,12 @@ def worktree_remove(
         project_dir: Path to the git repo (default: server cwd).
         keep_branch: Skip branch cleanup entirely (leave the branch as-is).
         force_delete_branch: Delete the branch even if not confirmed merged —
-            use only when you're sure the work is safe to discard.
+            use only when you're sure the work is safe to discard. Still
+            refuses a branch with an OPEN PR (deleting it would silently
+            close the PR) unless close_pr_branch is also set.
+        close_pr_branch: Combined with force_delete_branch, also delete a
+            branch that has an OPEN PR, closing it. Explicit escape hatch —
+            only set this when you mean to close that PR.
 
     Returns:
         Success message describing what was removed, or a loud failure
@@ -258,6 +264,8 @@ def worktree_remove(
         args += ["--keep-branch"]
     if force_delete_branch:
         args += ["--force-delete-branch"]
+    if close_pr_branch:
+        args += ["--close-pr-branch"]
     data = run_agentwire_cmd(args)
     session = data.get("session", name)
     killed = " (killed live session)" if data.get("killed") else ""

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/agentwire/pane_cli.py

@@ -37,6 +37,7 @@ from .core import (
     build_agent_command,
     inject_session_env,
     load_config,
+    load_session_metadata,
     parse_env_args,
     tmux_session_exists,
 )
@@ -172,6 +173,7 @@ def list_local_sessions(show_context: bool = False) -> list[dict]:
             "posture": cfg.get("posture"),
             "roles": cfg.get("roles", []),
             "parent": _display_parent(parts[0], path),
+            "role": load_session_metadata(parts[0]).get("role"),
         }
         if usage_limit_parked(parts[0]):
             session_info["usage_limit"] = True

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/agentwire/routes/notify.py

@@ -66,9 +66,20 @@ class NotifyRoutesMixin:
                 await self.broadcast_dashboard("sessions_update", {"sessions": sessions_data})
 
             elif event == "session_created":
+                # #747: name/parent/role travel in the payload when the
+                # creating process (cmd_new et al.) posts this explicitly —
+                # that's authoritative, no race. The bare global tmux hook
+                # (session-created, any tmux session) carries only the name,
+                # so fall back to a fresh lookup for that case (metadata may
+                # not be written yet on a very fast reattach — best-effort).
                 self._invalidate_session_caches()
-                await self.broadcast_dashboard("session_created", {"session": session})
                 sessions_data = await self._get_sessions_data()
+                entry = next((s for s in sessions_data if s.get("name") == session), None)
+                parent = data.get("parent") or (entry.get("parent") if entry else None)
+                role = data.get("role") or (entry.get("role") if entry else None)
+                await self.broadcast_dashboard("session_created", {
+                    "session": session, "name": session, "parent": parent, "role": role,
+                })
                 await self.broadcast_dashboard("sessions_update", {"sessions": sessions_data})
 
             elif event == "pane_died":

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/agentwire/routes/projects.py

@@ -379,6 +379,66 @@ class ProjectsRoutesMixin:
 
         return web.json_response({"existing": result.get("existing", [])})
 
+    async def api_worktree_cleanup(self, request: web.Request) -> web.Response:
+        """Tear down an orphaned worktree (Session HUD ghost card "Clean up").
+
+        Thin wrapper over the plain `agentwire worktree --remove` form — the
+        CLI's own merge/open-PR guard decides whether the branch is also
+        deleted; this never escalates to --force-delete-branch.
+
+        Body: {"name": "<branch or session>", "project": "/path/to/repo"}
+        Returns whatever the CLI returns verbatim: on success
+        {success, session, path, killed, worktree_removed, branch,
+        branch_deleted, branch_note, orphaned_tabs}; on failure
+        {success: false, error}.
+        """
+        try:
+            data = await request.json()
+        except Exception:
+            return web.json_response({"success": False, "error": "Invalid JSON body"}, status=400)
+
+        name = (data.get("name") or "").strip()
+        project = (data.get("project") or "").strip()
+        if not name or not project:
+            return web.json_response({"success": False, "error": "name and project are required"}, status=400)
+
+        # Thin wrapper: the git/registry/branch-safety logic lives in the CLI (SSOT).
+        success, result = await self.run_agentwire_cmd(
+            ["worktree", "--remove", name, "-p", project]
+        )
+        return web.json_response(result, status=200 if success else 400)
+
+    async def api_worktree_adopt(self, request: web.Request) -> web.Response:
+        """Spawn a session into an existing worktree (Session HUD ghost card "Adopt").
+
+        Thin wrapper over `agentwire worktree <name> -p <project> --existing
+        [--created-by <createdBy>]` — checks out the branch already on disk
+        (no new branch) and, when the dead session's recorded creator is
+        known, roots the new session under that same parent so it reports
+        back the way the original session would have.
+
+        Body: {"name": "<branch>", "project": "/path/to/repo", "createdBy": "<session>"}
+        Returns whatever the CLI returns verbatim (same shape as `agentwire new`'s
+        json — success/session/path/... — or {success: false, error}).
+        """
+        try:
+            data = await request.json()
+        except Exception:
+            return web.json_response({"success": False, "error": "Invalid JSON body"}, status=400)
+
+        name = (data.get("name") or "").strip()
+        project = (data.get("project") or "").strip()
+        created_by = (data.get("createdBy") or "").strip()
+        if not name or not project:
+            return web.json_response({"success": False, "error": "name and project are required"}, status=400)
+
+        args = ["worktree", name, "-p", project, "--existing"]
+        if created_by:
+            args += ["--created-by", created_by]
+
+        success, result = await self.run_agentwire_cmd(args)
+        return web.json_response(result, status=200 if success else 400)
+
 
 def register_projects_routes(server, app):
     """Wire the projects domain's routes onto ``app``."""
@@ -389,3 +449,5 @@ def register_projects_routes(server, app):
     app.router.add_get("/api/session/defaults", server.api_session_defaults)
     app.router.add_get("/api/check-path", server.api_check_path)
     app.router.add_get("/api/check-branches", server.api_check_branches)
+    app.router.add_post("/api/worktree/cleanup", server.api_worktree_cleanup)
+    app.router.add_post("/api/worktree/adopt", server.api_worktree_adopt)

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/agentwire/routes/sessions_admin.py

@@ -183,10 +183,10 @@ class SessionsAdminRoutesMixin:
                 yaml_config["voice"] = voice
                 await self._write_agentwire_yaml(session_path, yaml_config, machine_id)
 
-            # Broadcast session created to dashboard clients
-            await self.broadcast_dashboard("session_created", {"session": session_name})
-            sessions_data = await self._get_sessions_data()
-            await self.broadcast_dashboard("sessions_update", {"sessions": sessions_data})
+            # No manual broadcast here (#747): the `agentwire new` subprocess
+            # just awaited above already posted the enriched session_created
+            # (name/parent/role) + sessions_update to this same portal from
+            # inside cmd_new, before returning.
 
             # Wait until the tmux pane has actually rendered something. The CLI
             # returns the moment `tmux send-keys` *queues* the agent command, so

{agentwire_dev-1.60.0 → agentwire_dev-1.62.0}/agentwire/scheduler/__init__.py

@@ -24,6 +24,7 @@ from datetime import datetime, timezone
 import yaml
 
 from ..core import _atomic_write
+from . import zombie
 from .dispatch import (
     _WORKFLOW_STATUS_TO_SCHED,
     _apply_max_runs,
@@ -110,3 +111,6 @@ from .state import (
     load_board,
     save_board,
 )
+from .zombie import reap as reap_zombie_sessions
+from .zombie import scan as scan_zombie_sessions
+from .zombie import tick as zombie_tick

agentwire_dev-1.62.0/agentwire/scheduler/zombie.py

@@ -0,0 +1,160 @@
+"""Reap bare-shell scheduler sessions (#739).
+
+``_dispatch_worktree_task`` names every worktree branch
+``scheduler-<task>-<ts>``. If the session's launch crashes before the agent
+starts (e.g. the worktree directory went missing between ``agentwire new``
+reporting success and the pane's ``cd``), the tmux session drops to a bare
+shell — which the idle-reaper correctly never touches, since it only reaps a
+*running* agent that goes idle. Nothing else would ever clean that up, so it
+lingers indefinitely. This module finds and kills those sessions.
+
+Detected by branch naming rather than ``worktree_registry`` — scheduler
+dispatch goes through ``agentwire new``, which (unlike ``agentwire
+worktree``) never registers there.
+"""
+
+import subprocess
+import time
+
+from ..worktree import parse_session_name
+
+BRANCH_PREFIX = "scheduler-"
+
+# tmux `session_created` is whole seconds. A healthy launch's pre-agent shell
+# moment lasts well under a second (see `_launch_tmux_session`'s 0.1s
+# settle), but this gives a slow `claude` cold start real headroom before a
+# session still mid-launch could be mistaken for a zombie.
+MIN_AGE_SECONDS = 60
+
+_SHELL_COMMANDS = frozenset({"zsh", "bash", "sh", "fish", "tcsh", "csh", "dash"})
+
+
+def _is_bare_shell(command: str) -> bool:
+    """True if *command* (a ``pane_current_command`` value) is a login shell."""
+    return command.strip().lstrip("-") in _SHELL_COMMANDS
+
+
+def scan() -> list[dict]:
+    """Live scheduler-dispatched worktree sessions stuck at a bare shell.
+
+    Each entry: ``session``, ``branch``, ``command``, ``age_seconds``.
+    """
+    result = subprocess.run(
+        ["tmux", "list-sessions", "-F", "#{session_name}\t#{session_created}"],
+        capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        return []
+
+    now = time.time()
+    zombies = []
+    for line in result.stdout.strip().splitlines():
+        if "\t" not in line:
+            continue
+        session, created = line.split("\t", 1)
+        _, branch, machine = parse_session_name(session)
+        if machine or not branch or not branch.startswith(BRANCH_PREFIX):
+            continue
+        try:
+            age = now - float(created)
+        except ValueError:
+            continue
+        if age < MIN_AGE_SECONDS:
+            continue
+
+        panes = subprocess.run(
+            ["tmux", "list-panes", "-t", f"={session}", "-F", "#{pane_current_command}"],
+            capture_output=True, text=True,
+        )
+        if panes.returncode != 0:
+            continue
+        commands = [p for p in panes.stdout.strip().splitlines() if p]
+        if len(commands) == 1 and _is_bare_shell(commands[0]):
+            zombies.append({
+                "session": session, "branch": branch,
+                "command": commands[0], "age_seconds": int(age),
+            })
+    return zombies
+
+
+def _notify(session: str, branch: str, command: str) -> None:
+    """Alert on a reaped zombie session (#739 + #743).
+
+    Always posts a portal toast, so the reap is visible in-band rather than
+    only in an email the human has to notice and forward. When the session
+    has a recorded parent (``created_by`` in its metadata — set at
+    ``agentwire new`` time, see ``_record_session_creator``), the crash is
+    ALSO escalated there via the msg inbox (drained by the same watchdog that
+    runs this reap) — a worktree worker's crash reaches its orchestrator, not
+    just the owner's inbox. Owner email — the reused Resend wiring, mirrors
+    ``dispatch._notify_dispatch_timeout`` — is strictly the fallback for a
+    session with no recorded parent (the genuine root/scheduler-dispatch
+    case #739 originally covered). Each channel is independently
+    best-effort; this must never raise into the caller.
+    """
+    text = (
+        f"agentwire: reaped zombie scheduler session `{session}` (branch "
+        f"`{branch}`) — launch crashed at a bare shell (`{command}`) before "
+        "the agent started."
+    )
+
+    try:
+        from ..core import _post_desktop_notification
+        _post_desktop_notification(text, session=session, priority="high")
+    except Exception:
+        pass
+
+    parent = None
+    try:
+        from ..core import load_session_metadata
+        parent = load_session_metadata(session).get("created_by") or None
+    except Exception:
+        parent = None
+
+    if parent:
+        try:
+            from ..inbox import enqueue
+            enqueue(parent, text, kind="escalation", sender="agentwire")
+        except Exception:
+            pass
+        return
+
+    try:
+        import socket
+
+        from ..channels.email import send_email
+        send_email(
+            subject=f"[agentwire] reaped zombie scheduler session: {session}",
+            body=(
+                f"Scheduler dispatch session `{session}` (branch `{branch}`) "
+                f"on `{socket.gethostname()}` never reached its agent — the "
+                f"pane was stuck at a bare shell (`{command}`), the #739 "
+                "failure mode where the worktree launch crashes before "
+                "`claude` starts (e.g. a missing worktree directory). The "
+                "watchdog killed the session so it can't linger.\n\n"
+                "Check the scheduler events log for the originating "
+                "dispatch failure."
+            ),
+        )
+    except Exception:
+        pass
+
+
+def reap() -> dict:
+    """Kill every detected zombie session, logging + emailing each one."""
+    from agentwire import scheduler as _sched
+
+    killed = []
+    for z in scan():
+        _sched._kill_session(z["session"])
+        _sched._log_event("zombie_session_reaped", session=z["session"],
+                          branch=z["branch"], command=z["command"],
+                          age_seconds=z["age_seconds"])
+        _notify(z["session"], z["branch"], z["command"])
+        killed.append(z["session"])
+    return {"killed": killed}
+
+
+def tick() -> dict:
+    """Watchdog stage entry point — same ``{"killed": [...]}`` shape as ``reap()``."""
+    return reap()