aiur-cli 0.0.4 → 0.0.5-nightly.cd08c27

package/libexec/aiur-engine.sh

@@ -35,19 +35,180 @@ 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 used to key this instance. AIUR_REPO_ROOT (set by the dev
 # shim) wins. Otherwise walk up from $PWD to the first dir holding a REPO-LOCAL
-# config — but the walk STOPS at $HOME: the global config at ~/.aiur/config (legacy
-# ~/.aiurconfig) is not a repo root, and treating it as one would collapse every
+# 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
@@ -71,7 +232,7 @@ aiur_project_root() {
 
   local d="$pwd_real"
   while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "$home_real" ]; do
-    if [ -f "$d/.aiur/config" ] || [ -f "$d/.aiurconfig" ]; then
+    if [ -f "$d/.aiur/config" ]; then
       printf '%s' "$d"
       return
     fi
@@ -90,7 +251,7 @@ aiur_project_root_source() {
 
   local d="$pwd_real"
   while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "$home_real" ]; do
-    if [ -f "$d/.aiur/config" ] || [ -f "$d/.aiurconfig" ]; then
+    if [ -f "$d/.aiur/config" ]; then
       printf 'repo'
       return
     fi
@@ -213,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`) -------------
@@ -267,17 +447,39 @@ 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
@@ -287,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.
@@ -308,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:]]*}"}"
@@ -337,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
@@ -363,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
@@ -441,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
@@ -460,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 AIUR_WORKSPACE_ROOT_FILE \
-      ELIXIR_ERL_OPTIONS AIUR_LOGS_ROOT AIUR_OPENCODE_BRIDGE_PORT AIUR_DEBUG; do
+      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"
@@ -493,7 +816,10 @@ run_session() {
   # session whose BEAM/control plane is gone should be reclaimed before retry.
   if [ "$mode" = "background" ] && "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null; then
     if [ "$(probe_control_liveness)" = "up" ]; then
-      write_aiur_instance_record "$session" "$socket"
+      # 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
@@ -561,6 +887,7 @@ run_session() {
   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
@@ -902,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.
@@ -969,6 +1296,7 @@ write_aiur_instance_record() {
     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)"
@@ -1121,24 +1449,10 @@ reap_workspace_cwd_from_file() {
   reap_workspace_cwd_agents "$root"
 }
 
-current_workspace_root() {
-  resolve_release
-  prepare_distribution >/dev/null 2>&1 || return 1
-
-  local output status line
-  set +e
-  output="$("$release_bin" rpc "IO.puts(Aiur.Config.workspace_root())" 2>/dev/null)"
-  status=$?
-  set -e
-  [ "$status" -eq 0 ] || return 1
-
-  while IFS= read -r line; do
-    case "$line" in
-      "" | :ok) continue ;;
-      *) printf '%s\n' "$line"; return 0 ;;
-    esac
-  done <<<"$output"
-  return 1
+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
@@ -1189,7 +1503,10 @@ start_beam_death_watchdog() {
 
 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)"
@@ -1203,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
@@ -1231,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
@@ -1364,6 +1730,7 @@ load_aiur_instance_record() {
   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
@@ -1445,15 +1812,14 @@ $root
 }
 
 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
-  if [ -n "${AIUR_CONTROL_HINT_ROOTS:-}" ]; then
-    echo "aiur: live launch directory candidate(s):" >&2
-    printf '%s' "$AIUR_CONTROL_HINT_ROOTS" | sed '/^$/d; s/^/  /' >&2
-  fi
+  echo "aiur: live launch directory candidate(s):" >&2
+  printf '%s' "$AIUR_CONTROL_HINT_ROOTS" | sed '/^$/d; s/^/  /' >&2
 }
 
 control_rpc_timeout_seconds() {
@@ -1464,20 +1830,41 @@ control_rpc_timeout_seconds() {
   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
-    sleep 0.2
-    kill -KILL "-$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true
-    return 0
   fi
 
-  while IFS= read -r p; do tree+=("$p"); done < <(agent_pid_tree "$pid")
   for p in "${tree[@]}"; do kill -TERM "$p" 2>/dev/null || true; done
   sleep 0.2
+  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
 }
 
@@ -1510,7 +1897,14 @@ run_release_rpc_with_timeout() {
   else
     status=$?
   fi
-  kill "$watchdog_pid" 2>/dev/null || true
+  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)"
@@ -1525,19 +1919,66 @@ run_release_rpc_with_timeout() {
   return "$status"
 }
 
+control_command_label() {
+  printf '%s' "${AIUR_CONTROL_COMMAND:-control rpc}"
+}
+
+control_attempt_sentence() {
+  [ -n "${AIUR_CONTROL_ATTEMPT_CONTEXT:-}" ] || return 0
+  printf ' Attempted %s against daemon endpoint %s.' "$AIUR_CONTROL_ATTEMPT_CONTEXT" "${RELEASE_NODE:-unknown}"
+}
+
+# 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.$(control_attempt_sentence) 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."
+    elif [ -n "${AIUR_CONTROL_ATTEMPT_CONTEXT:-}" ]; then
+      control_rpc_say "aiur: $(control_command_label) failed (exit ${status}) and produced no diagnostic output.$(control_attempt_sentence) Outcome is unknown. '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
   run_release_rpc_with_timeout "$expression"
@@ -1545,9 +1986,15 @@ run_control_rpc() {
   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" ] && printf '%s\n' "$output" >&2
-    echo "aiur: control rpc to ${RELEASE_NODE} timed out after $(control_rpc_timeout_seconds)s; helper process was terminated" >&2
+    [ -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}.$(control_attempt_sentence) Commonly one blocked process inside the daemon, not host load."
     return 124
   fi
 
@@ -1560,26 +2007,35 @@ 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
-          print_global_config_control_hint
-        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"
+        elif [ -n "${AIUR_CONTROL_ATTEMPT_CONTEXT:-}" ]; then
+          control_rpc_say "aiur: $(control_command_label) failed against ${RELEASE_NODE} with no diagnostic output (node is running).$(control_attempt_sentence) Outcome is unknown. 'aiur alerts' is answered by a different process and can confirm the daemon is alive."
+        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"
+        elif [ -n "${AIUR_CONTROL_ATTEMPT_CONTEXT:-}" ]; then
+          control_rpc_say "aiur: $(control_command_label) failed against ${RELEASE_NODE} with no output (could not query epmd to confirm node state).$(control_attempt_sentence) Outcome is unknown."
+        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
@@ -1591,19 +2047,63 @@ 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"
 
   if [ "$saw_marker" -ne 1 ]; then
-    echo "aiur: control rpc to ${RELEASE_NODE} returned no exit marker; command output may be incomplete" >&2
+    if [ -n "${AIUR_CONTROL_ATTEMPT_CONTEXT:-}" ]; then
+      control_rpc_say "aiur: $(control_command_label) to ${RELEASE_NODE} returned no exit marker; command output may be incomplete.$(control_attempt_sentence)"
+    else
+      control_rpc_say "aiur: $(control_command_label) to ${RELEASE_NODE} returned no exit marker; command output may be incomplete"
+    fi
     return 1
   fi
 
+  if [ "$exit_code" -ne 0 ] && [ "$saw_error" -ne 1 ] && [ "$saw_output" -ne 1 ]; then
+    if [ -n "${AIUR_CONTROL_ATTEMPT_CONTEXT:-}" ]; then
+      control_rpc_say "aiur: $(control_command_label) failed with exit ${exit_code} and produced no diagnostic output.$(control_attempt_sentence) Outcome is unknown."
+    else
+      control_rpc_say "aiur: $(control_command_label) failed with exit ${exit_code} and returned no diagnostic output"
+    fi
+  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 '['
@@ -1647,11 +2147,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
 
@@ -1665,7 +2180,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() {
@@ -1696,8 +2232,270 @@ 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")\")"
+  local AIUR_CONTROL_ATTEMPT_CONTEXT="decision ID ${decision_id} with expected version ${expected_version}"
+  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")\")"
+  local AIUR_CONTROL_ATTEMPT_CONTEXT="decision ID ${decision_id} with expected version ${expected_version}"
+  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 operator-actionable alerts.
+# per-agent logs. `--needs-attention` filters to Executor-actionable alerts.
 cmd_alerts() {
   local needs_attention=0 arg
   for arg in "$@"; do
@@ -1761,6 +2559,78 @@ cmd_watch() {
   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
@@ -1841,7 +2711,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
@@ -1935,8 +2805,41 @@ 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"
@@ -1944,8 +2847,8 @@ cmd_stop() {
   export RELEASE_NODE ERL_EPMD_ADDRESS
   resolve_control_identity_from_records
 
-  local workspace_root
-  workspace_root="$(current_workspace_root 2>/dev/null || true)"
+  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)"
@@ -1963,7 +2866,9 @@ cmd_stop() {
     [ "$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
 
@@ -1984,9 +2889,10 @@ cmd_stop() {
   # it. Do not sweep by release dir: sibling instances share dev releases.
   kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
 
-  # Final cwd-sweep backstop after the BEAM is dead. `cmd_stop` is a fresh shell,
-  # so it captures the root from the live control node before the kill above.
-  reap_workspace_cwd_agents "$workspace_root"
+  # 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
@@ -2011,12 +2917,244 @@ cmd_stop() {
   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
@@ -2027,25 +3165,69 @@ 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 "$@"
@@ -2054,6 +3236,26 @@ aiur_engine_main() {
       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 "$@"
@@ -2062,6 +3264,10 @@ aiur_engine_main() {
       shift
       cmd_pause_resume "$cmd" "$@"
       ;;
+    reset-budget)
+      shift
+      cmd_reset_budget "$@"
+      ;;
     message)
       shift
       cmd_message "$@"
@@ -2073,19 +3279,24 @@ aiur_engine_main() {
     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