aiur-cli 0.0.2 → 0.0.4

package/libexec/aiur-engine.sh

@@ -23,6 +23,18 @@
 
 set -euo pipefail
 
+# Raise the soft open-file limit toward the hard maximum. High agent concurrency
+# spawns many tmux/opencode/git subprocesses + sockets; on hosts with a low
+# default (macOS ships 256) that exhausts file descriptors (:emfile) and crashes
+# the node. Soft<=hard needs no privilege; best-effort, never fatal.
+__aiur_hard_nofile="$(ulimit -Hn 2>/dev/null || echo)"
+if [ "${__aiur_hard_nofile}" = "unlimited" ]; then
+  ulimit -Sn 65536 2>/dev/null || true
+elif [ -n "${__aiur_hard_nofile}" ]; then
+  ulimit -Sn "${__aiur_hard_nofile}" 2>/dev/null || true
+fi
+unset __aiur_hard_nofile
+
 die() {
   echo "❌ $*" >&2
   exit 1
@@ -30,19 +42,99 @@ die() {
 
 engine_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-# --- distribution identity (fixed: the single `aiur` identity) ---------------
+# --- distribution identity (per-instance: keyed by the aiur project root) -----
+
+# 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
+
+  # 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. 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)"
+  [ -n "$root" ] || return 0
+  # Canonicalize (resolve symlinks) so launch and control commands invoked via
+  # different logical paths to the same project agree on the key. Fall back to the
+  # literal path when the dir doesn't exist (e.g. a test-fixture root).
+  root="$(cd "$root" 2>/dev/null && pwd -P || printf '%s' "$root")"
+  printf '%s' "$root" | { shasum -a 256 2>/dev/null || sha256sum; } | cut -c1-10
+}
 
 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}"
   : "${AIUR_SESSION_PREFIX:=aiur}"
   : "${AIUR_PROFILES_FILE:=$config_home/aiur/aiur.profiles}"
-  : "${AIUR_RELEASE_NODE:=aiur-${USER}@127.0.0.1}"
+  # Compute the per-instance key once. `${VAR+x}` so an explicit empty value (no
+  # project resolved) is honored and not recomputed on each call.
+  if [ -z "${AIUR_INSTANCE_KEY+x}" ]; then
+    AIUR_INSTANCE_KEY="$(aiur_instance_key)"
+  fi
+  : "${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_PROFILES_FILE AIUR_RELEASE_NODE AIUR_INSTANCE_KEY \
+    AIUR_PROJECT_ROOT AIUR_PROJECT_ROOT_SOURCE
 }
 
 aiur_print_identity() {
@@ -52,6 +144,9 @@ aiur_print_identity() {
   printf 'AIUR_SESSION_PREFIX=%s\n' "$AIUR_SESSION_PREFIX"
   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"
 }
 
@@ -172,12 +267,18 @@ build_init_cmd() {
 
 usage() {
   cat <<'EOF'
-Usage: aiur [--interactive] [--logs-root <path>] [--port <port>] [--host <host>] [path-to-.aiurconfig]
+Usage: aiur [--interactive] [--max-agents <n>] [--logs-root <path>] [--port <port>] [--host <host>] [path-to-.aiurconfig]
        aiur init [--force]   scaffold .aiurconfig (interactive setup wizard)
-       aiur --bg             start in a detached tmux session
+       aiur --bg             start in a lean, headless detached tmux session
        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
 }
@@ -265,19 +366,28 @@ run_session() {
 
   init_argv_file
 
-  # Inject the flags a bare `aiur` needs: loopback bind, interactive UI, and the
-  # no-guardrails ack. Skip any the user already passed.
-  local has_host=0 has_interactive=0 has_ack=0 arg
+  # Inject the flags a bare `aiur` needs: loopback bind, UI mode, and the
+  # no-guardrails ack. Skip any the user already passed. Foreground runs are
+  # interactive (tmux panes + dashboard); `--bg` runs lean/headless — no panes,
+  # no dashboard bind, no chat backfill — and is driven over the control RPC
+  # (status/agents/message/pause/set). `aiur --bg --interactive` opts back into
+  # the full interactive stack for an attachable background session.
+  local has_host=0 has_interactive=0 has_headless=0 has_ack=0 arg
   for arg in "$@"; do
     case "$arg" in
       --host | --host=*) has_host=1 ;;
       --interactive) has_interactive=1 ;;
+      --headless) has_headless=1 ;;
       --i-understand-that-this-will-be-running-without-the-usual-guardrails) has_ack=1 ;;
     esac
   done
   local injected=()
   [ "$has_host" -eq 1 ] || injected+=(--host 127.0.0.1)
