aiur-cli 0.0.3 → 0.0.5-nightly.24dcc4d

package/libexec/aiur-engine.sh

@@ -35,32 +35,237 @@ elif [ -n "${__aiur_hard_nofile}" ]; then
 fi
 unset __aiur_hard_nofile
 
+# Export the effective soft limit after the best-effort raise. The BEAM uses
+# this inherited value for FD-headroom admission on hosts without procfs,
+# avoiding a runtime `ulimit` subprocess precisely when descriptors are scarce.
+__aiur_soft_nofile="$(ulimit -Sn 2>/dev/null || echo)"
+if [[ "$__aiur_soft_nofile" =~ ^[0-9]+$ ]]; then
+  export AIUR_NOFILE_SOFT_LIMIT="$__aiur_soft_nofile"
+else
+  unset AIUR_NOFILE_SOFT_LIMIT
+fi
+unset __aiur_soft_nofile
+
+# Preserve the shell that initiated the run as a best-effort Executor root.
+# An explicit positive override wins (service managers may know a better root);
+# otherwise the engine's parent is the nearest identity available before tmux
+# hands daemon ownership to its pane launcher.
+if ! [[ "${AIUR_OPERATOR_PID:-}" =~ ^[1-9][0-9]*$ ]]; then
+  if [[ "${PPID:-}" =~ ^[1-9][0-9]*$ ]]; then
+    export AIUR_OPERATOR_PID="$PPID"
+  else
+    unset AIUR_OPERATOR_PID
+  fi
+fi
+
 die() {
   echo "❌ $*" >&2
   exit 1
 }
 
+legacy_config_path() {
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --logs-root | --host | --port | --max-agents)
+        if [ "$#" -ge 2 ]; then
+          shift 2
+        else
+          shift
+        fi
+        ;;
+      --)
+        shift
+        [ "$#" -gt 0 ] || return
+        case "$1" in
+          *.aiurconfig) printf '%s' "$1" ;;
+        esac
+        return
+        ;;
+      --logs-root=* | --host=* | --port=* | --max-agents=* | --*)
+        shift
+        ;;
+      *.aiurconfig)
+        printf '%s' "$1"
+        return
+        ;;
+      *)
+        # A positional non-legacy config is authoritative. Let the Elixir CLI
+        # validate it instead of rejecting an unrelated ambient legacy file.
+        return
+        ;;
+    esac
+  done
+
+  local target_root="${AIUR_REPO_ROOT:-}" home_real
+  home_real="$(cd "${HOME:-}" 2>/dev/null && pwd -P || printf '%s' "${HOME:-}")"
+
+  if [ -n "$target_root" ]; then
+    if [ -f "$target_root/.aiur/config" ]; then
+      return
+    fi
+    if [ -f "$target_root/.aiurconfig" ]; then
+      printf '%s' "$target_root/.aiurconfig"
+      return
+    fi
+  else
+    local pwd_real d
+    pwd_real="$(pwd -P 2>/dev/null || printf '%s' "$PWD")"
+    d="$pwd_real"
+
+    while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "$home_real" ]; do
+      if [ -f "$d/.aiur/config" ]; then
+        return
+      fi
+      if [ -f "$d/.aiurconfig" ]; then
+        printf '%s' "$d/.aiurconfig"
+        return
+      fi
+      d="$(dirname "$d")"
+    done
+  fi
+
+  if [ -n "$home_real" ] && [ ! -f "$home_real/.aiur/config" ] && [ -f "$home_real/.aiurconfig" ]; then
+    printf '%s' "$home_real/.aiurconfig"
+  fi
+}
+
+reject_legacy_config() {
+  local legacy legacy_basename canonical
+  legacy="$(legacy_config_path "$@")"
+  [ -z "$legacy" ] && return
+  legacy_basename="${legacy##*/}"
+
+  if [ "$legacy_basename" = ".aiurconfig" ]; then
+    canonical="$(dirname "$legacy")/.aiur/config"
+  else
+    canonical="${legacy%.aiurconfig}.yaml"
+  fi
+
+  die "$legacy is no longer supported. Move it to $canonical. Keep relative prompt_file and hooks_file paths valid from the new config directory."
+}
+
 engine_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
+package_version() {
+  local package_file="$1"
+  [ -r "$package_file" ] || return 1
+  sed -n 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$package_file" | head -n 1
+}
+
+cli_package_version() {
+  package_version "$engine_dir/../package.json"
+}
+
+version_is_older() {
+  local installed="$1" available="$2"
+  local installed_major installed_minor installed_patch installed_pre
+  local available_major available_minor available_patch available_pre
+
+  if [[ ! "$installed" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)(-([0-9A-Za-z.-]+))?(\+[0-9A-Za-z.-]+)?$ ]]; then return 1; fi
+  installed_major="${BASH_REMATCH[1]}"
+  installed_minor="${BASH_REMATCH[2]}"
+  installed_patch="${BASH_REMATCH[3]}"
+  installed_pre="${BASH_REMATCH[5]}"
+
+  if [[ ! "$available" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)(-([0-9A-Za-z.-]+))?(\+[0-9A-Za-z.-]+)?$ ]]; then return 1; fi
+  available_major="${BASH_REMATCH[1]}"
+  available_minor="${BASH_REMATCH[2]}"
+  available_patch="${BASH_REMATCH[3]}"
+  available_pre="${BASH_REMATCH[5]}"
+
+  [ "$installed_major" -lt "$available_major" ] ||
+    { [ "$installed_major" -eq "$available_major" ] && [ "$installed_minor" -lt "$available_minor" ]; } ||
+    { [ "$installed_major" -eq "$available_major" ] && [ "$installed_minor" -eq "$available_minor" ] && [ "$installed_patch" -lt "$available_patch" ]; } ||
+    {
+      [ "$installed_major" -eq "$available_major" ] &&
+        [ "$installed_minor" -eq "$available_minor" ] &&
+        [ "$installed_patch" -eq "$available_patch" ] &&
+        {
+          { [ -n "$installed_pre" ] && [ -z "$available_pre" ]; } ||
+            { [ -n "$installed_pre" ] && [ -n "$available_pre" ] && [[ "$installed_pre" < "$available_pre" ]]; }
+        }
+    }
+}
+
+warn_if_cli_behind_release_checkout() {
+  local stamp="${AIUR_RELEASE_DIR:-}/AIUR_BUILD_STAMP"
+  local repo_root installed_version checkout_version
+
+  [ -r "$stamp" ] || return 0
+  repo_root="$(sed -n 's/^repo_root=//p' "$stamp" | head -n 1)"
+  [ -n "$repo_root" ] || return 0
+
+  installed_version="$(cli_package_version || true)"
+  checkout_version="$(package_version "$repo_root/packaging/npm/aiur-cli/package.json" || true)"
+
+  if version_is_older "$installed_version" "$checkout_version"; then
+    echo "aiur: installed CLI $installed_version is older than checkout CLI $checkout_version; update aiur-cli before retrying" >&2
+  fi
+}
+
 # --- 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 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
-    if [ -f "$d/.aiur/config" ] || [ -f "$d/.aiurconfig" ]; then
+
+  # 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" ]; 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" ]; 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 +279,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 +294,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 +306,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"
 }
 
@@ -164,16 +374,35 @@ release_dir=""
 vsn_dir=""
 release_bin=""
 
+control_release_retry() {
+  [ -n "${AIUR_CONTROL_RELEASE_RETRY_SIGNAL:-}" ] && : >"$AIUR_CONTROL_RELEASE_RETRY_SIGNAL"
+  return 75
+}
+
 resolve_release() {
   release_dir="${AIUR_RELEASE_DIR:-}"
   [ -n "$release_dir" ] || die "AIUR_RELEASE_DIR is not set; the engine must be invoked via the aiur or aiurdev wrapper"
-  [ -d "$release_dir" ] || die "AIUR_RELEASE_DIR does not exist: $release_dir"
+  if [ ! -d "$release_dir" ]; then
+    # aiurdev uses EX_TEMPFAIL to wait out an in-place dev rebuild and retry
+    # exactly once. Product launches keep the existing fatal diagnostics.
+    if [ "${AIUR_CONTROL_RELEASE_RETRYABLE:-0}" = "1" ]; then
+      control_release_retry
+      return $?
+    fi
+    die "AIUR_RELEASE_DIR does not exist: $release_dir"
+  fi
 
   local release_vsn
-  release_vsn="$(cut -d' ' -f2 "$release_dir/releases/start_erl.data")"
+  release_vsn="$(cut -d' ' -f2 "$release_dir/releases/start_erl.data" 2>/dev/null || true)"
   vsn_dir="$release_dir/releases/$release_vsn"
   release_bin="$release_dir/bin/aiur"
-  [ -x "$vsn_dir/elixir" ] || die "release elixir launcher not found at $vsn_dir/elixir"
+  if [ -z "$release_vsn" ] || [ ! -x "$release_bin" ] || [ ! -x "$vsn_dir/elixir" ]; then
+    if [ "${AIUR_CONTROL_RELEASE_RETRYABLE:-0}" = "1" ]; then
+      control_release_retry
+      return $?
+    fi
+    die "release elixir launcher not found at $vsn_dir/elixir"
+  fi
 }
 
 # --- argv round-trip (System.argv is empty under `elixir --eval`) -------------
