aiur-cli 0.0.3 → 0.0.4

package/README.md

@@ -58,6 +58,7 @@ to the issues you want worked and run `aiur`.
 | `aiur` | Start the workflow in the foreground (local-only bind) |
 | `aiur --bg` | Start a headless BEAM in one detached tmux lifetime session |
 | `aiur status` | Show active agents and their state |
+| `aiur alerts [--needs-attention]` | Show structured alert feed JSON lines |
 | `aiur pause <id…>` / `resume <id…>` | Pause or resume agents by issue ID |
 | `aiur stop` | Stop the running session |
 

package/bin/aiur.js

@@ -162,8 +162,9 @@ function ensureTmux() {
   }
 }
 
-// True only when the pinned opencode is on PATH; a wrong version (e.g. 1.17.x,
-// which broke the panes) must be replaced, so presence alone isn't enough.
+// True only when the pinned opencode is on PATH; a wrong (e.g. newer,
+// unverified) version must be replaced with the pin, so presence alone
+// isn't enough.
 function opencodeMatchesPin() {
   const result = safeSpawn("opencode", ["--version"], { encoding: "utf8" });
   return !result.error && result.status === 0 && (result.stdout || "").trim() === opencodeVersion();

package/libexec/aiur-engine.sh

@@ -44,23 +44,67 @@ engine_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # --- distribution identity (per-instance: keyed by the aiur project root) -----
 
-# The aiur project root (dir holding the active config). AIUR_REPO_ROOT (set by
-# the dev shim) wins; otherwise walk up from $PWD. Empty when run outside a project.
+# The aiur project root used to key this instance. AIUR_REPO_ROOT (set by the dev
+# shim) wins. Otherwise walk up from $PWD to the first dir holding a REPO-LOCAL
+# config — but the walk STOPS at $HOME: the global config at ~/.aiur/config (legacy
+# ~/.aiurconfig) is not a repo root, and treating it as one would collapse every
+# project under $HOME onto one key (#443). When no repo-local config is found, the
+# BEAM serves this run via the global config (mirroring its discovery order in
+# src/lib/aiur/workflow.ex) — or via none — and in both cases the project being
+# served is the cwd, so we key by realpath($PWD). That gives each global-config
+# project a distinct identity instead of an empty key (legacy aiur-$USER@…) or $HOME.
+#
+# Caveat: a global-config run's key is cwd-derived (there is no repo root to
+# converge on), so control commands (status/pause/stop) must be run from the SAME
+# directory the run was launched from. A repo with a repo-local .aiur/config keeps
+# the walk-up, so its control commands still resolve from any subdir.
 aiur_project_root() {
   if [ -n "${AIUR_REPO_ROOT:-}" ]; then printf '%s' "$AIUR_REPO_ROOT"; return; fi
-  local d="$PWD"
-  while [ -n "$d" ] && [ "$d" != "/" ]; do
+
+  # Canonicalize $PWD and $HOME so the home-boundary test below holds even when
+  # either is reached through a symlink.
+  local pwd_real home_real
+  pwd_real="$(pwd -P 2>/dev/null || printf '%s' "$PWD")"
+  # ${HOME:-} (not bare $HOME) so an unset HOME under `set -u` can't abort the
+  # script here; an empty home_real simply disables the boundary (walk to /).
+  home_real="$(cd "${HOME:-}" 2>/dev/null && pwd -P || printf '%s' "${HOME:-}")"
+
+  local d="$pwd_real"
+  while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "$home_real" ]; do
     if [ -f "$d/.aiur/config" ] || [ -f "$d/.aiurconfig" ]; then
       printf '%s' "$d"
       return
     fi
     d="$(dirname "$d")"
   done
+
+  printf '%s' "$pwd_real"
+}
+
+aiur_project_root_source() {
+  if [ -n "${AIUR_REPO_ROOT:-}" ]; then printf 'env'; return; fi
+
+  local pwd_real home_real
+  pwd_real="$(pwd -P 2>/dev/null || printf '%s' "$PWD")"
+  home_real="$(cd "${HOME:-}" 2>/dev/null && pwd -P || printf '%s' "${HOME:-}")"
+
+  local d="$pwd_real"
+  while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "$home_real" ]; do
+    if [ -f "$d/.aiur/config" ] || [ -f "$d/.aiurconfig" ]; then
+      printf 'repo'
+      return
+    fi
+    d="$(dirname "$d")"
+  done
+
+  printf 'cwd'
 }
 
 # Short, stable, node-name-legal (lowercase hex) key for the project root, so two
 # aiur instances for the same user get distinct node/session/socket names and can't
