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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.60.0
+Version: 1.61.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.61.0}/agentwire/__init__.py

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

{agentwire_dev-1.60.0 → agentwire_dev-1.61.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:
@@ -847,6 +857,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 +915,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 +926,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 +941,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.61.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.61.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.61.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.61.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()

{agentwire_dev-1.60.0 → agentwire_dev-1.61.0}/agentwire/session_cli.py

@@ -402,7 +402,17 @@ def cmd_new(args) -> int:
                 return _output_result(False, json_mode, hint)
 
     if not session_path.exists():
-        if args.force or path:
+        if branch:
+            # #739: a worktree session's path is only ever meant to come from
+            # `_spawn_worktree`/`ensure_worktree` above. Reaching here with it
+            # still missing means that creation silently didn't happen (or
+            # the dir vanished right after) — mkdir-ing an empty placeholder
+            # would launch the agent into a directory with no git checkout at
+            # all. Fail loud instead of returning a `path` that doesn't back
+            # a real worktree.
+            return _output_result(False, json_mode,
+                                   f"Worktree path does not exist after creation: {session_path}")
+        elif args.force or path:
             # Auto-create directory with -f flag or when custom path explicitly provided
             session_path.mkdir(parents=True, exist_ok=True)
         else:
@@ -445,14 +455,51 @@ def cmd_new(args) -> int:
             # Kind default posture (no global default-role lookup).
             posture, _ = _resolve_posture_from_args(args)
 
+    # Record the creating session as parent for prompt routing. --created-by
+    # overrides (including '' to opt out); otherwise default to the caller
+    # ONLY when the new session is in the caller's own project — a
+    # cross-project spawn gets its own root instead of flattening into the
+    # caller's subtree (#715). --caller-session is the candidate caller for
+    # that check (MCP forwards it; direct CLI use falls back to the current
+    # tmux session). Resolved before building the agent env (#743 needs the
+    # real parent, if any, in AGENTWIRE_CREATED_BY BEFORE `tmux new-session
+    # -e` fires) and before seeding so a failed seed can name its sender.
+    #
+    # Joint default with role (#716): an EXPLICITLY requested orchestrator
+    # roots by default instead — a durable orchestrator shouldn't answer to
+    # whoever happened to spawn it. Gated on the explicit --kind flag (not
+    # the resolved `kind`, which is "orchestrator" by default for any
+    # branchless name) so the ubiquitous plain `agentwire new` case keeps
+    # its existing same-project-inherit behavior untouched. This is the one
+    # place this default lives — cmd_worktree's `_launch_session` forwards
+    # its own `--kind` straight through as `kind` here, so `agentwire
+    # worktree --kind orchestrator` / `agentwire orchestrator` compose with
+    # it for free.
+    created_by = getattr(args, 'created_by', None)
+    caller = None
+    if created_by is None and getattr(args, 'kind', None) == 'orchestrator':
+        created_by = ''
+    elif created_by is None:
+        caller = getattr(args, 'caller_session', None) or pane_manager.get_current_session()
+        created_by = resolve_default_created_by(caller, session_path)
+
     # Build agent command
     model_override = getattr(args, 'model', None)
     agent = build_agent_command(posture, roles if roles else None, model=model_override)
     agent.env.update(parse_env_args(getattr(args, 'env', None)))
-    _set_session_name_env(agent, session_name)
+    _set_session_name_env(agent, session_name, created_by=created_by)
 
     agent_cmd = agent.command
 
+    # #739: re-verify right before launch — closes the window between the
+    # earlier worktree-creation check and this point (shared-dir probe,
+    # posture/agent-command resolution) during which an external actor could
+    # still remove the directory. `agentwire new --json` must never report
+    # success with a `path` that doesn't exist on disk.
+    if not session_path.exists():
+        return _output_result(False, json_mode,
+                               f"Session path vanished before launch: {session_path}")
+
     # Create new tmux session with env vars injected at creation time, cd
     # into place, and start the agent (skipped when bare).
     _launch_tmux_session(session_name, session_path, agent.env, agent_cmd)
@@ -479,33 +526,6 @@ def cmd_new(args) -> int:
             )
         save_project_config(project_config, session_path)
 