@@ -218,15 +447,40 @@ build_init_cmd() {
 
 usage() {
   cat <<'EOF'
-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 lean, headless detached tmux session
+Usage: aiur [--interactive] [--no-dashboard] [--executor] [--pause] [--max-agents <n>] [--logs-root <path>] [--port <port>] [--host <host>] [config-path]
+       aiur run [--bg] [--no-dashboard] [--executor] [--debug]  explicit launch form (foreground unless --bg)
+       aiur init [--force]   scaffold .aiur/config (interactive setup wizard)
+       aiur --bg [--no-dashboard] [--executor] [--debug]   start detached; dashboard on unless suppressed
        aiur stop             stop the running session
+       aiur restart [--no-build] [run flags]  stop, refresh the build, start again (detached)
        aiur status           show agent status
        aiur agents           show each agent's state + current activity
+       aiur commands [<decision-id>] [--filter all|open|blocking|resolved] [--blocking] [--ticket <id>] [--search <text>] [--cursor <cursor>] [--limit <n>] [--json]
+       aiur executor-answer <decision-id> --expected-version <n> (--option <id>|--custom-response <text>) --rationale <text> --idempotency-key <key> [--executor-id <id>]
+       aiur executor-escalate <decision-id> --expected-version <n> --reason <text> [--executor-id <id>]
+       aiur units [--scope live|unfinished|all|none] [--condition active|alert|paused|queued|finished]... [--format auto|table|records] [--json]
+       aiur build-orders [<root>] [--json]  show the Build Order catalog or one root
+       aiur analytics [--range run|full] [--since <ISO-8601>] [--until <ISO-8601>] [--build-order <id>] [--json]
+       aiur alerts [--needs-attention]  show structured alert feed
+       aiur watch [--full|--changes] [--interval <secs>]  server-side status board
+       aiur executor-listen [--topic <pattern>]  stream Executor events as JSON lines
+       aiur executor-wait [--timeout <seconds>] [--json]  block until Executor work arrives
+       aiur executor-emit <topic> --payload <json>  publish an Executor event
+       aiur executor-subscribe|executor-unsubscribe <pattern>
+       aiur executor-subscriptions  list persistent Executor bindings
        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 pause | resume             flip the global pause switch (whole daemon)
+       aiur pause <ids|--all> | resume <ids|--all>  per-agent pause/resume
+       aiur message <id> <text>  send Executor text to a running agent
+       aiur --todo <ids...> [--only]  queue tickets; optionally dequeue all other pending tickets
+       aiur findings [--unfiled] [--slugs] [--scope aiur|repo]  inspect host-local findings
+       aiur findings --record <json> --repo <owner/repo>  append one validated finding
+       aiur findings --digest [--scope aiur|repo]  generate the promoted Markdown digest
+       aiur guard-pr-deletions [base-branch]  refuse PRs with excessive untouched deletions
+       aiur ask <title> [--body <text>|--body-file <path>] [--urgency low|normal|high] [--blocking]
+       aiur ask --done <id> [--note <text>]  create or resolve an operator request
+       aiur asks [--open|--all] [--json]  inspect current-repository operator requests
+       aiur cleanup-stale [--dry-run]  list/reap stale manual-smoke leftovers
        aiur --version
 EOF
 }
@@ -235,6 +489,8 @@ EOF
 
 run_version() {
   resolve_release
+  AIUR_CLI_VERSION="$(cli_package_version || true)"
+  export AIUR_CLI_VERSION
   # Distribution-free (like init): printing the version is a compile-time
   # constant, so never claim the node name — otherwise `aiur --version` fails
   # whenever an aiur session is already running.
@@ -256,16 +512,81 @@ run_init() {
   exec "${release_cmd[@]}"
 }
 
+# --- one-shot: --todo (control RPC; requires a running daemon) ----------------
+
+parsed_todo_only=0
+
+parse_todo_args() {
+  parsed_targets=()
+  parsed_todo_only=0
+
+  local saw_todo=0 raw part parts
+  for raw in "$@"; do
+    case "$raw" in
+      --todo)
+        [ "$saw_todo" -eq 0 ] || return 1
+        saw_todo=1
+        ;;
+      --only)
+        parsed_todo_only=1
+        ;;
+      -*)
+        return 1
+        ;;
+      *)
+        IFS=',' read -ra parts <<<"$raw"
+        for part in "${parts[@]}"; do
+          part="$(trim "$part")"
+          if [ -z "$part" ] || [[ ! "$part" =~ ^[0-9]+$ ]]; then return 1; fi
+          while [ "${#part}" -gt 1 ] && [ "${part#0}" != "$part" ]; do
+            part="${part#0}"
+          done
+          parsed_targets+=("$part")
+        done
+        ;;
+    esac
+  done
+
+  [ "$saw_todo" -eq 1 ] && [ "${#parsed_targets[@]}" -gt 0 ]
+}
+
+run_todo() {
+  if ! parse_todo_args "$@"; then
+    echo "aiur: --todo expects one or more numeric issue IDs, optionally followed by --only" >&2
+    exit 64
+  fi
+
+  local only_arg="false"
+  [ "$parsed_todo_only" -eq 1 ] && only_arg="true"
+  run_control_rpc "Aiur.AgentControlCLI.todo($(elixir_list_literal "${parsed_targets[@]}"), only: $only_arg, emit_exit_marker: true)"
+}
+
+# --- one-shot: findings (distribution-free, no daemon/tmux) -------------------
+
+run_findings() {
+  run_init "$@"
+}
+
+# --- one-shot: ask / asks (distribution-free, no daemon/tmux) ----------------
+
+run_asks() {
+  run_init "$@"
+}
+
 # --- interactive / background run -------------------------------------------
 #
 # mode=foreground attaches the UI and tears down on exit; mode=background leaves
 # the detached tmux session running and returns.
 