-# reap each other. Empty when no project resolves (names fall back to the legacy form).
+# reap each other. Any real cwd now resolves a key (global-config runs key by
+# realpath($PWD), #443); only a degenerate unreadable cwd yields empty, falling back
+# to the legacy un-keyed name.
 aiur_instance_key() {
   local root
   root="$(aiur_project_root)"
@@ -74,6 +118,8 @@ aiur_instance_key() {
 
 aiur_resolve_identity() {
   local config_home="${XDG_CONFIG_HOME:-$HOME/.config}"
+  AIUR_PROJECT_ROOT="$(aiur_project_root)"
+  AIUR_PROJECT_ROOT_SOURCE="$(aiur_project_root_source)"
 
   : "${AIUR_BG_STATE_DIR:=$config_home/aiur}"
   : "${AIUR_COOKIE_FILE:=$AIUR_BG_STATE_DIR/cookie}"
@@ -87,7 +133,8 @@ aiur_resolve_identity() {
   : "${AIUR_RELEASE_NODE:=aiur-${USER}${AIUR_INSTANCE_KEY:+-$AIUR_INSTANCE_KEY}@127.0.0.1}"
 
   export AIUR_BG_STATE_DIR AIUR_COOKIE_FILE AIUR_SESSION_PREFIX \
-    AIUR_PROFILES_FILE AIUR_RELEASE_NODE AIUR_INSTANCE_KEY
+    AIUR_PROFILES_FILE AIUR_RELEASE_NODE AIUR_INSTANCE_KEY \
+    AIUR_PROJECT_ROOT AIUR_PROJECT_ROOT_SOURCE
 }
 
 aiur_print_identity() {
@@ -98,6 +145,8 @@ aiur_print_identity() {
   printf 'AIUR_PROFILES_FILE=%s\n' "$AIUR_PROFILES_FILE"
   printf 'AIUR_RELEASE_NODE=%s\n' "$AIUR_RELEASE_NODE"
   printf 'AIUR_INSTANCE_KEY=%s\n' "$AIUR_INSTANCE_KEY"
+  printf 'AIUR_PROJECT_ROOT=%s\n' "$AIUR_PROJECT_ROOT"
+  printf 'AIUR_PROJECT_ROOT_SOURCE=%s\n' "$AIUR_PROJECT_ROOT_SOURCE"
   printf 'AIUR_COOKIE_FILE=%s\n' "$AIUR_COOKIE_FILE"
 }
 
@@ -224,9 +273,12 @@ Usage: aiur [--interactive] [--max-agents <n>] [--logs-root <path>] [--port <por
        aiur stop             stop the running session
        aiur status           show agent status
        aiur agents           show each agent's state + current activity
+       aiur alerts [--needs-attention]  show structured alert feed
+       aiur watch [--full|--changes] [--interval <secs>]  server-side status board
        aiur set max-agents <n>   change the concurrent-agent cap at runtime
        aiur pause <ids|--all> | resume <ids|--all>
        aiur message <id> <text>  send operator text to a running agent
+       aiur cleanup-stale [--dry-run]  list/reap stale manual-smoke leftovers
        aiur --version
 EOF
 }
@@ -355,6 +407,8 @@ run_session() {
   conf="$(resolve_tmux_conf)"
   [ -f "$conf" ] || die "tmux conf not found at $conf"
 
+  preflight_stale_manual_smoke
+
   mkdir -p "$AIUR_BG_STATE_DIR"
   printf '%s\n' "$session" >"$AIUR_BG_STATE_DIR/state"
   export AIUR_TMUX_SESSION="$session"
@@ -372,6 +426,11 @@ run_session() {
   export AIUR_AGENT_TMPFILE="${session_root}/aiur-${$}-agents"
   : >"$AIUR_AGENT_TMPFILE"
 
+  # Workspace-root handoff for the shell cwd-sweep backstop. The BEAM writes the
+  # resolved Aiur.Config.workspace_root() here after config loads.
+  export AIUR_WORKSPACE_ROOT_FILE="${session_root}/aiur-${$}-workspace-root"
+  : >"$AIUR_WORKSPACE_ROOT_FILE"
+
   # Background runs persist under a known run log dir so (a) the BEAM-death
   # watchdog, which outlives the BEAM, can drop a crash record next to aiur.log,
   # and (b) the post-start boot capture is not lost to /tmp when the launcher
@@ -406,8 +465,8 @@ run_session() {
     for v in AIUR_RELEASE_DIR AIUR_ARGV_FILE RELEASE_DISTRIBUTION RELEASE_NODE \
       RELEASE_COOKIE ERL_AFLAGS ERL_EPMD_ADDRESS AIUR_NODE AIUR_ERLANG_COOKIE \
       AIUR_TMUX_SESSION AIUR_TMUX_SOCKET AIUR_TMUX_CONF AIUR_BIN \
-      AIUR_SESSION_TMPFILE AIUR_AGENT_TMPFILE ELIXIR_ERL_OPTIONS AIUR_LOGS_ROOT \
-      AIUR_OPENCODE_BRIDGE_PORT AIUR_DEBUG; do
+      AIUR_SESSION_TMPFILE AIUR_AGENT_TMPFILE AIUR_WORKSPACE_ROOT_FILE \
+      ELIXIR_ERL_OPTIONS AIUR_LOGS_ROOT AIUR_OPENCODE_BRIDGE_PORT AIUR_DEBUG; do
       if [ -n "${!v:-}" ]; then printf 'export %s=%q\n' "$v" "${!v}"; fi
     done
     printf 'capture=%q\n' "$startup_capture"
@@ -424,7 +483,8 @@ run_session() {
     _session_socket="$socket" _session_name="$session" _session_conf="$conf" \
       _session_tmpfile="$AIUR_SESSION_TMPFILE" _session_capture="$startup_capture" \
       _session_argv="$argv_file" _session_release="$release_dir" _session_tmux="$tmux_bin" \
-      _session_node="$AIUR_RELEASE_NODE" _session_pidfile="$AIUR_AGENT_TMPFILE"
+      _session_node="$AIUR_RELEASE_NODE" _session_pidfile="$AIUR_AGENT_TMPFILE" \
+      _session_workspace_root_file="$AIUR_WORKSPACE_ROOT_FILE"
     install_foreground_traps
   fi
 
@@ -433,10 +493,11 @@ run_session() {
   # session whose BEAM/control plane is gone should be reclaimed before retry.
   if [ "$mode" = "background" ] && "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null; then
     if [ "$(probe_control_liveness)" = "up" ]; then
+      write_aiur_instance_record "$session" "$socket"
       echo "aiur is already running in the background (tmux session ${session})." >&2
       echo "Use: aiur status   # inspect agents" >&2
       echo "Use: aiur stop     # stop it before starting a fresh session" >&2
-      rm -f "$startup_capture" "$argv_file" "$launcher" "$AIUR_SESSION_TMPFILE" "$AIUR_AGENT_TMPFILE" 2>/dev/null || true
+      rm -f "$startup_capture" "$argv_file" "$launcher" "$AIUR_SESSION_TMPFILE" "$AIUR_AGENT_TMPFILE" "$AIUR_WORKSPACE_ROOT_FILE" 2>/dev/null || true
       return 0
     fi
 
@@ -474,7 +535,7 @@ run_session() {
     -x "${COLUMNS:-200}" -y "${LINES:-50}" "$inner_cmd"; then
     echo "❌ aiur failed to start; captured output:" >&2
     tail -n 30 "$startup_capture" 2>/dev/null | sed 's/^/  /' >&2 || true
-    rm -f "$startup_capture" "$argv_file" "$launcher" "$AIUR_SESSION_TMPFILE" "$AIUR_AGENT_TMPFILE" 2>/dev/null || true
+    rm -f "$startup_capture" "$argv_file" "$launcher" "$AIUR_SESSION_TMPFILE" "$AIUR_AGENT_TMPFILE" "$AIUR_WORKSPACE_ROOT_FILE" 2>/dev/null || true
     exit 1
   fi
 
@@ -483,11 +544,11 @@ run_session() {
   # chat panes it opens. Best-effort — a missing title just shows the default.
   "$tmux_bin" -L "$socket" -f "$conf" select-pane -t "$session" -T "AIUR Agents" 2>/dev/null || true
 
-  # Grace window: surface a boot crash instead of attaching to nothing. For
-  # headless background runs, also prove the control plane can answer before
-  # claiming startup succeeded; control commands depend on that RPC path.
-  local require_control=0
-  [ "$mode" = "background" ] && require_control=1
+  # Grace window: surface a boot crash instead of attaching to nothing. Prove
+  # the control plane can answer before declaring startup usable: background
+  # control commands depend on that RPC path, and foreground automation must not
+  # treat a pre-TUI application crash as a successful `tmux attach`.
+  local require_control=1
   if ! wait_for_session_startup "$tmux_bin" "$socket" "$conf" "$session" "$startup_capture" "$require_control"; then
     if [ "$mode" = "background" ]; then
       "$tmux_bin" -L "$socket" -f "$conf" kill-session -t "$session" 2>/dev/null || true
@@ -495,10 +556,16 @@ run_session() {
       kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
     fi
     [ "$mode" = "foreground" ] && return 1
-    rm -f "$startup_capture" "$argv_file" "$launcher" "$AIUR_SESSION_TMPFILE" "$AIUR_AGENT_TMPFILE" 2>/dev/null || true
+    rm -f "$startup_capture" "$argv_file" "$launcher" "$AIUR_SESSION_TMPFILE" "$AIUR_AGENT_TMPFILE" "$AIUR_WORKSPACE_ROOT_FILE" 2>/dev/null || true
     exit 1
   fi
 
+  write_aiur_instance_record "$session" "$socket"
+
+  if [ "$mode" = "foreground" ]; then
+    echo "aiur foreground tmux socket ${socket}, session ${session}" >&2
+  fi
+
   if [ "$mode" = "background" ]; then
     # Fresh run: drop any stale crash/stop state from a prior dead instance so
     # `status` doesn't report a phantom orphan and the watchdog starts clean.
@@ -508,9 +575,9 @@ run_session() {
     background_watchdog_pid="$(start_beam_death_watchdog \
       "-name ${AIUR_RELEASE_NODE}" "$socket" "$AIUR_AGENT_TMPFILE" 1 1 \
       "$AIUR_RELEASE_NODE" "${AIUR_LOGS_ROOT:-}" \
-      "$(aiur_stop_sentinel_path)" "$(aiur_crash_marker_path)")"
+      "$(aiur_stop_sentinel_path)" "$(aiur_crash_marker_path)" "$AIUR_WORKSPACE_ROOT_FILE")"
     disown "$background_watchdog_pid" 2>/dev/null || true
-    echo "aiur started in the background (tmux session ${session}). Attach with: aiur" >&2
+    echo "aiur started in the background (tmux socket ${socket}, session ${session}). Attach with: aiur" >&2
     # Keep $startup_capture (boot.out.log) for the run's lifetime; only the
     # transient argv file is no longer needed.
     rm -f "$argv_file" 2>/dev/null || true
@@ -524,11 +591,19 @@ run_session() {
   # the session, and unblocks the attach. It polls the node name rather than a
   # captured pid, so another Aiur instance from the same release cannot hold it open.
   _session_watchdog_pid="$(start_beam_death_watchdog \
-    "-name ${AIUR_RELEASE_NODE}" "$socket" "$AIUR_AGENT_TMPFILE" 1)"
+    "-name ${AIUR_RELEASE_NODE}" "$socket" "$AIUR_AGENT_TMPFILE" 1 0 \
+    "" "" "" "" "$AIUR_WORKSPACE_ROOT_FILE")"
 
   # Foreground: attach the UI. Do not exec — that would drop the teardown trap.
-  "$tmux_bin" -L "$socket" -f "$conf" attach -t "$session" 2> >(grep -v -F "[server exited]" >&2)
-  return $?
+  # Avoid process substitution here: some sandboxed non-TTY launchers reject
+  # opening /dev/fd/* during the real manual-test wrapper path.
+  local attach_stderr attach_code
+  attach_stderr="$(mktemp "${TMPDIR:-/tmp}/aiur-attach-stderr.XXXXXX")"
+  "$tmux_bin" -L "$socket" -f "$conf" attach -t "$session" 2>"$attach_stderr"
+  attach_code=$?
+  grep -v -F "[server exited]" "$attach_stderr" >&2 || true
+  rm -f "$attach_stderr" 2>/dev/null || true
+  return "$attach_code"
 }
 
 resolve_tmux_conf() {
@@ -563,6 +638,237 @@ kill_beams_matching() {
   for pid in $pids; do kill -KILL "$pid" 2>/dev/null || true; done
 }
 
+pid_owner() {
+  ps -p "$1" -o user= 2>/dev/null | awk '{print $1}' || true
+}
+
+pid_command() {
+  ps -p "$1" -o command= 2>/dev/null || true
+}
+
+pid_ppid() {
+  ps -p "$1" -o ppid= 2>/dev/null | awk '{print $1}' || true
+}
+
+pid_cwd() {
+  local pid="$1" cwd
+  if [ -e "/proc/$pid/cwd" ]; then
+    readlink "/proc/$pid/cwd" 2>/dev/null || true
+    return 0
+  fi
+  if command -v lsof >/dev/null 2>&1; then
+    cwd="$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p' | head -n 1 || true)"
+    [ -n "$cwd" ] && printf '%s\n' "$cwd"
+  fi
+}
+
+kill_pid_with_escalation() {
+  local pid="$1" waited=0
+  [ -n "$pid" ] || return 0
+  kill -TERM "$pid" 2>/dev/null || true
+  while [ "$waited" -lt 20 ]; do
+    kill -0 "$pid" 2>/dev/null || return 0
+    sleep 0.1
+    waited=$((waited + 1))
+  done
+  kill -KILL "$pid" 2>/dev/null || true
+}
+
+aiur_node_from_command() {
+  local cmd="$1" node
+  node="$(printf '%s\n' "$cmd" | sed -n "s/.*--name[[:space:]]\\(aiur-${USER}[-A-Za-z0-9_]*@127\\.0\\.0\\.1\\).*/\\1/p" | head -n 1)"
+  [ -n "$node" ] && printf '%s\n' "$node"
+}
+
+aiur_release_root_from_command() {
+  local cmd="$1"
+  if [[ "$cmd" =~ --boot-var[[:space:]]+RELEASE_LIB[[:space:]]+([^[:space:]]+)/lib ]]; then
+    printf '%s\n' "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  if [[ "$cmd" =~ ([^[:space:]]*/src/_build/dev/rel/aiur)/releases/ ]]; then
+    printf '%s\n' "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  if [[ "$cmd" =~ ([^[:space:]]*/release)/releases/ ]]; then
+    printf '%s\n' "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  return 1
+}
+
+workspace_root_from_aiur_release_root() {
+  local release_root="${1%/}"
+  case "$release_root" in
+    */src/_build/dev/rel/aiur)
+      printf '%s\n' "${release_root%/src/_build/dev/rel/aiur}"
+      ;;
+    *)
+      printf '%s\n' "$release_root"
+      ;;
+  esac
+}
+
+aiur_node_tmux_session_alive() {
+  local node="$1" short tmux_bin
+  short="${node%@*}"
+  tmux_bin="$(command -v tmux || true)"
+  [ -n "$tmux_bin" ] || return 1
+  "$tmux_bin" -L "$short" has-session -t "${short}-default" 2>/dev/null
+}
+
+stale_manual_smoke_beam_inventory() {
+  local pid cmd node release_root workspace_root owner
+  aiur_resolve_identity
+
+  for pid in $(pgrep -f -- "beam\\.smp.*--name aiur-${USER}.*@127\\.0\\.0\\.1" 2>/dev/null || true); do
+    [ -n "$pid" ] || continue
+    owner="$(pid_owner "$pid")"
+    [ "$owner" = "$USER" ] || continue
+
+    cmd="$(pid_command "$pid")"
+    node="$(aiur_node_from_command "$cmd")"
+    [ -n "$node" ] || continue
+
+    release_root="$(aiur_release_root_from_command "$cmd" || true)"
+    [ -n "$release_root" ] || continue
+    workspace_root="$(workspace_root_from_aiur_release_root "$release_root")"
+
+    # Scope this broad cleanup to stale issue/manual-smoke workspaces. The
+    # current instance cleanup path handles the active daemon's own node.
+    case "$workspace_root" in
+      */aiur-workspaces/*) ;;
+      *) continue ;;
+    esac
+
+    # A matching live aiur tmux session means this node may still be in use.
+    aiur_node_tmux_session_alive "$node" && continue
+
+    printf '%s\t%s\t%s\t%s\n' "$pid" "$node" "$workspace_root" "$release_root"
+  done
+}
+
+manual_smoke_wrapper_tmux_sockets() {
+  local tmux_bin sockdir path name panes current pane_path start manual_context all_sleep
+  tmux_bin="$(command -v tmux || true)"
+  [ -n "$tmux_bin" ] || return 0
+  sockdir="${TMUX_TMPDIR:-/tmp}/tmux-$(id -u)"
+  [ -d "$sockdir" ] || return 0
+
+  for path in "$sockdir"/*; do
+    [ -S "$path" ] || continue
+    name="${path##*/}"
+    case "$name" in
+      codex-driver-* | codex-aiur* | codex-[0-9]* | claude-driver*) ;;
+      *) continue ;;
+    esac
+    panes="$("$tmux_bin" -L "$name" list-panes -a -F '#{pane_current_command}	#{pane_current_path}	#{pane_start_command}' 2>/dev/null || true)"
+    [ -n "$panes" ] || continue
+    manual_context=0
+    all_sleep=1
+    while IFS=$'\t' read -r current pane_path start; do
+      case "$start" in
+        *aiurdev\ --test* | *scripts/aiurdev\ --test*) manual_context=1 ;;
+      esac
+      [ "$current" = "sleep" ] || all_sleep=0
+    done <<<"$panes"
+    [ "$manual_context" -eq 1 ] && [ "$all_sleep" -eq 1 ] && printf '%s\n' "$name"
+  done
+}
+
+orphaned_opencode_attach_inventory() {
+  local pid owner ppid cmd cwd
+  for pid in $(pgrep -f -- "opencode attach http://127\\.0\\.0\\.1:" 2>/dev/null || true); do
+    owner="$(pid_owner "$pid")"
+    [ "$owner" = "$USER" ] || continue
+    ppid="$(pid_ppid "$pid")"
+    [ "$ppid" = "1" ] || continue
+    cwd="$(pid_cwd "$pid")"
+    case "$cwd" in
+      */aiur-workspaces/*) ;;
+      *) continue ;;
+    esac
+    cmd="$(pid_command "$pid")"
+    case "$cmd" in
+      *"opencode attach http://127.0.0.1:"*) printf '%s\t%s\t%s\n' "$pid" "$cwd" "$cmd" ;;
+    esac
+  done
+}
+
+report_stale_manual_smoke() {
+  local found=0 pid node workspace_root release_root socket cwd cmd
+
+  while IFS=$'\t' read -r pid node workspace_root release_root; do
+    [ -n "$pid" ] || continue
+    if [ "$found" -eq 0 ]; then
+      echo "aiur: stale manual-smoke leftovers detected:" >&2
+      found=1
+    fi
+    echo "  BEAM pid=${pid} node=${node} workspace=${workspace_root} release=${release_root}" >&2
+  done < <(stale_manual_smoke_beam_inventory)
+
+  while IFS= read -r socket; do
+    [ -n "$socket" ] || continue
+    if [ "$found" -eq 0 ]; then
+      echo "aiur: stale manual-smoke leftovers detected:" >&2
+      found=1
+    fi
+    echo "  wrapper tmux socket=${socket}" >&2
+  done < <(manual_smoke_wrapper_tmux_sockets)
+
+  while IFS=$'\t' read -r pid cwd cmd; do
+    [ -n "$pid" ] || continue
+    if [ "$found" -eq 0 ]; then
+      echo "aiur: stale manual-smoke leftovers detected:" >&2
+      found=1
+    fi
+    echo "  orphan opencode attach pid=${pid} workspace=${cwd}" >&2
+  done < <(orphaned_opencode_attach_inventory)
+
+  if [ "$found" -eq 1 ]; then
+    echo "aiur: run 'aiur cleanup-stale' to TERM/KILL only these same-user Aiur leftovers." >&2
+  fi
+
+  return "$found"
+}
+
+preflight_stale_manual_smoke() {
+  report_stale_manual_smoke >/dev/null || true
+}
+
+reap_stale_manual_smoke() {
+  local include_wrappers="${1:-0}"
+  local pid node workspace_root release_root socket cwd cmd tmux_bin reaped=0
+
+  while IFS=$'\t' read -r pid node workspace_root release_root; do
+    [ -n "$pid" ] || continue
+    echo "aiur: reaping stale BEAM pid=${pid} node=${node} workspace=${workspace_root}" >&2
+    kill_pid_with_escalation "$pid"
+    reaped=$((reaped + 1))
+  done < <(stale_manual_smoke_beam_inventory)
+
+  tmux_bin="$(command -v tmux || true)"
+  if [ "$include_wrappers" = "1" ] && [ -n "$tmux_bin" ]; then
+    while IFS= read -r socket; do
+      [ -n "$socket" ] || continue
+      echo "aiur: reaping stale wrapper tmux socket=${socket}" >&2
+      "$tmux_bin" -L "$socket" kill-server 2>/dev/null || true
+      reaped=$((reaped + 1))
+    done < <(manual_smoke_wrapper_tmux_sockets)
+  fi
+
+  while IFS=$'\t' read -r pid cwd cmd; do
+    [ -n "$pid" ] || continue
+    echo "aiur: reaping orphan opencode attach pid=${pid}" >&2
+    kill_pid_with_escalation "$pid"
+    reaped=$((reaped + 1))
+  done < <(orphaned_opencode_attach_inventory)
+
+  if [ "$reaped" -eq 0 ]; then
+    echo "aiur: no stale manual-smoke leftovers found" >&2
+  fi
+}
+
 # Echo $1 and every descendant pid, depth-first. Mac-safe (`pgrep -P`, no
 # /proc), mirroring Aiur.RemoteControl.collect_descendants so the launcher reaps
 # the same tree the BEAM-side reaper would. The recorded agent pid is a bash
@@ -643,6 +949,34 @@ aiur_state_slug() {
   printf '%s' "${AIUR_RELEASE_NODE:-aiur}" | tr -c 'A-Za-z0-9._-' '_'
 }
 
+aiur_instances_dir() {
+  printf '%s/instances' "${AIUR_BG_STATE_DIR:?}"
+}
+
+aiur_instance_record_path() {
+  printf '%s/%s.instance' "$(aiur_instances_dir)" "$(aiur_state_slug)"
+}
+
+write_aiur_instance_record() {
+  local session="$1" socket="$2" record_dir record tmp root
+  record_dir="$(aiur_instances_dir)"
+  record="$(aiur_instance_record_path)"
+  root="$(canonical_workspace_root "${AIUR_PROJECT_ROOT:-}")"
+  mkdir -p "$record_dir" 2>/dev/null || return 0
+  tmp="$(mktemp "$record_dir/.${AIUR_INSTANCE_KEY:-aiur}.XXXXXX" 2>/dev/null)" || return 0
+  {
+    printf 'AIUR_RECORD_NODE=%q\n' "$AIUR_RELEASE_NODE"
+    printf 'AIUR_RECORD_INSTANCE_KEY=%q\n' "$AIUR_INSTANCE_KEY"
+    printf 'AIUR_RECORD_SESSION=%q\n' "$session"
+    printf 'AIUR_RECORD_SOCKET=%q\n' "$socket"
+    printf 'AIUR_RECORD_PROJECT_ROOT=%q\n' "$root"
+    printf 'AIUR_RECORD_PROJECT_ROOT_SOURCE=%q\n' "${AIUR_PROJECT_ROOT_SOURCE:-}"
+    printf 'AIUR_RECORD_WRITTEN_AT=%q\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)"
+  } >"$tmp" || { rm -f "$tmp" 2>/dev/null || true; return 0; }
+  chmod 0600 "$tmp" 2>/dev/null || true
+  mv "$tmp" "$record" 2>/dev/null || rm -f "$tmp" 2>/dev/null || true
+}
+
 # Marker `status` reads to tell "daemon crashed, agents may be orphaned" apart
 # from "nothing was ever running". Written by the watchdog on an unexpected exit,
 # cleared on a clean stop and on the next successful background start.
@@ -690,6 +1024,123 @@ record_beam_crash() {
   fi
 }
 
+canonical_workspace_root() {
+  local root="$1"
+  if [ -d "$root" ]; then
+    (cd "$root" 2>/dev/null && pwd -P) || printf '%s\n' "$root"
+  else
+    printf '%s\n' "$root"
+  fi
+}
+
+workspace_root_is_shallow() {
+  local root="${1%/}" trimmed
+  trimmed="${root#/}"
+  [ -n "$trimmed" ] || return 0
+  case "$trimmed" in
+    */*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+workspace_cwd_pids() {
+  local root="${1%/}" proc_dir="${2:-/proc}" entry pid cwd
+  [ -d "$proc_dir" ] || return 0
+
+  for entry in "$proc_dir"/[0-9]*; do
+    [ -d "$entry" ] || continue
+    pid="${entry##*/}"
+    cwd="$(readlink "$entry/cwd" 2>/dev/null || true)"
+    [ -n "$cwd" ] || continue
+    cwd="${cwd%/}"
+    if [ "$cwd" != "$root" ] && [[ "$cwd/" == "$root/"* ]]; then
+      printf '%s\n' "$pid"
+    fi
+  done
+}
+
+shell_protected_pid_list() {
+  local p
+  printf '%s\n' "$$"
+  [ "${BASHPID:-$$}" = "$$" ] || printf '%s\n' "$BASHPID"
+  [ -n "${PPID:-}" ] && printf '%s\n' "$PPID"
+  for p in $(agent_pid_tree "$$" 2>/dev/null || true); do
+    printf '%s\n' "$p"
+  done
+}
+
+reap_workspace_cwd_agents() {
+  local root="${1:-}"
+  [ -n "$root" ] || return 0
+  [ -d /proc ] || return 0
+
+  root="$(canonical_workspace_root "$root")"
+  if workspace_root_is_shallow "$root"; then
+    echo "⚠️ refusing shallow workspace cwd sweep root: $root" >&2
+    return 0
+  fi
+
+  local max_sweeps="${AIUR_WORKSPACE_REAP_SWEEPS:-6}"
+  case "$max_sweeps" in '' | *[!0-9]*) max_sweeps=6 ;; esac
+  [ "$max_sweeps" -gt 0 ] || return 0
+
+  local protected pids=() filtered=() pid p sweep waited any
+  protected=" $(shell_protected_pid_list | tr '\n' ' ') "
+
+  sweep=0
+  while [ "$sweep" -lt "$max_sweeps" ]; do
+    mapfile -t pids < <(workspace_cwd_pids "$root" /proc)
+    filtered=()
+    for pid in "${pids[@]}"; do
+      case "$protected" in *" $pid "*) continue ;; esac
+      kill -0 "$pid" 2>/dev/null && filtered+=("$pid")
+    done
+
+    [ "${#filtered[@]}" -gt 0 ] || return 0
+
+    for p in "${filtered[@]}"; do kill -TERM "$p" 2>/dev/null || true; done
+    waited=0
+    while [ "$waited" -lt 10 ]; do
+      any=0
+      for p in "${filtered[@]}"; do kill -0 "$p" 2>/dev/null && { any=1; break; }; done
+      [ "$any" -eq 0 ] && break
+      sleep 0.1
+      waited=$((waited + 1))
+    done
+    for p in "${filtered[@]}"; do kill -KILL "$p" 2>/dev/null || true; done
+
+    sweep=$((sweep + 1))
+    sleep 0.1
+  done
+}
+
+reap_workspace_cwd_from_file() {
+  local root_file="${1:-}" root
+  [ -n "$root_file" ] && [ -s "$root_file" ] || return 0
+  IFS= read -r root <"$root_file" || root=""
+  reap_workspace_cwd_agents "$root"
+}
+
+current_workspace_root() {
+  resolve_release
+  prepare_distribution >/dev/null 2>&1 || return 1
+
+  local output status line
+  set +e
+  output="$("$release_bin" rpc "IO.puts(Aiur.Config.workspace_root())" 2>/dev/null)"
+  status=$?
+  set -e
+  [ "$status" -eq 0 ] || return 1
+
+  while IFS= read -r line; do
+    case "$line" in
+      "" | :ok) continue ;;
+      *) printf '%s\n' "$line"; return 0 ;;
+    esac
+  done <<<"$output"
+  return 1
+}
+
 # Background watchdog that survives the BEAM. Polls for the release BEAM by
 # command pattern and, once it has SEEN the BEAM and then the BEAM disappears
 # (orderly halt OR :emfile-style crash), reaps every agent. Polling the pattern
@@ -702,12 +1153,13 @@ record_beam_crash() {
 #
 #   $1 beam_pattern  $2 socket  $3 pidfile  $4 interval_s  $5 initial_seen
 #   $6 node  $7 run_log_dir  $8 stop_sentinel  $9 crash_marker
+#   $10 workspace_root_file
 # Args 6-9 arm crash recording (background mode). Omit them (foreground) and the
 # watchdog only reaps — a foreground BEAM death is already visible at the UI.
 # Prints the watchdog's own pid so the caller can kill it on a clean teardown.
 start_beam_death_watchdog() {
   local beam_pattern="$1" socket="$2" pidfile="$3" interval="${4:-1}" initial_seen="${5:-0}"
-  local node="${6:-}" run_log_dir="${7:-}" stop_sentinel="${8:-}" crash_marker="${9:-}"
+  local node="${6:-}" run_log_dir="${7:-}" stop_sentinel="${8:-}" crash_marker="${9:-}" workspace_root_file="${10:-}"
   # Redirect the subshell's stdout so a command-substitution caller
   # (`pid=$(start_beam_death_watchdog ...)`) returns immediately instead of
   # blocking on the still-open pipe until the watchdog finishes.
@@ -730,6 +1182,7 @@ start_beam_death_watchdog() {
       record_beam_crash "$node" "$run_log_dir" "$crash_marker"
     fi
     reap_aiur_agents "$socket" "$pidfile"
+    reap_workspace_cwd_from_file "$workspace_root_file"
   ) >/dev/null 2>&1 &
   printf '%s\n' "$!"
 }
@@ -789,7 +1242,7 @@ wait_for_session_startup() {
 # Foreground teardown: kill the session + BEAM and reap opencode sessions on exit.
 _session_socket="" _session_name="" _session_conf="" _session_tmpfile=""
 _session_capture="" _session_argv="" _session_release="" _session_tmux="" _session_node=""
-_session_pidfile="" _session_watchdog_pid=""
+_session_pidfile="" _session_watchdog_pid="" _session_workspace_root_file=""
 _cleanup_ran=0
 session_cleanup() {
   [ "$_cleanup_ran" = 1 ] && return 0
@@ -819,6 +1272,11 @@ session_cleanup() {
   # release dir, so release-path pgrep would terminate sibling workflows.
   [ -n "$_session_node" ] && kill_beams_matching "-name ${_session_node}"
 
+  # Final cwd-sweep backstop after the BEAM is gone: catches workspace-rooted
+  # agents or test children that registered too late, reparented during the
+  # BEAM-side sweep, or survived a bounded in-BEAM cleanup.
+  reap_workspace_cwd_from_file "$_session_workspace_root_file"
+
   # Reap the epmd our BEAM spawned for distribution so it doesn't linger after
   # exit. The node is dead by now, so `epmd -kill` succeeds; it safely refuses
   # while any *other* Erlang node is alive, so a daemon shared with an unrelated
@@ -846,7 +1304,8 @@ session_cleanup() {
   # tempfiles are spared (fresh + live pid) before the explicit rm below clears them.
   sweep_stale_tmp_artifacts || true
 
-  rm -f "$_session_tmpfile" "$_session_capture" "$_session_argv" "$_session_pidfile" 2>/dev/null || true
+  rm -f "$_session_tmpfile" "$_session_capture" "$_session_argv" "$_session_pidfile" "$_session_workspace_root_file" 2>/dev/null || true
+  rm -f "$(aiur_instance_record_path)" 2>/dev/null || true
   return $code
 }
 install_foreground_traps() {
@@ -891,21 +1350,207 @@ probe_node_liveness() {
   printf 'unknown'
 }
 
+probe_named_node_liveness() {
+  local node="$1" old_node="${RELEASE_NODE:-}" state
+  RELEASE_NODE="$node"
+  state="$(probe_node_liveness)"
+  RELEASE_NODE="$old_node"
+  printf '%s' "$state"
+}
+
+load_aiur_instance_record() {
+  local file="$1"
+  AIUR_RECORD_NODE=""
+  AIUR_RECORD_INSTANCE_KEY=""
+  AIUR_RECORD_SESSION=""
+  AIUR_RECORD_SOCKET=""
+  AIUR_RECORD_PROJECT_ROOT=""
+  AIUR_RECORD_PROJECT_ROOT_SOURCE=""
+  [ -r "$file" ] || return 1
+  # Records are written by this engine as KEY=%q lines under the user's state dir.
+  # shellcheck disable=SC1090
+  source "$file" 2>/dev/null || return 1
+  [ -n "$AIUR_RECORD_NODE" ] && [ -n "$AIUR_RECORD_SESSION" ] && \
+    [ -n "$AIUR_RECORD_SOCKET" ] && [ -n "$AIUR_RECORD_PROJECT_ROOT" ]
+}
+
+path_is_within_root() {
+  local root child
+  root="$(canonical_workspace_root "$1")"
+  child="$(canonical_workspace_root "$2")"
+  [ "$child" = "$root" ] || [[ "$child/" == "$root/"* ]]
+}
+
+AIUR_CONTROL_ADOPTED_RECORD=0
+AIUR_CONTROL_CURRENT_NODE_STATE=""
+AIUR_CONTROL_HINT_ROOTS=""
+AIUR_CONTROL_CALLER_ROOT=""
+AIUR_CONTROL_CALLER_NODE=""
+AIUR_CONTROL_CALLER_ROOT_SOURCE=""
+
+resolve_control_identity_from_records() {
+  AIUR_CONTROL_ADOPTED_RECORD=0
+  AIUR_CONTROL_CURRENT_NODE_STATE="$(probe_node_liveness)"
+  AIUR_CONTROL_HINT_ROOTS=""
+  AIUR_CONTROL_CALLER_ROOT="$(canonical_workspace_root "${AIUR_PROJECT_ROOT:-}")"
+  AIUR_CONTROL_CALLER_NODE="$AIUR_RELEASE_NODE"
+  AIUR_CONTROL_CALLER_ROOT_SOURCE="${AIUR_PROJECT_ROOT_SOURCE:-}"
+
+  [ "$AIUR_CONTROL_CURRENT_NODE_STATE" = "down" ] || return 0
+  [ "${AIUR_PROJECT_ROOT_SOURCE:-}" = "cwd" ] || return 0
+
+  local dir file state root match_count=0
+  local match_node="" match_key="" match_session="" match_socket="" match_root="" match_source=""
+  dir="$(aiur_instances_dir)"
+  [ -d "$dir" ] || return 0
+
+  for file in "$dir"/*.instance; do
+    [ -e "$file" ] || continue
+    load_aiur_instance_record "$file" || continue
+    state="$(probe_named_node_liveness "$AIUR_RECORD_NODE")"
+    [ "$state" = "up" ] || continue
+
+    root="$(canonical_workspace_root "$AIUR_RECORD_PROJECT_ROOT")"
+    case "$AIUR_CONTROL_HINT_ROOTS" in
+      *"
+$root
+"*) ;;
+      *) AIUR_CONTROL_HINT_ROOTS="${AIUR_CONTROL_HINT_ROOTS}${root}
+" ;;
+    esac
+
+    path_is_within_root "$root" "$AIUR_CONTROL_CALLER_ROOT" || continue
+    match_count=$((match_count + 1))
+    match_node="$AIUR_RECORD_NODE"
+    match_key="$AIUR_RECORD_INSTANCE_KEY"
+    match_session="$AIUR_RECORD_SESSION"
+    match_socket="$AIUR_RECORD_SOCKET"
+    match_root="$root"
+    match_source="$AIUR_RECORD_PROJECT_ROOT_SOURCE"
+  done
+
+  [ "$match_count" -eq 1 ] || return 0
+
+  AIUR_RELEASE_NODE="$match_node"
+  AIUR_INSTANCE_KEY="$match_key"
+  AIUR_PROJECT_ROOT="$match_root"
+  AIUR_PROJECT_ROOT_SOURCE="$match_source"
+  AIUR_ADOPTED_TMUX_SESSION="$match_session"
+  AIUR_ADOPTED_TMUX_SOCKET="$match_socket"
+  export AIUR_RELEASE_NODE AIUR_INSTANCE_KEY AIUR_PROJECT_ROOT AIUR_PROJECT_ROOT_SOURCE \
+    AIUR_ADOPTED_TMUX_SESSION AIUR_ADOPTED_TMUX_SOCKET
+  RELEASE_NODE="$AIUR_RELEASE_NODE"
+  export RELEASE_NODE
+  AIUR_CONTROL_ADOPTED_RECORD=1
+}
+
+print_global_config_control_hint() {
+  [ "${AIUR_CONTROL_CALLER_ROOT_SOURCE:-}" = "cwd" ] || return 0
+  [ "${AIUR_CONTROL_CURRENT_NODE_STATE:-}" = "down" ] || return 0
+
+  echo "aiur: global-config control identity is keyed by cwd ${AIUR_CONTROL_CALLER_ROOT:-${AIUR_PROJECT_ROOT:-unknown}}" >&2
+  echo "aiur: run control commands from the launch directory, or from a subdirectory of that launch directory" >&2
+  if [ -n "${AIUR_CONTROL_HINT_ROOTS:-}" ]; then
+    echo "aiur: live launch directory candidate(s):" >&2
+    printf '%s' "$AIUR_CONTROL_HINT_ROOTS" | sed '/^$/d; s/^/  /' >&2
+  fi
+}
+
+control_rpc_timeout_seconds() {
+  local seconds="${AIUR_CONTROL_RPC_TIMEOUT_SECONDS:-10}"
+  case "$seconds" in
+    '' | *[!0-9]* | 0) seconds=10 ;;
+  esac
+  printf '%s' "$seconds"
+}
+
+kill_control_rpc_process() {
+  local pid="$1" grouped="$2" p tree=()
+  [ -n "$pid" ] || return 0
+
+  if [ "$grouped" = "1" ]; then
+    kill -TERM "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+    sleep 0.2
+    kill -KILL "-$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true
+    return 0
+  fi
+
+  while IFS= read -r p; do tree+=("$p"); done < <(agent_pid_tree "$pid")
+  for p in "${tree[@]}"; do kill -TERM "$p" 2>/dev/null || true; done
+  sleep 0.2
+  for p in "${tree[@]}"; do kill -KILL "$p" 2>/dev/null || true; done
+}
+
+run_release_rpc_with_timeout() {
+  local expression="$1" timeout output_file timeout_file pid watchdog_pid status grouped=0
+  timeout="$(control_rpc_timeout_seconds)"
+  output_file="$(mktemp "${TMPDIR:-/tmp}/aiur-control-rpc-output.XXXXXX")"
+  timeout_file="$(mktemp "${TMPDIR:-/tmp}/aiur-control-rpc-timeout.XXXXXX")"
+  rm -f "$timeout_file" 2>/dev/null || true
+
+  if command -v setsid >/dev/null 2>&1; then
+    setsid "$release_bin" rpc "$expression" >"$output_file" 2>&1 &
+    grouped=1
+  else
+    "$release_bin" rpc "$expression" >"$output_file" 2>&1 &
+  fi
+  pid=$!
+
+  (
+    sleep "$timeout"
+    if kill -0 "$pid" 2>/dev/null; then
+      : >"$timeout_file"
+      kill_control_rpc_process "$pid" "$grouped"
+    fi
+  ) &
+  watchdog_pid=$!
+
+  if wait "$pid"; then
+    status=0
+  else
+    status=$?
+  fi
+  kill "$watchdog_pid" 2>/dev/null || true
+  wait "$watchdog_pid" 2>/dev/null || true
+
+  AIUR_CONTROL_RPC_OUTPUT="$(cat "$output_file" 2>/dev/null || true)"
+  if [ -f "$timeout_file" ]; then
+    AIUR_CONTROL_RPC_TIMED_OUT=1
+    status=124
+  else
+    AIUR_CONTROL_RPC_TIMED_OUT=0
+  fi
+
+  rm -f "$output_file" "$timeout_file" 2>/dev/null || true
+  return "$status"
+}
+
 # RPC an expression into the running node. The control CLI prints a trailing
 # `__AIUR_CONTROL_EXIT__:<code>` marker we translate into the process exit code.
 run_control_rpc() {
   local expression="$1"
   resolve_release
   prepare_distribution || die "distribution setup failed; cannot contact aiur"
+  resolve_control_identity_from_records
+  if [ "${AIUR_CONTROL_ADOPTED_RECORD:-0}" -eq 1 ]; then
+    prepare_distribution || die "distribution setup failed; cannot contact aiur"
+  fi
 
   local marker="__AIUR_CONTROL_EXIT__:"
   local output status exit_code=0 saw_marker=0 line
 
   set +e
-  output="$("$release_bin" rpc "$expression" 2>&1)"
+  run_release_rpc_with_timeout "$expression"
   status=$?
+  output="$AIUR_CONTROL_RPC_OUTPUT"
   set -e
 
+  if [ "${AIUR_CONTROL_RPC_TIMED_OUT:-0}" -eq 1 ]; then
+    [ -n "$output" ] && printf '%s\n' "$output" >&2
+    echo "aiur: control rpc to ${RELEASE_NODE} timed out after $(control_rpc_timeout_seconds)s; helper process was terminated" >&2
+    return 124
+  fi
+
   if [ "$status" -ne 0 ]; then
     # A non-zero exit here is the rpc transport failing — application-level
     # outcomes ride the marker path below. `bin/aiur rpc` (Elixir --rpc-eval)
@@ -925,6 +1570,7 @@ run_control_rpc() {
           echo "aiur: run 'aiur stop' to reap any orphaned agents, then start aiur again" >&2
         else
           echo "aiur: no running aiur node at ${RELEASE_NODE}; start aiur and try again" >&2
+          print_global_config_control_hint
         fi
         ;;
       up)
@@ -950,7 +1596,11 @@ run_control_rpc() {
     esac
   done <<<"$output"
 
-  [ "$saw_marker" -eq 1 ] || return 1
+  if [ "$saw_marker" -ne 1 ]; then
+    echo "aiur: control rpc to ${RELEASE_NODE} returned no exit marker; command output may be incomplete" >&2
+    return 1
+  fi
+
   return "$exit_code"
 }
 
@@ -1046,6 +1696,99 @@ cmd_agents() {
   run_control_rpc "Aiur.AgentControlCLI.agents()"
 }
 
+# `aiur alerts` — newline-delimited structured alert feed from persisted
+# per-agent logs. `--needs-attention` filters to operator-actionable alerts.
+cmd_alerts() {
+  local needs_attention=0 arg
+  for arg in "$@"; do
+    case "$arg" in
+      --needs-attention) needs_attention=1 ;;
+      *)
+        echo "aiur: alerts only accepts --needs-attention" >&2
+        exit 64
+        ;;
+    esac
+  done
+
+  if [ "$needs_attention" -eq 1 ]; then
+    run_control_rpc "Aiur.AgentControlCLI.alerts(needs_attention: true)"
+  else
+    run_control_rpc "Aiur.AgentControlCLI.alerts()"
+  fi
+}
+
+# `aiur watch` — the server-side status board. Compiles one row per active
+# agent (state · complexity · activity-age · doing) plus an actionable section
+# from aiur's own state, with no GitHub round-trip. `--changes` (default) prints
+# only state-level deltas since the last call; `--full` prints every row;
+# `--interval N` re-renders every N seconds as a foreground watcher (the Elixir
+# call stays one-shot — the loop lives here).
+cmd_watch() {
+  local mode="changes" interval="" arg
+
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --full) mode="full" ;;
+      --changes) mode="changes" ;;
+      --once) : ;;
+      --interval)
+        shift
+        interval="${1:-}"
+        watch_validate_interval "$interval"
+        ;;
+      --interval=*)
+        interval="${arg#--interval=}"
+        watch_validate_interval "$interval"
+        ;;
+      *)
+        echo "aiur: watch accepts --full, --changes, --once, --interval <secs>" >&2
+        exit 64
+        ;;
+    esac
+    shift
+  done
+
+  local expression="Aiur.AgentControlCLI.watch(mode: :${mode})"
+
+  if [ -n "$interval" ]; then
+    while true; do
+      run_control_rpc "$expression" || true
+      sleep "$interval"
+    done
+  else
+    run_control_rpc "$expression"
+  fi
+}
+
+watch_validate_interval() {
+  if ! [[ "$1" =~ ^[0-9]+$ ]] || [ "$1" -le 0 ]; then
+    echo "aiur: watch --interval expects a positive integer (seconds)" >&2
+    exit 64
+  fi
+}
+
+cmd_cleanup_stale() {
+  local dry_run=0 arg
+  for arg in "$@"; do
+    case "$arg" in
+      --dry-run) dry_run=1 ;;
+      *)
+        echo "aiur: cleanup-stale only accepts --dry-run" >&2
+        exit 64
+        ;;
+    esac
+  done
+
+  aiur_resolve_identity
+  if [ "$dry_run" -eq 1 ]; then
+    report_stale_manual_smoke || true
+  else
+    report_stale_manual_smoke || true
+    reap_stale_manual_smoke 1
+  fi
+}
+
 # `aiur set <key> <value>` — runtime config overrides without editing
 # `.aiur/config`. Currently: `aiur set max-agents N`.
 cmd_set() {
@@ -1196,11 +1939,33 @@ sweep_stale_tmp_artifacts() {
 cmd_stop() {
   resolve_release
   aiur_resolve_identity
+  RELEASE_NODE="$AIUR_RELEASE_NODE"
+  ERL_EPMD_ADDRESS="${ERL_EPMD_ADDRESS:-127.0.0.1}"
+  export RELEASE_NODE ERL_EPMD_ADDRESS
+  resolve_control_identity_from_records
+
+  local workspace_root
+  workspace_root="$(current_workspace_root 2>/dev/null || true)"
 
   local tmux_bin
   tmux_bin="$(command -v tmux || true)"
-  local session="${AIUR_SESSION_PREFIX}-${USER:-user}${AIUR_INSTANCE_KEY:+-$AIUR_INSTANCE_KEY}-default"
-  local socket="${AIUR_SESSION_PREFIX}-${USER:-user}${AIUR_INSTANCE_KEY:+-$AIUR_INSTANCE_KEY}"
+  local session="${AIUR_ADOPTED_TMUX_SESSION:-${AIUR_SESSION_PREFIX}-${USER:-user}${AIUR_INSTANCE_KEY:+-$AIUR_INSTANCE_KEY}-default}"
+  local socket="${AIUR_ADOPTED_TMUX_SOCKET:-${AIUR_SESSION_PREFIX}-${USER:-user}${AIUR_INSTANCE_KEY:+-$AIUR_INSTANCE_KEY}}"
+
+  local has_session=0
+  if [ -n "$tmux_bin" ] && "$tmux_bin" -L "$socket" has-session -t "$session" 2>/dev/null; then
+    has_session=1
+  fi
+
+  if [ "${AIUR_CONTROL_ADOPTED_RECORD:-0}" -ne 1 ] && \
+    [ "${AIUR_CONTROL_CURRENT_NODE_STATE:-}" = "down" ] && \
+    [ "${AIUR_PROJECT_ROOT_SOURCE:-}" = "cwd" ] && \
+    [ "$has_session" -eq 0 ] && \
+    [ ! -f "$(aiur_crash_marker_path)" ]; then
+    echo "aiur: no running aiur node at ${AIUR_RELEASE_NODE}; nothing stopped" >&2
+    print_global_config_control_hint
+    return 1
+  fi
 
   # Tell the background BEAM-death watchdog this exit is intentional before we
   # kill the BEAM, so it consumes the sentinel instead of recording a crash. The
@@ -1219,6 +1984,10 @@ cmd_stop() {
   # it. Do not sweep by release dir: sibling instances share dev releases.
   kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
 
+  # Final cwd-sweep backstop after the BEAM is dead. `cmd_stop` is a fresh shell,
+  # so it captures the root from the live control node before the kill above.
+  reap_workspace_cwd_agents "$workspace_root"
+
   # The BEAM (alive until the TERM above) reaped its own headless agents through
   # ProcessReaper on Application.stop. kill-server is the guarantee the earlier
   # kill-session can't give for mid-turn agents: every pane agent across all
@@ -1238,8 +2007,10 @@ cmd_stop() {
     rm -f "$agentfile" 2>/dev/null || true
   done
 
+  reap_stale_manual_smoke 0
   sweep_dead_tmux_sockets
   sweep_stale_tmp_artifacts
+  rm -f "$(aiur_instance_record_path)" 2>/dev/null || true
 }
 
 # --- dispatch ----------------------------------------------------------------
@@ -1275,6 +2046,14 @@ aiur_engine_main() {
       shift
       cmd_agents "$@"
       ;;
+    alerts)
+      shift
+      cmd_alerts "$@"
+      ;;
+    watch)
+      shift
+      cmd_watch "$@"
+      ;;
     set)
       shift
       cmd_set "$@"
@@ -1287,6 +2066,10 @@ aiur_engine_main() {
       shift
       cmd_message "$@"
       ;;
+    cleanup-stale)
+      shift
+      cmd_cleanup_stale "$@"
+      ;;
     stop)
       cmd_stop
       ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiur-cli",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "AI Unit Runtime for Executors.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/its-everdred/aiur",
@@ -24,11 +24,11 @@
   "engines": {
     "node": ">=18"
   },
-  "opencodeVersion": "1.15.6",
+  "opencodeVersion": "1.17.10",
   "optionalDependencies": {
-    "aiur-cli-linux-x64": "0.0.3",
-    "aiur-cli-linux-arm64": "0.0.3",
-    "aiur-cli-darwin-x64": "0.0.3",
-    "aiur-cli-darwin-arm64": "0.0.3"
+    "aiur-cli-linux-x64": "0.0.4",
+    "aiur-cli-linux-arm64": "0.0.4",
+    "aiur-cli-darwin-x64": "0.0.4",
+    "aiur-cli-darwin-arm64": "0.0.4"
   }
 }

package/scripts/postinstall.mjs

@@ -23,14 +23,15 @@ import path from "node:path";
 
 // Pinned opencode version, read from package.json `opencodeVersion` (single
 // source of truth — keep in sync with mise.toml). aiur's opencode pane
-// integration is validated against this version; 1.17.x broke custom-provider
-// model resolution (ProviderModelNotFoundError), blanking the chat panes.
+// integration is validated end-to-end against this exact version; floating to
+// `latest` would adopt an unverified opencode that could regress custom-provider
+// model resolution or the chat panes, so the spec must carry a fixed version.
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 export const OPENCODE_PACKAGE = `opencode-ai@${pkg.opencodeVersion}`;
 
 // True only when the *pinned* opencode version is on PATH. A wrong (e.g.
-// newer) version must be reinstalled — leaving 1.17.x in place keeps the
-// panes broken — so a mere presence check isn't enough.
+// newer, unverified) version must be reinstalled to the pin — so a mere
+// presence check isn't enough.
 export function opencodeMatchesPin() {
   const result = spawnSync("opencode", ["--version"], { encoding: "utf8" });
   return !result.error && result.status === 0 && result.stdout.trim() === pkg.opencodeVersion;