aiur-cli 0.0.5-nightly.e30c636 → 0.0.6

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

@@ -456,7 +456,7 @@ Usage: aiur [--interactive] [--no-dashboard] [--executor] [--pause] [--max-agent
        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-answer <decision-id> --expected-version <n> (--option <id>|--custom-response <text>) --rationale <text> --idempotency-key <key> [--supersede] [--executor-id <id>]
        aiur executor-escalate <decision-id> --expected-version <n> --reason <text> [--executor-id <id>]
        aiur executor-moot <decision-id> --expected-version <n> --reason-class <class> [--reason <text>] [--executor-id <id>]
        aiur units [--scope live|unfinished|all|none] [--condition active|alert|paused|queued|finished]... [--format auto|table|records] [--json]
@@ -468,6 +468,7 @@ Usage: aiur [--interactive] [--no-dashboard] [--executor] [--pause] [--max-agent
        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-fast-forward <wake-id> [--as <id>]  acknowledge an externally covered wake prefix
        aiur executor-emit <topic> --payload <json>  publish an Executor event
        aiur executor-subscribe|executor-unsubscribe <pattern>
        aiur executor-subscriptions  list persistent Executor bindings
@@ -479,17 +480,18 @@ Usage: aiur [--interactive] [--no-dashboard] [--executor] [--pause] [--max-agent
        aiur upgrade [--force]   install the newer aiur-cli on your channel
        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 message <id> [--message-id 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
+
+Bare aiur: start or attach to this directory's interactive session.
 EOF
 }
 
@@ -586,31 +588,84 @@ run_asks() {
 # mode=foreground attaches the UI and tears down on exit; mode=background leaves
 # the detached tmux session running and returns.
 
-# Load operator/machine credentials before repo-local settings. Since each file
-# only fills unset names, shell exports win first, then ~/.aiur/.env, then ./.env.
+# Dotenv precedence: shell exports win, then ./.env, then ~/.aiur/.env. Each
+# file only fills names that are still unset, so the repo-local file (the more
+# specific scope) is read first and the machine-wide file only fills its gaps.
+# A blank value is a placeholder, not a setting: `aiur init` scaffolds
+# `GITHUB_TOKEN=` and `.env.example` renders every name blank, so a blank line
+# neither exports nor shadows anything.
+#
+# GitHub credentials are one group. A repo `.env` that sets any member has
+# chosen that repository's auth mode, so none of the global file's members may
+# leak in beside it: a global GITHUB_APP_* triple filling the gaps around a
+# repo-local GITHUB_TOKEN would outrank that token and force the daemon onto an
+# App that is not installed on the repo (#2638).
+GITHUB_CREDENTIAL_ENV_NAMES="GITHUB_TOKEN GITHUB_APP_ID GITHUB_APP_INSTALLATION_ID GITHUB_APP_PRIVATE_KEY_PATH GITHUB_APP_PRIVATE_KEY"
+
 load_dotenv() {
-  load_dotenv_file "$HOME/.aiur/.env"
+  local global_skip=""
+  if dotenv_file_sets_github_credential ".env"; then
+    global_skip="github_credentials"
+  fi
   load_dotenv_file ".env"
+  load_dotenv_file "$HOME/.aiur/.env" "$global_skip"
+}
+
+github_credential_env_name() {
+  case " $GITHUB_CREDENTIAL_ENV_NAMES " in
+    *" $1 "*) return 0 ;;
+  esac
+  return 1
+}
+
+# Parses one dotenv line into DOTENV_KEY / DOTENV_VAL. Returns 1 for blank,
+# comment, malformed, and blank-valued lines so callers skip them. Shared by
+# the loader and the credential-group probe so both agree on what counts.
+parse_dotenv_line() {
+  local line="$1" key val
+  DOTENV_KEY="" DOTENV_VAL=""
+  line="${line#"${line%%[![:space:]]*}"}"
+  case "$line" in '' | '#'*) return 1 ;; esac
+  [ "${line#*=}" = "$line" ] && return 1
+  key="${line%%=*}"
+  key="${key%"${key##*[![:space:]]}"}"
+  case "$key" in '' | *[!A-Za-z0-9_]*) return 1 ;; esac
+  val="${line#*=}"
+  val="${val#"${val%%[![:space:]]*}"}"
+  case "$val" in
+    \"*\") val="${val#\"}" && val="${val%\"}" ;;
+    \'*\') val="${val#\'}" && val="${val%\'}" ;;
+  esac
+  [ -n "$val" ] || return 1
+  DOTENV_KEY="$key"
+  DOTENV_VAL="$val"
+}
+
+# True when the file sets any GitHub credential name to a non-blank value.
+dotenv_file_sets_github_credential() {
+  local file="$1" line
+  [ -f "$file" ] || return 1
+  while IFS= read -r line || [ -n "$line" ]; do
+    parse_dotenv_line "$line" || continue
+    if github_credential_env_name "$DOTENV_KEY"; then
+      return 0
+    fi
+  done <"$file"
+  return 1
 }
 
+# Usage: load_dotenv_file <file> [github_credentials]
+# The optional second argument skips the GitHub credential group.
 load_dotenv_file() {
-  local file="$1" line key val
+  local file="$1" skip="${2:-}" line
   [ -f "$file" ] || return 0
   while IFS= read -r line || [ -n "$line" ]; do
-    line="${line#"${line%%[![:space:]]*}"}"
-    case "$line" in '' | '#'*) continue ;; esac
-    [ "${line#*=}" = "$line" ] && continue
-    key="${line%%=*}"
-    key="${key%"${key##*[![:space:]]}"}"
-    case "$key" in '' | *[!A-Za-z0-9_]*) continue ;; esac
-    val="${line#*=}"
-    val="${val#"${val%%[![:space:]]*}"}"
-    case "$val" in
-      \"*\") val="${val#\"}" && val="${val%\"}" ;;
-      \'*\') val="${val#\'}" && val="${val%\'}" ;;
-    esac
-    [ -n "${!key+x}" ] && continue
-    export "$key=$val"
+    parse_dotenv_line "$line" || continue
+    if [ "$skip" = "github_credentials" ] && github_credential_env_name "$DOTENV_KEY"; then
+      continue
+    fi
+    [ -n "${!DOTENV_KEY+x}" ] && continue
+    export "$DOTENV_KEY=$DOTENV_VAL"
   done <"$file"
 }
 
@@ -686,6 +741,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.
@@ -693,6 +807,16 @@ run_session() {
   scrub_run_only_env
   export AIUR_DEFAULT_DASHBOARD_HOST="$(default_dashboard_host)"
 
+  # The BEAM lives in tmux, but a fresh foreground run belongs to this shell:
+  # it waits on the UI attach and owns the teardown trap. Hand its pid to the
+  # pane watchdog so a hard-killed launcher cannot leave agents running.
+  # A detached run has no such owner; discard any inherited stale value.
+  if [ "$mode" = "foreground" ]; then
+    export AIUR_LAUNCHER_PID="$$"
+  else
+    unset AIUR_LAUNCHER_PID
+  fi
+
   # The daemon's `Aiur.Upgrade` check uses the CLI package version (not the mix
   # version) as the "installed" version, so an npm install's notice names what
   # the user actually has. `run_version` sets the same var for `--version`.
@@ -717,7 +841,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 +848,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"
@@ -816,7 +933,7 @@ run_session() {
       AIUR_TMUX_SESSION AIUR_TMUX_SOCKET AIUR_TMUX_CONF AIUR_BIN \
       AIUR_SESSION_TMPFILE AIUR_AGENT_TMPFILE AIUR_WORKSPACE_ROOT_FILE AIUR_ALERT_LEDGER_PATH_FILE \
       ELIXIR_ERL_OPTIONS AIUR_LOGS_ROOT AIUR_OPENCODE_BRIDGE_PORT AIUR_DEFAULT_DASHBOARD_HOST AIUR_DEBUG \
-      AIUR_OPERATOR_PID AIUR_NOFILE_SOFT_LIMIT ERL_CRASH_DUMP ERL_CRASH_DUMP_SECONDS \
+      AIUR_OPERATOR_PID AIUR_LAUNCHER_PID AIUR_NOFILE_SOFT_LIMIT ERL_CRASH_DUMP ERL_CRASH_DUMP_SECONDS \
       AIUR_BG_STATE_DIR AIUR_CLI_VERSION; do
       if [ -n "${!v:-}" ]; then printf 'export %s=%q\n' "$v" "${!v}"; fi
     done
@@ -844,31 +961,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,9 +996,24 @@ 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
 
+  # Each instance has its own tmux socket. Publish the executable shipped next
+  # to this engine before the TUI opens a chat pane; tmux receives the path as
+  # one argument, including when the npm install directory contains spaces.
+  if [ "$mode" = "foreground" ]; then
+    local ctrlc_helper="$engine_dir/aiur-pane-ctrlc"
+    if [ ! -x "$ctrlc_helper" ] ||
+       ! "$tmux_bin" -L "$socket" -f "$conf" set-option -g @aiur_ctrlc "$ctrlc_helper"; then
+      "$tmux_bin" -L "$socket" -f "$conf" kill-session -t "$session" 2>/dev/null || true
+      rm -f "${launch_tempfiles[@]}" 2>/dev/null || true
+      release_aiur_launch_lock "$launch_lock"
+      die "aiur pane control helper is unavailable at $ctrlc_helper"
+    fi
+  fi
+
   # 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.
@@ -924,12 +1036,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 +1092,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 +1126,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
@@ -1284,7 +1427,8 @@ agent_pid_matches() {
 # 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.
+# process tree, checking the recorded command. A recycled pid with a matching
+# command is still possible (#2844). Idempotent.
 reap_aiur_agents() {
   local socket="$1" pidfile="${2:-}"
   local tmux_bin
@@ -1336,8 +1480,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:-}")"
@@ -1348,13 +1560,21 @@ 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_AGENT_TMPFILE=%q\n' "${AIUR_AGENT_TMPFILE:-}"
     printf 'AIUR_RECORD_WORKSPACE_ROOT_FILE=%q\n' "${AIUR_WORKSPACE_ROOT_FILE:-}"
     printf 'AIUR_RECORD_PROJECT_ROOT=%q\n' "$root"
     printf 'AIUR_RECORD_PROJECT_ROOT_SOURCE=%q\n' "${AIUR_PROJECT_ROOT_SOURCE:-}"
     printf 'AIUR_RECORD_WRITTEN_AT=%q\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)"
   } >"$tmp" || { rm -f "$tmp" 2>/dev/null || true; return 0; }
   chmod 0600 "$tmp" 2>/dev/null || true
-  mv "$tmp" "$record" 2>/dev/null || rm -f "$tmp" 2>/dev/null || true
+  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 +1689,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
@@ -1570,6 +1800,31 @@ workspace_root_file_from_instance_record() {
   printf '%s\n' "$AIUR_RECORD_WORKSPACE_ROOT_FILE"
 }
 
+agent_pidfile_from_instance_record() {
+  load_aiur_instance_record "$(aiur_instance_record_path)" || return 1
+  if [ -n "${AIUR_RECORD_AGENT_TMPFILE:-}" ]; then
+    printf '%s\n' "$AIUR_RECORD_AGENT_TMPFILE"
+    return 0
+  fi
+
+  # Records written before the pidfile field still carry the handoff created
+  # by the same launcher: aiur-PID-workspace-root and aiur-PID-agents share a
+  # runtime directory. Derive that one file only when the old path has the
+  # exact launch shape under this runtime root; never scan other instances.
+  local session_root="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}" handoff pid
+  session_root="${session_root%/}"
+  [ -n "$session_root" ] || session_root=/
+  handoff="${AIUR_RECORD_WORKSPACE_ROOT_FILE:-}"
+  case "$handoff" in
+    "$session_root"/aiur-*-workspace-root) ;;
+    *) return 1 ;;
+  esac
+  pid="${handoff#"$session_root"/aiur-}"
+  pid="${pid%-workspace-root}"
+  [[ "$pid" =~ ^[0-9]+$ ]] || return 1
+  printf '%s/aiur-%s-agents\n' "$session_root" "$pid"
+}
+
 # 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
@@ -1742,7 +1997,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 +2024,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 +2066,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 +2112,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"
@@ -1866,6 +2141,7 @@ load_aiur_instance_record() {
   AIUR_RECORD_INSTANCE_KEY=""
   AIUR_RECORD_SESSION=""
   AIUR_RECORD_SOCKET=""
+  AIUR_RECORD_AGENT_TMPFILE=""
   AIUR_RECORD_WORKSPACE_ROOT_FILE=""
   AIUR_RECORD_PROJECT_ROOT=""
   AIUR_RECORD_PROJECT_ROOT_SOURCE=""
@@ -2004,6 +2280,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 +2309,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 +2334,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
 
@@ -2341,7 +2636,8 @@ cmd_reset_budget() {
 # 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 usage="aiur: message expects an issue ID and text (e.g. aiur message 44 \"ship it\" or aiur message 44 --message-id ID \"ship it\")"
+  local message_id="" message_id_given=0
 
   local issue="${1:-}"
   if [ -z "$issue" ] || [[ ! "$issue" =~ ^[0-9]+$ ]]; then
@@ -2350,6 +2646,26 @@ cmd_message() {
   fi
   shift
 
+  # `--message-id ID` names this send, so a retry after an unknown outcome
+  # returns the first copy instead of queueing a second one (#2717).
+  case "${1:-}" in
+    --message-id)
+      [ "$#" -gt 1 ] || { echo "aiur: message --message-id requires a value" >&2; exit 64; }
+      message_id="$2"
+      message_id_given=1
+      shift 2
+      ;;
+    --message-id=*)
+      message_id="${1#--message-id=}"
+      message_id_given=1
+      shift
+      ;;
+  esac
+  if [ "$message_id_given" = 1 ] && [[ ! "$message_id" =~ ^[A-Za-z0-9._:-]{1,128}$ ]]; then
+    echo "aiur: message --message-id must be 1-128 letters, digits, '.', '_', ':' or '-' (it cannot be empty)" >&2
+    exit 64
+  fi
+
   local text="$*"
   if [ -z "$text" ]; then
     echo "$usage" >&2
@@ -2358,7 +2674,11 @@ cmd_message() {
 
   local encoded
   encoded="$(printf '%s' "$text" | base64 | tr -d '\n')"
-  run_control_rpc "Aiur.AgentControlCLI.message(\"$issue\", Base.decode64!(\"$encoded\"))"
+  if [ -n "$message_id" ]; then
+    run_control_rpc "Aiur.AgentControlCLI.message(\"$issue\", Base.decode64!(\"$encoded\"), \"$message_id\")"
+  else
+    run_control_rpc "Aiur.AgentControlCLI.message(\"$issue\", Base.decode64!(\"$encoded\"))"
+  fi
 }
 
 # `aiur agents` — concise one-line-per-agent state + current activity from a
@@ -2427,7 +2747,7 @@ encode_control_value() {
 # 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
+  local decision_id="${1:-}" expected_version="" option_id="" custom_response="" rationale="" idempotency_key="" executor_id="aiur-cli" supersede=0 arg
   if [ -z "$decision_id" ] || [[ "$decision_id" = -* ]]; then
     echo "aiur: executor-answer expects exactly one decision ID" >&2
     exit 64
@@ -2449,6 +2769,7 @@ cmd_executor_answer() {
       --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=}" ;;
+      --supersede) supersede=1 ;;
       -*) 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
@@ -2473,6 +2794,9 @@ cmd_executor_answer() {
   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")\")"
+  if [ "$supersede" -eq 1 ]; then
+    opts="$opts, supersede: true"
+  fi
   local AIUR_CONTROL_ATTEMPT_CONTEXT="decision ID ${decision_id} with expected version ${expected_version}"
   run_control_rpc "Aiur.AgentControlCLI.executor_answer([$opts])"
 }
@@ -2860,6 +3184,33 @@ cmd_executor_roster() {
   run_control_rpc "Aiur.AgentControlCLI.executor_roster(json: $json_arg)"
 }
 
+cmd_executor_fast_forward() {
+  local wake_id="${1:-}" as="" arg
+  [ -n "$wake_id" ] || { echo "aiur: executor-fast-forward expects a positive wake id" >&2; exit 64; }
+  shift
+  [[ "$wake_id" =~ ^[1-9][0-9]*$ ]] || { echo "aiur: executor-fast-forward expects a positive wake id" >&2; exit 64; }
+
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --as)
+        shift
+        [ "$#" -gt 0 ] && [ -n "${1:-}" ] || { echo "aiur: executor-fast-forward --as requires a consumer id" >&2; exit 64; }
+        as="$1"
+        ;;
+      --as=*)
+        as="${arg#--as=}"
+        [ -n "$as" ] || { echo "aiur: executor-fast-forward --as requires a consumer id" >&2; exit 64; }
+        ;;
+      *) echo "aiur: executor-fast-forward accepts <wake-id> and --as <id>" >&2; exit 64 ;;
+    esac
+    shift
+  done
+
+  executor_validate_consumer_id "$as" "executor-fast-forward"
+  run_control_rpc "Aiur.AgentControlCLI.executor_fast_forward($wake_id, [$(executor_as_keyword "$as")])"
+}
+
 cmd_executor_claim() {
   local as="" arg
   while [ "$#" -gt 0 ]; do
@@ -3157,8 +3508,9 @@ cmd_stop() {
   export RELEASE_NODE ERL_EPMD_ADDRESS
   resolve_control_identity_from_records
 
-  local workspace_root_file
+  local workspace_root_file agent_pidfile
   workspace_root_file="$(workspace_root_file_from_instance_record 2>/dev/null || true)"
+  agent_pidfile="$(agent_pidfile_from_instance_record 2>/dev/null || true)"
 
   local tmux_bin
   tmux_bin="$(command -v tmux || true)"
@@ -3196,8 +3548,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
@@ -3212,16 +3569,13 @@ cmd_stop() {
     "$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
+  # Belt-and-suspenders for this run's headless agents after the BEAM exits.
+  # The instance record owns its pidfile; a global sweep can kill live agents
+  # belonging to another instance that shares the runtime directory.
+  if [ -n "$agent_pidfile" ] && [ -e "$agent_pidfile" ]; then
+    reap_aiur_agents "" "$agent_pidfile"
+    rm -f "$agent_pidfile" 2>/dev/null || true
+  fi
 
   reap_stale_manual_smoke 0
   sweep_dead_tmux_sockets
@@ -3707,10 +4061,6 @@ aiur_engine_main() {
     findings)
       run_findings "$@"
       ;;
-    guard-pr-deletions)
-      shift
-      "$engine_dir/guard-pr-deletions.sh" "$@"
-      ;;
     ask | asks)
       run_asks "$@"
       ;;
@@ -3801,6 +4151,10 @@ aiur_engine_main() {
       shift
       cmd_executor_roster "$@"
       ;;
+    executor-fast-forward)
+      shift
+      cmd_executor_fast_forward "$@"
+      ;;
     executor-claim)
       shift
       cmd_executor_claim "$@"

