aiur-cli 0.0.0 → 0.0.2

package/README.md

@@ -0,0 +1,72 @@
+# AIUR
+
+**AI Unit Runtime for Executors**
+
+Oversee a fleet of coding agents that **coordinate via events**.
+
+> [!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.
+
+## Install
+
+```bash
+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.
+
+## Get started
+
+```bash
+cd your-repo
+aiur init     # interactive setup wizard
+aiur          # start agents (foreground); use `aiur --bg` to detach
+```
+
+`aiur init` scaffolds `.aiurconfig` and provisions the repo. It walks you through:
+
+1. **Where to store config** — repo-local `./.aiurconfig` or global `~/.aiurconfig`.
+2. **Tracker** — GitHub or Linear, plus the repo.
+3. **Agents & routing** — Claude and/or Codex, optional per-complexity model
+   routing, and the permission mode.
+4. **Limits** — max concurrent agents, turns, duration, pre-warmed sessions, and
+   polling interval.
+5. **GitHub token** — to create labels and act as the bot account.
+6. **Labels** — the lifecycle (`agent:*`), complexity, model, and remote-control
+   labels aiur routes on. Only missing labels are created; a group that already
+   exists is reported as created and skipped.
+
+Re-running resumes from your saved answers. When setup finishes, add `agent:todo`
+to the issues you want worked and run `aiur`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `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 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 |
+
+## 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. Supports Claude and Codex.
+- **Take the Wheel** — Drive at any moment via pre-warmed [Opencode](https://opencode.ai) sessions in configurable tmux panes.
+- **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.
+
+---
+
+_Command macro, delegate micro, maximize APM._
+
+[github.com/its-everdred/aiur](https://github.com/its-everdred/aiur)

package/bin/aiur.js

@@ -1,6 +1,246 @@
 #!/usr/bin/env node
-console.error(
-  "aiur-cli is not released yet — this is a placeholder reserving the name.\n" +
-    "Track progress at https://github.com/its-everdred/aiur",
-);
-process.exit(1);
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+// 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
+// missing tmux/opencode/brew degrades gracefully rather than crashing.
+function safeSpawn(command, args, options) {
+  try {
+    return spawnSync(command, args, options);
+  } catch (error) {
+    return { error, status: null, stdout: "" };
+  }
+}
+
+// Map this host to the platform package that carries its OTP release.
+const PLATFORMS = {
+  "darwin arm64": "darwin-arm64",
+  "darwin x64": "darwin-x64",
+  "linux arm64": "linux-arm64",
+  "linux x64": "linux-x64",
+};
+
+const MIN_TMUX = [3, 3];
+
+function fail(message) {
+  process.stderr.write(`aiur: ${message}\n`);
+  process.exit(1);
+}
+
+function resolveReleaseDir() {
+  // A pre-set AIUR_RELEASE_DIR (the dev shim, or local `npm pack` install
+  // verification) wins over platform-package resolution.
+  const preset = process.env.AIUR_RELEASE_DIR;
+  if (preset) {
+    try {
+      if (fs.statSync(preset).isDirectory()) return preset;
+    } catch (_) {
+      // fall through to the explicit error below
+    }
+    fail(`AIUR_RELEASE_DIR is set but not a directory: ${preset}`);
+  }
+
+  const triple = PLATFORMS[`${process.platform} ${process.arch}`];
+  if (!triple) {
+    fail(
+      `unsupported platform ${process.platform}/${process.arch}. ` +
+        "Supported: darwin/linux on arm64/x64. " +
+        "See https://github.com/its-everdred/aiur",
+    );
+  }
+
+  const pkg = `aiur-cli-${triple}`;
+  let pkgJson;
+  try {
+    pkgJson = require.resolve(`${pkg}/package.json`);
+  } catch (err) {
+    if (err && err.code === "MODULE_NOT_FOUND") {
+      fail(
+        `platform package "${pkg}" is not installed. ` +
+          "This usually means optional dependencies were skipped " +
+          "(--no-optional, a shared lockfile, or a known npm install bug). " +
+          "Reinstall aiur-cli, or see https://github.com/its-everdred/aiur",
+      );
+    }
+    throw err;
+  }
+
+  return path.join(path.dirname(pkgJson), "release");
+}
+
+// Pinned opencode version — single source of truth is this package's
+// package.json `opencodeVersion` (kept in sync with scripts/postinstall.mjs
+// and mise.toml).
+function opencodeVersion() {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"),
+  );
+  return pkg.opencodeVersion;
+}
+
+// ---------------------------------------------------------------------------
+// Lazy first-run provisioning
+//
+// The npm postinstall (scripts/postinstall.mjs) provisions tmux + opencode, but
+// bun/pnpm/yarn block postinstall scripts by default — a package cannot force a
+// consumer to run them. So the launcher guarantees the peer tools here, on the
+// first real (TUI) launch, regardless of which package manager installed
+// aiur-cli. Both steps are idempotent (skip when already satisfied); tmux is a
+// hard requirement, opencode is best-effort. Honors the same AIUR_SKIP_* env
+// vars as the postinstall. This logic mirrors postinstall.mjs intentionally —
+// the launcher stays dependency-free and cannot import the .mjs counterpart.
+// ---------------------------------------------------------------------------
+
+function tmuxVersion() {
+  const result = safeSpawn("tmux", ["-V"], { encoding: "utf8" });
+  if (result.error || result.status !== 0) return null;
+  const match = /tmux\s+(\d+)\.(\d+)/.exec(result.stdout || "");
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2])];
+}
+
+function tmuxSatisfiesMin() {
+  const version = tmuxVersion();
+  if (!version) return false;
+  const [major, minor] = version;
+  const [needMajor, needMinor] = MIN_TMUX;
+  return major > needMajor || (major === needMajor && minor >= needMinor);
+}
+
+function tmuxHint() {
+  return process.platform === "darwin"
+    ? "install it with: brew install tmux"
+    : "install it with: apt install tmux (or your distro's package manager)";
+}
+
+// Best-effort system install of tmux. macOS uses Homebrew; Linux uses the first
+// package manager present. Never invokes sudo (a hidden password prompt mid-
+// launch would hang). Returns false so the caller can fail with a clear hint.
+function installTmux(platform) {
+  const has = (bin) => !safeSpawn(bin, ["--version"], { stdio: "ignore" }).error;
+  if (platform === "darwin") {
+    if (!has("brew")) return false;
+    return safeSpawn("brew", ["install", "tmux"], { stdio: "inherit" }).status === 0;
+  }
+  if (platform === "linux") {
+    const managers = [
+      ["apt-get", ["install", "-y", "tmux"]],
+      ["dnf", ["install", "-y", "tmux"]],
+      ["apk", ["add", "tmux"]],
+      ["pacman", ["-S", "--noconfirm", "tmux"]],
+    ];
+    for (const [bin, argv] of managers) {
+      if (!has(bin)) continue;
+      return safeSpawn(bin, argv, { stdio: "inherit" }).status === 0;
+    }
+  }
+  return false;
+}
+
+// tmux is required — the TUI runs inside it — so this provisions if missing and
+// fails hard only when tmux still can't be made available.
+function ensureTmux() {
+  if (tmuxSatisfiesMin()) return;
+  if (process.env.AIUR_SKIP_TMUX_INSTALL !== "1") {
+    process.stderr.write(
+      `aiur: tmux (>= ${MIN_TMUX.join(".")}) runs the interactive TUI; installing it…\n`,
+    );
+    installTmux(process.platform);
+  }
+  if (!tmuxSatisfiesMin()) {
+    const v = tmuxVersion();
+    fail(
+      v
+        ? `tmux ${v[0]}.${v[1]} is too old; aiur needs >= ${MIN_TMUX.join(".")}. ${tmuxHint()}`
+        : `tmux is required but was not found on PATH. ${tmuxHint()}`,
+    );
+  }
+}
+
+// True only when the pinned opencode is on PATH; a wrong version (e.g. 1.17.x,
+// which broke the panes) must be replaced, so presence alone isn't enough.
+function opencodeMatchesPin() {
+  const result = safeSpawn("opencode", ["--version"], { encoding: "utf8" });
+  return !result.error && result.status === 0 && (result.stdout || "").trim() === opencodeVersion();
+}
+
+// Install the pinned opencode globally. Forces online so it never inherits an
+// --offline / prefer-offline context (CI, mirrors, air-gapped) that would fail
+// on a cold cache — mirrors scripts/postinstall.mjs:installOpencode.
+function installOpencode() {
+  const env = { ...process.env };
+  delete env.npm_config_offline;
+  delete env.npm_config_prefer_offline;
+  const result = safeSpawn(
+    "npm",
+    ["install", "-g", `opencode-ai@${opencodeVersion()}`, "--no-offline", "--no-prefer-offline"],
+    { stdio: "inherit", env },
+  );
+  return !result.error && result.status === 0;
+}
+
+// opencode powers the interactive "take the wheel" panes. Non-fatal: everything
+// else works without it.
+function ensureOpencode() {
+  if (opencodeMatchesPin()) return;
+  if (process.env.AIUR_SKIP_OPENCODE_INSTALL !== "1") {
+    process.stderr.write(
+      `aiur: provisioning opencode@${opencodeVersion()} (one-time, for the interactive 'take the wheel' panes)…\n`,
+    );
+    installOpencode();
+    if (opencodeMatchesPin()) return;
+  }
+  process.stderr.write(
+    "aiur: opencode was not found on PATH. The interactive 'take the wheel' " +
+      "feature needs it; everything else works without it. " +
+      "Install from https://opencode.ai\n",
+  );
+}
+
+// `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`.
+function isForegroundOneShot(argv) {
+  for (const arg of argv) {
+    if (arg === "--version") return true;
+    if (arg.startsWith("-")) continue;
+    return arg === "init";
+  }
+  return false;
+}
+
+function main() {
+  const releaseDir = resolveReleaseDir();
+
+  if (!isForegroundOneShot(process.argv.slice(2))) {
+    ensureTmux();
+    ensureOpencode();
+  }
+
+  const pkgRoot = path.resolve(__dirname, "..");
+  const launcher = path.join(pkgRoot, "libexec", "aiur-engine.sh");
+
+  const result = spawnSync(launcher, process.argv.slice(2), {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      AIUR_RELEASE_DIR: releaseDir,
+      AIUR_TMUX_CONF: path.join(pkgRoot, "share", "aiur.tmux.conf"),
+    },
+  });
+
+  if (result.error) {
+    fail(`failed to launch ${launcher}: ${result.error.message}`);
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    return;
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+main();

package/libexec/aiur-engine.sh

@@ -0,0 +1,695 @@
+#!/usr/bin/env bash
+#
+# Shared aiur launcher engine.
+#
+# Owns every aiur subcommand. Both the installed `aiur` (bin/aiur.js) and the dev
+# `aiurdev` (scripts/aiurdev) exec this one engine, differing only in which
+# release is run:
+#
+#   AIUR_RELEASE_DIR    release dir whose bin/aiur is exec'd (required; set by the caller)
+#
+# There is a single `aiur` distribution identity (node/cookie/session). aiurdev
+# shares it. The identity vars resolve to the fixed `aiur` values; they remain
+# overridable only so tests can redirect state to a temp dir:
+#
+#   AIUR_BG_STATE_DIR   cookie + state dir  (default: ~/.config/aiur)
+#   AIUR_COOKIE_FILE    cookie file         (default: $AIUR_BG_STATE_DIR/cookie)
+#   AIUR_SESSION_PREFIX tmux session prefix (default: aiur)
+#   AIUR_PROFILES_FILE  profiles file       (default: ~/.config/aiur/aiur.profiles)
+#   AIUR_RELEASE_NODE   full node name      (default: aiur-$USER@127.0.0.1)
+#
+# The release is self-contained (bundled ERTS), so it runs without mise/Elixir on
+# PATH. Dev's build-if-stale step lives in the aiurdev shim, not here.
+
+set -euo pipefail
+
+die() {
+  echo "❌ $*" >&2
+  exit 1
+}
+
+engine_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# --- distribution identity (fixed: the single `aiur` identity) ---------------
+
+aiur_resolve_identity() {
+  local config_home="${XDG_CONFIG_HOME:-$HOME/.config}"
+
+  : "${AIUR_BG_STATE_DIR:=$config_home/aiur}"
+  : "${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}"
+
+  export AIUR_BG_STATE_DIR AIUR_COOKIE_FILE AIUR_SESSION_PREFIX \
+    AIUR_PROFILES_FILE AIUR_RELEASE_NODE
+}
+
+aiur_print_identity() {
+  aiur_resolve_identity
+  printf 'AIUR_RELEASE_DIR=%s\n' "${AIUR_RELEASE_DIR:-}"
+  printf 'AIUR_BG_STATE_DIR=%s\n' "$AIUR_BG_STATE_DIR"
+  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_COOKIE_FILE=%s\n' "$AIUR_COOKIE_FILE"
+}
+
+# --- BEAM distribution (cookie + named node) ---------------------------------
+
+ensure_bg_state_dir() {
+  aiur_resolve_identity
+  mkdir -p "$AIUR_BG_STATE_DIR"
+}
+
+ensure_erlang_cookie() {
+  aiur_resolve_identity
+  ensure_bg_state_dir
+
+  local cookie_file="$AIUR_COOKIE_FILE"
+
+  if [ ! -f "$cookie_file" ]; then
+    (
+      umask 0177
+      tmp_file="$(mktemp "$AIUR_BG_STATE_DIR/cookie.XXXXXX")"
+      head -c 32 /dev/urandom | base64 | tr -d '\n=+/' | head -c 32 >"$tmp_file"
+      mv "$tmp_file" "$cookie_file"
+    )
+    chmod 0400 "$cookie_file"
+  fi
+
+  [ -r "$cookie_file" ] || die "$cookie_file is not readable"
+
+  if [ "$(stat -c '%U' "$cookie_file" 2>/dev/null || stat -f '%Su' "$cookie_file")" != "$USER" ]; then
+    die "$cookie_file is not owned by $USER"
+  fi
+
+  local size
+  size="$(wc -c <"$cookie_file" | tr -d ' ')"
+  [ "$size" -ge 16 ] || die "$cookie_file is shorter than 16 bytes"
+
+  printf '%s' "$cookie_file"
+}
+
+prepare_distribution() {
+  aiur_resolve_identity
+
+  local cookie_file
+  cookie_file="$(ensure_erlang_cookie)" || return 1
+
+  local cookie
+  cookie="$(cat "$cookie_file")"
+
+  export RELEASE_DISTRIBUTION="name"
+  export RELEASE_NODE="$AIUR_RELEASE_NODE"
+  export RELEASE_COOKIE="$cookie"
+  # Pin the distribution listener to 127.0.0.1 too, matching the node-name IP.
+  # {127,0,0,1} is the Erlang tuple — unquoted because bash inside the
+  # surrounding double quotes does not brace-expand it.
+  export ERL_AFLAGS=" -proto_dist inet_tcp -kernel inet_dist_use_interface {127,0,0,1}"
+  export ERL_EPMD_ADDRESS="127.0.0.1"
+  export AIUR_NODE="$RELEASE_NODE"
+  export AIUR_ERLANG_COOKIE="$RELEASE_COOKIE"
+}
+
+# --- release resolution ------------------------------------------------------
+
+release_dir=""
+vsn_dir=""
+release_bin=""
+
+resolve_release() {
+  release_dir="${AIUR_RELEASE_DIR:-}"
+  [ -n "$release_dir" ] || die "AIUR_RELEASE_DIR is not set; the engine must be invoked via the aiur or aiurdev wrapper"
+  [ -d "$release_dir" ] || die "AIUR_RELEASE_DIR does not exist: $release_dir"
+
+  local release_vsn
+  release_vsn="$(cut -d' ' -f2 "$release_dir/releases/start_erl.data")"
+  vsn_dir="$release_dir/releases/$release_vsn"
+  release_bin="$release_dir/bin/aiur"
+  [ -x "$vsn_dir/elixir" ] || die "release elixir launcher not found at $vsn_dir/elixir"
+}
+
+# --- argv round-trip (System.argv is empty under `elixir --eval`) -------------
+
+argv_file=""
+init_argv_file() {
+  argv_file="$(mktemp "${TMPDIR:-/tmp}/aiur-argv.XXXXXX")"
+  : >"$argv_file"
+}
+write_argv() {
+  local a
+  for a in "$@"; do printf '%s\n' "$a" >>"$argv_file"; done
+}
+
+release_cmd=()
+build_release_cmd() {
+  release_cmd=(
+    "$vsn_dir/elixir"
+    --cookie "$RELEASE_COOKIE"
+    --name "$RELEASE_NODE"
+    --erl-config "$vsn_dir/sys"
+    --boot "$vsn_dir/start_clean"
+    --boot-var RELEASE_LIB "$release_dir/lib"
+    --vm-args "$vsn_dir/vm.args"
+    --eval "Aiur.CLI.main(Aiur.CLI.argv_from_file())"
+  )
+}
+
+# Distribution-free boot for the `init` wizard: same interactive `--eval` form
+# (so the wizard's prompts receive keystrokes — `bin/aiur eval` is -noinput),
+# but with no --name/--cookie since the wizard makes no RPC calls.
+build_init_cmd() {
+  release_cmd=(
+    "$vsn_dir/elixir"
+    --erl-config "$vsn_dir/sys"
+    --boot "$vsn_dir/start_clean"
+    --boot-var RELEASE_LIB "$release_dir/lib"
+    --vm-args "$vsn_dir/vm.args"
+    --eval "Aiur.CLI.main(Aiur.CLI.argv_from_file())"
+  )
+}
+
+usage() {
+  cat <<'EOF'
+Usage: aiur [--interactive] [--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 stop             stop the running session
+       aiur status           show agent status
+       aiur pause <ids|--all> | resume <ids|--all>
+       aiur --version
+EOF
+}
+
+# --- one-shot: --version (no tmux) -------------------------------------------
+
+run_version() {
+  resolve_release
+  # Distribution-free (like init): printing the version is a compile-time
+  # constant, so never claim the node name — otherwise `aiur --version` fails
+  # whenever an aiur session is already running.
+  build_init_cmd
+  init_argv_file
+  write_argv "$@"
+  export AIUR_ARGV_FILE="$argv_file"
+  exec "${release_cmd[@]}"
+}
+
+# --- one-shot: init (interactive wizard, distribution-free, no tmux) ----------
+
+run_init() {
+  resolve_release
+  build_init_cmd
+  init_argv_file
+  write_argv "$@"
+  export AIUR_ARGV_FILE="$argv_file"
+  exec "${release_cmd[@]}"
+}
+
+# --- interactive / background run -------------------------------------------
+#
+# mode=foreground attaches the UI and tears down on exit; mode=background leaves
+# the detached tmux session running and returns.
+
+# Load KEY=VALUE pairs from ./.env into the environment so the running release
+# (e.g. GITHUB_TOKEN, dashboard creds) sees what `aiur init` scaffolded there.
+# An already-exported variable always wins, so a shell export overrides the file.
+load_dotenv() {
+  local file=".env" line key val
+  [ -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"
+  done <"$file"
+}
+
+run_session() {
+  local mode="$1"
+  shift
+
+  # --debug is an engine-level convenience on the run path: turn on verbose
+  # logging (AIUR_DEBUG) and strip the flag before the release parses argv.
+  local run_args=() run_arg
+  for run_arg in "$@"; do
+    case "$run_arg" in
+      --debug) export AIUR_DEBUG=1 ;;
+      *) run_args+=("$run_arg") ;;
+    esac
+  done
+  if [ "${#run_args[@]}" -gt 0 ]; then set -- "${run_args[@]}"; else set --; fi
+
+  resolve_release
+
+  local tmux_bin
+  tmux_bin="$(command -v tmux || true)"
+  [ -n "$tmux_bin" ] || die "tmux is required to run aiur; install tmux and retry"
+
+  aiur_resolve_identity
+
+  # Pick up GITHUB_TOKEN / dashboard creds the wizard wrote to ./.env so the
+  # running tracker can authenticate. Shell exports still take precedence.
+  load_dotenv
+
+  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
+  for arg in "$@"; do
+    case "$arg" in
+      --host | --host=*) has_host=1 ;;
+      --interactive) has_interactive=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)
+  [ "$has_ack" -eq 1 ] || injected+=(--i-understand-that-this-will-be-running-without-the-usual-guardrails)
+
+  write_argv "${injected[@]}" "$@"
+  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.
+  if [ -z "${LANG:-}" ] && [ -z "${LC_ALL:-}" ] && [ -z "${LC_CTYPE:-}" ]; then
+    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 conf
+  conf="$(resolve_tmux_conf)"
+  [ -f "$conf" ] || die "tmux conf not found at $conf"
+
+  mkdir -p "$AIUR_BG_STATE_DIR"
+  printf '%s\n' "$session" >"$AIUR_BG_STATE_DIR/state"
+  export AIUR_TMUX_SESSION="$session"
+  export AIUR_TMUX_SOCKET="$socket"
+  export AIUR_TMUX_CONF="$conf"
+  export AIUR_BIN="${BASH_SOURCE[0]}"
+
+  local session_root="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}"
+  export AIUR_SESSION_TMPFILE="${session_root}/aiur-${$}-sessions"
+  : >"$AIUR_SESSION_TMPFILE"
+
+  local startup_capture
+  startup_capture="$(mktemp "${TMPDIR:-/tmp}/aiur-startup.XXXXXX")"
+
+  # 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.
+  local launcher
+  launcher="$(mktemp "${TMPDIR:-/tmp}/aiur-pane.XXXXXX")"
+  chmod +x "$launcher"
+  {
+    printf '#!/usr/bin/env bash\n'
+    printf 'set -o pipefail\n'
+    printf 'cd %q || exit 1\n' "$PWD"
+    local v
+    for v in AIUR_RELEASE_DIR AIUR_ARGV_FILE RELEASE_DISTRIBUTION RELEASE_NODE \
+      RELEASE_COOKIE ERL_AFLAGS ERL_EPMD_ADDRESS AIUR_NODE AIUR_ERLANG_COOKIE \
+      AIUR_TMUX_SESSION AIUR_TMUX_SOCKET AIUR_TMUX_CONF AIUR_BIN \
+      AIUR_SESSION_TMPFILE ELIXIR_ERL_OPTIONS AIUR_LOGS_ROOT AIUR_DEBUG; do
+      if [ -n "${!v:-}" ]; then printf 'export %s=%q\n' "$v" "${!v}"; fi
+    done
+    printf 'capture=%q\n' "$startup_capture"
+    printf '%q' "${release_cmd[0]}"
+    for arg in "${release_cmd[@]:1}"; do printf ' %q' "$arg"; done
+    printf ' 2>&1 | tee -a "$capture"\n'
+    printf 'exit ${PIPESTATUS[0]}\n'
+  } >"$launcher"
+
+  local inner_cmd
+  printf -v inner_cmd '%q; rc=$?; rm -f %q; exit $rc' "$launcher" "$launcher"
+
+  if [ "$mode" = "foreground" ]; then
+    _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"
+    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".
+  if ! "$tmux_bin" -L "$socket" -f "$conf" has-session -t "$session" 2>/dev/null; then
+    kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
+  fi
+
+  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
+    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
+    fi
+    sleep 0.1
+  done
+
+  if [ "$mode" = "background" ]; then
+    echo "aiur started in the background (tmux session ${session}). Attach with: aiur" >&2
+    rm -f "$startup_capture" "$argv_file" 2>/dev/null || true
+    return 0
+  fi
+
+  # 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 $?
+}
+
+resolve_tmux_conf() {
+  if [ -n "${AIUR_TMUX_CONF:-}" ] && [ -f "${AIUR_TMUX_CONF:-}" ]; then
+    printf '%s\n' "$AIUR_TMUX_CONF"
+    return
+  fi
+  local user_conf="${XDG_CONFIG_HOME:-$HOME/.config}/aiur/tmux.conf"
+  if [ -f "$user_conf" ]; then
+    printf '%s\n' "$user_conf"
+    return
+  fi
+  printf '%s\n' "$engine_dir/../share/aiur.tmux.conf"
+}
+
+# TERM-then-KILL every BEAM whose command line matches $1. Reaps a stale node by
+# 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.
+kill_beams_matching() {
+  local pattern="$1" pids pid waited=0
+  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
+    pids="$(pgrep -f -- "$pattern" 2>/dev/null || true)"
+    [ -z "$pids" ] && break
+    sleep 0.1
+    waited=$((waited + 1))
+  done
+  pids="$(pgrep -f -- "$pattern" 2>/dev/null || true)"
+  for pid in $pids; do kill -KILL "$pid" 2>/dev/null || true; done
+}
+
+# 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=""
+_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
+
+  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
+  fi
+
+  # Belt-and-suspenders: reap any BEAM still holding our node name, even one
+  # launched from a different release dir than this run.
+  [ -n "$_session_node" ] && kill_beams_matching "-name ${_session_node}"
+
+  if command -v opencode >/dev/null 2>&1 && [ -s "$_session_tmpfile" ]; then
+    local id
+    while IFS= read -r id; do
+      [ -n "$id" ] || continue
+      opencode session delete "$id" >/dev/null 2>&1 &
+    done <"$_session_tmpfile"
+    wait 2>/dev/null || true
+  fi
+
+  # 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
+  return $code
+}
+install_foreground_traps() {
+  trap 'session_cleanup' EXIT
+  trap 'trap - EXIT INT TERM HUP; session_cleanup; exit 130' INT
+  trap 'trap - EXIT INT TERM HUP; session_cleanup; exit 143' TERM
+  trap 'trap - EXIT INT TERM HUP; session_cleanup; exit 129' HUP
+}
+
+# --- lifecycle (RPC into the running node + tmux ops) ------------------------
+
+trim() {
+  local s="$1"
+  s="${s#"${s%%[![:space:]]*}"}"
+  s="${s%"${s##*[![:space:]]}"}"
+  printf '%s' "$s"
+}
+
+# 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() {
+  local expression="$1"
+  resolve_release
+  prepare_distribution || die "distribution setup failed; cannot contact aiur"
+
+  local marker="__AIUR_CONTROL_EXIT__:"
+  local output status exit_code=0 saw_marker=0 line
+
+  set +e
+  output="$("$release_bin" rpc "$expression" 2>&1)"
+  status=$?
+  set -e
+
+  if [ "$status" -ne 0 ]; then
+    echo "aiur: no running aiur node at ${RELEASE_NODE}; start aiur and try again" >&2
+    return 1
+  fi
+
+  while IFS= read -r line; do
+    case "$line" in
+      "$marker"*)
+        saw_marker=1
+        exit_code="${line#"$marker"}"
+        ;;
+      :ok | "") ;;
+      *) printf '%s\n' "$line" ;;
+    esac
+  done <<<"$output"
+
+  [ "$saw_marker" -eq 1 ] || return 1
+  return "$exit_code"
+}
+
+elixir_list_literal() {
+  local first=1 item
+  printf '['
+  for item in "$@"; do
+    [ "$first" -eq 0 ] && printf ', '
+    printf '"%s"' "$item"
+    first=0
+  done
+  printf ']'
+}
+
+# Parse issue-id targets (e.g. `44 45,46` or `--all`) into parsed_targets/parsed_all.
+parsed_targets=()
+parsed_all=0
+parse_issue_targets() {
+  parsed_targets=()
+  parsed_all=0
+  [ "$#" -gt 0 ] || return 1
+
+  if [ "$#" -eq 1 ] && [ "$1" = "--all" ]; then
+    parsed_all=1
+    return 0
+  fi
+
+  local raw part parts
+  for raw in "$@"; do
+    [ "$raw" = "--all" ] && return 1
+    IFS=',' read -ra parts <<<"$raw"
+    for part in "${parts[@]}"; do
+      part="$(trim "$part")"
+      if [ -z "$part" ] || [[ ! "$part" =~ ^[0-9]+$ ]]; then return 1; fi
+      parsed_targets+=("$part")
+    done
+  done
+
+  [ "${#parsed_targets[@]}" -gt 0 ]
+}
+
+cmd_status() {
+  [ "$#" -eq 0 ] || die "status does not accept arguments"
+  run_control_rpc "Aiur.AgentControlCLI.status()"
+}
+
+cmd_pause_resume() {
+  local command="$1"
+  shift
+  if ! parse_issue_targets "$@"; then
+    echo "aiur: $command expects issue IDs or --all (e.g. aiur $command 44 45,46; aiur $command --all)" >&2
+    exit 64
+  fi
+
+  local expression
+  if [ "$parsed_all" -eq 1 ]; then
+    expression="Aiur.AgentControlCLI.${command}(:all)"
+  else
+    expression="Aiur.AgentControlCLI.${command}($(elixir_list_literal "${parsed_targets[@]}"))"
+  fi
+
+  run_control_rpc "$expression"
+}
+
+sweep_dead_tmux_sockets() {
+  local tmux_bin
+  tmux_bin="$(command -v tmux || true)"
+  [ -n "$tmux_bin" ] || return 0
+
+  local sockdir="${TMUX_TMPDIR:-/tmp}/tmux-$(id -u)"
+  [ -d "$sockdir" ] || return 0
+
+  local removed=0 name path
+  for path in "$sockdir"/*; do
+    [ -S "$path" ] || continue
+    name="${path##*/}"
+    case "$name" in
+      aiur* | *-driver | *-driver-*) ;;
+      *) continue ;;
+    esac
+    if ! "$tmux_bin" -L "$name" list-sessions >/dev/null 2>&1; then
+      rm -f "$path" 2>/dev/null && removed=$((removed + 1))
+    fi
+  done
+
+  [ "$removed" -gt 0 ] && echo "🧹 swept $removed dead aiur tmux socket(s)" >&2
+  return 0
+}
+
+# Stop the running session: kill the tmux session + the release 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}"
+  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.
+  kill_beams_matching "-name ${AIUR_RELEASE_NODE}"
+
+  sweep_dead_tmux_sockets
+}
+
+# --- dispatch ----------------------------------------------------------------
+
+aiur_engine_main() {
+  local cmd="${1:-}"
+  case "$cmd" in
+    __identity)
+      aiur_print_identity
+      ;;
+    help | -h | -help | --h | --help)
+      usage
+      ;;
+    --version)
+      run_version "$@"
+      ;;
+    init)
+      run_init "$@"
+      ;;
+    --bg)
+      shift
+      run_session background "$@"
+      ;;
+    run)
+      shift
+      run_session foreground "$@"
+      ;;
+    status)
+      shift
+      cmd_status "$@"
+      ;;
+    pause | resume)
+      shift
+      cmd_pause_resume "$cmd" "$@"
+      ;;
+    stop)
+      cmd_stop
+      ;;
+    "")
+      run_session foreground
+      ;;
+    -*)
+      # leading-flag forms (e.g. `aiur --interactive <config>`) are a run
+      run_session foreground "$@"
+      ;;
+    *)
+      # a path/config argument is a run; anything else is a usage error
+      if [ -e "$cmd" ]; then
+        run_session foreground "$@"
+      else
+        echo "aiur: unknown command: $cmd" >&2
+        usage >&2
+        exit 64
+      fi
+      ;;
+  esac
+}
+
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  aiur_engine_main "$@"
+fi

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aiur-cli",
-  "version": "0.0.0",
-  "description": "AI Unit Runtime for Executors — placeholder, full release coming soon.",
+  "version": "0.0.2",
+  "description": "AI Unit Runtime for Executors.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/its-everdred/aiur",
   "repository": {
@@ -11,10 +11,24 @@
   "bin": {
     "aiur": "bin/aiur.js"
   },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
+    "test": "bun test"
+  },
   "files": [
-    "bin/aiur.js"
+    "bin/aiur.js",
+    "libexec/aiur-engine.sh",
+    "scripts/postinstall.mjs",
+    "share/aiur.tmux.conf"
   ],
   "engines": {
     "node": ">=18"
+  },
+  "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"
   }
 }