-  [ "$has_interactive" -eq 1 ] || injected+=(--interactive)
+  if [ "$mode" = "background" ] && [ "$has_interactive" -eq 0 ]; then
+    [ "$has_headless" -eq 1 ] || injected+=(--headless)
+  else
+    [ "$has_interactive" -eq 1 ] || injected+=(--interactive)
+  fi
   [ "$has_ack" -eq 1 ] || injected+=(--i-understand-that-this-will-be-running-without-the-usual-guardrails)
 
   write_argv "${injected[@]}" "$@"
@@ -291,12 +401,14 @@ run_session() {
     export ELIXIR_ERL_OPTIONS="${ELIXIR_ERL_OPTIONS:-} +fnu"
   fi
 
-  local session="${AIUR_SESSION_PREFIX}-${USER:-user}-default"
-  local socket="${AIUR_SESSION_PREFIX}-${USER:-user}"
+  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 conf
   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"
@@ -308,8 +420,37 @@ run_session() {
   export AIUR_SESSION_TMPFILE="${session_root}/aiur-${$}-sessions"
   : >"$AIUR_SESSION_TMPFILE"
 
+  # Agent pidfile: the BEAM appends one line per spawned agent (pane or headless
+  # os_pid) via Aiur.ProcessReaper. The BEAM-death watchdog and session_cleanup
+  # reap from it after the BEAM is gone — a crashed BEAM can kill nothing itself.
+  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
+  # removes its startup tempfile. Minting it here and exporting it makes the
+  # shell and the BEAM (Aiur.LogFile honors AIUR_LOGS_ROOT) agree on one dir.
+  if [ "$mode" = "background" ] && [ -z "${AIUR_LOGS_ROOT:-}" ]; then
+    AIUR_LOGS_ROOT="$(printf '%s/%s-%s' "$HOME/.aiur/logs" "$(date -u +%Y%m%dT%H%M%SZ)" "$$")"
+    export AIUR_LOGS_ROOT
+  fi
+
+  # Capture sink for BEAM startup (and, in background mode, the whole run's
+  # boot stdout/stderr). Foreground uses a throwaway tempfile; background points
+  # at a durable file in the run log dir. The dir/file is created lazily just
+  # before launch (below) so an idempotent early-return start leaves no empty dir.
   local startup_capture
-  startup_capture="$(mktemp "${TMPDIR:-/tmp}/aiur-startup.XXXXXX")"
+  if [ "$mode" = "background" ] && [ -n "${AIUR_LOGS_ROOT:-}" ]; then
+    startup_capture="$AIUR_LOGS_ROOT/log/boot.out.log"
+  else
+    startup_capture="$(mktemp "${TMPDIR:-/tmp}/aiur-startup.XXXXXX")"
+  fi
 
   # Inner pane script: tmux's server may pre-exist and not inherit our env, so
   # re-export every var the BEAM needs. tee preserves a startup capture.
@@ -324,7 +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 ELIXIR_ERL_OPTIONS AIUR_LOGS_ROOT 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"
@@ -341,48 +483,127 @@ 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_node="$AIUR_RELEASE_NODE" _session_pidfile="$AIUR_AGENT_TMPFILE" \
+      _session_workspace_root_file="$AIUR_WORKSPACE_ROOT_FILE"
     install_foreground_traps
   fi
 
-  # An orphaned BEAM (its tmux session gone) can still hold the node name —
-  # under the unified identity, even one from a different release dir. With no
-  # live session on our socket, reap any name-holder so the launch isn't blocked
-  # by "name seems to be in use".
+  # Background starts are intentionally idempotent. A prior live node should not
+  # fall through to tmux's opaque "duplicate session" failure, and a stale tmux
+  # 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" "$AIUR_WORKSPACE_ROOT_FILE" 2>/dev/null || true
+      return 0
+    fi
+
+    echo "aiur found stale tmux session ${session}; cleaning it up before restart" >&2
+    reap_aiur_agents "$socket" "$AIUR_AGENT_TMPFILE"
+    kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
+  fi
+
+  # An orphaned BEAM (its tmux session gone) can still hold THIS instance's node
+  # name. With no live session on our (instance-keyed) socket, reap the name-holder
+  # so the launch isn't blocked by "name seems to be in use". The keyed name means
+  # this only ever reaps our own instance's orphan, never another live aiur.
   if ! "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null; then
     kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
   fi
 
+  # Transition reclaim: a keyed instance also reaps a stale beam under the legacy
+  # un-keyed name (aiur-$USER@127.0.0.1) — but only when no live legacy session
+  # exists, so a pre-fix run still in progress is never killed. (Runs on every keyed
+  # launch, not latched; it's a cheap best-effort sweep guarded by has-session.)
+  if [ -n "${AIUR_INSTANCE_KEY:-}" ]; then
+    local legacy_socket="${AIUR_SESSION_PREFIX}-${USER:-user}"
+    if ! "$tmux_bin" -L "$legacy_socket" -f "$conf" has-session -t "${legacy_socket}-default" 2>/dev/null; then
+      kill_beams_matching "-name aiur-${USER}@127.0.0.1"
+    fi
+  fi
+
+  # Create the capture sink now (after the idempotent early-return checks above,
+  # so a no-op "already running" start never mints an empty run log dir). The
+  # launcher's `tee -a` needs the file's parent to exist when the pane runs.
+  mkdir -p "$(dirname "$startup_capture")" 2>/dev/null || true
+  : >"$startup_capture" 2>/dev/null || true
+
   if ! "$tmux_bin" -L "$socket" -f "$conf" new-session -d -s "$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" 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
 
-  # Grace window: surface a boot crash instead of attaching to nothing.
-  local tick
-  for ((tick = 0; tick < 30; tick++)); do
-    if ! "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null; then
-      echo "❌ aiur exited during startup; captured output:" >&2
-      tail -n 30 "$startup_capture" 2>/dev/null | sed 's/^/  /' >&2 || true
-      [ "$mode" = "foreground" ] && return 1
-      rm -f "$startup_capture" "$argv_file" 2>/dev/null || true
-      exit 1
+  # Title the agent-list pane (the only pane in the fresh session). The conf's
+  # `pane-border-status`/`pane-border-format` render it; PaneManager titles the
+  # 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. 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
+      reap_aiur_agents "$socket" "$AIUR_AGENT_TMPFILE"
+      kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
     fi
-    sleep 0.1
-  done
+    [ "$mode" = "foreground" ] && return 1
+    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
-    echo "aiur started in the background (tmux session ${session}). Attach with: aiur" >&2
-    rm -f "$startup_capture" "$argv_file" 2>/dev/null || true
+    # 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.
+    rm -f "$(aiur_stop_sentinel_path)" "$(aiur_crash_marker_path)" 2>/dev/null || true
+
+    local background_watchdog_pid
+    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_WORKSPACE_ROOT_FILE")"
+    disown "$background_watchdog_pid" 2>/dev/null || true
+    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
     return 0
   fi
 
+  # Arm the BEAM-death watchdog before attaching. If the BEAM crashes
+  # (:emfile) mid-run, agent windows keep the orphaned session alive so the
+  # `tmux attach` below never returns and the EXIT trap never fires — the
+  # watchdog is the external reaper that survives the dead BEAM, kill-servers
+  # 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 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() {
@@ -417,37 +638,655 @@ 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
+# `-lc` wrapper; the model process (claude --print / codex) is its child and
+# reparents to init if only the wrapper is signalled — orphan-and-survive is
+# exactly the bug — so the whole tree must be collected before any kill lands.
+agent_pid_tree() {
+  local root="$1" child
+  printf '%s\n' "$root"
+  for child in $(pgrep -P "$root" 2>/dev/null || true); do
+    agent_pid_tree "$child"
+  done
+}
+
+# pid-reuse guard: succeeds when pid $1 is alive AND its command still contains
+# the comm substring $2 the BEAM recorded. An empty comm kills unconditionally.
+# Mirrors the BEAM-side cmdline guard (Aiur.ProcessReaper) but Mac-safe via
+# `ps -o command=`, so a recycled pid whose command no longer matches is spared.
+agent_pid_matches() {
+  local pid="$1" comm="$2" cmd
+  kill -0 "$pid" 2>/dev/null || return 1
+  [ -n "$comm" ] || return 0
+  cmd="$(ps -p "$pid" -o command= 2>/dev/null || true)"
+  case "$cmd" in *"$comm"*) return 0 ;; *) return 1 ;; esac
+}
+
+# Reap every aiur agent the BEAM can no longer reap itself.
+#
+#   $1 socket   aiur tmux socket (-L); kill-server nukes all panes (may be empty)
+#   $2 pidfile  AIUR_AGENT_TMPFILE (BEAM-written agent refs; may be empty/missing)
+#
+# tmux runs on aiur's PRIVATE socket (-L aiur-$USER), so kill-server tears down
+# every REPL/chat pane agent in one shot AND leaves no live aiur tmux server —
+# never touching the operator's own default tmux. Headless agents (claude/codex
+# app-servers spawned via Port) are bare OS processes that reparent to init on a
+# BEAM crash; kill-server can't see them, so they're reaped from the pidfile by
+# process tree, comm-guarded against pid reuse. Idempotent.
+reap_aiur_agents() {
+  local socket="$1" pidfile="${2:-}"
+  local tmux_bin
+  tmux_bin="$(command -v tmux || true)"
+
+  if [ -n "$tmux_bin" ] && [ -n "$socket" ]; then
+    "$tmux_bin" -L "$socket" kill-server 2>/dev/null || true
+  fi
+
+  [ -n "$pidfile" ] && [ -r "$pidfile" ] || return 0
+
+  # Snapshot the full process tree of every still-matching headless agent before
+  # signalling, so descendants that reparent mid-reap are already on the list.
+  local kind pid comm tree=() p
+  while read -r kind pid comm; do
+    [ "$kind" = "pid" ] && [ -n "$pid" ] || continue
+    agent_pid_matches "$pid" "$comm" || continue
+    while IFS= read -r p; do tree+=("$p"); done < <(agent_pid_tree "$pid")
+  done <"$pidfile"
+
+  [ "${#tree[@]}" -gt 0 ] || return 0
+
+  for p in "${tree[@]}"; do kill -TERM "$p" 2>/dev/null || true; done
+  local waited=0
+  while [ "$waited" -lt 20 ]; do
+    local any=0
+    for p in "${tree[@]}"; 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 "${tree[@]}"; do kill -KILL "$p" 2>/dev/null || true; done
+}
+
+# Stable, per-instance state paths the background BEAM-death machinery shares
+# across `run`, `stop`, and `status`. Keyed by the (instance-keyed) release node
+# rather than the tmux socket so `status` — which resolves the node but not the
+# socket — agrees on the same files. AIUR_BG_STATE_DIR and AIUR_RELEASE_NODE are
+# resolved by aiur_resolve_identity, which every one of those paths calls first.
+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.
+aiur_crash_marker_path() {
+  printf '%s/%s.last-crash' "${AIUR_BG_STATE_DIR:?}" "$(aiur_state_slug)"
+}
+
+# Sentinel `stop` drops before killing the BEAM so the watchdog knows the exit
+# was intentional and does not record a false crash.
+aiur_stop_sentinel_path() {
+  printf '%s/%s.stopping' "${AIUR_BG_STATE_DIR:?}" "$(aiur_state_slug)"
+}
+
+# Write a durable record that the background BEAM exited unexpectedly. Two sinks:
+# the run log dir (full record next to aiur.log, for forensics) and the stable
+# per-instance marker (for `status` to surface). Best-effort throughout — this
+# runs in the disowned watchdog after the BEAM is already gone, so it must never
+# fail loudly or block the reap that follows.
+record_beam_crash() {
+  local node="$1" run_log_dir="$2" marker="$3"
+  local ts boot_tail=""
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)"
+  if [ -n "$run_log_dir" ] && [ -r "$run_log_dir/log/boot.out.log" ]; then
+    boot_tail="$(tail -n 20 "$run_log_dir/log/boot.out.log" 2>/dev/null || true)"
+  fi
+
+  local body
+  body="$(
+    printf 'aiur background BEAM exited unexpectedly\n'
+    printf 'timestamp: %s\n' "${ts:-unknown}"
+    printf 'node: %s\n' "${node:-unknown}"
+    printf 'run_log_dir: %s\n' "${run_log_dir:-unknown}"
+    printf 'detected_by: background BEAM-death watchdog (no clean stop sentinel)\n'
+    if [ -n "$boot_tail" ]; then
+      printf -- '--- last 20 lines of boot.out.log ---\n%s\n' "$boot_tail"
+    fi
+  )"
+
+  if [ -n "$run_log_dir" ]; then
+    mkdir -p "$run_log_dir/log" 2>/dev/null || true
+    printf '%s\n' "$body" >>"$run_log_dir/log/aiur.crash" 2>/dev/null || true
+  fi
+  if [ -n "$marker" ]; then
+    printf '%s\n' "$body" >"$marker" 2>/dev/null || true
+  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
+# rather than a captured pid avoids two failure modes: a recycled BEAM pid the
+# watchdog would poll forever, and an empty pid at arm time that would silently
+# disarm the only crash reaper. The `seen` latch prevents a startup race from
+# reaping before the BEAM has come up. kill-server collapses the orphaned tmux
+# session, which returns the foreground `tmux attach` so the EXIT trap
+# (session_cleanup) runs its idempotent reap too.
+#
+#   $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:-}" 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.
+  (
+    seen="$initial_seen"
+    while :; do
+      if pgrep -f -- "$beam_pattern" >/dev/null 2>&1; then
+        seen=1
+      elif [ "$seen" = 1 ]; then
+        break
+      fi
+      sleep "$interval"
+    done
+    # The BEAM we had seen is gone. A clean `aiur stop` drops the sentinel first;
+    # its presence means an intentional exit (consume it, no crash record).
+    # Anything else is an unexpected exit worth a durable record before reaping.
+    if [ -n "$stop_sentinel" ] && [ -f "$stop_sentinel" ]; then
+      rm -f "$stop_sentinel" 2>/dev/null || true
+    elif [ -n "$crash_marker" ] || [ -n "$run_log_dir" ]; then
+      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' "$!"
+}
+
+probe_control_liveness() {
+  local expression output status
+  expression='case Process.whereis(Aiur.Orchestrator) do pid when is_pid(pid) -> case Aiur.Orchestrator.status(Aiur.Orchestrator, 100) do statuses when is_list(statuses) -> IO.puts("__AIUR_CONTROL_READY__"); _ -> IO.puts("__AIUR_CONTROL_NOT_READY__") end; _ -> IO.puts("__AIUR_CONTROL_NOT_READY__") end'
+
+  set +e
+  output="$("$release_bin" rpc "$expression" 2>&1)"
+  status=$?
+  set -e
+
+  if [ "$status" -eq 0 ] && [[ "$output" == *"__AIUR_CONTROL_READY__"* ]]; then
+    printf 'up'
+  else
+    printf 'down'
+  fi
+}
+
+wait_for_session_startup() {
+  local tmux_bin="$1" socket="$2" conf="$3" session="$4" startup_capture="$5" require_control="$6"
+  local max_ticks="${AIUR_TMUX_GRACE_TICKS:-30}" tick control_state
+  if [ "$require_control" = "1" ]; then
+    max_ticks="${AIUR_NODE_GRACE_TICKS:-100}"
+  fi
+
+  for ((tick = 0; tick < max_ticks; tick++)); do
+    if ! "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null; then
+      echo "❌ aiur exited during startup; captured output:" >&2
+      tail -n 30 "$startup_capture" 2>/dev/null | sed 's/^/  /' >&2 || true
+      return 1
+    fi
+
+    if [ "$require_control" != "1" ]; then
+      sleep 0.1
+      continue
+    fi
+
+    control_state="$(probe_control_liveness)"
+    if [ "$control_state" = "up" ]; then
+      return 0
+    fi
+
+    sleep 0.1
+  done
+
+  if [ "$require_control" = "1" ]; then
+    echo "❌ aiur control plane did not become ready at ${RELEASE_NODE:-unknown} during startup; captured output:" >&2
+    tail -n 30 "$startup_capture" 2>/dev/null | sed 's/^/  /' >&2 || true
+    return 1
+  fi
+
+  return 0
+}
+
 # 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_workspace_root_file=""
 _cleanup_ran=0
 session_cleanup() {
   [ "$_cleanup_ran" = 1 ] && return 0
   _cleanup_ran=1
   local code=$?
 
-  if [ -n "$_session_tmux" ]; then
-    "$_session_tmux" -L "$_session_socket" -f "$_session_conf" kill-session -t "$_session_name" 2>/dev/null || true
-  fi
+  # Stop the BEAM-death watchdog: cleanup is running, so it has no work left and
+  # a lingering poller would outlive this teardown.
+  [ -n "$_session_watchdog_pid" ] && kill "$_session_watchdog_pid" 2>/dev/null || true
 
-  local beam_pids pid waited=0
-  beam_pids="$(pgrep -f "$_session_release/.*erts.*beam.smp" 2>/dev/null || true)"
-  if [ -n "$beam_pids" ]; then
-    for pid in $beam_pids; do kill -TERM "$pid" 2>/dev/null || true; done
-    while [ $waited -lt 30 ]; do
-      beam_pids="$(pgrep -f "$_session_release/.*erts.*beam.smp" 2>/dev/null || true)"
-      [ -z "$beam_pids" ] && break
-      sleep 0.1
-      waited=$((waited + 1))
-    done
-    beam_pids="$(pgrep -f "$_session_release/.*erts.*beam.smp" 2>/dev/null || true)"
-    for pid in $beam_pids; do kill -KILL "$pid" 2>/dev/null || true; done
+  # kill-session on the detached aiur session FIRST: this is what propagates
+  # SIGHUP to the BEAM in that session so it begins its own orderly shutdown.
+  # Without it the BEAM survives Ctrl+C, holding port 4000 + the node name and
+  # breaking the next launch (regression test/aiur/regression/shutdown_cleanup_test.exs).
+  if [ -n "$_session_tmux" ] && [ -n "$_session_socket" ] && [ -n "$_session_name" ]; then
+    "$_session_tmux" -L "$_session_socket" kill-session -t "$_session_name" 2>/dev/null || true
   fi
 
-  # Belt-and-suspenders: reap any BEAM still holding our node name, even one
-  # launched from a different release dir than this run.
+  # Then kill-server on aiur's private socket: tears down every pane agent across
+  # all windows AND leaves no live aiur tmux server, then reaps headless agents
+  # from the pidfile. Idempotent with the watchdog's own reap and the kill-session
+  # above. reap_aiur_agents re-resolves tmux itself and reaps headless agents even
+  # when tmux is absent, so it is not gated on $_session_tmux.
+  reap_aiur_agents "$_session_socket" "$_session_pidfile"
+
+  # Reap only this instance's BEAM. Multiple keyed instances can share the same
+  # 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
+  # Erlang program is never disrupted. Use the release's bundled epmd and pin it
+  # to the loopback address aiur starts it on.
+  for _epmd in "$_session_release"/erts-*/bin/epmd; do
+    [ -x "$_epmd" ] || continue
+    ERL_EPMD_ADDRESS="${ERL_EPMD_ADDRESS:-127.0.0.1}" "$_epmd" -kill >/dev/null 2>&1 || true
+  done
+
   if command -v opencode >/dev/null 2>&1 && [ -s "$_session_tmpfile" ]; then
     local id
     while IFS= read -r id; do
@@ -460,7 +1299,13 @@ session_cleanup() {
   # Reap agent-driver sockets this run orphaned at close, not next launch.
   sweep_dead_tmux_sockets || true
 
-  rm -f "$_session_tmpfile" "$_session_capture" "$_session_argv" 2>/dev/null || true
+  # Reap stale aiur /tmp debris (per-run tempfiles, leaked test artifacts) so a
+  # tmpfs /tmp can't fill across runs. Age-gated + pid-safe; our own still-present
+  # 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" "$_session_workspace_root_file" 2>/dev/null || true
+  rm -f "$(aiur_instance_record_path)" 2>/dev/null || true
   return $code
 }
 install_foreground_traps() {
@@ -479,23 +1324,264 @@ trim() {
   printf '%s' "$s"
 }
 
+# Classify our distribution node's liveness via epmd, which only advertises a
+# node while its BEAM holds the registration. Echoes exactly one word:
+#   up      — node is registered: it is alive, so an rpc failure is a real error
+#   down    — epmd answered and our node is absent: it genuinely is not running
+#   unknown — epmd could not be queried (binary missing, or daemon unreachable),
+#             so node state is indeterminate and callers must NOT assume "down"
+#             and mask the real error
+# Distinguishing `unknown` from `down` matters: a live node whose epmd we cannot
+# reach must still surface its real rpc error rather than the "start aiur" hint.
+# Relies on RELEASE_NODE + ERL_EPMD_ADDRESS (prepare_distribution) and
+# release_dir (resolve_release), so call it only after both have run.
+probe_node_liveness() {
+  local epmd names short="${RELEASE_NODE%@*}"
+  for epmd in "$release_dir"/erts-*/bin/epmd; do
+    [ -x "$epmd" ] || continue
+    names="$(ERL_EPMD_ADDRESS="${ERL_EPMD_ADDRESS:-127.0.0.1}" "$epmd" -names 2>/dev/null)" \
+      || { printf 'unknown'; return; }
+    case "$names" in
+      *"name ${short} at port "*) printf 'up' ;;
+      *) printf 'down' ;;
+    esac
+    return
+  done
+  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
-    echo "aiur: no running aiur node at ${RELEASE_NODE}; start aiur and try again" >&2
+    # A non-zero exit here is the rpc transport failing — application-level
+    # outcomes ride the marker path below. `bin/aiur rpc` (Elixir --rpc-eval)
+    # reports a genuinely-down node and a live-but-unreachable one identically
+    # (`:noconnection`), and prints any exception raised inside the expression.
+    # So the reason string can't be trusted; classify via epmd instead. Only a
+    # node epmd confirms is down earns the friendly "start aiur" hint; an `up`
+    # node failed for a real reason, and an `unknown` probe must not be assumed
+    # down — in both of those cases surface the actual rpc output, never mask it.
+    case "$(probe_node_liveness)" in
+      down)
+        local crash_marker
+        crash_marker="$(aiur_crash_marker_path)"
+        if [ -f "$crash_marker" ]; then
+          echo "aiur: background daemon at ${RELEASE_NODE} is DOWN after an unexpected exit; agents may be orphaned" >&2
+          sed 's/^/  /' "$crash_marker" >&2 2>/dev/null || true
+          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)
+        [ -n "$output" ] && printf '%s\n' "$output" >&2
+        echo "aiur: rpc to ${RELEASE_NODE} failed (node is running); see the error above" >&2
+        ;;
+      *)
+        [ -n "$output" ] && printf '%s\n' "$output" >&2
+        echo "aiur: rpc to ${RELEASE_NODE} failed (could not query epmd to confirm node state); see the error above" >&2
+        ;;
+    esac
     return 1
   fi
 