package/libexec/aiur-pane-ctrlc

@@ -0,0 +1,135 @@
+#!/usr/bin/env sh
+# Opencode pane Ctrl+C bridge. Bound to `C-c` for non-agent-list panes in
+# aiur.tmux.conf. Asks Aiur what a Ctrl+C should do for the agent painted
+# into this pane (drain a queued message, pause an idle agent, or close
+# the pane when already paused) and acts on the answer.
+#
+# The whole point is safe degradation: if Aiur is unreachable, the URL is
+# unset, or anything else goes wrong, we fall back to plain `kill-pane`,
+# which is exactly the pre-bridge behaviour. The 3-state UX is a pure
+# enhancement layered on top — a failure here never strands the Executor
+# with a pane they cannot close.
+#
+# Args:
+#   $1  tmux pane id (e.g. "%9")
+#   $2  control base URL (e.g. "http://127.0.0.1:4000"), may be empty
+#
+# Runs inside tmux `run-shell`, so `$TMUX` is set and a bare `tmux`
+# command targets the same server/socket.
+set -u
+
+pane_id="${1:-}"
+control_url="${2:-}"
+# Optional action: "hide" skips the 3-state interrupt query and goes
+# straight to hide-with-kill-fallback (the Ctrl+Q binding's path).
+mode="${3:-interrupt}"
+
+# Always-on breadcrumb so a Ctrl+C that closes a pane leaves evidence of which
+# branch ran — the tmux binding and this helper are otherwise invisible to
+# aiur.log. One line per press; pane id and outcome only, never the URL.
+log_ctrlc() {
+  printf '%s ctrlc pane_id=%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$pane_id" "$1" \
+    >> "${TMPDIR:-/tmp}/aiur-ctrlc.log" 2>/dev/null || true
+}
+
+close_pane() {
+  log_ctrlc "action=close_pane reason=${1:-degraded}"
+  [ -n "$pane_id" ] && tmux kill-pane -t "$pane_id" 2>/dev/null
+  exit 0
+}
+
+# Closing a chat pane must never kill the opencode-attach process — ask
+# Aiur to HIDE the pane (move it to the warm window, slot binding kept)
+# so reopening swaps the same pane back instantly. Only when the hide
+# call fails (Aiur down, unknown pane) does this degrade to kill-pane.
+hide_pane() {
+  if [ -n "$control_url" ]; then
+    # shellcheck disable=SC2086
+    if curl -fsS -m 2 \
+      -H 'X-Aiur-Request: 1' \
+      -H 'Origin: http://127.0.0.1' \
+      --data-urlencode "pane_id=${pane_id}" \
+      $auth_args \
+      "${control_url}/api/v1/pane/hide" >/dev/null 2>&1; then
+      log_ctrlc "action=hide_pane reason=${1:-requested}"
+      exit 0
+    fi
+  fi
+
+  close_pane "hide_failed_${1:-requested}"
+}
+
+# No pane to act on, or no idea where Aiur is listening: degrade to close.
+[ -z "$pane_id" ] && exit 0
+
+# Loopback dashboards bind without auth; only attach credentials when the
+# Executor has explicitly configured them for a non-loopback bind.
+auth_args=""
+if [ -n "${AIUR_DASHBOARD_USERNAME:-}" ] && [ -n "${AIUR_DASHBOARD_PASSWORD:-}" ]; then
+  auth_args="--user ${AIUR_DASHBOARD_USERNAME}:${AIUR_DASHBOARD_PASSWORD}"
+fi
+
+# Ctrl+Q path: unconditional hide (kill only as fallback).
+[ "$mode" = "hide" ] && hide_pane "ctrl_q"
+
+[ -z "$control_url" ] && close_pane "no_control_url"
+
+# The interrupt timeout MUST exceed the orchestrator's own 5s
+# GenServer.call timeout: that call serializes behind the single
+# Orchestrator mailbox, so under load the reply can take seconds. A
+# shorter curl timeout abandons a call that would have succeeded and then
+# (below) degraded to a destructive kill — exactly the race that reset a
+# live conversation when Ctrl+C was pressed on a busy agent.
+# shellcheck disable=SC2086
+response="$(
+  curl -fsS -m 8 \
+    -H 'X-Aiur-Request: 1' \
+    -H 'Origin: http://127.0.0.1' \
+    --data-urlencode "pane_id=${pane_id}" \
+    $auth_args \
+    "${control_url}/api/v1/pane/interrupt" 2>/dev/null
+)"
+curl_status=$?
+
+# Curl failed: distinguish "aiur busy" from "aiur unreachable" so a slow
+# call never costs the Executor their live pane. Exit 28 is a timeout —
+# the dashboard is alive and the interrupt is almost certainly still
+# being processed server-side, so KEEP THE PANE OPEN (killing it here is
+# what broke the opencode pipe, tripped :repl_gone, and re-dispatched a
+# fresh session). Any other non-zero (connection refused, DNS, HTTP
+# error) means aiur is unreachable or erroring: degrade to a
+# non-destructive hide (session + attach survive); hide_pane itself falls
+# back to kill only if the hide call also fails.
+if [ "$curl_status" -ne 0 ]; then
+  if [ "$curl_status" -eq 28 ]; then
+    log_ctrlc "action=keep_open reason=curl_timeout"
+    exit 0
+  fi
+  hide_pane "curl_failed_${curl_status}"
+fi
+
+# opencode owns the interrupt for codex/opencode agents: forward its native
+# interrupt key (Esc) to the pane so it drains its queued Executor message and
+# keeps working. Aiur mutates no state on this reply; the keystroke is the
+# whole effect. Pane stays open.
+case "$response" in
+  *send_interrupt*)
+    tmux send-keys -t "$pane_id" Escape 2>/dev/null
+    log_ctrlc "action=send_interrupt response=${response}"
+    exit 0
+    ;;
+esac
+
+# The agent handled the keypress (interrupted its REPL turn or paused). Leave
+# the pane open so the Executor stays in the conversation.
+case "$response" in
+  *interrupted* | *pause_requested* | *paused*)
+    log_ctrlc "action=keep_open response=${response}"
+    exit 0
+    ;;
+esac
+
+# close_pane, an error, or any unexpected body: hide the pane (the
+# paused agent's session and attach process stay alive; reopen swaps the
+# same pane back). Kill only when the hide call itself fails.
+hide_pane "response=${response}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiur-cli",
-  "version": "0.0.5-nightly.e30c636",
+  "version": "0.0.6",
   "description": "AI Unit Runtime for Executors.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/aiur-team/aiur",
