aiur-cli 0.0.5-nightly.df55dc3 → 0.0.5

package/README.md

@@ -1,61 +1,77 @@
 # AIUR
 
-**AI Unit Runtime for Executors**
+Oversee a fleet of coding agents that coordinate via events.
 
-Oversee a fleet of coding agents that **coordinate via events**.
+## Install
 
-Aiur watches your issue tracker, dispatches one agent per ticket into its own
-workspace and checkout, and gives you four ways to supervise the fleet instead
-of babysitting individual coding sessions.
-
-> [!WARNING]
-> **Use at your own risk.** Aiur is an unstable, vibecoded engineering preview for trusted
-> environments only. It **bypasses all agent permission prompts** and has very few efficiency
-> optimizations. Suggested for simple tasks under supervision.
->
-> Provided "as is", without warranty of any kind. You assume all risk for any cost, token
-> spend, data loss, or damage from running it.
+```bash
+npm install --global aiur-cli
+```
 
-## Get started
+## Usage
 
 ```bash
-npm install -g aiur-cli   # Node.js 18+
-
 cd your-repo
-aiur init                 # interactive setup wizard
-aiur                      # start the run
+aiur init     # interactive setup wizard
+aiur
 ```
 
 `aiur init` scaffolds `.aiur/config` and provisions the repo: tracker and
 repository, agent backends and routing, concurrency and turn limits, the GitHub
 token, and the `agent:*` lifecycle labels. Re-running resumes from your saved
-answers.
+answers. When setup finishes, label the issues you want worked `agent:todo` and
+run `aiur`.
 