-# Load KEY=VALUE pairs from ./.env into the environment so the running release
-# (e.g. GITHUB_TOKEN, dashboard creds) sees what `aiur init` scaffolded there.
-# An already-exported variable always wins, so a shell export overrides the file.
+# Load operator/machine credentials before repo-local settings. Since each file
+# only fills unset names, shell exports win first, then ~/.aiur/.env, then ./.env.
 load_dotenv() {
-  local file=".env" line key val
+  load_dotenv_file "$HOME/.aiur/.env"
+  load_dotenv_file ".env"
+}
+
+load_dotenv_file() {
+  local file="$1" line key val
   [ -f "$file" ] || return 0
   while IFS= read -r line || [ -n "$line" ]; do
     line="${line#"${line%%[![:space:]]*}"}"
@@ -285,6 +606,56 @@ load_dotenv() {
   done <"$file"
 }
 
+# The readiness token grants the one-shot `aiur init` assessment access that a
+# normal daemon and its child agents must never inherit. Keep dotenv loading
+# generic, then remove this run-only secret before any session process starts.
+scrub_run_only_env() {
+  unset AIUR_CI_READINESS_TOKEN
+}
+
+run_argv=()
+# Default dashboard bind host. Prefer this machine's Tailscale IPv4 so the
+# dashboard is reachable across the tailnet by default (when config omits it);
+# fall back to loopback when Tailscale is absent, or when dashboard credentials
+# are unset (a non-loopback bind requires them, so we stay on loopback rather
+# than refuse to start). The BEAM applies this below an explicit `server.host`,
+# while an explicit `--host` remains the highest-precedence value.
+default_dashboard_host() {
+  local ip=""
+  if command -v tailscale >/dev/null 2>&1; then
+    ip="$(tailscale ip -4 2>/dev/null | grep -m1 -E '^100\.[0-9]+\.[0-9]+\.[0-9]+$' || true)"
+  fi
+  if [ -n "$ip" ] && [ -n "${AIUR_DASHBOARD_USERNAME:-}" ] && [ -n "${AIUR_DASHBOARD_PASSWORD:-}" ]; then
+    printf '%s' "$ip"
+  else
+    printf '127.0.0.1'
+  fi
+}
+
+build_run_argv() {
+  local mode="$1"
+  shift
+
+  local has_interactive=0 has_headless=0 has_ack=0 arg
+  for arg in "$@"; do
+    case "$arg" in
+      --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=()
+  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)
+
+  run_argv=("${injected[@]}" "$@")
+}
+
 run_session() {
   local mode="$1"
   shift
@@ -311,34 +682,25 @@ run_session() {
   # Pick up GITHUB_TOKEN / dashboard creds the wizard wrote to ./.env so the
   # running tracker can authenticate. Shell exports still take precedence.
   load_dotenv
+  scrub_run_only_env
+  export AIUR_DEFAULT_DASHBOARD_HOST="$(default_dashboard_host)"
 
   init_argv_file
 
-  # 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
+  # Supply the flags a bare `aiur` needs: UI mode and the no-guardrails ack.
+  # The exported dashboard host fills only a missing config value; an explicit
+  # server.host or --host remains authoritative. Foreground runs are
+  # interactive; `--bg` runs headless (no panes/chat backfill) and is driven
+  # over the control RPC (status/agents/message/pause/set). Dashboard binding is
+  # independent: it remains enabled in either mode unless `--no-dashboard` is
+  # supplied. `aiur --bg --interactive` opts back into the full terminal stack
+  # for an attachable background session.
+  build_run_argv "$mode" "$@"
+  local no_dashboard=0
+  for run_arg in "${run_argv[@]}"; do
+    [ "$run_arg" = "--no-dashboard" ] && no_dashboard=1
   done
-  local injected=()
-  [ "$has_host" -eq 1 ] || injected+=(--host 127.0.0.1)
-  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[@]}" "$@"
+  write_argv "${run_argv[@]}"
   export AIUR_ARGV_FILE="$argv_file"
 
   prepare_distribution
@@ -355,6 +717,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 +736,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
@@ -382,6 +751,17 @@ run_session() {
     export AIUR_LOGS_ROOT
   fi
 
+  # Capture an erl_crash.dump on daemon BEAM death (#852) so a crash under load
+  # is diagnosable instead of vanishing. Written next to the run's aiur.log so it
+  # survives the launcher's tempfile cleanup; ERL_CRASH_DUMP_SECONDS bounds the
+  # write so a wedged BEAM can't hang the dump indefinitely. Nothing in the
+  # release boot disables dumps, and an Executor override of either var is kept.
+  # Requires a durable logs root (background run or agent IR sandbox).
+  if [ -n "${AIUR_LOGS_ROOT:-}" ]; then
+    export ERL_CRASH_DUMP="${ERL_CRASH_DUMP:-$AIUR_LOGS_ROOT/erl_crash.dump}"
+    export ERL_CRASH_DUMP_SECONDS="${ERL_CRASH_DUMP_SECONDS:-30}"
+  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
@@ -401,13 +781,15 @@ run_session() {
   {
     printf '#!/usr/bin/env bash\n'
     printf 'set -o pipefail\n'
+    printf 'unset AIUR_CI_READINESS_TOKEN\n'
     printf 'cd %q || exit 1\n' "$PWD"
     local v
     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_DEFAULT_DASHBOARD_HOST AIUR_DEBUG \
+      AIUR_OPERATOR_PID AIUR_NOFILE_SOFT_LIMIT ERL_CRASH_DUMP ERL_CRASH_DUMP_SECONDS; do
       if [ -n "${!v:-}" ]; then printf 'export %s=%q\n' "$v" "${!v}"; fi
     done
     printf 'capture=%q\n' "$startup_capture"
@@ -424,7 +806,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 +816,14 @@ 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 a record only when none exists. A live session's own start already
+      # wrote one — and it owns the BEAM-written AIUR_RECORD_WORKSPACE_ROOT_FILE
+      # path, which must not be overwritten by this invocation's temp file.
+      [ -f "$(aiur_instance_record_path)" ] || (AIUR_WORKSPACE_ROOT_FILE="" 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 +861,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 +870,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 +882,17 @@ 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"
+  print_dashboard_status "$no_dashboard" "$startup_capture"
+
+  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 +902,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 +918,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 +965,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
@@ -596,7 +1229,7 @@ agent_pid_matches() {
 #
 # 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
+# never touching the Executor’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.
@@ -643,6 +1276,35 @@ 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_WORKSPACE_ROOT_FILE=%q\n' "${AIUR_WORKSPACE_ROOT_FILE:-}"
+    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,24 +1352,128 @@ record_beam_crash() {
   fi
 }
 
-# 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
-# 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() {
+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"
+}
+
+workspace_root_file_from_instance_record() {
+  load_aiur_instance_record "$(aiur_instance_record_path)" || return 1
+  [ -n "${AIUR_RECORD_WORKSPACE_ROOT_FILE:-}" ] || return 1
+  printf '%s\n' "$AIUR_RECORD_WORKSPACE_ROOT_FILE"
+}
+
+# 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:-}"
+  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,13 +1496,17 @@ 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' "$!"
 }
 
 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'
+  # The Orchestrator starts before the dashboard child, so an answering status
+  # call alone does not prove startup (or the bind attempt) finished. Wait until
+  # OTP marks :aiur started before printing the effective dashboard status.
+  expression='aiur_started = Enum.any?(Application.started_applications(), fn {app, _description, _version} -> app == :aiur end); case {Process.whereis(Aiur.Orchestrator), aiur_started} do {pid, true} 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)"
@@ -750,11 +1520,51 @@ probe_control_liveness() {
   fi
 }
 
+# Return the useful URL and effective bind host/port only when the running node
+# confirms that Bandit actually bound a listener. An empty result means the
+# listener was suppressed or refused; configured server.port alone is never
+# proof of service.
+probe_dashboard_status() {
+  local expression output status marker="__AIUR_DASHBOARD_STATUS__:"
+  expression='case {Aiur.HttpServer.base_url(), Aiur.Config.server_host(), Aiur.HttpServer.bound_port()} do {url, host, port} when is_binary(url) and is_binary(host) and is_integer(port) -> IO.puts("__AIUR_DASHBOARD_STATUS__:Dashboard: " <> url <> " (bind host=" <> host <> ", port=" <> Integer.to_string(port) <> ")"); _ -> :ok end'
+
+  set +e
+  run_release_rpc_with_timeout "$expression"
+  status=$?
+  set -e
+  output="$AIUR_CONTROL_RPC_OUTPUT"
+
+  if [ "$status" -eq 0 ] && [[ "$output" == *"$marker"* ]]; then
+    output="${output#*"$marker"}"
+    printf '%s' "${output%%$'\n'*}"
+  fi
+}
+
+print_dashboard_status() {
+  local no_dashboard="$1" startup_capture="$2" dashboard_status
+
+  if [ "$no_dashboard" -eq 1 ]; then
+    echo "Dashboard disabled by --no-dashboard." >&2
+    return
+  fi
+
+  dashboard_status="$(probe_dashboard_status)"
+  if [ -n "$dashboard_status" ]; then
+    echo "${dashboard_status}" >&2
+  else
+    echo "⚠️ dashboard listener unavailable; inspect ${startup_capture} for bind or authentication refusal." >&2
+  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}"
+    # 0.1s per tick. The old 100-tick (10s) budget was under a cold control
+    # plane's real boot time, so a healthy daemon was killed mid-startup and
+    # reported as a failure. Boot time grows with the module count; keep the
+    # headroom generous, since the loop exits as soon as the probe says "up".
+    max_ticks="${AIUR_NODE_GRACE_TICKS:-1200}"
   fi
 
   for ((tick = 0; tick < max_ticks; tick++)); do
@@ -778,7 +1588,16 @@ wait_for_session_startup() {
   done
 
   if [ "$require_control" = "1" ]; then
-    echo "❌ aiur control plane did not become ready at ${RELEASE_NODE:-unknown} during startup; captured output:" >&2
+    # A live session at this point means the BEAM never died -- we ran out of
+    # patience, not the daemon out of health. Saying so is the difference
+    # between "your release is broken" and "give it longer", and the empty
+    # capture below is evidence of the latter, not of a silent crash.
+    if "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null; then
+      echo "❌ aiur control plane at ${RELEASE_NODE:-unknown} was still booting after $(awk "BEGIN{printf \"%.0f\", ${max_ticks} / 10}")s; the BEAM is alive but not yet answering." >&2
+      echo "   Raise the budget with AIUR_NODE_GRACE_TICKS (ticks of 0.1s) if this box is just slow." >&2
+    else
+      echo "❌ aiur control plane did not become ready at ${RELEASE_NODE:-unknown} during startup; captured output:" >&2
+    fi
     tail -n 30 "$startup_capture" 2>/dev/null | sed 's/^/  /' >&2 || true
     return 1
   fi
@@ -789,7 +1608,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 +1638,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 +1670,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 +1716,281 @@ 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_WORKSPACE_ROOT_FILE=""
+  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() {
+  [ -n "${AIUR_CONTROL_HINT_ROOTS:-}" ] || return 0
+  [ "${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
+  echo "aiur: live launch directory candidate(s):" >&2
+  printf '%s' "$AIUR_CONTROL_HINT_ROOTS" | sed '/^$/d; s/^/  /' >&2
+}
+
+control_rpc_timeout_seconds() {
+  local seconds="${AIUR_CONTROL_RPC_TIMEOUT_SECONDS:-10}"
+  case "$seconds" in
+    '' | *[!0-9]* | 0) seconds=10 ;;
+  esac
+  printf '%s' "$seconds"
+}
+
+print_not_running_message() {
+  echo "error: aiur is not running. Start it with \`aiurdev run\` (or \`aiurdev --bg\`), then retry." >&2
+}
+
+print_control_down_message() {
+  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
+    print_not_running_message
+    print_global_config_control_hint
+  fi
+}
+
+kill_control_rpc_process() {
+  local pid="$1" grouped="$2" p tree=()
+  [ -n "$pid" ] || return 0
+
+  # Snapshot descendants before signalling the wrapper. A release launcher may
+  # fork its rpc BEAM into another process group and then exit; group signalling
+  # alone would orphan that child and lose the only relationship we can reap.
+  while IFS= read -r p; do tree+=("$p"); done < <(agent_pid_tree "$pid")
+
+  if [ "$grouped" = "1" ]; then
+    kill -TERM "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+  fi
+
+  for p in "${tree[@]}"; do kill -TERM "$p" 2>/dev/null || true; done
+  sleep 0.2
+  if [ "$grouped" = "1" ]; then
+    kill -KILL "-$pid" 2>/dev/null || true
+  fi
+  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
+  if [ -f "$timeout_file" ]; then
+    # The timeout watchdog owns descendant cleanup. Once it has marked the
+    # timeout, let it finish its TERM/KILL sequence; cancelling it here can
+    # strand descendants that ignored TERM after the root process exits.
+    :
+  else
+    kill "$watchdog_pid" 2>/dev/null || true
+  fi
+  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"
+}
+
+control_command_label() {
+  printf '%s' "${AIUR_CONTROL_COMMAND:-control rpc}"
+}
+
+# Every line a control RPC surfaces to the operator routes through one of these
+# two helpers, so `run_control_rpc` can prove it never returns non-zero while
+# saying nothing (#1684): a silent failure is indistinguishable from a healthy
+# idle fleet, and nobody reads exit codes interactively.
+control_rpc_say() {
+  AIUR_CONTROL_RPC_DIAGNOSED=1
+  printf '%s\n' "$1" >&2
+}
+
+control_rpc_echo_output() {
+  [ -n "$1" ] || return 0
+  AIUR_CONTROL_RPC_DIAGNOSED=1
+  printf '%s\n' "$1" >&2
+}
+
 # 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.
+#
+# Wrapper contract: a non-zero return ALWAYS carries at least one stderr line
+# naming the command that failed. EX_TEMPFAIL (75) is exempt — it is the dev
+# shim's internal rebuild-and-retry signal, never an operator-visible outcome.
 run_control_rpc() {
+  local status=0
+
+  AIUR_CONTROL_RPC_DIAGNOSED=0
+  run_control_rpc_dispatch "$@" || status=$?
+
+  if [ "$status" -ne 0 ] && [ "$status" -ne 75 ] && [ "${AIUR_CONTROL_RPC_DIAGNOSED:-0}" -ne 1 ]; then
+    if [ "$status" -eq 124 ]; then
+      control_rpc_say "aiur: $(control_command_label) to ${RELEASE_NODE:-the daemon} timed out after $(control_rpc_timeout_seconds)s; outcome is unknown. The daemon did not reply within the budget - commonly one blocked process inside it, not host load. 'aiur alerts' is answered by a different process and can confirm the daemon is alive."
+    else
+      control_rpc_say "aiur: $(control_command_label) failed (exit ${status}) and produced no diagnostic output; outcome is unknown. 'aiur alerts' is answered by a different process and can confirm the daemon is alive."
+    fi
+  fi
+
+  return "$status"
+}
+
+run_control_rpc_dispatch() {
   local expression="$1"
-  resolve_release
+  resolve_release || return $?
   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
+  local marker="__AIUR_CONTROL_EXIT__:" error_marker="__AIUR_CONTROL_ERROR__:"
+  local output status exit_code=0 saw_marker=0 saw_error=0 saw_output=0 line partial_suffix=""
 
   set +e
-  output="$("$release_bin" rpc "$expression" 2>&1)"
+  run_release_rpc_with_timeout "$expression"
   status=$?
+  output="$AIUR_CONTROL_RPC_OUTPUT"
   set -e
 
+  if [ "$status" -ne 0 ] && [ "${AIUR_CONTROL_RELEASE_RETRYABLE:-0}" = "1" ] && \
+    { [ ! -x "$release_bin" ] || [ ! -x "$vsn_dir/elixir" ] || [ ! -r "$release_dir/releases/start_erl.data" ]; }; then
+    control_release_retry
+    return $?
+  fi
+
+  if [ "${AIUR_CONTROL_RPC_TIMED_OUT:-0}" -eq 1 ]; then
+    [ -n "$output" ] && partial_suffix="; partial output was discarded"
+    control_rpc_say "aiur: $(control_command_label) to ${RELEASE_NODE} timed out after $(control_rpc_timeout_seconds)s; outcome is unknown${partial_suffix}. Commonly one blocked process inside the daemon, not host load."
+    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)
@@ -915,25 +2000,31 @@ run_control_rpc() {
     # 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.
+    #
+    # An empty buffer is its own case: `--rpc-eval` kills itself without a word
+    # when the evaluated expression exits (a GenServer call timing out against a
+    # saturated daemon does exactly that), so "see the error above" would point
+    # at nothing (#1684). Name the failure instead.
     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
-        fi
+        print_control_down_message
+        AIUR_CONTROL_RPC_DIAGNOSED=1
         ;;
       up)
-        [ -n "$output" ] && printf '%s\n' "$output" >&2
-        echo "aiur: rpc to ${RELEASE_NODE} failed (node is running); see the error above" >&2
+        control_rpc_echo_output "$output"
+        if [ -n "$output" ]; then
+          control_rpc_say "aiur: $(control_command_label) failed against ${RELEASE_NODE} (node is running); see the error above"
+        else
+          control_rpc_say "aiur: $(control_command_label) failed against ${RELEASE_NODE} with no diagnostic output (node is running); outcome is unknown. 'aiur alerts' is answered by a different process and can confirm the daemon is alive."
+        fi
         ;;
       *)
-        [ -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
+        control_rpc_echo_output "$output"
+        if [ -n "$output" ]; then
+          control_rpc_say "aiur: $(control_command_label) failed against ${RELEASE_NODE} (could not query epmd to confirm node state); see the error above"
+        else
+          control_rpc_say "aiur: $(control_command_label) failed against ${RELEASE_NODE} with no output (could not query epmd to confirm node state)"
+        fi
         ;;
     esac
     return 1
@@ -945,15 +2036,55 @@ run_control_rpc() {
         saw_marker=1
         exit_code="${line#"$marker"}"
         ;;
+      "$error_marker"*)
+        saw_error=1
+        AIUR_CONTROL_RPC_DIAGNOSED=1
+        printf '%s\n' "${line#"$error_marker"}" >&2
+        ;;
       :ok | "") ;;
-      *) printf '%s\n' "$line" ;;
+      *)
+        saw_output=1
+        AIUR_CONTROL_RPC_DIAGNOSED=1
+        printf '%s\n' "$line"
+        ;;
     esac
   done <<<"$output"
 
-  [ "$saw_marker" -eq 1 ] || return 1
+  if [ "$saw_marker" -ne 1 ]; then
+    control_rpc_say "aiur: $(control_command_label) to ${RELEASE_NODE} returned no exit marker; command output may be incomplete"
+    return 1
+  fi
+
+  if [ "$exit_code" -ne 0 ] && [ "$saw_error" -ne 1 ] && [ "$saw_output" -ne 1 ]; then
+    control_rpc_say "aiur: $(control_command_label) failed with exit ${exit_code} and returned no diagnostic output"
+  fi
+
   return "$exit_code"
 }
 
+# A streaming Executor listener must retain the RPC process and its stdout. It
+# intentionally bypasses the one-shot control timeout and exit-marker wrapper.
+run_control_stream() {
+  local expression="$1"
+  resolve_release || return $?
+  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
+  if [ "$(probe_node_liveness)" = "down" ]; then
+    print_control_down_message
+    return 1
+  fi
+  if "$release_bin" rpc "$expression"; then
+    return 0
+  else
+    local status=$?
+    echo "aiur: streaming control RPC failed with exit ${status}" >&2
+    return "$status"
+  fi
+}
+
 elixir_list_literal() {
   local first=1 item
   printf '['
@@ -997,11 +2128,26 @@ cmd_status() {
   run_control_rpc "Aiur.AgentControlCLI.status()"
 }
 
+# `aiur usage` — Codex/Claude limit headroom from the daemon's meter
+# projection, each value carrying the age of its observation.
+cmd_usage() {
+  [ "$#" -eq 0 ] || die "usage does not accept arguments"
+  run_control_rpc "Aiur.AgentControlCLI.usage()"
+}
+
 cmd_pause_resume() {
   local command="$1"
   shift
+
+  # Bare `aiur pause` / `aiur resume` (no IDs, no --all) flips the single
+  # global pause switch: a daemon-wide halt distinct from per-agent pause.
+  if [ "$#" -eq 0 ]; then
+    run_control_rpc "Aiur.AgentControlCLI.${command}_global()"
+    return
+  fi
+
   if ! parse_issue_targets "$@"; then
-    echo "aiur: $command expects issue IDs or --all (e.g. aiur $command 44 45,46; aiur $command --all)" >&2
+    echo "aiur: $command expects issue IDs or --all (e.g. aiur $command 44 45,46; aiur $command --all; or bare aiur $command for the global switch)" >&2
     exit 64
   fi
 
@@ -1015,7 +2161,28 @@ cmd_pause_resume() {
   run_control_rpc "$expression"
 }
 
-# `aiur message <issue> <text>` — deliver operator text to one running agent.
+# `aiur reset-budget <id>...` — clear the lifetime dispatch latch for one or
+# more tickets (the supported exit from the #1453 latch; no JSON hand-editing).
+cmd_reset_budget() {
+  if ! parse_issue_targets "$@"; then
+    echo "aiur: reset-budget expects issue IDs (e.g. aiur reset-budget 44 45,46)" >&2
+    exit 64
+  fi
+
+  # --all is rejected (exit 64 with guidance) rather than silently no-opping:
+  # clearing every ticket's latch at once is not a documented operation and
+  # would mask which tickets are structurally stuck (#1453 review P2d).
+  if [ "$parsed_all" -eq 1 ]; then
+    echo "aiur: reset-budget does not accept --all; name ticket IDs explicitly (e.g. aiur reset-budget 44 45,46)" >&2
+    exit 64
+  fi
+
+  local expression
+  expression="Aiur.AgentControlCLI.reset_budget($(elixir_list_literal "${parsed_targets[@]}"))"
+  run_control_rpc "$expression"
+}
+
+# `aiur message <issue> <text>` — deliver Executor 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() {
@@ -1046,6 +2213,431 @@ cmd_agents() {
   run_control_rpc "Aiur.AgentControlCLI.agents()"
 }
 
+# `aiur commands` — read the dashboard's retained Decision projection without
+# exposing any dispatch or answer mutation path.
+cmd_commands() {
+  local filter="all" blocking=0 json=0 decision_id="" ticket="" search="" cursor="" limit="" arg
+
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --filter) [ "$#" -gt 1 ] || { echo "aiur: commands --filter requires a value" >&2; exit 64; }; shift; filter="$1" ;;
+      --filter=*) filter="${arg#--filter=}" ;;
+      --blocking) blocking=1 ;;
+      --ticket) [ "$#" -gt 1 ] || { echo "aiur: commands --ticket requires a value" >&2; exit 64; }; shift; ticket="$1" ;;
+      --ticket=*) ticket="${arg#--ticket=}" ;;
+      --search) [ "$#" -gt 1 ] || { echo "aiur: commands --search requires a value" >&2; exit 64; }; shift; search="$1" ;;
+      --search=*) search="${arg#--search=}" ;;
+      --cursor) [ "$#" -gt 1 ] || { echo "aiur: commands --cursor requires a value" >&2; exit 64; }; shift; cursor="$1" ;;
+      --cursor=*) cursor="${arg#--cursor=}" ;;
+      --limit) [ "$#" -gt 1 ] || { echo "aiur: commands --limit requires a value" >&2; exit 64; }; shift; limit="$1" ;;
+      --limit=*) limit="${arg#--limit=}" ;;
+      --json) json=1 ;;
+      -*) echo "aiur: commands received an unknown option: $arg" >&2; exit 64 ;;
+      *)
+        if [ -n "$decision_id" ]; then
+          echo "aiur: commands accepts at most one decision ID" >&2
+          exit 64
+        fi
+        decision_id="$arg"
+        ;;
+    esac
+    shift
+  done
+
+  case "$filter" in all|open|blocking|resolved) ;; *) echo "aiur: commands --filter accepts all, open, blocking, or resolved" >&2; exit 64 ;; esac
+  [ -z "$limit" ] || [[ "$limit" =~ ^[1-9][0-9]*$ ]] || { echo "aiur: commands --limit expects a positive integer" >&2; exit 64; }
+  [ -z "$ticket" ] || [ "$filter" = "all" ] || { echo "aiur: commands --ticket requires --filter all" >&2; exit 64; }
+  [ -z "$search" ] || [ "$filter" = "all" ] || { echo "aiur: commands --search requires --filter all" >&2; exit 64; }
+
+  local opts="filter: :$filter"
+  [ "$blocking" -eq 1 ] && opts="$opts, blocking: true"
+  [ "$json" -eq 1 ] && opts="$opts, json: true"
+  [ -n "$limit" ] && opts="$opts, limit: $limit"
+  local key raw encoded
+  for key in decision_id ticket search cursor; do
+    raw="${!key}"
+    [ -n "$raw" ] || continue
+    encoded="$(printf '%s' "$raw" | base64 | tr -d '\n')"
+    opts="$opts, $key: Base.decode64!(\"$encoded\")"
+  done
+
+  run_control_rpc "Aiur.AgentControlCLI.commands([$opts])"
+}
+
+encode_control_value() {
+  printf '%s' "$1" | base64 | tr -d '\n'
+}
+
+# These are explicit trusted-Executor mutations, deliberately separate from
+# the read-only `commands` catalog. Revisions remain dashboard-owned.
+cmd_executor_answer() {
+  local decision_id="${1:-}" expected_version="" option_id="" custom_response="" rationale="" idempotency_key="" executor_id="aiur-cli" arg
+  if [ -z "$decision_id" ] || [[ "$decision_id" = -* ]]; then
+    echo "aiur: executor-answer expects exactly one decision ID" >&2
+    exit 64
+  fi
+  shift
+
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --expected-version) [ "$#" -gt 1 ] || { echo "aiur: executor-answer --expected-version requires a value" >&2; exit 64; }; shift; expected_version="$1" ;;
+      --expected-version=*) expected_version="${arg#--expected-version=}" ;;
+      --option) [ "$#" -gt 1 ] || { echo "aiur: executor-answer --option requires a value" >&2; exit 64; }; shift; option_id="$1" ;;
+      --option=*) option_id="${arg#--option=}" ;;
+      --custom-response) [ "$#" -gt 1 ] || { echo "aiur: executor-answer --custom-response requires a value" >&2; exit 64; }; shift; custom_response="$1" ;;
+      --custom-response=*) custom_response="${arg#--custom-response=}" ;;
+      --rationale) [ "$#" -gt 1 ] || { echo "aiur: executor-answer --rationale requires a value" >&2; exit 64; }; shift; rationale="$1" ;;
+      --rationale=*) rationale="${arg#--rationale=}" ;;
+      --idempotency-key) [ "$#" -gt 1 ] || { echo "aiur: executor-answer --idempotency-key requires a value" >&2; exit 64; }; shift; idempotency_key="$1" ;;
+      --idempotency-key=*) idempotency_key="${arg#--idempotency-key=}" ;;
+      --executor-id) [ "$#" -gt 1 ] || { echo "aiur: executor-answer --executor-id requires a value" >&2; exit 64; }; shift; executor_id="$1" ;;
+      --executor-id=*) executor_id="${arg#--executor-id=}" ;;
+      -*) echo "aiur: executor-answer received an unknown option: $arg" >&2; exit 64 ;;
+      *) echo "aiur: executor-answer expects exactly one decision ID" >&2; exit 64 ;;
+    esac
+    shift
+  done
+
+  [[ "$expected_version" =~ ^[1-9][0-9]*$ ]] || { echo "aiur: executor-answer --expected-version expects a positive integer" >&2; exit 64; }
+  if { [ -n "$option_id" ] && [ -n "$custom_response" ]; } || { [ -z "$option_id" ] && [ -z "$custom_response" ]; }; then
+    echo "aiur: executor-answer requires exactly one of --option or --custom-response" >&2
+    exit 64
+  fi
+  [ -n "$rationale" ] || { echo "aiur: executor-answer --rationale is required" >&2; exit 64; }
+  [ -n "$idempotency_key" ] || { echo "aiur: executor-answer --idempotency-key is required" >&2; exit 64; }
+  [ -n "$executor_id" ] || { echo "aiur: executor-answer --executor-id must not be empty" >&2; exit 64; }
+
+  local opts="decision_id: Base.decode64!(\"$(encode_control_value "$decision_id")\"), expected_version: $expected_version"
+  if [ -n "$option_id" ]; then
+    opts="$opts, option_id: Base.decode64!(\"$(encode_control_value "$option_id")\")"
+  else
+    opts="$opts, custom_response: Base.decode64!(\"$(encode_control_value "$custom_response")\")"
+  fi
+  opts="$opts, rationale: Base.decode64!(\"$(encode_control_value "$rationale")\")"
+  opts="$opts, idempotency_key: Base.decode64!(\"$(encode_control_value "$idempotency_key")\")"
+  opts="$opts, executor_id: Base.decode64!(\"$(encode_control_value "$executor_id")\")"
+  run_control_rpc "Aiur.AgentControlCLI.executor_answer([$opts])"
+}
+
+cmd_executor_escalate() {
+  local decision_id="${1:-}" expected_version="" reason="" executor_id="aiur-cli" arg
+  if [ -z "$decision_id" ] || [[ "$decision_id" = -* ]]; then
+    echo "aiur: executor-escalate expects exactly one decision ID" >&2
+    exit 64
+  fi
+  shift
+
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --expected-version) [ "$#" -gt 1 ] || { echo "aiur: executor-escalate --expected-version requires a value" >&2; exit 64; }; shift; expected_version="$1" ;;
+      --expected-version=*) expected_version="${arg#--expected-version=}" ;;
+      --reason) [ "$#" -gt 1 ] || { echo "aiur: executor-escalate --reason requires a value" >&2; exit 64; }; shift; reason="$1" ;;
+      --reason=*) reason="${arg#--reason=}" ;;
+      --executor-id) [ "$#" -gt 1 ] || { echo "aiur: executor-escalate --executor-id requires a value" >&2; exit 64; }; shift; executor_id="$1" ;;
+      --executor-id=*) executor_id="${arg#--executor-id=}" ;;
+      -*) echo "aiur: executor-escalate received an unknown option: $arg" >&2; exit 64 ;;
+      *) echo "aiur: executor-escalate expects exactly one decision ID" >&2; exit 64 ;;
+    esac
+    shift
+  done
+
+  [[ "$expected_version" =~ ^[1-9][0-9]*$ ]] || { echo "aiur: executor-escalate --expected-version expects a positive integer" >&2; exit 64; }
+  [ -n "$reason" ] || { echo "aiur: executor-escalate --reason is required" >&2; exit 64; }
+  [ -n "$executor_id" ] || { echo "aiur: executor-escalate --executor-id must not be empty" >&2; exit 64; }
+
+  local opts="decision_id: Base.decode64!(\"$(encode_control_value "$decision_id")\"), expected_version: $expected_version"
+  opts="$opts, reason: Base.decode64!(\"$(encode_control_value "$reason")\")"
+  opts="$opts, executor_id: Base.decode64!(\"$(encode_control_value "$executor_id")\")"
+  run_control_rpc "Aiur.AgentControlCLI.executor_escalate([$opts])"
+}
+
+# `aiur units` — read the dashboard Units catalog through its own projection,
+# including non-running tickets in current-run membership.
+cmd_units() {
+  local scope="live" format="" json=0 arg condition condition_value condition_encoded conditions_literal=""
+  local -a conditions=() condition_values=()
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --scope) [ "$#" -gt 1 ] || { echo "aiur: units --scope requires a value" >&2; exit 64; }; shift; scope="$1" ;;
+      --scope=*) scope="${arg#--scope=}" ;;
+      --condition) [ "$#" -gt 1 ] || { echo "aiur: units --condition requires a value" >&2; exit 64; }; shift; conditions+=("$1") ;;
+      --condition=*) conditions+=("${arg#--condition=}") ;;
+      --format) [ "$#" -gt 1 ] || { echo "aiur: units --format requires a value" >&2; exit 64; }; shift; format="$1" ;;
+      --format=*) format="${arg#--format=}" ;;
+      --json) json=1 ;;
+      -*) echo "aiur: units received an unknown option: $arg" >&2; exit 64 ;;
+      *) echo "aiur: units does not accept positional arguments" >&2; exit 64 ;;
+    esac
+    shift
+  done
+
+  for condition in "${conditions[@]+"${conditions[@]}"}"; do
+    IFS=',' read -r -a condition_values <<< "$condition"
+    for condition_value in "${condition_values[@]+"${condition_values[@]}"}"; do
+      if [ -n "$conditions_literal" ]; then conditions_literal="$conditions_literal, "; fi
+      condition_encoded="$(printf '%s' "$condition_value" | base64 | tr -d '\n')"
+      conditions_literal="${conditions_literal}Base.decode64!(\"${condition_encoded}\")"
+    done
+  done
+
+  local scope_encoded
+  scope_encoded="$(printf '%s' "$scope" | base64 | tr -d '\n')"
+  local opts="scope: Base.decode64!(\"$scope_encoded\")"
+  [ -z "$conditions_literal" ] || opts="$opts, conditions: [$conditions_literal]"
+
+  if [ -n "$format" ]; then
+    local format_encoded
+    format_encoded="$(printf '%s' "$format" | base64 | tr -d '\n')"
+    opts="$opts, format: Base.decode64!(\"$format_encoded\")"
+  fi
+
+  [ "$json" -eq 1 ] && opts="$opts, json: true"
+  run_control_rpc "Aiur.AgentControlCLI.units([$opts])"
+}
+
+# `aiur build-orders` — read the dashboard Build Order projection without a
+# second GitHub or API derivation. A root selector switches from catalog to the
+# selected-root graph view.
+cmd_build_orders() {
+  local json=0 root="" arg
+
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --json) json=1 ;;
+      -*) echo "aiur: build-orders received an unknown option: $arg" >&2; exit 64 ;;
+      *)
+        if [ -n "$root" ]; then
+          echo "aiur: build-orders accepts at most one root" >&2
+          exit 64
+        fi
+        root="$arg"
+        ;;
+    esac
+    shift
+  done
+
+  local opts=""
+  [ "$json" -eq 1 ] && opts="json: true"
+
+  if [ -n "$root" ]; then
+    local encoded
+    encoded="$(printf '%s' "$root" | base64 | tr -d '\n')"
+    [ -n "$opts" ] && opts="$opts, "
+    opts="${opts}root: Base.decode64!(\"$encoded\")"
+  fi
+
+  run_control_rpc "Aiur.AgentControlCLI.build_orders([$opts])"
+}
+
+# `aiur analytics` — render the dashboard analytics projection for an explicit
+# time window. This is read-only and obtains the same durable telemetry snapshot
+# the page uses through the running node.
+cmd_analytics() {
+  local range="run" json=0 since="" until="" build_order="" has_build_order=0 arg
+
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --range) [ "$#" -gt 1 ] || { echo "aiur: analytics --range requires a value" >&2; exit 64; }; shift; range="$1" ;;
+      --range=*) range="${arg#--range=}" ;;
+      --since) [ "$#" -gt 1 ] || { echo "aiur: analytics --since requires a value" >&2; exit 64; }; shift; since="$1" ;;
+      --since=*) since="${arg#--since=}" ;;
+      --until) [ "$#" -gt 1 ] || { echo "aiur: analytics --until requires a value" >&2; exit 64; }; shift; until="$1" ;;
+      --until=*) until="${arg#--until=}" ;;
+      --build-order) [ "$#" -gt 1 ] || { echo "aiur: analytics --build-order requires a value" >&2; exit 64; }; shift; build_order="$1"; has_build_order=1 ;;
+      --build-order=*) build_order="${arg#--build-order=}"; has_build_order=1 ;;
+      --json) json=1 ;;
+      -*) echo "aiur: analytics received an unknown option: $arg" >&2; exit 64 ;;
+      *) echo "aiur: analytics does not accept positional arguments" >&2; exit 64 ;;
+    esac
+    shift
+  done
+
+  case "$range" in run|full) ;; *) echo "aiur: analytics --range accepts run or full" >&2; exit 64 ;; esac
+  [ "$has_build_order" -eq 0 ] || [[ "$build_order" =~ ^[0-9]+$ ]] || { echo "aiur: analytics --build-order expects a numeric ticket ID" >&2; exit 64; }
+
+  local opts="range: :$range" key raw encoded
+  [ "$json" -eq 1 ] && opts="$opts, json: true"
+  for key in since until build_order; do
+    raw="${!key}"
+    [ -n "$raw" ] || continue
+    encoded="$(printf '%s' "$raw" | base64 | tr -d '\n')"
+    opts="$opts, $key: Base.decode64!(\"$encoded\")"
+  done
+
+  run_control_rpc "Aiur.AgentControlCLI.analytics([$opts])"
+}
+
+# `aiur alerts` — newline-delimited structured alert feed from persisted
+# per-agent logs. `--needs-attention` filters to Executor-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
+}
+
+cmd_executor_listen() {
+  local topic="executor.#" arg
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --topic) shift; topic="${1:-}" ;;
+      --topic=*) topic="${arg#--topic=}" ;;
+      *) echo "aiur: executor-listen accepts --topic <pattern>" >&2; exit 64 ;;
+    esac
+    [ -n "$topic" ] || { echo "aiur: executor-listen requires a topic" >&2; exit 64; }
+    shift
+  done
+  local encoded
+  encoded="$(printf '%s' "$topic" | base64 | tr -d '\n')"
+  run_control_stream "Aiur.AgentControlCLI.executor_listen(topic: Base.decode64!(\"$encoded\"))"
+}
+
+cmd_executor_wait() {
+  local timeout=300 json=0 arg
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --timeout) shift; timeout="${1:-}" ;;
+      --timeout=*) timeout="${arg#--timeout=}" ;;
+      --json) json=1 ;;
+      *) echo "aiur: executor-wait accepts --timeout <seconds> and --json" >&2; exit 64 ;;
+    esac
+    shift
+  done
+  [[ "$timeout" =~ ^[1-9][0-9]*$ ]] || { echo "aiur: executor-wait --timeout expects a positive integer" >&2; exit 64; }
+  local json_arg=false
+  if [ "$json" -eq 1 ]; then json_arg=true; fi
+  AIUR_CONTROL_COMMAND="executor-wait"
+  AIUR_CONTROL_RPC_TIMEOUT_SECONDS=$((timeout + 10)) run_control_rpc "Aiur.AgentControlCLI.executor_wait(timeout_ms: $((timeout * 1000)), json: $json_arg)"
+}
+
+cmd_executor_emit() {
+  local topic="${1:-}" payload="" arg
+  shift 2>/dev/null || true
+  [ -n "$topic" ] || { echo "aiur: executor-emit requires a topic" >&2; exit 64; }
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --payload) shift; payload="${1:-}" ;;
+      --payload=*) payload="${arg#--payload=}" ;;
+      *) echo "aiur: executor-emit accepts only --payload <json>" >&2; exit 64 ;;
+    esac
+    shift
+  done
+  [ -n "$payload" ] || { echo "aiur: executor-emit requires --payload <json>" >&2; exit 64; }
+  local topic_encoded payload_encoded
+  topic_encoded="$(printf '%s' "$topic" | base64 | tr -d '\n')"
+  payload_encoded="$(printf '%s' "$payload" | base64 | tr -d '\n')"
+  run_control_rpc "Aiur.AgentControlCLI.executor_emit(Base.decode64!(\"$topic_encoded\"), Base.decode64!(\"$payload_encoded\"))"
+}
+
+cmd_executor_subscription() {
+  local action="$1" topic="${2:-}"
+  [ -n "$topic" ] && [ "$#" -eq 2 ] || { echo "aiur: $action requires one topic pattern" >&2; exit 64; }
+  local encoded
+  encoded="$(printf '%s' "$topic" | base64 | tr -d '\n')"
+  case "$action" in
+    executor-subscribe) run_control_rpc "Aiur.AgentControlCLI.executor_subscribe(Base.decode64!(\"$encoded\"))" ;;
+    executor-unsubscribe) run_control_rpc "Aiur.AgentControlCLI.executor_unsubscribe(Base.decode64!(\"$encoded\"))" ;;
+  esac
+}
+
+cmd_executor_subscriptions() {
+  [ "$#" -eq 0 ] || { echo "aiur: executor-subscriptions does not accept arguments" >&2; exit 64; }
+  run_control_rpc "Aiur.AgentControlCLI.executor_subscriptions()"
+}
+
+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() {
@@ -1098,7 +2690,7 @@ sweep_dead_tmux_sockets() {
 # 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
+#     and BEAM write to. Arbitrary Executor 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
@@ -1192,15 +2784,72 @@ sweep_stale_tmp_artifacts() {
   return 0
 }
 
+# A stop only reaps the daemon whose node name matches this project root's
+# instance key (keys are sha256(project_root), so instances can't reap each
+# other). A daemon launched from a different directory therefore survives a stop
+# invoked elsewhere — the silent orphan that keeps holding the dashboard port and
+# serving stale code/credentials. Surface it loudly (we warn, not reap, to
+# respect the deliberate isolation) so the operator can stop it explicitly.
+warn_other_aiur_daemons() {
+  local self_node="$1" me pids pid cmd node port found=0
+  me="${USER:-$(id -un 2>/dev/null)}"
+  pids="$(pgrep -u "$me" -f -- "-name aiur-${me}" 2>/dev/null || true)"
+  for pid in $pids; do
+    cmd="$(pid_command "$pid")"
+    case "$cmd" in *beam.smp*) : ;; *) continue ;; esac
+    node="$(printf '%s' "$cmd" | grep -oE -- '-name [^ ]+' | awk '{print $2}' | head -1)"
+    [ -z "$node" ] && continue
+    [ "$node" = "$self_node" ] && continue
+    port="$(ss -tlnpH 2>/dev/null | awk -v p="pid=$pid," '$0 ~ p {print $4}' \
+      | grep -oE '[0-9]+$' | head -1 || true)"
+    if [ "$found" -eq 0 ]; then
+      echo "aiur: heads up — another aiur daemon is still running that this stop did not touch" >&2
+      echo "      (launched from a different directory, so it has a different instance key):" >&2
+      found=1
+    fi
+    echo "      pid=$pid node=$node${port:+ dashboard-port=$port} — stop it with:  kill $pid" >&2
+  done
+}
+
+# Set when cmd_stop returns nonzero only because there was nothing to stop. It
+# lets a caller (cmd_restart) tell that benign outcome apart from a stop that
+# failed for a real reason, without changing `aiur stop`'s own exit code.
+AIUR_STOP_FOUND_NOTHING=0
+
 # Stop the running session: kill this instance's tmux + BEAM, then sweep.
 cmd_stop() {
+  AIUR_STOP_FOUND_NOTHING=0
   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_file
+  workspace_root_file="$(workspace_root_file_from_instance_record 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
+    warn_other_aiur_daemons "$AIUR_RELEASE_NODE"
+    print_global_config_control_hint
+    AIUR_STOP_FOUND_NOTHING=1
+    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 +2868,11 @@ 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. The launcher's instance
+  # record points to the BEAM-written root handoff, so degraded stop never has
+  # to wait for an overloaded daemon before it starts tearing workers down.
+  reap_workspace_cwd_from_file "$workspace_root_file"
+
   # 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,14 +2892,248 @@ 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
+  warn_other_aiur_daemons "$AIUR_RELEASE_NODE"
+}
+
+# Stop, refresh the release, start again — `aiur restart`.
+#
+# The refresh deliberately runs BETWEEN the stop and the start. A dev rebuild
+# rewrites the release directory in place, and a BEAM booted from that directory
+# is exactly what the control-retry path (EX_TEMPFAIL) exists to survive; doing
+# it while the daemon is down means the new daemon boots from a release nothing
+# else is holding half-written.
+#
+# The engine itself never knows how to build: the installed CLI runs a pinned
+# platform release with no source tree beside it, so its restart is a plain
+# bounce. The dev shim supplies its build-if-stale step through
+# AIUR_RESTART_BUILD_CMD, a shell command line run via `bash -c` so the wrapper
+# (not this parser) owns quoting.
+aiur_restart_daemon_state="untouched"
+
+# Everything between the stop and a confirmed start runs with this armed, so the
+# operator hears about a fleet that is down no matter which step failed — a
+# rebuild, a missing tmux, a BEAM that would not boot, or a Ctrl-C during the
+# minutes-long rebuild. Naming only the step that failed would let "aiur failed
+# to start" read as "nothing changed", which is the silently stopped fleet.
+aiur_restart_report_state() {
+  [ "$aiur_restart_daemon_state" = "stopped" ] || return 0
+
+  # release_dir is resolved by the stop; fall back to the caller's declared dir
+  # for the paths that fail before that.
+  local dir="${release_dir:-${AIUR_RELEASE_DIR:-}}"
+
+  echo "aiur: the daemon is STOPPED and was NOT restarted" >&2
+  if [ -n "$dir" ] && [ -x "$dir/bin/aiur" ]; then
+    echo "aiur: fix the cause and run 'aiur restart' again, or 'aiur restart --no-build' to start" >&2
+    echo "      on the release already on disk" >&2
+  else
+    # The dev builder removes an incomplete release, so after a failed rebuild
+    # there is nothing for --no-build to start. Advertising it anyway would cost
+    # the operator a second failed cycle while the fleet stays down.
+    echo "aiur: no complete release is left on disk, so --no-build has nothing to start —" >&2
+    echo "      fix the build and run 'aiur restart' again" >&2
+  fi
+}
+
+# The rebuild runs in a process this command cannot see into, so "the builder
+# exited 0" is not the same claim as "the release I am about to boot is the one
+# it just built" — a wrapper pointed at another checkout satisfies the first and
+# not the second, which is exactly how a bounce ships a stale release while every
+# step reports success. The builder leaves a receipt naming the release dir it
+# vouches for and the commit it built from; this checks both against the release
+# on disk. Anything unverifiable is reported as unverifiable, never as success.
+verify_restart_build() {
+  local receipt="$1"
+  local built_dir built_sha stamped_sha stamp target_dir
+
+  if [ ! -s "$receipt" ]; then
+    echo "aiur: the rebuild left no build receipt, so restart cannot confirm which" >&2
+    echo "      release it produced" >&2
+    return 1
+  fi
+
+  built_dir="$(sed -n 's/^release_dir=//p' "$receipt" | head -n 1)"
+  built_sha="$(sed -n 's/^source_sha=//p' "$receipt" | head -n 1)"
+
+  # Fail on the missing field rather than on whatever an empty one happens to
+  # compare equal to further down.
+  if [ -z "$built_dir" ] || [ -z "$built_sha" ]; then
+    echo "aiur: the build receipt is malformed; restart cannot confirm what was built" >&2
+    return 1
+  fi
+
+  # Compare canonical paths: the builder and this engine can reach the same
+  # release through different symlinked parents.
+  built_dir="$(cd -P "$built_dir" 2>/dev/null && pwd || printf '%s' "$built_dir")"
+  target_dir="$(cd -P "${AIUR_RELEASE_DIR:-}" 2>/dev/null && pwd || printf '%s' "${AIUR_RELEASE_DIR:-}")"
+
+  if [ "$built_dir" != "$target_dir" ]; then
+    echo "aiur: the rebuild targeted a different release than the one about to boot" >&2
+    echo "      rebuilt : $built_dir" >&2
+    echo "      booting : $target_dir" >&2
+    return 1
+  fi
+
+  stamp="$target_dir/AIUR_BUILD_STAMP"
+  if [ ! -r "$stamp" ]; then
+    echo "aiur: the release carries no build stamp, so restart cannot confirm it is" >&2
+    echo "      the one just built ($stamp)" >&2
+    return 1
+  fi
+
+  stamped_sha="$(sed -n 's/^source_sha=//p' "$stamp" | head -n 1)"
+  if [ "$stamped_sha" != "$built_sha" ]; then
+    echo "aiur: the release on disk was not built from the commit the rebuild reported" >&2
+    echo "      rebuild reported : $built_sha" >&2
+    echo "      release stamped  : $stamped_sha" >&2
+    return 1
+  fi
+
+  # Say what was actually established. "verified ... built from unknown" would be
+  # a silent-pass guard reporting success over a release it cannot identify, and
+  # a dirty tree means the SHA is a floor rather than an identity.
+  if [ "$stamped_sha" = "unknown" ]; then
+    echo "aiur: release $target_dir matches the rebuild, but its source commit is" >&2
+    echo "      unknown (built outside a git work tree) — provenance unverified" >&2
+    return 0
+  fi
+
+  if [ "$(sed -n 's/^dirty=//p' "$stamp" | head -n 1)" = "yes" ]; then
+    echo "aiur: release $target_dir built from $stamped_sha with uncommitted changes" >&2
+    return 0
+  fi
+
+  echo "aiur: verified release $target_dir built from $stamped_sha" >&2
+}
+
+cmd_restart() {
+  local skip_build=0 arg
+  local run_args=()
+
+  # Refuse a stale config before stopping a healthy daemon. dispatch_run also
+  # checks this for ordinary launches, but restart mutates state before it gets
+  # that far.
+  reject_legacy_config "$@"
+
+  for arg in "$@"; do
+    case "$arg" in
+      --no-build) skip_build=1 ;;
+      *) run_args+=("$arg") ;;
+    esac
+  done
+
+  # Restarting something that is already down is a start, not an error: the
+  # operator asked for a running daemon on current code, and that is what they
+  # get. Any OTHER stop failure is fatal — building and starting on top of a
+  # half-stopped instance is the in-place rewrite this ordering exists to avoid.
+  local stop_status=0
+  cmd_stop || stop_status=$?
+  if [ "$stop_status" -ne 0 ]; then
+    if [ "${AIUR_STOP_FOUND_NOTHING:-0}" -eq 1 ]; then
+      echo "aiur: nothing was running; restart will start a fresh session" >&2
+    else
+      die "restart aborted: stop failed (exit $stop_status); the daemon may still be running"
+    fi
+  fi
+
+  # cmd_stop's tmux teardown is best-effort (`|| true`), so a stop can report
+  # success while the session survives. Starting from there would rebuild the
+  # release under a live BEAM and then hit run_session's idempotent "already
+  # running" return — exit 0, stale release, no bounce. Refuse instead.
+  # release_bin is unset only when the stop was stubbed out, i.e. in tests.
+  if [ -n "${release_bin:-}" ] && [ "$(probe_control_liveness)" = "up" ]; then
+    die "restart aborted: the previous session still answers after the stop; nothing was rebuilt or restarted"
+  fi
+
+  aiur_restart_daemon_state="stopped"
+  trap aiur_restart_report_state EXIT INT TERM
+
+  if [ -n "${AIUR_RESTART_BUILD_CMD:-}" ] && [ "$skip_build" -eq 0 ]; then
+    local build_status=0 receipt
+    receipt="$(mktemp "${TMPDIR:-/tmp}/aiur-restart-receipt.XXXXXX")"
+    AIUR_RESTART_BUILD_RECEIPT="$receipt" bash -c "$AIUR_RESTART_BUILD_CMD" || build_status=$?
+    if [ "$build_status" -ne 0 ]; then
+      # Exit with the builder's own status rather than a flat 1, so a caller can
+      # still tell a failed rebuild from any other abort.
+      rm -f "$receipt"
+      echo "❌ restart aborted before start: the rebuild failed" >&2
+      aiur_restart_report_state
+      trap - EXIT INT TERM
+      exit "$build_status"
+    fi
+
+    # A builder that declares AIUR_RESTART_BUILD_VERIFIES has promised a receipt,
+    # so a missing or contradicted one is a real failure and an unverifiable
+    # rebuild is not a lesser success — starting anyway would hand back the
+    # stale-release outcome this ordering exists to prevent, with a "restarted"
+    # line on top of it. A builder that makes no such promise cannot be held to
+    # it; say plainly that the guarantee did not apply rather than convert an
+    # unknown wrapper into a stopped fleet.
+    if [ "${AIUR_RESTART_BUILD_VERIFIES:-0}" = "1" ]; then
+      local verify_status=0
+      verify_restart_build "$receipt" || verify_status=$?
+      rm -f "$receipt"
+      if [ "$verify_status" -ne 0 ]; then
+        echo "❌ restart aborted before start: the rebuild could not be verified" >&2
+        # Naming the builder makes an inherited AIUR_RESTART_BUILD_CMD — a dev
+        # shim leaking into another shell — diagnosable from this output alone,
+        # instead of an identical refusal on every retry.
+        echo "   rebuild command: ${AIUR_RESTART_BUILD_CMD}" >&2
+        echo "   Rebuild from the checkout you mean and retry, or 'aiur restart --no-build'" >&2
+        echo "   to start the release on disk without the guarantee." >&2
+        aiur_restart_report_state
+        trap - EXIT INT TERM
+        exit 70
+      fi
+    else
+      rm -f "$receipt"
+      echo "aiur: UNVERIFIED rebuild — this builder reports no receipt, so restart" >&2
+      echo "      cannot confirm the release it is about to boot is the one just built" >&2
+    fi
+  elif [ "$skip_build" -eq 1 ]; then
+    echo "aiur: --no-build — restarting on the release already on disk" >&2
+  fi
+
+  # Always detached: the daemon this stopped was itself detached, and a restart
+  # that captured the terminal would be a surprise. `--interactive` still opts
+  # into the attachable session (`aiur --bg --interactive`), and a purely
+  # foreground restart remains `aiur stop && aiur run`.
+  dispatch_run --bg "${run_args[@]+"${run_args[@]}"}"
+
+  aiur_restart_daemon_state="running"
+  trap - EXIT INT TERM
 }
 
 # --- dispatch ----------------------------------------------------------------
 