@@ -18,7 +18,7 @@
   "files": [
     "bin/aiur.js",
     "libexec/aiur-engine.sh",
-    "libexec/guard-pr-deletions.sh",
+    "libexec/aiur-pane-ctrlc",
     "scripts/postinstall.mjs",
     "share/aiur.tmux.conf"
   ],
@@ -35,8 +35,8 @@
   ],
   "opencodeVersion": "1.17.10",
   "optionalDependencies": {
-    "aiur-cli-linux-x64": "0.0.5-nightly.e30c636",
-    "aiur-cli-linux-arm64": "0.0.5-nightly.e30c636",
-    "aiur-cli-darwin-arm64": "0.0.5-nightly.e30c636"
+    "aiur-cli-linux-x64": "0.0.6",
+    "aiur-cli-linux-arm64": "0.0.6",
+    "aiur-cli-darwin-arm64": "0.0.6"
   }
 }

package/share/aiur.tmux.conf

@@ -19,6 +19,15 @@ set -g mouse on
 # for the agent list pane's Shift+Enter "open in new pane" keybind.
 set -s extended-keys on
 set -as terminal-features "*:extkeys"
+# Advertise synchronized-output (DEC private mode 2026) support to tmux so
+# it presents each agent-list frame atomically to the attached client. The
+# renderer wraps every frame in `\e[?2026h … \e[?2026l`; without this
+# feature tmux applies the app's sync internally but still streams partial
+# cell updates to the outer terminal, so a multi-byte glyph (emoji, box
+# drawing, the 🔄 title / events `💬`) caught mid-repaint flashes as `?`
+# replacement chars just above the "oldest" divider. Modern terminals
+# (iTerm2, kitty, wezterm, Ghostty, recent xterm/VTE) all support 2026.
+set -as terminal-features "*:sync"
 set -g status off
 
 # Show each pane's title in a one-line top border. PaneManager sets every