@@ -510,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"
 }
 
@@ -575,6 +1665,152 @@ cmd_pause_resume() {
   run_control_rpc "$expression"
 }
 
+# `aiur message <issue> <text>` — deliver operator text to one running agent.
+# The text is base64-encoded for the RPC hop so arbitrary content (quotes,
+# backslashes, `#{}`, newlines) survives without Elixir-string escaping.
+cmd_message() {
+  local usage="aiur: message expects an issue ID and text (e.g. aiur message 44 \"ship it\")"
+
+  local issue="${1:-}"
+  if [ -z "$issue" ] || [[ ! "$issue" =~ ^[0-9]+$ ]]; then
+    echo "$usage" >&2
+    exit 64
+  fi
+  shift
+
+  local text="$*"
+  if [ -z "$text" ]; then
+    echo "$usage" >&2
+    exit 64
+  fi
+
+  local encoded
+  encoded="$(printf '%s' "$text" | base64 | tr -d '\n')"
+  run_control_rpc "Aiur.AgentControlCLI.message(\"$issue\", Base.decode64!(\"$encoded\"))"
+}
+
+# `aiur agents` — concise one-line-per-agent state + current activity from a
+# live node (the headless equivalent of the dashboard / aiur-status skill).
+cmd_agents() {
+  [ "$#" -eq 0 ] || die "agents does not accept arguments"
+  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() {
+  local key="${1:-}"
+  shift 2>/dev/null || true
+
+  case "$key" in
+    max-agents)
+      local n="${1:-}"
+      if [ -z "$n" ] || [[ ! "$n" =~ ^[0-9]+$ ]] || [ "$n" -lt 1 ]; then
+        echo "aiur: set max-agents expects a positive integer (e.g. aiur set max-agents 5)" >&2
+        exit 64
+      fi
+      run_control_rpc "Aiur.AgentControlCLI.set_max_agents($n)"
+      ;;
+    *)
+      echo "aiur: unknown setting: ${key:-(none)} (supported: max-agents)" >&2
+      exit 64
+      ;;
+  esac
+}
+
 sweep_dead_tmux_sockets() {
   local tmux_bin
   tmux_bin="$(command -v tmux || true)"
@@ -600,38 +1836,181 @@ sweep_dead_tmux_sockets() {
   return 0
 }
 
-# Stop the running session: kill the tmux session + the release BEAM, then sweep.
+# Reap stale aiur /tmp debris so a tmpfs /tmp can't fill from accumulated per-run
+# tempfiles and leaked test artifacts. Runs alongside sweep_dead_tmux_sockets on
+# foreground teardown (session_cleanup) and on `aiur stop`. Bounded and safe:
+#
+#   * Only exact top-level Aiur artifact families under the temp roots the engine
+#     and BEAM write to. Arbitrary operator worktrees/checkouts like
+#     `/tmp/aiur-pr490` are not candidates.
+#   * Age-gated by AIUR_TMP_REAP_MINUTES (default 1440 = 24h). An entry is removed
+#     only when NOTHING in its subtree was modified within the window, so a live
+#     run's shared debug dir (aiur-rc / aiur-claude-hooks / aiur-debug) holding a
+#     fresh file is spared even when the dir's own mtime is stale. A non-numeric or
+#     0 value disables the sweep.
+#   * Ownership-gated: if anything in the tree is not owned by the effective user,
+#     the whole tree is spared.
+#   * A live run's `aiur-<pid>-sessions|-agents` bookkeeping is kept while its pid
+#     is alive, regardless of age.
+is_aiur_tmp_artifact_candidate() {
+  local base="$1" pid
+  case "$base" in
+    aiur-argv.* | aiur-startup.* | aiur-pane.* | aiur-launcher.* | aiur-capture.* | \
+      aiur-trap.*.log | aiur-tree.*.json | aiur-wrapper.pid | aiur-*-frames.bin | \
+      aiur-rc | aiur-claude-hooks | aiur-debug)
+      return 0
+      ;;
+    aiur-*-sessions | aiur-*-agents)
+      pid="${base#aiur-}"
+      pid="${pid%-*}"
+      [ -n "$pid" ] && [ -z "${pid//[0-9]/}" ]
+      return
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+sweep_stale_tmp_artifacts() {
+  local minutes="${AIUR_TMP_REAP_MINUTES:-1440}"
+  case "$minutes" in '' | *[!0-9]*) return 0 ;; esac
+  [ "$minutes" -gt 0 ] || return 0
+
+  # The dirs the engine + BEAM target: ${TMPDIR:-/tmp} (argv/startup/pane tempfiles
+  # plus the BEAM's System.tmp_dir debug dirs) and ${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}
+  # (the session/agent pidfiles' session_root). Deduped — a typical box scans one dir.
+  local roots=() d seen
+  for d in "${TMPDIR:-/tmp}" "${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}"; do
+    [ -d "$d" ] || continue
+    seen=0
+    local root
+    if [ "${#roots[@]}" -gt 0 ]; then
+      for root in "${roots[@]}"; do
+        [ "$root" = "$d" ] && { seen=1; break; }
+      done
+    fi
+    [ "$seen" -eq 1 ] || roots+=("$d")
+  done
+  [ "${#roots[@]}" -gt 0 ] || return 0
+
+  local removed=0 path base pid uid found
+  uid="$(id -u)"
+  for d in "${roots[@]}"; do
+    while IFS= read -r -d '' path; do
+      base="${path##*/}"
+      is_aiur_tmp_artifact_candidate "$base" || continue
+
+      # Spare mixed-ownership trees; cleanup should never cross user boundaries.
+      if ! found="$(find "$path" ! -user "$uid" -print -quit 2>/dev/null)"; then
+        continue
+      fi
+      if [ -n "$found" ]; then
+        continue
+      fi
+      # Spare anything modified within the window anywhere in its subtree.
+      if ! found="$(find "$path" -mmin "-$minutes" -print -quit 2>/dev/null)"; then
+        continue
+      fi
+      if [ -n "$found" ]; then
+        continue
+      fi
+      # Spare a live run's session/agent bookkeeping (name is aiur-<pid>-<kind>).
+      case "$base" in
+        aiur-*-sessions | aiur-*-agents)
+          pid="${base#aiur-}"
+          pid="${pid%-*}"
+          if [ -n "$pid" ] && [ -z "${pid//[0-9]/}" ] && kill -0 "$pid" 2>/dev/null; then
+            continue
+          fi
+          ;;
+      esac
+      if rm -rf -- "$path" 2>/dev/null; then
+        removed=$((removed + 1))
+      fi
+    done < <(find "$d" -maxdepth 1 -mindepth 1 -name 'aiur-*' -print0 2>/dev/null)
+  done
+
+  [ "$removed" -gt 0 ] && echo "🧹 swept $removed stale aiur tmp artifact(s)" >&2
+  return 0
+}
+
+# Stop the running session: kill this instance's tmux + BEAM, then sweep.
 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}-default"