+dispatch_run() {
+  local mode="foreground" arg
+  local args=()
+
+  reject_legacy_config "$@"
+
+  for arg in "$@"; do
+    if [ "$arg" = "--bg" ]; then
+      mode="background"
+    else
+      args+=("$arg")
+    fi
+  done
+
+  # bash 3.2 (macOS default) errors on "${args[@]}" when args is empty under
+  # `set -u` — happens for a bare `--bg` run. Guard the expansion.
+  run_session "$mode" "${args[@]+"${args[@]}"}"
+}
+
 aiur_engine_main() {
   local cmd="${1:-}"
+  # Names the running subcommand in control-RPC diagnostics so a failure says
+  # which command failed instead of a generic "control rpc" (#1684).
+  AIUR_CONTROL_COMMAND="${cmd:-run}"
   case "$cmd" in
     __identity)
       aiur_print_identity
@@ -1256,25 +3144,97 @@ aiur_engine_main() {
     --version)
       run_version "$@"
       ;;
+    --todo)
+      run_todo "$@"
+      ;;
+    --only)
+      echo "aiur: --only is valid only with --todo" >&2
+      exit 64
+      ;;
     init)
       run_init "$@"
       ;;
-    --bg)
+    findings)
+      run_findings "$@"
+      ;;
+    guard-pr-deletions)
       shift