-    # Record the creating session as parent for prompt routing. --created-by
-    # overrides (including '' to opt out); otherwise default to the caller
-    # ONLY when the new session is in the caller's own project — a
-    # cross-project spawn gets its own root instead of flattening into the
-    # caller's subtree (#715). --caller-session is the candidate caller for
-    # that check (MCP forwards it; direct CLI use falls back to the current
-    # tmux session). Resolved before seeding so a failed seed can name its
-    # sender.
-    #
-    # Joint default with role (#716): an EXPLICITLY requested orchestrator
-    # roots by default instead — a durable orchestrator shouldn't answer to
-    # whoever happened to spawn it. Gated on the explicit --kind flag (not
-    # the resolved `kind`, which is "orchestrator" by default for any
-    # branchless name) so the ubiquitous plain `agentwire new` case keeps
-    # its existing same-project-inherit behavior untouched. This is the one
-    # place this default lives — cmd_worktree's `_launch_session` forwards
-    # its own `--kind` straight through as `kind` here, so `agentwire
-    # worktree --kind orchestrator` / `agentwire orchestrator` compose with
-    # it for free.
-    created_by = getattr(args, 'created_by', None)
-    caller = None
-    if created_by is None and getattr(args, 'kind', None) == 'orchestrator':
-        created_by = ''
-    elif created_by is None:
-        caller = getattr(args, 'caller_session', None) or pane_manager.get_current_session()
-        created_by = resolve_default_created_by(caller, session_path)
-
     # Deliver the first message once the agent is ready (verified paste).
     # Delivery failure doesn't fail the command — the session exists — but it
     # must be LOUD (#695): clear the partial paste out of the box and fall
@@ -787,6 +807,24 @@ def cmd_recreate(args) -> int:
     return 0
 
 
+def _resolve_project_arg(project_arg: str, projects_dir: Path) -> Path:
+    """Resolve ``--project`` to an absolute repo path, independent of cwd.
+
+    An explicit path (absolute, or one that actually exists relative to cwd —
+    ``.``, ``../sibling``) is honored as given. Otherwise ``project_arg`` is
+    treated as a bare project NAME and resolved against the configured
+    projects dir, the same way ``cmd_new`` resolves a bare project name from
+    ``project/branch`` session syntax — never by blindly joining it onto
+    whatever directory the command happens to run from. That naive join is
+    what path-doubled ``<cwd>/<project>`` into a nonexistent dir when cwd was
+    already the project's own directory (#740).
+    """
+    expanded = Path(project_arg).expanduser()
+    if expanded.is_absolute() or expanded.exists():
+        return expanded.resolve()
+    return (projects_dir / project_arg).resolve()
+
+
 def cmd_worktree(args) -> int:
     """Create a git worktree + agentwire session in one command.
 
@@ -816,13 +854,14 @@ def cmd_worktree(args) -> int:
     ref = getattr(args, 'ref', None)
 
     from .config import load_config as load_config_typed
-    wt_config = load_config_typed().worktree
+    full_config = load_config_typed()
+    wt_config = full_config.worktree
 
     # Resolve the repo: explicit --project → config default → git root of cwd
     # (so a worktree session can be spawned from any subdir of a monorepo).
     project_arg = getattr(args, 'project', None)
     if project_arg:
-        project_base = Path(project_arg).expanduser().resolve()
+        project_base = _resolve_project_arg(project_arg, full_config.projects.dir)
     elif wt_config.default_project:
         project_base = Path(wt_config.default_project).expanduser().resolve()
     else:
@@ -846,7 +885,7 @@ def cmd_worktree(args) -> int:
         return _worktree_list(args, project_path, json_mode)
     if getattr(args, 'watch', False):
         return _worktree_watch(args, project_path, json_mode)
-    if getattr(args, 'prune', False):
+    if getattr(args, 'prune', False) or getattr(args, 'gc_merged', False):
         return _worktree_prune(args, project_path, worktree_dir, json_mode)
     if getattr(args, 'dangling', False):
         return _worktree_dangling(args, project_path, json_mode)
@@ -1233,6 +1272,11 @@ def _worktree_prune(args, project_path: Path, worktree_dir: Path, json_mode: boo
     branch is already merged" sweep from #717. Off by default: this command
     is normally a safe, read-mostly cleanup and shouldn't kill a live,
     in-flight session just because its branch happens to look merged.
+
+    ``--gc-merged`` alone (no ``--prune``) also dispatches here and runs the
+    same sweep — cmd_worktree treats it as implying --prune (#740), so
+    ``--help`` and behavior agree instead of --gc-merged falling through to
+    the usage error.
     """
     removed = []
     gc_merged_out = []