-When setup finishes, label the issues you want worked `agent:todo` and run
-`aiur`.
+To have a coding agent operate the run as its Executor, install the repository's
+[`aiur-intro`, `aiur-run`, and `aiur-monitor` skills](https://aiur.team/docs/skills#executor-skills)
+through the agent's supported skill mechanism, then ask it to "run aiur." The npm
+package installs the CLI, not those skills. [Learn about the Executor role](https://aiur.team/docs/concepts/executor).
 
-| Requirement | Why |
-| --- | --- |
-| [tmux](https://github.com/tmux/tmux) | Runtime for the TUI and agent panes |
-| [opencode](https://opencode.ai) | In-pane agent chat (provisioned on install) |
-| Claude Code or Codex | The agents themselves |
+## Features
+
+- **Issue Monitoring** — Dispatch agents automatically via GitHub or Linear tickets.
+- **Shared Bus** — Agents auto-pub/sub to dependency events, unblocking work early.
+- **Optimize Effort** — Story points guide model sizes and skills across Claude and Codex.
+- **Take the Wheel** — Drive at any moment via pre-warmed [Opencode](https://opencode.ai) sessions in configurable tmux panes.
+- **Smart Alerts** — Customizable notifications and sounds when agents finish, stall, or need a decision.
+- **Live Dashboard** — Shareable web view of every agent, event, and progress bar.
+- **Build Orders** — Plan a large feature into typed members, lanes, phases, and dependencies, dispatched in dependency-safe parallel batches.
+- **Analytics** — Live-run telemetry: lifecycle time, concurrency, complexity tiers, and cost over a chosen window.
+- **Stream Deck** — Elgato Stream Deck + keys ranked by urgency, with pause/resume, a live log surface, and hold-to-dictate voice messages.
+- **Hyper Optimized** — Monitors API and model token usage, routes on peak pricing and other factors, and supports Cloudflare and more.
 
-## The four surfaces
+The TUI and GUI are both optional: `aiur --bg` runs headless with the GUI, and
+`--no-dashboard` drops the web listener. Every usable GUI requires
+`AIUR_DASHBOARD_USERNAME` and `AIUR_DASHBOARD_PASSWORD` — without them the loopback
+listener binds but refuses every request until both are set. The GUI is writable
+by default, and writable mode requires those same two credentials even on loopback.
 
-| Surface | What it gives you | How to open it |
-| --- | --- | --- |
-| **CLI** | Scriptable control of a run from any shell | `aiur status`, `aiur pause 142` |
-| **TUI** | Live agent board plus chat panes, in your terminal | `aiur` (foreground) |
-| **Dashboard** | Browser view of the fleet, decisions, and analytics | `http://127.0.0.1:4000` |
-| **Stream Deck** | Physical keys and dictation for the fleet | Separate sidecar, see below |
+## Interfaces
+
+### GUI
+
+![The Units page of the GUI](https://aiur.team/images/dashboard/units-dark.png)
+
+The GUI is the browser interface for supervising a run: the Units fleet table
+and meters, the Commands decision inbox, Build Order graphs, and Analytics.
+
+### TUI
+
+![The Aiur TUI: the agent-list board and a chat pane](https://aiur.team/images/tui/aiur-tui.gif)
+
+The TUI is a live agent board in your terminal with chat panes opened into
+individual agent sessions. Press `enter` on a row to open its conversation,
+`space` to pause or resume, `←` / `→` to change the concurrency cap, and `?`
+for the full keymap. A later bare `aiur` from the same project attaches to that
+live directory-scoped session; detaching leaves the run healthy.
 
 ### CLI
 
 | Command | What it does |
 | --- | --- |
 | `aiur init` | Interactive setup wizard |
-| `aiur` | Start the run in the foreground with the TUI |
-| `aiur --bg` | Start a detached headless run, dashboard still served |
+| `aiur` | Start a foreground TUI, or attach to this directory's live session |
+| `aiur --bg` | Start a detached headless run, GUI still served |
 | `aiur status` | Daemon state, active agents, and the current concurrency cap |
 | `aiur alerts --needs-attention` | Unresolved items waiting on you |
 | `aiur pause <id…>` / `aiur resume <id…>` | Pause or resume agents by issue id |
@@ -64,56 +80,15 @@ When setup finishes, label the issues you want worked `agent:todo` and run
 | `aiur --todo <id…> [--only]` | Queue tickets; `--only` dequeues the rest |
 | `aiur stop` / `aiur restart` | Stop the session, or refresh the release and restart |
 
-Add `--no-dashboard` to either mode to skip the web listener.
-
-### TUI
-
-The foreground run opens a tmux board with one row per ticket, showing runtime,
-turn count, backend, pinned model, and a state glyph. Press `enter` on a row to
-open that agent's chat pane beside the board, `space` to pause or resume, `←`
-and `→` to change the concurrency cap, and `?` for the full keymap.
-
-### Dashboard
-
-Served on foreground and `--bg` runs at the host and port in your config,
-`http://127.0.0.1:4000` by default. The launch output prints the real URL.
-
-| Page | What it shows |
-| --- | --- |
-| Units | Fleet table, ticket backlog, provider rate meters |
-| Commands | Durable decision inbox: answer, revise, retry delivery |
-| Build Order | Ticket dependency graph and phases |
-| Analytics | Throughput, complexity tiers, and spend over a chosen window |
-
-Writable mode is the default and requires `AIUR_DASHBOARD_USERNAME` and
-`AIUR_DASHBOARD_PASSWORD`, even on loopback. Set
-`observability.dashboard_writable: false` for an unauthenticated read-only
-loopback dashboard. Basic Auth is unencrypted, so put a TLS proxy in front of any
-non-loopback bind.
-
-### Stream Deck
+## License
 
-An Elgato Stream Deck + can drive the fleet: agent keys ranked by urgency, pause
-and resume, a live log surface, and hold-to-dictate voice messages. A browser
-emulator of the same layout is at `/streamdeck` on the dashboard.
-
-> The physical sidecar is **experimental** and ships separately from this
-> package, as a Linux x64 archive (glibc 2.28+, systemd user session). It is not
-> installed by `npm install aiur-cli`. See the
-> [Stream Deck guide](https://aiur.team/docs/guide/stream-deck).
-
-## Update notices
-
-When a newer `aiur-cli` is published, a one-line notice is printed to stderr,
-checked in the background at most once a day and never blocking your command.
-Set `AIUR_NO_UPDATE_NOTIFIER=1` to silence it; it is skipped under CI.
-
-Prerelease builds are published under the `nightly` dist-tag and never reach
-`latest`, so a plain `npm install -g aiur-cli` always gives you a stable release.
-To try one: `npm install -g aiur-cli@nightly`.
-
----
-
-_Command macro, delegate micro, maximize APM._
+> [!WARNING]
+> **Use at your own risk.** Aiur is an unstable, vibecoded engineering preview
+> for trusted environments only. It **bypasses all agent permission prompts**
+> and has very few efficiency optimizations. Suggested for simple tasks under
+> supervision.
+>
+> Provided "as is", without warranty of any kind. You assume all risk for any
+> cost, token spend, data loss, or damage from running it.
 
-[github.com/aiur-team/aiur](https://github.com/aiur-team/aiur)
+This project is licensed under the [Apache License 2.0](https://github.com/aiur-team/aiur/blob/main/LICENSE).

package/libexec/aiur-engine.sh

@@ -490,6 +490,8 @@ Usage: aiur [--interactive] [--no-dashboard] [--executor] [--pause] [--max-agent
        aiur asks [--open|--all] [--json]  inspect current-repository operator requests
        aiur cleanup-stale [--dry-run]  list/reap stale manual-smoke leftovers
        aiur --version
+
+Bare aiur: start or attach to this directory's interactive session.
 EOF
 }
 
@@ -686,6 +688,65 @@ run_session() {
   [ -n "$tmux_bin" ] || die "tmux is required to run aiur; install tmux and retry"
 
   aiur_resolve_identity
+  prepare_distribution
+
+  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 launch_lock
+  conf="$(resolve_tmux_conf)"
+  [ -f "$conf" ] || die "tmux conf not found at $conf"
+  launch_lock="$(aiur_launch_lock_path)"
+  acquire_aiur_launch_lock "$launch_lock" || return 1
+
+  # An invocation targeting an existing directory session resolves here before
+  # fresh-start credentials, argv files, run logs, watchdogs, or teardown traps.
+  # Foreground attaches; background exits with explicit attach guidance.
+  if "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null; then
+    if [ "$(probe_control_liveness)" = "up" ]; then
+      # Preserve the live launch's record and workspace-root handoff. Only
+      # backfill old/missing records, without pointing them at this attach
+      # invocation's transient state.
+      AIUR_WORKSPACE_ROOT_FILE="" write_aiur_instance_record "$session" "$socket" if-absent
+
+      if [ "$mode" = "background" ]; then
+        echo "aiur is already running in the background (tmux session ${session})." >&2
+        echo "Attach with: aiur" >&2
+        echo "Use: aiur status   # inspect agents" >&2
+        echo "Use: aiur stop     # stop it before starting a fresh session" >&2
+        release_aiur_launch_lock "$launch_lock"
+        return 0
+      fi
+
+      echo "aiur is already running; attaching to the running session ${session}." >&2
+      release_aiur_launch_lock "$launch_lock"
+      attach_tmux_session "$tmux_bin" "$socket" "$conf" "$session"
+      return $?
+    fi
+
+    # A tmux holder can exist while a healthy BEAM is still booting or while
+    # epmd itself is temporarily unreachable. Never turn one failed control
+    # probe into destructive cleanup unless distribution confirms the keyed
+    # node is absent.
+    case "$(probe_node_liveness)" in
+      down)
+        if ! confirm_stale_tmux_session "$tmux_bin" "$socket" "$conf" "$session"; then
+          echo "aiur found session ${session}, but it became live while checking stale state; leaving it intact." >&2
+          echo "Retry: aiur" >&2
+          release_aiur_launch_lock "$launch_lock"
+          return 1
+        fi
+        echo "aiur found stale tmux session ${session}; cleaning it up before restart" >&2
+        reap_aiur_agents "$socket" ""
+        kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
+        ;;
+      up | unknown)
+        echo "aiur found session ${session}, but its control plane is not ready; leaving the running session intact." >&2
+        echo "Retry: aiur" >&2
+        release_aiur_launch_lock "$launch_lock"
+        return 1
+        ;;
+    esac
+  fi
 
   # Pick up GITHUB_TOKEN / dashboard creds the wizard wrote to ./.env so the
   # running tracker can authenticate. Shell exports still take precedence.
@@ -717,7 +778,6 @@ run_session() {
   write_argv "${run_argv[@]}"
   export AIUR_ARGV_FILE="$argv_file"
 
-  prepare_distribution
   build_release_cmd
 
   # Force +fnu when no locale is set so the BEAM does not mangle non-ASCII paths.
@@ -725,12 +785,6 @@ run_session() {
     export ELIXIR_ERL_OPTIONS="${ELIXIR_ERL_OPTIONS:-} +fnu"
   fi
 
-  local session="${AIUR_SESSION_PREFIX}-${USER:-user}${AIUR_INSTANCE_KEY:+-$AIUR_INSTANCE_KEY}-default"
-  local socket="${AIUR_SESSION_PREFIX}-${USER:-user}${AIUR_INSTANCE_KEY:+-$AIUR_INSTANCE_KEY}"
-  local conf
-  conf="$(resolve_tmux_conf)"
-  [ -f "$conf" ] || die "tmux conf not found at $conf"
-
   preflight_stale_manual_smoke
 
   mkdir -p "$AIUR_BG_STATE_DIR"
@@ -844,31 +898,11 @@ run_session() {
       _session_node="$AIUR_RELEASE_NODE" _session_pidfile="$AIUR_AGENT_TMPFILE" \
       _session_workspace_root_file="$AIUR_WORKSPACE_ROOT_FILE" \
       _session_alert_ledger_path_file="$AIUR_ALERT_LEDGER_PATH_FILE" \
-      _session_crash_dump_baseline_file="$crash_dump_baseline_file"
+      _session_crash_dump_baseline_file="$crash_dump_baseline_file" \
+      _session_launch_lock="$launch_lock"
     install_foreground_traps
   fi
 
-  # Background starts are intentionally idempotent. A prior live node should not
-  # fall through to tmux's opaque "duplicate session" failure, and a stale tmux
-  # session whose BEAM/control plane is gone should be reclaimed before retry.
-  if [ "$mode" = "background" ] && "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null; then
-    if [ "$(probe_control_liveness)" = "up" ]; then
-      # Write a record only when none exists. A live session's own start already
-      # wrote one — and it owns the BEAM-written AIUR_RECORD_WORKSPACE_ROOT_FILE
-      # path, which must not be overwritten by this invocation's temp file.
-      [ -f "$(aiur_instance_record_path)" ] || (AIUR_WORKSPACE_ROOT_FILE="" write_aiur_instance_record "$session" "$socket")
-      echo "aiur is already running in the background (tmux session ${session})." >&2
-      echo "Use: aiur status   # inspect agents" >&2
-      echo "Use: aiur stop     # stop it before starting a fresh session" >&2
-      rm -f "${launch_tempfiles[@]}" 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
@@ -899,6 +933,7 @@ run_session() {
     echo "❌ aiur failed to start; captured output:" >&2
     tail -n 30 "$startup_capture" 2>/dev/null | sed 's/^/  /' >&2 || true
     rm -f "${launch_tempfiles[@]}" 2>/dev/null || true
+    release_aiur_launch_lock "$launch_lock"
     exit 1
   fi
 
@@ -924,12 +959,16 @@ run_session() {
       reap_aiur_agents "$socket" "$AIUR_AGENT_TMPFILE"
       kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
     fi
+    release_aiur_launch_lock "$launch_lock"
+    _session_launch_lock=""
     [ "$mode" = "foreground" ] && return 1
     rm -f "${launch_tempfiles[@]}" 2>/dev/null || true
     exit 1
   fi
 
   write_aiur_instance_record "$session" "$socket"
+  release_aiur_launch_lock "$launch_lock"
+  _session_launch_lock=""
   print_config_status "$startup_capture"
   print_dashboard_status "$no_dashboard" "$startup_capture"
   # The `aiur run` version notice: a cheap local state read (the daemon's
@@ -976,10 +1015,18 @@ run_session() {
   # Foreground: attach the UI. Do not exec — that would drop the teardown trap.
   # Avoid process substitution here: some sandboxed non-TTY launchers reject
   # opening /dev/fd/* during the real manual-test wrapper path.
+  attach_tmux_session "$tmux_bin" "$socket" "$conf" "$session"
+}
+
+attach_tmux_session() {
+  local tmux_bin="$1" socket="$2" conf="$3" session="$4"
   local attach_stderr attach_code
   attach_stderr="$(mktemp "${TMPDIR:-/tmp}/aiur-attach-stderr.XXXXXX")"
-  "$tmux_bin" -L "$socket" -f "$conf" attach -t "$session" 2>"$attach_stderr"
-  attach_code=$?
+  if "$tmux_bin" -L "$socket" -f "$conf" attach -t "$session" 2>"$attach_stderr"; then
+    attach_code=0
+  else
+    attach_code=$?
+  fi
   grep -v -F "[server exited]" "$attach_stderr" >&2 || true
   rm -f "$attach_stderr" 2>/dev/null || true
   return "$attach_code"
@@ -1002,12 +1049,31 @@ resolve_tmux_conf() {
 # name (covers orphans from any release dir): under the unified identity a dev
 # `_build` BEAM and an installed BEAM both claim the same node name, so a
 # release-path pgrep misses whichever one this run didn't launch.
+# TERM the node(s) matching $pattern, give them $grace_ticks (0.1s) to exit
+# gracefully, then SIGKILL whatever remains. The default grace is short (3s)
+# because startup reclaim wants to clear a stale BEAM quickly; the stop paths
+# pass a longer grace so the BEAM can finish its own agent reap + session
+# deletion instead of being SIGKILLed mid-cleanup (which is what orphaned agent
+# processes on `aiur stop`). Callers may override the grace internally; invalid
+# or excessive values fall back to the 3s startup-reclaim default instead of
+# skipping the wait and jumping straight to SIGKILL.
 kill_beams_matching() {
-  local pattern="$1" pids pid waited=0
+  local pattern="$1" grace_ticks="${2:-30}" pids pid waited=0
+  case "$grace_ticks" in
+    "" | *[!0-9]*) grace_ticks=30 ;;
+    *)
+      # Reject overlong digit strings before numeric comparison so shell integer
+      # overflow cannot turn an excessive grace into an immediate SIGKILL.
+      if [ "${#grace_ticks}" -gt 5 ] ||
+        { [ "${#grace_ticks}" -eq 5 ] && [ "$grace_ticks" -gt 36000 ]; }; then
+        grace_ticks=30
+      fi
+      ;;
+  esac
   pids="$(pgrep -f -- "$pattern" 2>/dev/null || true)"
   [ -n "$pids" ] || return 0
   for pid in $pids; do kill -TERM "$pid" 2>/dev/null || true; done
-  while [ "$waited" -lt 30 ]; do
+  while [ "$waited" -lt "$grace_ticks" ]; do
     pids="$(pgrep -f -- "$pattern" 2>/dev/null || true)"
     [ -z "$pids" ] && break
     sleep 0.1
@@ -1336,8 +1402,76 @@ aiur_instance_record_path() {
   printf '%s/%s.instance' "$(aiur_instances_dir)" "$(aiur_state_slug)"
 }
 
+aiur_launch_lock_path() {
+  printf '%s/locks/%s.launch' "${AIUR_BG_STATE_DIR:?}" "$(aiur_state_slug)"
+}
+
+acquire_aiur_launch_lock() {
+  local lock="$1" owner_file="$1/owner" recovery_lock="$1.recovery"
+  local owner tick lock_age
+  local max_ticks="${AIUR_LAUNCH_LOCK_TICKS:-${AIUR_NODE_GRACE_TICKS:-1200}}"
+  local ownerless_stale_seconds="${AIUR_OWNERLESS_LOCK_STALE_SECONDS:-120}"
+  mkdir -p "$(dirname "$lock")" 2>/dev/null || return 1
+
+  for ((tick = 0; tick < max_ticks; tick++)); do
+    if mkdir "$lock" 2>/dev/null; then
+      printf '%s\n' "$$" >"$owner_file" || { rmdir "$lock" 2>/dev/null || true; return 1; }
+      return 0
+    fi
+
+    owner="$(sed -n '1p' "$owner_file" 2>/dev/null || true)"
+    if [[ "$owner" =~ ^[0-9]+$ ]] && kill -0 "$owner" 2>/dev/null; then
+      sleep 0.1
+      continue
+    fi
+
+    lock_age="$(aiur_lock_age_seconds "$lock")"
+    if [ -z "$owner" ] && { [ -z "$lock_age" ] || [ "$lock_age" -lt "$ownerless_stale_seconds" ]; }; then
+      sleep 0.1
+      continue
+    fi
+
+    # Only one contender may reclaim a dead lock. Re-read ownership while the
+    # recovery mutex is held so another contender cannot delete a newly claimed
+    # launch directory after losing the original stale-lock race.
+    if mkdir "$recovery_lock" 2>/dev/null; then
+      owner="$(sed -n '1p' "$owner_file" 2>/dev/null || true)"
+      lock_age="$(aiur_lock_age_seconds "$lock")"
+      if { [ -z "$owner" ] && [ -n "$lock_age" ] && [ "$lock_age" -ge "$ownerless_stale_seconds" ]; } || \
+        { [[ "$owner" =~ ^[0-9]+$ ]] && ! kill -0 "$owner" 2>/dev/null; }; then
+        rm -f "$owner_file" 2>/dev/null || true
+        rmdir "$lock" 2>/dev/null || true
+      fi
+      rmdir "$recovery_lock" 2>/dev/null || true
+    fi
+    sleep 0.1
+  done
+
+  echo "aiur: another launch for this directory is still in progress; retry aiur" >&2
+  return 1
+}
+
+aiur_lock_age_seconds() {
+  local path="$1" now modified
+  now="$(date +%s 2>/dev/null || true)"
+  modified="$(stat -c %Y "$path" 2>/dev/null || stat -f %m "$path" 2>/dev/null || true)"
+  [[ "$now" =~ ^[0-9]+$ ]] && [[ "$modified" =~ ^[0-9]+$ ]] || return 0
+  [ "$now" -ge "$modified" ] || return 0
+  printf '%s' "$((now - modified))"
+}
+
+release_aiur_launch_lock() {
+  local lock="${1:-}" owner_file owner
+  [ -n "$lock" ] || return 0
+  owner_file="$lock/owner"
+  owner="$(sed -n '1p' "$owner_file" 2>/dev/null || true)"
+  [ "$owner" = "$$" ] || return 0
+  rm -f "$owner_file" 2>/dev/null || true
+  rmdir "$lock" 2>/dev/null || true
+}
+
 write_aiur_instance_record() {
-  local session="$1" socket="$2" record_dir record tmp root
+  local session="$1" socket="$2" write_mode="${3:-replace}" record_dir record tmp root
   record_dir="$(aiur_instances_dir)"
   record="$(aiur_instance_record_path)"
   root="$(canonical_workspace_root "${AIUR_PROJECT_ROOT:-}")"
@@ -1354,7 +1488,14 @@ write_aiur_instance_record() {
     printf 'AIUR_RECORD_WRITTEN_AT=%q\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)"
   } >"$tmp" || { rm -f "$tmp" 2>/dev/null || true; return 0; }
   chmod 0600 "$tmp" 2>/dev/null || true
-  mv "$tmp" "$record" 2>/dev/null || rm -f "$tmp" 2>/dev/null || true
+  if [ "$write_mode" = "if-absent" ]; then
+    # Same-directory hard-link creation is atomic: a concurrent live launcher
+    # can win without an attaching shell overwriting its workspace handoff.
+    ln "$tmp" "$record" 2>/dev/null || true
+    rm -f "$tmp" 2>/dev/null || true
+  else
+    mv "$tmp" "$record" 2>/dev/null || rm -f "$tmp" 2>/dev/null || true
+  fi
 }
 
 # Marker `status` reads to tell "daemon crashed, agents may be orphaned" apart
@@ -1469,6 +1610,16 @@ record_beam_crash() {
 
 canonical_workspace_root() {
   local root="$1"
+  # The BEAM hands off Config.workspace_root() verbatim, which may be a `~/...`
+  # path (e.g. this repo's `workspace.root: ~/code/aiur-workspaces`). `cd` does
+  # not expand `~` inside a quoted variable, so without this a `~`-rooted cwd
+  # sweep compared against the literal `~/...` string, matched no /proc cwd, and
+  # silently reaped nothing — the exact backstop that must catch workspace-rooted
+  # agents on stop. Expand a leading `~` before canonicalizing so the sweep and
+  # the /proc cwd values (always absolute) agree.
+  case "$root" in
+    "~" | "~/"*) root="${HOME:-}${root#\~}" ;;
+  esac
   if [ -d "$root" ]; then
     (cd "$root" 2>/dev/null && pwd -P) || printf '%s\n' "$root"
   else
@@ -1742,7 +1893,7 @@ wait_for_session_startup() {
 _session_socket="" _session_name="" _session_conf="" _session_tmpfile=""
 _session_capture="" _session_argv="" _session_release="" _session_tmux="" _session_node=""
 _session_pidfile="" _session_watchdog_pid="" _session_workspace_root_file=""
-_session_alert_ledger_path_file="" _session_crash_dump_baseline_file=""
+_session_alert_ledger_path_file="" _session_crash_dump_baseline_file="" _session_launch_lock=""
 _cleanup_ran=0
 session_cleanup() {
   [ "$_cleanup_ran" = 1 ] && return 0
@@ -1769,8 +1920,11 @@ session_cleanup() {
   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}"
+  # release dir, so release-path pgrep would terminate sibling workflows. Give
+  # the BEAM a generous TERM grace (the stop grace, not the 3s startup reclaim
+  # default) so its own graceful shutdown — ProcessReaper reaping the agent tree
+  # plus the BEAM-side workspace sweep — completes before any SIGKILL lands.
+  [ -n "$_session_node" ] && kill_beams_matching "-name ${_session_node}" 300
 
   # Final cwd-sweep backstop after the BEAM is gone: catches workspace-rooted
   # agents or test children that registered too late, reparented during the
@@ -1808,6 +1962,8 @@ session_cleanup() {
     "$_session_workspace_root_file" "$_session_alert_ledger_path_file" \
     "$_session_crash_dump_baseline_file" 2>/dev/null || true
   rm -f "$(aiur_instance_record_path)" 2>/dev/null || true
+  release_aiur_launch_lock "$_session_launch_lock"
+  _session_launch_lock=""
   return $code
 }
 install_foreground_traps() {
@@ -1852,6 +2008,21 @@ probe_node_liveness() {
   printf 'unknown'
 }
 
+confirm_stale_tmux_session() {
+  local tmux_bin="$1" socket="$2" conf="$3" session="$4"
+  local max_ticks="${AIUR_STALE_SESSION_GRACE_TICKS:-30}" tick
+
+  for ((tick = 0; tick < max_ticks; tick++)); do
+    "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null || return 0
+    [ "$(probe_control_liveness)" = "up" ] && return 1
+    [ "$(probe_node_liveness)" = "down" ] || return 1
+    sleep 0.1
+  done
+
+  "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null || return 0
+  [ "$(probe_control_liveness)" != "up" ] && [ "$(probe_node_liveness)" = "down" ]
+}
+
 probe_named_node_liveness() {
   local node="$1" old_node="${RELEASE_NODE:-}" state
   RELEASE_NODE="$node"
@@ -2004,6 +2175,20 @@ kill_control_rpc_process() {
   for p in "${tree[@]}"; do kill -KILL "$p" 2>/dev/null || true; done
 }
 
+# Signalling the watchdog subshell alone leaves its `sleep` child running and
+# orphaned: bash forks the subshell, and the sleep is a separate process the
+# subshell's death does not reap. Kill the descendants too so a fast reply
+# leaves nothing behind that outlives the command.
+# Deepest-first: a bash subshell that is TERMed while waiting on a foreground
+# child defers the signal until that child exits, so signalling the wrapper
+# before the sleep it is waiting on can leave the sleep running.
+cancel_timeout_watchdog() {
+  local pid="$1" p tree=() i
+  [ -n "$pid" ] || return 0
+  while IFS= read -r p; do tree+=("$p"); done < <(agent_pid_tree "$pid")
+  for ((i = ${#tree[@]} - 1; i >= 0; i--)); do kill -TERM "${tree[i]}" 2>/dev/null || true; done
+}
+
 run_release_rpc_with_timeout() {
   local expression="$1" timeout output_file timeout_file pid watchdog_pid status grouped=0
   timeout="$(control_rpc_timeout_seconds)"
@@ -2019,13 +2204,18 @@ run_release_rpc_with_timeout() {
   fi
   pid=$!
 
+  # The watchdog must not hold the caller's stdout/stderr. A caller that captures
+  # our output (command substitution, a pipe, a language runtime's subprocess
+  # capture) reads until EOF, and EOF arrives only when every process holding the
+  # write end exits - including a watchdog that is merely sleeping. Closing those
+  # descriptors here is what keeps the timeout a ceiling instead of a floor.
   (
     sleep "$timeout"
     if kill -0 "$pid" 2>/dev/null; then
       : >"$timeout_file"
       kill_control_rpc_process "$pid" "$grouped"
     fi
-  ) &
+  ) >/dev/null 2>&1 &
   watchdog_pid=$!
 
   if wait "$pid"; then
@@ -2039,7 +2229,7 @@ run_release_rpc_with_timeout() {
     # strand descendants that ignored TERM after the root process exits.
     :
   else
-    kill "$watchdog_pid" 2>/dev/null || true
+    cancel_timeout_watchdog "$watchdog_pid"
   fi
   wait "$watchdog_pid" 2>/dev/null || true
 
@@ -3196,8 +3386,13 @@ cmd_stop() {
   fi
 
   # Reap any BEAM holding our node name regardless of which release dir launched
-  # it. Do not sweep by release dir: sibling instances share dev releases.
-  kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
+  # it. Do not sweep by release dir: sibling instances share dev releases. Use
+  # the generous stop TERM grace: the BEAM, once TERM'd, runs its own graceful
+  # shutdown (ProcessReaper reaping the agent tree, opencode session deletes,
+  # then the BEAM-side workspace sweep) and the short 3s startup default would
+  # SIGKILL it mid-cleanup, orphaning exactly the agents this stop must reap.
+  # The loop exits the moment the BEAM is gone, so a fast stop costs nothing.
+  kill_beams_matching "-name ${AIUR_RELEASE_NODE}" 300
 
   # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiur-cli",
-  "version": "0.0.5-nightly.df55dc3",
+  "version": "0.0.5",
   "description": "AI Unit Runtime for Executors.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/aiur-team/aiur",
@@ -35,8 +35,8 @@
   ],
   "opencodeVersion": "1.17.10",
   "optionalDependencies": {
-    "aiur-cli-linux-x64": "0.0.5-nightly.df55dc3",
-    "aiur-cli-linux-arm64": "0.0.5-nightly.df55dc3",
-    "aiur-cli-darwin-arm64": "0.0.5-nightly.df55dc3"
+    "aiur-cli-linux-x64": "0.0.5",
+    "aiur-cli-linux-arm64": "0.0.5",
+    "aiur-cli-darwin-arm64": "0.0.5"
   }
 }