@@ -58,9 +67,24 @@ bind-key -n M-Tab  select-pane -t :.0
 # tmux/tmux#882).
 set -gq @aiur_ctrlc ''
 set -gq @aiur_control_url ''
+# NB: reference `#{q:@aiur_ctrlc}` inline rather than via a `h=...; $h` shell
+# variable. tmux re-parses this double-quoted run-shell argument when if-shell
+# dispatches it and expands `$h` itself (to empty), so a shell-variable form
+# silently falls through to the `else` branch and raw-kills the pane. `q:`
+# shell-escapes installed paths, including quotes and whitespace.
 bind-key -n C-c if-shell -F '#{==:#{pane_index},0}' \
                  'kill-session' \
-                 'run-shell "h=\"#{@aiur_ctrlc}\"; if [ -x \"$h\" ]; then \"$h\" \"#{pane_id}\" \"#{@aiur_control_url}\"; else tmux kill-pane -t \"#{pane_id}\"; fi"'
+                 'run-shell "if [ -x #{q:@aiur_ctrlc} ]; then #{q:@aiur_ctrlc} \"#{pane_id}\" \"#{@aiur_control_url}\"; else tmux kill-pane -t \"#{pane_id}\"; fi"'
+
+# Ctrl+Q closes a chat pane WITHOUT touching agent state — no pause, and
+# the opencode-attach process survives: the helper asks Aiur to HIDE the
+# pane (move to the warm window), so reopening from the agent list swaps
+# the same pane back instantly. Degrades to kill-pane when the helper or
+# Aiur is unreachable. On the agent list itself (pane 0) it is a
+# deliberate no-op; do NOT mirror the C-c binding's pane-0 kill-session.
+bind-key -n C-q if-shell -F '#{==:#{pane_index},0}' \
+                 '' \
+                 'run-shell "if [ -x #{q:@aiur_ctrlc} ]; then #{q:@aiur_ctrlc} \"#{pane_id}\" \"#{@aiur_control_url}\" hide; else tmux kill-pane -t \"#{pane_id}\"; fi"'
 
 # Pane layout is owned exclusively by `Aiur.PaneManager`, which applies an
 # explicit `select-layout <string>` after every slot change. No