-      run_session background "$@"
+      "$engine_dir/guard-pr-deletions.sh" "$@"
+      ;;
+    ask | asks)
+      run_asks "$@"
+      ;;
+    --bg)
+      dispatch_run "$@"
       ;;
     run)
       shift
-      run_session foreground "$@"
+      dispatch_run "$@"
       ;;
     status)
       shift
       cmd_status "$@"
       ;;
+    usage)
+      shift
+      cmd_usage "$@"
+      ;;
     agents)
       shift
       cmd_agents "$@"
       ;;
+    commands)
+      shift
+      cmd_commands "$@"
+      ;;
+    executor-answer)
+      shift
+      cmd_executor_answer "$@"
+      ;;
+    executor-escalate)
+      shift
+      cmd_executor_escalate "$@"
+      ;;
+    units)
+      shift
+      cmd_units "$@"
+      ;;
+    build-orders)
+      shift
+      cmd_build_orders "$@"
+      ;;
+    analytics)
+      shift
+      cmd_analytics "$@"
+      ;;
+    alerts)
+      shift
+      cmd_alerts "$@"
+      ;;
+    watch)
+      shift
+      cmd_watch "$@"
+      ;;
+    executor-listen)
+      shift
+      cmd_executor_listen "$@"
+      ;;
+    executor-wait)
+      shift
+      cmd_executor_wait "$@"
+      ;;
+    executor-emit)
+      shift
+      cmd_executor_emit "$@"
+      ;;
+    executor-subscribe | executor-unsubscribe)
+      shift
+      cmd_executor_subscription "$cmd" "$@"
+      ;;
+    executor-subscriptions)
+      shift
+      cmd_executor_subscriptions "$@"
+      ;;
     set)
       shift
       cmd_set "$@"
@@ -1283,26 +3243,39 @@ aiur_engine_main() {
       shift
       cmd_pause_resume "$cmd" "$@"
       ;;
+    reset-budget)
+      shift
+      cmd_reset_budget "$@"
+      ;;
     message)
       shift
       cmd_message "$@"
       ;;
+    cleanup-stale)
+      shift
+      cmd_cleanup_stale "$@"
+      ;;
     stop)
       cmd_stop
       ;;
+    restart)
+      shift
+      cmd_restart "$@"
+      ;;
     "")
-      run_session foreground
+      dispatch_run
       ;;
     -*)
       # leading-flag forms (e.g. `aiur --interactive <config>`) are a run
-      run_session foreground "$@"
+      dispatch_run "$@"
       ;;
     *)
       # a path/config argument is a run; anything else is a usage error
       if [ -e "$cmd" ]; then
-        run_session foreground "$@"
+        dispatch_run "$@"
       else
         echo "aiur: unknown command: $cmd" >&2
+        warn_if_cli_behind_release_checkout
         usage >&2
         exit 64
       fi