aiur-cli 0.0.2 → 0.0.3

package/README.md

@@ -21,6 +21,11 @@ npm install -g aiur-cli
 Requires [tmux](https://github.com/tmux/tmux) at runtime. Install
 [opencode](https://opencode.ai) too for in-pane agent chat.
 
+When a newer `aiur-cli` is published, a one-line update notice is printed to
+stderr (checked in the background at most once a day, never blocking your
+command). Set `AIUR_NO_UPDATE_NOTIFIER=1` to silence it; it is also skipped under
+CI (`CI=true`).
+
 ## Get started
 
 ```bash
@@ -51,7 +56,7 @@ to the issues you want worked and run `aiur`.
 |---|---|
 | `aiur init` | Interactive setup wizard (scaffold `.aiurconfig`) |
 | `aiur` | Start the workflow in the foreground (local-only bind) |
-| `aiur --bg` | Start in a detached tmux session |
+| `aiur --bg` | Start a headless BEAM in one detached tmux lifetime session |
 | `aiur status` | Show active agents and their state |
 | `aiur pause <id…>` / `resume <id…>` | Pause or resume agents by issue ID |
 | `aiur stop` | Stop the running session |
@@ -65,6 +70,12 @@ to the issues you want worked and run `aiur`.
 - **Smart Alerts** — Customize notifications and sounds when agents finish, stall, or need a decision.
 - **Live Dashboard** — Shareable web view of every agent, event, and progress bar.
 
+Background mode is headless inside Aiur: it skips the interactive agent-list
+pane, chat/prewarm panes, and dashboard unless you explicitly opt into a
+dashboard port. The launcher still keeps one detached tmux session as the BEAM
+lifetime holder. Re-running `aiur --bg` against a live session exits with an
+already-running hint; stale tmux state is cleaned up before restart.
+
 ---
 
 _Command macro, delegate micro, maximize APM._

package/bin/aiur.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 "use strict";
 
-const { spawnSync } = require("node:child_process");
+const { spawnSync, spawn } = require("node:child_process");
 const path = require("node:path");
 const fs = require("node:fs");
+const os = require("node:os");
 
 // Node's spawnSync reports a missing executable via `result.error`; some
 // runtimes (e.g. Bun) throw instead. Normalize to the error-return shape so a
@@ -201,6 +202,228 @@ function ensureOpencode() {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Update notifier
+//
+// When a newer aiur-cli is published, surface a one-line "update available"
+// notice — npm-update-notifier style: every run reads a small cache file and
+// prints from it; the registry is only hit in a detached background worker,
+// at most once per interval, so the check never blocks or errors the command.
+// The notice always goes to stderr so piped stdout stays clean.
+//
+// This file is its own background worker: main() re-spawns it with
+// AIUR_UPDATE_NOTIFIER_WORKER=1 set, which short-circuits to runUpdateWorker().
+// Keeps the launcher dependency-free (a tiny semver compare + https.get).
+// ---------------------------------------------------------------------------
+
+const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h
+const REGISTRY_LATEST_URL = "https://registry.npmjs.org/aiur-cli/latest";
+// Unpublished/source builds carry this sentinel; never nag on a dev checkout.
+const DEV_VERSION = "0.0.0";
+
+function currentVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"),
+    );
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// Minimal semver: parse major.minor.patch with an optional prerelease tag.
+// Enough for the launcher's own clean release versions — not a full spec impl.
+// The regex is fully anchored (and tolerates a +build suffix) so a registry- or
+// cache-supplied string with trailing junk — e.g. control/ANSI bytes meant to
+// hijack the terminal when the notice is printed — fails to parse and is treated
+// as not-newer rather than reaching printUpdateNotice verbatim.
+function parseSemver(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    String(value).trim(),
+  );
+  if (!match) return null;
+  return { major: +match[1], minor: +match[2], patch: +match[3], pre: match[4] || "" };
+}
+
+// True when `a` is strictly newer than `b`. A release outranks a prerelease at
+// the same core version (1.0.0 > 1.0.0-rc.1); unparseable input is never newer.
+function semverGt(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return false;
+  if (pa.major !== pb.major) return pa.major > pb.major;
+  if (pa.minor !== pb.minor) return pa.minor > pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch > pb.patch;
+  if (pa.pre === pb.pre) return false;
+  if (!pa.pre) return true; // a is a release, b is a prerelease
+  if (!pb.pre) return false; // a is a prerelease, b is a release
+  return pa.pre > pb.pre; // both prereleases: lexical tiebreak
+}
+
+function cacheFile() {
+  const base = process.env.XDG_CACHE_HOME
+    ? path.join(process.env.XDG_CACHE_HOME, "aiur")
+    : path.join(os.homedir(), ".aiur");
+  return path.join(base, "update-check.json");
+}
+
+function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(cacheFile(), "utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeCache(data) {
+  try {
+    const file = cacheFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    // Write-then-rename so a reader never sees a half-written file: if the
+    // detached worker is killed mid-write, or two workers race, the rename is
+    // atomic on POSIX and a torn cache can't trigger a respawn-every-run loop.
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data));
+    fs.renameSync(tmp, file);
+  } catch (_) {
+    // A missing-cache write must never break the run; silently skip.
+  }
+}
+
+// Treat any non-falsy CI value except an explicit "false"/"0" as a CI run.
+function isCI() {
+  const value = process.env.CI;
+  return !!value && value !== "false" && value !== "0";
+}
+
+function notifierDisabled(current) {
+  return (
+    process.env.AIUR_NO_UPDATE_NOTIFIER === "1" ||
+    isCI() ||
+    !current ||
+    current === DEV_VERSION
+  );
+}
+
+function printUpdateNotice(current, latest) {
+  process.stderr.write(
+    `aiur: a new version is available — ${current} → ${latest}\n` +
+      "      update: npm install -g aiur-cli@latest\n",
+  );
+}
+
+// Synchronous, fast, never-throwing: print from cache when a newer version is
+// known, then kick off a detached refresh if the cache is stale. The notice is
+// TTY-gated so non-interactive/piped invocations stay quiet.
+function maybeNotifyUpdate() {
+  try {
+    const current = currentVersion();
+    if (notifierDisabled(current)) return;
+
+    const cache = readCache();
+    if (
+      cache &&
+      cache.latest &&
+      process.stderr.isTTY &&
+      semverGt(cache.latest, current)
+    ) {
+      printUpdateNotice(current, cache.latest);
+    }
+
+    const stale =
+      !cache ||
+      typeof cache.lastCheck !== "number" ||
+      Date.now() - cache.lastCheck > UPDATE_CHECK_INTERVAL_MS;
+    if (stale) spawnUpdateWorker();
+  } catch (_) {
+    // The version check is best-effort; never let it affect the command.
+  }
+}
+
+function spawnUpdateWorker() {
+  try {
+    const child = spawn(process.execPath, [__filename], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, AIUR_UPDATE_NOTIFIER_WORKER: "1" },
+    });
+    child.unref();
+  } catch (_) {
+    // If we can't detach a worker, just skip — the next run retries.
+  }
+}
+
+// Fetch the `latest` dist-tag's version. Bounded by a timeout and a response
+// cap; any error resolves to null so the worker stays silent when offline.
+function fetchLatestVersion(url, done) {
+  let settled = false;
+  const finish = (value) => {
+    if (settled) return;
+    settled = true;
+    done(value);
+  };
+  try {
+    const transport = url.startsWith("http://") ? require("node:http") : require("node:https");
+    const req = transport.get(
+      url,
+      { headers: { Accept: "application/json" }, timeout: 5000 },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          return finish(null);
+        }
+        let body = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          body += chunk;
+          // Abort an oversized body. req.destroy() emits only "close" (no "end"
+          // or "error"), so resolve here explicitly — otherwise the worker would
+          // hang forever and never stamp the cache, respawning on every run.
+          if (body.length > 1_000_000) {
+            req.destroy();
+            finish(null);
+          }
+        });
+        res.on("end", () => {
+          try {
+            const version = JSON.parse(body).version;
+            finish(typeof version === "string" ? version : null);
+          } catch (_) {
+            finish(null);
+          }
+        });
+      },
+    );
+    // A timeout's req.destroy() likewise emits only "close", so resolve here too
+    // rather than waiting on an event that never comes. "error" covers the
+    // connection-failure case (offline, refused).
+    req.on("timeout", () => {
+      req.destroy();
+      finish(null);
+    });
+    req.on("error", () => finish(null));
+  } catch (_) {
+    finish(null);
+  }
+}
+
+// Detached worker entrypoint: refresh the cache, then exit. Always stamps
+// lastCheck (even on failure) so an offline machine doesn't respawn every run.
+function runUpdateWorker() {
+  const previous = readCache();
+  const url = process.env.AIUR_REGISTRY_URL || REGISTRY_LATEST_URL;
+  fetchLatestVersion(url, (latest) => {
+    writeCache({
+      lastCheck: Date.now(),
+      // Keep the last known `latest` when the fetch fails so a transient outage
+      // doesn't drop a pending notice.
+      latest: latest || (previous && previous.latest) || null,
+    });
+    process.exit(0);
+  });
+}
+
 // `init` and `--version` run as foreground one-shots that never start the
 // tmux-backed UI, so their tmux/opencode provisioning is irrelevant — and tmux
 // may legitimately be absent on a machine that only ever runs `aiur init`.
@@ -214,6 +437,14 @@ function isForegroundOneShot(argv) {
 }
 
 function main() {
+  // Detached refresh worker: do only the registry check, never the real launch.
+  if (process.env.AIUR_UPDATE_NOTIFIER_WORKER === "1") {
+    runUpdateWorker();
+    return;
+  }
+
+  maybeNotifyUpdate();
+
   const releaseDir = resolveReleaseDir();
 
   if (!isForegroundOneShot(process.argv.slice(2))) {

package/libexec/aiur-engine.sh

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiur-cli",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "AI Unit Runtime for Executors.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/its-everdred/aiur",
@@ -26,9 +26,9 @@
   },
   "opencodeVersion": "1.15.6",
   "optionalDependencies": {
-    "aiur-cli-linux-x64": "0.0.2",
-    "aiur-cli-linux-arm64": "0.0.2",
-    "aiur-cli-darwin-x64": "0.0.2",
-    "aiur-cli-darwin-arm64": "0.0.2"
+    "aiur-cli-linux-x64": "0.0.3",
+    "aiur-cli-linux-arm64": "0.0.3",
+    "aiur-cli-darwin-x64": "0.0.3",
+    "aiur-cli-darwin-arm64": "0.0.3"
   }
 }

package/share/aiur.tmux.conf

@@ -20,6 +20,16 @@ set -g mouse on
 set -s extended-keys on
 set -as terminal-features "*:extkeys"
 set -g status off
+
+# Show each pane's title in a one-line top border. PaneManager sets every
+# chat pane's title to "<issue id> <issue title>" via `select-pane -T`, and
+# the launcher sets the agent-list pane's title to "AIUR Agents". The format
+# truncates the title to the pane's current width with an ellipsis (tmux
+# evaluates the nested `#{pane_width}` before applying the `=/N/…` limit), so
+# a long title never wraps and re-clips automatically on resize.
+set -g pane-border-status top
+set -g pane-border-format "#{=/#{pane_width}/…:#{pane_title}}"
+
 set -g history-limit 50000
 set -g default-terminal "tmux-256color"
 set -ga terminal-overrides ",*256col*:Tc"