package/scripts/postinstall.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Provisions the peer tools every aiur user needs at runtime, so that a single
+// global `npm install -g aiur-cli` yields a working install with nothing left
+// to install by hand:
+//
+//   - tmux      the multiplexer the interactive TUI runs inside. aiur refuses
+//               to launch without tmux >= MIN_TMUX, so it is a hard runtime
+//               requirement (not merely nice-to-have).
+//   - opencode  the peer CLI behind the interactive "take the wheel" panes.
+//
+// A global aiur-cli install does not link a dependency's bin onto PATH, and
+// tmux is a system package rather than an npm one, so we provision both here.
+// Every step is idempotent (skips when already satisfied) and non-fatal (a
+// failure prints a hint but never breaks the aiur install).
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// opencode
+// ---------------------------------------------------------------------------
+
+// Pinned opencode version, read from package.json `opencodeVersion` (single
+// source of truth — keep in sync with mise.toml). aiur's opencode pane
+// integration is validated against this version; 1.17.x broke custom-provider
+// model resolution (ProviderModelNotFoundError), blanking the chat panes.
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const OPENCODE_PACKAGE = `opencode-ai@${pkg.opencodeVersion}`;
+
+// True only when the *pinned* opencode version is on PATH. A wrong (e.g.
+// newer) version must be reinstalled — leaving 1.17.x in place keeps the
+// panes broken — so a mere presence check isn't enough.
+export function opencodeMatchesPin() {
+  const result = spawnSync("opencode", ["--version"], { encoding: "utf8" });
+  return !result.error && result.status === 0 && result.stdout.trim() === pkg.opencodeVersion;
+}
+
+// Build the nested-install command. Provisioning fetches opencode from the
+// registry, so it must NOT inherit an offline context from the outer
+// `npm install` that triggered this postinstall — CI's `npm install -g
+// --offline`, a `prefer-offline` config, or an air-gapped box. npm hands those
+// to lifecycle scripts as npm_config_* env vars; a naive nested install
+// inherits them and dies with ENOTCACHED on a cold cache, silently leaving
+// opencode unprovisioned. We force online two ways (CLI flags outrank env, and
+// stripping the env vars is belt-and-suspenders) so a plain `npm install -g
+// aiur-cli` provisions opencode regardless of how the parent was invoked.
+export function opencodeInstallSpec(env = process.env) {
+  const childEnv = { ...env };
+  delete childEnv.npm_config_offline;
+  delete childEnv.npm_config_prefer_offline;
+  return {
+    command: "npm",
+    args: ["install", "-g", OPENCODE_PACKAGE, "--no-offline", "--no-prefer-offline"],
+    env: childEnv,
+  };
+}
+
+export function installOpencode() {
+  const spec = opencodeInstallSpec();
+  const result = spawnSync(spec.command, spec.args, { stdio: "inherit", env: spec.env });
+  return !result.error && result.status === 0;
+}
+
+export function provisionOpencode({
+  env = process.env,
+  isPresent = opencodeMatchesPin,
+  install = installOpencode,
+  log = (message) => process.stderr.write(message + "\n"),
+} = {}) {
+  if (env.AIUR_SKIP_OPENCODE_INSTALL === "1") return "skipped:disabled";
+  if (isPresent()) return "skipped:present";
+
+  log(`aiur: installing pinned opencode (${OPENCODE_PACKAGE}) for the interactive 'take the wheel' feature…`);
+
+  if (install()) return "installed";
+
+  log(
+    "aiur: couldn't install opencode automatically. Install it manually: " +
+      "npm install -g opencode-ai (see https://opencode.ai)",
+  );
+  return "failed";
+}
+
+// ---------------------------------------------------------------------------
+// tmux
+// ---------------------------------------------------------------------------
+
+// Minimum tmux the TUI needs. Keep in sync with the runtime preflight in
+// bin/aiur.js — that preflight stays as a safety net, this just front-loads
+// the install so the first `aiur` run isn't a dead end.
+export const MIN_TMUX = [3, 3];
+
+function tmuxHint(platform = process.platform) {
+  return platform === "darwin"
+    ? "install it with: brew install tmux"
+    : "install it with: apt install tmux (or your distro's package manager)";
+}
+
+// True only when a new-enough tmux is on PATH. The TUI won't launch with an
+// older tmux, so — as with opencode's pin — presence alone isn't enough.
+export function tmuxSatisfiesMin(run = (cmd, argv) => spawnSync(cmd, argv, { encoding: "utf8" })) {
+  const result = run("tmux", ["-V"]);
+  if (result.error || result.status !== 0) return false;
+  const match = /tmux\s+(\d+)\.(\d+)/.exec(result.stdout || "");
+  if (!match) return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  const [needMajor, needMinor] = MIN_TMUX;
+  return major > needMajor || (major === needMajor && minor >= needMinor);
+}
+
+// Best-effort system install of tmux. macOS uses Homebrew; Linux uses the
+// first package manager that is present. Returns false (so the caller can
+// print a manual hint) when no usable installer exists or the install fails —
+// including the common non-root case where a Linux package manager can't
+// proceed. We never invoke sudo: a hidden password prompt during `npm install`
+// would hang the install.
+export function installTmux(platform = process.platform) {
+  const has = (bin) => !spawnSync(bin, ["--version"], { stdio: "ignore" }).error;
+
+  if (platform === "darwin") {
+    if (!has("brew")) return false;
+    return spawnSync("brew", ["install", "tmux"], { stdio: "inherit" }).status === 0;
+  }
+
+  if (platform === "linux") {
+    const managers = [
+      ["apt-get", ["install", "-y", "tmux"]],
+      ["dnf", ["install", "-y", "tmux"]],
+      ["apk", ["add", "tmux"]],
+      ["pacman", ["-S", "--noconfirm", "tmux"]],
+    ];
+    for (const [bin, argv] of managers) {
+      if (!has(bin)) continue;
+      return spawnSync(bin, argv, { stdio: "inherit" }).status === 0;
+    }
+  }
+
+  return false;
+}
+
+export function provisionTmux({
+  env = process.env,
+  isPresent = tmuxSatisfiesMin,
+  install = installTmux,
+  platform = process.platform,
+  log = (message) => process.stderr.write(message + "\n"),
+} = {}) {
+  if (env.AIUR_SKIP_TMUX_INSTALL === "1") return "skipped:disabled";
+  if (isPresent()) return "skipped:present";
+
+  log(
+    `aiur: tmux (>= ${MIN_TMUX.join(".")}) not found; aiur's interactive TUI runs inside tmux. Installing…`,
+  );
+
+  if (install(platform)) return "installed";
+
+  log(`aiur: couldn't install tmux automatically. ${tmuxHint(platform)}`);
+  return "failed";
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+// Run only when invoked directly as the postinstall step, not when a test
+// imports the helpers above. tmux is provisioned first — it is the hard
+// requirement — then opencode for the optional panes.
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  provisionTmux();
+  provisionOpencode();
+}