-  local socket="${AIUR_SESSION_PREFIX}-${USER:-user}"
-  if [ -n "$tmux_bin" ]; then
-    "$tmux_bin" -L "$socket" kill-session -t "$session" 2>/dev/null || true
+  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
 
-  local beam_pids pid waited=0
-  beam_pids="$(pgrep -f "$release_dir/.*erts.*beam.smp" 2>/dev/null || true)"
-  if [ -n "$beam_pids" ]; then
-    for pid in $beam_pids; do kill -TERM "$pid" 2>/dev/null || true; done
-    while [ $waited -lt 30 ]; do
-      beam_pids="$(pgrep -f "$release_dir/.*erts.*beam.smp" 2>/dev/null || true)"
-      [ -z "$beam_pids" ] && break
-      sleep 0.1
-      waited=$((waited + 1))
-    done
-    beam_pids="$(pgrep -f "$release_dir/.*erts.*beam.smp" 2>/dev/null || true)"
-    for pid in $beam_pids; do kill -KILL "$pid" 2>/dev/null || true; done
+  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
+  # watchdog removes the sentinel when it fires; a fresh start also clears it.
+  # Clear any prior crash marker too — `status` should report a clean stop, not
+  # a stale orphan from an earlier dead run.
+  mkdir -p "$AIUR_BG_STATE_DIR" 2>/dev/null || true
+  : >"$(aiur_stop_sentinel_path)" 2>/dev/null || true
+  rm -f "$(aiur_crash_marker_path)" 2>/dev/null || true
+
+  if [ -n "$tmux_bin" ]; then
+    "$tmux_bin" -L "$socket" kill-session -t "$session" 2>/dev/null || true
   fi
 
   # Reap any BEAM holding our node name regardless of which release dir launched