@@ -1443,7 +1487,7 @@ def _teardown_entry(
     project_path: Path, worktree_dir: Path, session_name: str, worktree_path: Path,
     branch: str | None, base: str | None, *, keep_branch: bool = False, force_branch: bool = False,
 ) -> dict:
-    """Core atomic teardown: kill session, force-remove the worktree + prune,
+    """Core atomic teardown: force-remove the worktree + prune, kill session,
     unregister, best-effort branch cleanup. Shared by --remove and
     --prune --gc-merged so both paths go through the exact same steps (#717).
 
@@ -1451,12 +1495,13 @@ def _teardown_entry(
     `git worktree remove --force` can't clear it, this fails LOUDLY
     (success: False) and leaves the registry entry in place, instead of
     silently "unregistering" an orphan.
-    """
-    killed = False
-    if tmux_session_exists(session_name):
-        subprocess.run(["tmux", "kill-session", "-t", session_name], capture_output=True)
-        killed = True
 
+    The worktree removal is attempted BEFORE the session is killed, and the
+    session is only killed once removal is confirmed — never the reverse.
+    Killing first would leave a live session's worktree+branch orphaned on
+    disk with no session left to notice, on any removal failure (bad
+    project_path, a stuck worktree, ...) (#740).
+    """
     # Force-remove the git worktree, then prune admin files either way.
     _, remove_error = remove_worktree(project_path, worktree_path, force=True)
     subprocess.run(["git", "-C", str(project_path), "worktree", "prune"], capture_output=True)
@@ -1464,7 +1509,12 @@ def _teardown_entry(
     if worktree_path.exists():
         reason = remove_error or "worktree directory still present after `git worktree remove --force`"
         return {"success": False, "session": session_name, "path": str(worktree_path),
-                "killed": killed, "worktree_removed": False, "error": reason}
+                "killed": False, "worktree_removed": False, "error": reason}
+
+    killed = False
+    if tmux_session_exists(session_name):
+        subprocess.run(["tmux", "kill-session", "-t", session_name], capture_output=True)
+        killed = True
 
     # Removing a project's last worktree also removes the now-empty
     # ~/worktrees/<project>/ dir.
@@ -1490,7 +1540,7 @@ def _teardown_entry(
 
 
 def _worktree_remove(args, project_path: Path, worktree_dir: Path, json_mode: bool) -> int:
-    """Teardown: kill the session, force-remove the worktree + prune, unregister,
+    """Teardown: force-remove the worktree + prune, kill the session, unregister,
     and (best-effort) delete the branch — one atomic call (#717)."""
     name = getattr(args, 'name', None)
     if not name:
@@ -1960,11 +2010,11 @@ def register_session_parser(subparsers) -> None:
                                  "parent — a PR nobody is positioned to review/merge (--all for every "
                                  "repo). Distinct from --list's 'orphan' state (dead session, disk "
                                  "remnant) — this flags a LIVE session no one is watching.")
-        parser.add_argument("--remove", action="store_true", help="Atomic teardown: kill the session, force-remove the worktree, delete the branch once merged, and unregister (cleanup/recovery)")
+        parser.add_argument("--remove", action="store_true", help="Atomic teardown: force-remove the worktree, kill the session, delete the branch once merged, and unregister (cleanup/recovery)")
         parser.add_argument("--keep-branch", action="store_true", help="With --remove: skip branch cleanup entirely (default: best-effort delete once confirmed merged)")
         parser.add_argument("--force-delete-branch", action="store_true", help="With --remove: delete the branch (local + remote) even if not confirmed merged")
         parser.add_argument("--prune", action="store_true", help="Drop registry entries whose worktree is gone + git worktree prune")
-        parser.add_argument("--gc-merged", action="store_true", help="With --prune: also tear down (session/worktree/branch) any registered entry whose branch is confirmed merged")
+        parser.add_argument("--gc-merged", action="store_true", help="Tear down (session/worktree/branch) any registered entry whose branch is confirmed merged; implies --prune (runs standalone too)")
         parser.add_argument("--all", action="store_true", help="With --list/--dangling: include worktree sessions across every repo")
         _add_posture_flag(parser)
         parser.add_argument("--roles", help="Comma-separated roles, STACKED on top of the always-present worker etiquette (kind=orchestrator: REPLACES the default persona instead)")