package/share/aiur.tmux.conf

@@ -0,0 +1,76 @@
+# Aiur's isolated tmux configuration.
+#
+# Loaded by `scripts/aiur` via `tmux -L aiur-$USER -f <path>` so it
+# runs on its own socket and never touches the user's normal tmux server
+# or `~/.tmux.conf`.
+#
+# To customize without touching this tracked file, copy it to
+# `~/.config/aiur/tmux.conf` and edit there — that path takes
+# precedence and survives `git pull`.
+
+# No prefix — every Aiur binding is direct (`-n`).
+set -g prefix None
+unbind-key -aT prefix
+
+set -sg escape-time 0
+set -g mouse on
+# Pass CSI-u extended-key sequences (e.g. Shift+Enter as `\e[13;2u`)
+# through to the foreground pane instead of collapsing them. Required
+# for the agent list pane's Shift+Enter "open in new pane" keybind.
+set -s extended-keys on
+set -as terminal-features "*:extkeys"
+set -g status off
+set -g history-limit 50000
+set -g default-terminal "tmux-256color"
+set -ga terminal-overrides ",*256col*:Tc"
+set -g remain-on-exit off
+set -g destroy-unattached off
+
+# Pane navigation (cycle right / cycle left).
+bind-key -n Tab    select-pane -t :.+
+bind-key -n BTab   select-pane -t :.-
+
+# Option+Tab from inside any chat pane jumps focus to pane 0 (the
+# agent list, by convention — see the C-c handler below for the same
+# pane-index assumption).
+bind-key -n M-Tab  select-pane -t :.0
+
+# Close: pane 0 (the agent list, by convention) tears down the whole
+# session; any other pane routes Ctrl+C through the opencode bridge
+# helper, which asks Aiur for the 3-state action (drain a queued message,
+# pause an idle agent, or close an already-paused pane). `@aiur_ctrlc` is
+# the helper path (set by the launcher) and `@aiur_control_url` is the
+# dashboard URL (published by Aiur once the server binds). When either is
+# unset, or the helper isn't executable, Ctrl+C degrades to a plain pane
+# close — the pre-bridge behaviour. `if-shell -F` is the synchronous
+# format-string form so the condition is evaluated against tmux's format
+# engine (the shell-mode `if-shell` has been buggy since tmux 2.4 —
+# tmux/tmux#882).
+set -gq @aiur_ctrlc ''
+set -gq @aiur_control_url ''
+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"'
+
+# Pane layout is owned exclusively by `Aiur.PaneManager`, which applies an
+# explicit `select-layout <string>` after every slot change. No
+# `after-split-window` hook lives here — historically a hook ran
+# `select-layout even-horizontal` to "rebalance widths", but it ran on every
+# split (including PaneManager's anchored slot splits) and forced every pane
+# into a single equal-width row, defeating the slot grid. See issue #34.
+
+# Wheel routing:
+#   1. If the foreground app set mouse mode (opencode-attach / any Bubble Tea
+#      TUI does), forward wheel events with `send-keys -M` so the app handles
+#      scroll inside its own viewport.
+#   2. Else if tmux is already in copy mode (`pane_in_mode`), forward.
+#   3. Else (plain shell pane, mobile SSH client doing touch-scroll) enter
+#      copy mode so the user can scroll the pane's scrollback buffer.
+#
+# Without (1), wheel up on an opencode chat pane would force tmux into copy
+# mode against opencode's full-screen TUI, which has no tmux-side scrollback
+# — the indicator just sticks at `[0/0]` and chat history can't be reached.
+bind-key -n WheelUpPane if-shell -F -t = '#{?mouse_any_flag,1,0}' \
+                         'send-keys -M' \
+                         "if-shell -F -t = '#{pane_in_mode}' 'send-keys -M' 'copy-mode -e -t ='"
+bind-key -n WheelDownPane send-keys -M