package/libexec/guard-pr-deletions.sh

@@ -1,70 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-readonly deletion_threshold=50
-base_branch="${1:-${AIUR_BASE_BRANCH:-}}"
-
-if [[ -z "$base_branch" ]]; then
-  echo "guard-pr-deletions: base branch is required (argument or AIUR_BASE_BRANCH)" >&2
-  exit 2
-fi
-
-if ! git diff --quiet || ! git diff --cached --quiet; then
-  echo "guard-pr-deletions: tracked changes must be committed before checking PR deletions" >&2
-  exit 2
-fi
-
-if ! git fetch --quiet --no-tags origin "refs/heads/$base_branch"; then
-  echo "guard-pr-deletions: could not fetch origin/$base_branch; refusing to use a stale base" >&2
-  exit 2
-fi
-
-if ! base_sha="$(git rev-parse --verify 'FETCH_HEAD^{commit}')"; then
-  echo "guard-pr-deletions: fetched base commit is unavailable" >&2
-  exit 2
-fi
-
-scratch_dir="$(mktemp -d)"
-trap 'rm -rf "$scratch_dir"' EXIT
-
-git diff --diff-filter=D --name-only "$base_sha"..HEAD | LC_ALL=C sort -u >"$scratch_dir/deleted"
-deleted_count="$(wc -l <"$scratch_dir/deleted" | tr -d ' ')"
-
-if ((deleted_count <= deletion_threshold)); then
-  echo "guard-pr-deletions: $deleted_count untouched file deletions (limit: $deletion_threshold)"
-  exit 0
-fi
-
-branch_start="${AIUR_BRANCH_START_SHA:-}"
-
-if [[ -z "$branch_start" ]] && git rev-parse --verify --quiet 'refs/aiur/branch-start^{commit}' >/dev/null; then
-  branch_start="$(git rev-parse --verify 'refs/aiur/branch-start^{commit}')"
-fi
-
-if [[ -z "$branch_start" ]]; then
-  echo "guard-pr-deletions: refusing $deleted_count deletions because the workspace branch-start ref is unavailable" >&2
-  exit 1
-fi
-
-if ! git merge-base --is-ancestor "$branch_start" HEAD; then
-  echo "guard-pr-deletions: workspace branch-start $branch_start is not an ancestor of HEAD" >&2
-  exit 2
-fi
-
-git log --format= --name-only "$branch_start"..HEAD | sed '/^$/d' | LC_ALL=C sort -u >"$scratch_dir/touched"
-# Both inputs are sorted with LC_ALL=C, so comm must compare with the same
-# collation. Under a UTF-8 locale comm reads C-sorted input as unsorted (any
-# mix of upper- and lower-case initial paths, e.g. README.md beside src/...)
-# and its output on unsorted input is undefined -- it can drop rows, which
-# would make this guard under-count untouched deletions and fail open.
-LC_ALL=C comm -23 "$scratch_dir/deleted" "$scratch_dir/touched" >"$scratch_dir/untouched-deletions"
-
-untouched_count="$(wc -l <"$scratch_dir/untouched-deletions" | tr -d ' ')"
-
-if ((untouched_count > deletion_threshold)); then
-  echo "guard-pr-deletions: refusing PR with $untouched_count untouched file deletions (limit: $deletion_threshold)" >&2
-  sed -n '1,20p' "$scratch_dir/untouched-deletions" >&2
-  exit 1
-fi
-
-echo "guard-pr-deletions: $untouched_count untouched file deletions (limit: $deletion_threshold)"