-  # it — orphans from a dev build or a prior install share the unified name.
+  # 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
+  # windows dies and no live aiur tmux server is left behind.
+  if [ -n "$tmux_bin" ]; then
+    "$tmux_bin" -L "$socket" kill-server 2>/dev/null || true
+  fi
+
+  # Belt-and-suspenders for a mid-turn stop: sweep any headless agent (this run
+  # or a prior crashed one) still recorded in a pidfile. comm-guarded, so a
+  # recycled pid is spared. Empty socket: the kill-server above already ran.
+  local session_root agentfile
+  session_root="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}"
+  for agentfile in "$session_root"/aiur-*-agents; do
+    [ -e "$agentfile" ] || continue
+    reap_aiur_agents "" "$agentfile"
+    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 ----------------------------------------------------------------
@@ -663,10 +2042,34 @@ aiur_engine_main() {
       shift
       cmd_status "$@"
       ;;
+    agents)
+      shift
+      cmd_agents "$@"
+      ;;
+    alerts)
+      shift
+      cmd_alerts "$@"
+      ;;
+    watch)
+      shift
+      cmd_watch "$@"
+      ;;
+    set)
+      shift
+      cmd_set "$@"
+      ;;
     pause | resume)
       shift
       cmd_pause_resume "$cmd" "$@"
       ;;
+    message)
+      shift
+      cmd_message "$@"
+      ;;
+    cleanup-stale)
+      shift
+      cmd_cleanup_stale "$@"
+      ;;
     stop)
       cmd_stop
       ;;