aiur-cli 0.0.9-nightly.5a0d430 → 0.0.9-nightly.fac02a9

package/bin/aiur.js

@@ -165,8 +165,8 @@ function ensureTmux() {
 // True only when the pinned opencode is on PATH; a wrong (e.g. newer,
 // unverified) version must be replaced with the pin, so presence alone
 // isn't enough.
-function opencodeMatchesPin() {
-  const result = safeSpawn("opencode", ["--version"], { encoding: "utf8" });
+function opencodeMatchesPin(command = "opencode") {
+  const result = safeSpawn(command, ["--version"], { encoding: "utf8" });
   return !result.error && result.status === 0 && (result.stdout || "").trim() === opencodeVersion();
 }
 
@@ -185,40 +185,60 @@ function installOpencode() {
   return !result.error && result.status === 0;
 }
 
+// npm's global bin may be shadowed by another OpenCode on the incoming PATH.
+// Verify the actual installed executable before making it the release's choice.
+function selectGlobalOpencode() {
+  const result = safeSpawn("npm", ["prefix", "-g"], { encoding: "utf8" });
+  if (result.error || result.status !== 0) return false;
+  const prefix = (result.stdout || "").trim();
+  if (!path.isAbsolute(prefix)) return false;
+  const bin = path.join(prefix, "bin");
+  if (!opencodeMatchesPin(path.join(bin, "opencode"))) return false;
+  process.env.PATH = `${bin}${path.delimiter}${process.env.PATH || ""}`;
+  return true;
+}
+
 // opencode powers the interactive "take the wheel" panes. Non-fatal: everything
 // else works without it.
 function ensureOpencode() {
-  if (opencodeMatchesPin()) return;
+  if (opencodeMatchesPin() || selectGlobalOpencode()) 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;
+    if (opencodeMatchesPin() || selectGlobalOpencode()) return;
   }
   process.stderr.write(
-    "aiur: opencode was not found on PATH. The interactive 'take the wheel' " +
+    `aiur: opencode@${opencodeVersion()} is unavailable. The interactive 'take the wheel' ` +
       "feature needs it; everything else works without it. " +
-      "Install from https://opencode.ai\n",
+      `Install with: npm install -g opencode-ai@${opencodeVersion()}, ` +
+      "and put npm's global bin ahead of other opencode binaries on PATH.\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;
+// Match the shared engine's first-argument dispatch: only session launch paths
+// need interactive tools. Unknown commands still reach the engine's usage error.
+function requiresInteractiveTools(argv) {
+  const command = argv[0] || "";
+  if (["", "run", "restart", "--bg"].includes(command)) return true;
+  const nonLaunchCommands = new Set([
+    "__identity", "help", "-h", "-help", "--h", "--help", "--version", "--todo", "--only",
+    "init", "findings", "ask", "asks", "status", "usage", "agents", "commands", "units",
+    "build-orders", "queue", "analytics", "github-cost", "github-usage", "alerts", "watch", "set",
+    "upgrade", "pause", "resume", "reset-budget", "message", "cleanup-stale", "stop",
+    "executor-answer", "executor-escalate", "executor-moot", "executor-listen", "executor-wait",
+    "executor-emit", "executor-subscribe", "executor-unsubscribe", "executor-subscriptions",
+    "executor-roster", "executor-fast-forward", "executor-claim", "executor-release", "executor-revoke",
+  ]);
+  if (nonLaunchCommands.has(command)) return false;
+  return command.startsWith("-") || fs.existsSync(command);
 }
 
 function main() {
   const releaseDir = resolveReleaseDir();
 
-  if (!isForegroundOneShot(process.argv.slice(2))) {
+  if (requiresInteractiveTools(process.argv.slice(2))) {
     ensureTmux();
     ensureOpencode();
   }

package/libexec/aiur-engine.sh

@@ -20,9 +20,7 @@
 #
 # 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
-
 # Raise the soft open-file limit toward the hard maximum. High agent concurrency
 # spawns many tmux/opencode/git subprocesses + sockets; on hosts with a low
 # default (macOS ships 256) that exhausts file descriptors (:emfile) and crashes
@@ -34,7 +32,6 @@ elif [ -n "${__aiur_hard_nofile}" ]; then
   ulimit -Sn "${__aiur_hard_nofile}" 2>/dev/null || true
 fi
 unset __aiur_hard_nofile
-
 # Export the effective soft limit after the best-effort raise. The BEAM uses
 # this inherited value for FD-headroom admission on hosts without procfs,
 # avoiding a runtime `ulimit` subprocess precisely when descriptors are scarce.
@@ -45,7 +42,6 @@ else
   unset AIUR_NOFILE_SOFT_LIMIT
 fi
 unset __aiur_soft_nofile
-
 # Preserve the shell that initiated the run as a best-effort Executor root.
 # An explicit positive override wins (service managers may know a better root);
 # otherwise the engine's parent is the nearest identity available before tmux
@@ -57,12 +53,10 @@ if ! [[ "${AIUR_OPERATOR_PID:-}" =~ ^[1-9][0-9]*$ ]]; then
     unset AIUR_OPERATOR_PID
   fi
 fi
-
 die() {
   echo "❌ $*" >&2
   exit 1
 }
-
 legacy_config_path() {
   while [ "$#" -gt 0 ]; do
     case "$1" in
@@ -203,7 +197,6 @@ warn_if_cli_behind_release_checkout() {
   fi
 }
 
-# --- distribution identity (per-instance: keyed by the aiur project root) -----
 
 # The aiur project root used to key this instance. AIUR_REPO_ROOT (set by the dev
 # shim) wins. Otherwise walk up from $PWD to the first dir holding a REPO-LOCAL
@@ -311,7 +304,6 @@ aiur_print_identity() {
   printf 'AIUR_COOKIE_FILE=%s\n' "$AIUR_COOKIE_FILE"
 }
 
-# --- BEAM distribution (cookie + named node) ---------------------------------
 
 ensure_bg_state_dir() {
   aiur_resolve_identity
@@ -368,7 +360,6 @@ prepare_distribution() {
   export AIUR_ERLANG_COOKIE="$RELEASE_COOKIE"
 }
 
-# --- release resolution ------------------------------------------------------
 
 release_dir=""
 vsn_dir=""
@@ -405,7 +396,6 @@ resolve_release() {
   fi
 }
 
-# --- argv round-trip (System.argv is empty under `elixir --eval`) -------------
 
 argv_file=""
 init_argv_file() {
@@ -450,6 +440,9 @@ usage() {
 Usage: aiur [--interactive] [--no-dashboard] [--executor] [--pause] [--max-agents <n>] [--logs-root <path>] [--port <port>] [--host <host>] [config-path]
        aiur run [--bg] [--no-dashboard] [--executor] [--debug]  explicit launch form (foreground unless --bg)
        aiur init [--force]   scaffold .aiur/config (interactive setup wizard)
+       aiur login <harness> <name> [--dir <path>]  sign in to a supported backend account
+       aiur accounts [<harness>] [--json]  list registered accounts
+       aiur logout <harness> <name> [--purge]  remove a backend account
        aiur --bg [--no-dashboard] [--executor] [--debug]   start detached; dashboard on unless suppressed
        aiur stop             stop the running session
        aiur restart [--no-build] [run flags]  stop, refresh the build, start again (detached)
@@ -460,18 +453,25 @@ Usage: aiur [--interactive] [--no-dashboard] [--executor] [--pause] [--max-agent
        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]
+       aiur queue show [--queue NAME] [--json]  read queue; add/remove/reorder/hold/release/recover/clear steer it
        aiur build-orders [<root>] [--json]  show the Build Order catalog or one root
+       aiur epic set <epic> <ids...> [--as <who>] [--source cli|backfill-agent] [--json]
+       aiur epic clear <ids...> [--as <who>] [--json]
+       aiur epic show [<ids...>] [--json]
+       aiur epic list [--json]
        aiur analytics [--range run|full] [--since <ISO-8601>] [--until <ISO-8601>] [--build-order <id>] [--json]
        aiur github-cost [--budget graphql|core|all] [--format auto|table|records] [--json]  rank GitHub API spend by call site
        aiur github-usage [--json]  per-actor (daemon vs agent) GitHub usage and ceilings
        aiur alerts [--needs-attention]  show structured alert feed
        aiur watch [--full|--changes] [--interval <secs>]  server-side status board
-       aiur executor-listen [--topic <pattern>]  stream Executor events as JSON lines
+       aiur listen [--topic <pattern> | --ticket <id>]  stream events as JSON lines
+       aiur executor-listen [--topic <pattern>]  deprecated alias for listen
        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
+       aiur workspace-recover <ticket-identifier> <generation>  release a held workspace after verified provider exit
        aiur executor-roster [--json]  list Executor consumers with their liveness evidence
        aiur executor-claim [--as <id>]  claim the wake stream, or refuse and name the live owner
        aiur executor-release [--as <id>]  give up this consumer's claim
@@ -488,14 +488,13 @@ Usage: aiur [--interactive] [--no-dashboard] [--executor] [--pause] [--max-agent
        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 doctor [--repair]         check mise shims; repair only with consent
        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
 }
 
-# --- one-shot: --version (no tmux) -------------------------------------------
 
 run_version() {
   resolve_release
@@ -511,7 +510,6 @@ run_version() {
   exec "${release_cmd[@]}"
 }
 
-# --- one-shot: init (interactive wizard, distribution-free, no tmux) ----------
 
 run_init() {
   resolve_release
@@ -522,6 +520,47 @@ run_init() {
   exec "${release_cmd[@]}"
 }
 
+run_local_cli() {
+  resolve_release
+  build_init_cmd
+  init_argv_file
+  write_argv "$@"
+  export AIUR_ARGV_FILE="$argv_file"
+  exec "${release_cmd[@]}"
+}
+
+run_claude_login() {
+  resolve_release
+  local profile_dir
+  build_init_cmd
+  init_argv_file
+  write_argv "__login_prepare" "${@:2}"
+  export AIUR_ARGV_FILE="$argv_file"
+  profile_dir="$("${release_cmd[@]}")" || return $?
+  [ -n "$profile_dir" ] || { echo "aiur: account profile directory is unavailable" >&2; return 1; }
+  exec env "CLAUDE_CONFIG_DIR=$profile_dir" claude
+}
+
+run_account_login() {
+  local harness="$2"
+  case "$harness" in
+    kimi|deepseek|openrouter) run_local_cli "$@"; return $? ;;
+  esac
+  resolve_release
+  local profile_dir
+  build_init_cmd
+  init_argv_file
+  write_argv "__login_prepare" "$harness" "${@:3}"
+  export AIUR_ARGV_FILE="$argv_file"
+  profile_dir="$("${release_cmd[@]}")" || return $?
+  [ -n "$profile_dir" ] || { echo "aiur: account profile directory is unavailable" >&2; return 1; }
+  case "$harness" in
+    claude) exec env "CLAUDE_CONFIG_DIR=$profile_dir" claude ;;
+    codex) exec env "CODEX_HOME=$profile_dir" codex ;;
+    *) echo "aiur: unsupported account harness: $harness" >&2; return 64 ;;
+  esac
+}
+
 # --- one-shot: --todo (control RPC; requires a running daemon) ----------------
 
 parsed_todo_only=0
@@ -723,22 +762,10 @@ scrub_run_only_env() {
 }
 
 run_argv=()
-# Default dashboard bind host. Prefer this machine's Tailscale IPv4 so the
-# dashboard is reachable across the tailnet by default (when config omits it);
-# fall back to loopback when Tailscale is absent, or when dashboard credentials
-# are unset (a non-loopback bind requires them, so we stay on loopback rather
-# than refuse to start). The BEAM applies this below an explicit `server.host`,
-# while an explicit `--host` remains the highest-precedence value.
+# Default dashboard bind host. Remote access is an explicit operator choice.
+# The BEAM applies this below `server.host`; `--host` has highest precedence.
 default_dashboard_host() {
-  local ip=""
-  if command -v tailscale >/dev/null 2>&1; then
-    ip="$(tailscale ip -4 2>/dev/null | grep -m1 -E '^100\.[0-9]+\.[0-9]+\.[0-9]+$' || true)"
-  fi
-  if [ -n "$ip" ] && [ -n "${AIUR_DASHBOARD_USERNAME:-}" ] && [ -n "${AIUR_DASHBOARD_PASSWORD:-}" ]; then
-    printf '%s' "$ip"
-  else
-    printf '127.0.0.1'
-  fi
+  printf '%s' "${AIUR_DEFAULT_DASHBOARD_HOST:-127.0.0.1}"
 }
 
 build_run_argv() {
@@ -2620,8 +2647,8 @@ parse_issue_targets() {
 
   [ "${#parsed_targets[@]}" -gt 0 ]
 }
-
 cmd_status() {
+  [ ! -f "$engine_dir/aiur-mise-doctor" ] || bash "$engine_dir/aiur-mise-doctor" --check || true
   [ "$#" -eq 0 ] || die "status does not accept arguments"
   run_control_rpc "Aiur.AgentControlCLI.status()"
 }
@@ -2633,6 +2660,44 @@ cmd_usage() {
   run_control_rpc "Aiur.AgentControlCLI.usage()"
 }
 
+cmd_accounts() {
+  local json_arg=false harness="" arg encoded expression
+  for arg in "$@"; do
+    case "$arg" in
+      --json)
+        [ "$json_arg" = false ] || die "accounts accepts --json only once"
+        json_arg=true
+        ;;
+      --all)
+        ;;
+      -*)
+        die "accounts accepts an optional harness and --json"
+        ;;
+      *)
+        [ -z "$harness" ] || die "accounts accepts only one harness"
+        harness="$arg"
+        ;;
+    esac
+  done
+
+  resolve_release || return $?
+  prepare_distribution || die "distribution setup failed; cannot contact aiur"
+  resolve_control_identity_from_records
+  if [ "$(probe_node_liveness)" = "down" ]; then
+    # The local one-shot CLI renders the identity and marks usage unavailable.
+    # It never makes a provider request.
+    run_local_cli accounts "$@"
+  else
+    if [ -n "$harness" ]; then
+      encoded="$(printf '%s' "$harness" | base64 | tr -d '\n')"
+      expression="Aiur.AgentControlCLI.accounts($json_arg, Base.decode64!(\"$encoded\"))"
+    else
+      expression="Aiur.AgentControlCLI.accounts($json_arg)"
+    fi
+    run_control_rpc "$expression"
+  fi
+}
+
 cmd_pause_resume() {
   local command="$1"
   shift
@@ -2680,6 +2745,16 @@ cmd_reset_budget() {
   run_control_rpc "$expression"
 }
 
+# Requires the operator to name the exact ticket and generation shown by
+# status. The daemon independently verifies the recorded boot proof.
+cmd_workspace_recover() {
+  [ "$#" -eq 2 ] || { echo "aiur: workspace-recover expects a ticket identifier and generation (e.g. aiur workspace-recover ENG-123 7)" >&2; exit 64; }
+  local ticket="$1" generation="$2" encoded
+  [[ "$generation" =~ ^[1-9][0-9]*$ ]] || { echo "aiur: workspace-recover generation must be a positive integer" >&2; exit 64; }
+  encoded="$(printf '%s' "$ticket" | base64 | tr -d '\n')"
+  run_control_rpc "Aiur.AgentControlCLI.recover_workspace(Base.decode64!(\"$encoded\"), $generation)"
+}
+
 # `aiur message <issue> <text>` — deliver Executor text to one running agent.
 # The text is base64-encoded for the RPC hop so arbitrary content (quotes,
 # backslashes, `#{}`, newlines) survives without Elixir-string escaping.
@@ -3161,21 +3236,61 @@ cmd_watch() {
   fi
 }
 
-cmd_executor_listen() {
-  local topic="executor.#" arg
+listen_clock() { printf '%s' "$SECONDS"; }
+
+cmd_listen() {
+  local topic="executor.#" ticket="" arg
   while [ "$#" -gt 0 ]; do
     arg="$1"
     case "$arg" in
       --topic) shift; topic="${1:-}" ;;
       --topic=*) topic="${arg#--topic=}" ;;
-      *) echo "aiur: executor-listen accepts --topic <pattern>" >&2; exit 64 ;;
+      --ticket) shift; ticket="${1:-}" ;;
+      --ticket=*) ticket="${arg#--ticket=}" ;;
+      *) echo "aiur: listen accepts --topic <pattern> or --ticket <id>" >&2; exit 64 ;;
     esac
-    [ -n "$topic" ] || { echo "aiur: executor-listen requires a topic" >&2; exit 64; }
     shift
   done
+  if [ -n "$ticket" ]; then
+    [[ "$ticket" =~ ^[0-9]+$ ]] || { echo "aiur: listen --ticket expects a numeric ticket id" >&2; exit 64; }
+    [ "$topic" = "executor.#" ] || { echo "aiur: listen cannot combine --ticket and --topic" >&2; exit 64; }
+    topic="ticket.${ticket}.#"
+  fi
+  [ -n "$topic" ] || { echo "aiur: listen requires a topic" >&2; exit 64; }
   local encoded
   encoded="$(printf '%s' "$topic" | base64 | tr -d '\n')"
-  run_control_stream "Aiur.AgentControlCLI.executor_listen(topic: Base.decode64!(\"$encoded\"))"
+  run_control_rpc "Aiur.AgentControlCLI.executor_listen_validate(Base.decode64!(\"$encoded\"))" || return $?
+  # A stream that stayed up 30s had a live connection, so losing it starts a
+  # new outage. Each outage gets a bounded backoff totalling ~10 minutes, long
+  # enough to outlast a normal `aiur restart`.
+  # ponytail: attempt duration stands in for "connected"; a wedged daemon whose
+  # RPC hangs 30s+ before failing keeps the listener retrying past the budget.
+  # Upgrade to a listener-ready signal if that case shows up in practice.
+  local waited=0 delay=2 started status
+  while :; do
+    started="$(listen_clock)"
+    status=0
+    # Subshell: a `die` inside (e.g. the release dir missing mid-rebuild during
+    # `aiurdev restart`) fails this attempt with exit 1 instead of the listener.
+    (run_control_stream "Aiur.AgentControlCLI.executor_listen(topic: Base.decode64!(\"$encoded\"))") || status=$?
+    [ "$status" -eq 0 ] && return 0
+    if [ "$status" -ne 1 ] || [ "${AIUR_LISTEN_RECONNECT:-1}" -ne 1 ]; then
+      echo "aiur: listen stopped after streaming control RPC failure (exit ${status}); restart the command after correcting the daemon error" >&2
+      return "$status"
+    fi
+    if [ $(($(listen_clock) - started)) -ge 30 ]; then
+      waited=0
+      delay=2
+    fi
+    if [ "$waited" -ge 600 ]; then
+      echo "aiur: listen could not reconnect within ${waited} seconds; daemon may be unavailable" >&2
+      return 1
+    fi
+    echo "aiur: listen lost the daemon stream (exit ${status}); reconnecting in ${delay} seconds" >&2
+    sleep "$delay"
+    waited=$((waited + delay))
+    delay=$((delay * 2 > 60 ? 60 : delay * 2))
+  done
 }
 
 cmd_executor_wait() {
@@ -4061,8 +4176,8 @@ cmd_upgrade() {
 }
 
 # --- dispatch ----------------------------------------------------------------
-
 dispatch_run() {
+  [ ! -f "$engine_dir/aiur-mise-doctor" ] || bash "$engine_dir/aiur-mise-doctor" --check || true
   local mode="foreground" arg
   local args=()
 
@@ -4080,7 +4195,6 @@ dispatch_run() {
   # `set -u` — happens for a bare `--bg` run. Guard the expansion.
   run_session "$mode" "${args[@]+"${args[@]}"}"
 }
-
 aiur_engine_main() {
   local cmd="${1:-}"
   # Names the running subcommand in control-RPC diagnostics so a failure says
@@ -4106,6 +4220,16 @@ aiur_engine_main() {
     init)
       run_init "$@"
       ;;
+    login)
+      run_account_login "$@"
+      ;;
+    accounts)
+      shift
+      cmd_accounts "$@"
+      ;;
+    logout)
+      run_local_cli "$@"
+      ;;
     findings)
       run_findings "$@"
       ;;
@@ -4119,6 +4243,7 @@ aiur_engine_main() {
       shift
       dispatch_run "$@"
       ;;
+    doctor) shift; exec bash "$engine_dir/aiur-mise-doctor" "$@" ;;
     status)
       shift
       cmd_status "$@"
@@ -4151,6 +4276,11 @@ aiur_engine_main() {
       shift
       cmd_units "$@"
       ;;
+    queue)
+      shift
+      cmd_queue "$@"
+      ;;
+    epic) shift; cmd_epic "$@" ;;
     build-orders)
       shift
       cmd_build_orders "$@"
@@ -4175,9 +4305,9 @@ aiur_engine_main() {
       shift
       cmd_watch "$@"
       ;;
-    executor-listen)
+    listen|executor-listen)
       shift
-      cmd_executor_listen "$@"
+      cmd_listen "$@"
       ;;
     executor-wait)
       shift
@@ -4231,6 +4361,10 @@ aiur_engine_main() {
       shift
       cmd_reset_budget "$@"
       ;;
+    workspace-recover)
+      shift
+      cmd_workspace_recover "$@"
+      ;;
     message)
       shift
       cmd_message "$@"
@@ -4267,6 +4401,8 @@ aiur_engine_main() {
   esac
 }
 
+source "$(dirname "${BASH_SOURCE[0]}")/aiur-queue.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/aiur-epic.sh"
 if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
   aiur_engine_main "$@"
 fi

package/libexec/aiur-epic.sh

@@ -0,0 +1,41 @@
+# Shared launcher epic command parser. Sourced by aiur-engine.sh.
+cmd_epic() {
+  local action="${1:-}" epic="" who="${USER:-}" source="cli" json=0 ids="" count=0 arg n opts
+  [ "$#" -gt 0 ] && shift
+  case "$action" in
+    set) [ "$#" -gt 0 ] || { echo 'aiur: epic set requires an epic' >&2; exit 64; }; epic="$1"; shift
+      [[ "$epic" =~ ^[a-z0-9][a-z0-9_-]{0,63}$ ]] || { echo 'aiur: invalid epic key' >&2; exit 64; } ;;
+    clear|show|list) ;;
+    *) echo 'aiur: epic requires set, clear, show or list' >&2; exit 64 ;;
+  esac
+  while [ "$#" -gt 0 ]; do
+    arg="$1"
+    case "$arg" in
+      --json) json=1 ;;
+      --as)
+        [[ "$action" == set || "$action" == clear ]] && [ "$#" -ge 2 ] || { echo 'aiur: invalid --as' >&2; exit 64; }
+        who="$2"; shift ;;
+      --source)
+        [ "$action" = set ] && [ "$#" -ge 2 ] || { echo 'aiur: invalid --source' >&2; exit 64; }
+        source="$2"; shift
+        [[ "$source" == cli || "$source" == backfill-agent ]] || { echo 'aiur: invalid epic source' >&2; exit 64; } ;;
+      -*) echo 'aiur: unknown epic option' >&2; exit 64 ;;
+      *)
+        [ "$action" != list ] && [[ "$arg" =~ ^#?[1-9][0-9]{0,9}$ ]] || { echo 'aiur: invalid epic ticket id' >&2; exit 64; }
+        n="${arg#\#}"; [ -n "$ids" ] && ids="$ids, "; ids="$ids$n"; count=$((count + 1)) ;;
+    esac
+    shift
+  done
+  [ "$count" -le 200 ] || { echo 'aiur: epic accepts at most 200 ids' >&2; exit 64; }
+  opts="action: :$action"
+  if [[ "$action" == set || "$action" == clear ]]; then
+    [ "$count" -gt 0 ] && [[ "$who" =~ ^[A-Za-z0-9._-]{1,64}$ ]] || { echo 'aiur: epic write requires ids and a valid --as or USER' >&2; exit 64; }
+    [ "$action" = set ] && opts="$opts, epic: Base.decode64!(\"$(encode_control_value "$epic")\")"
+    opts="$opts, ids: [$ids], who: Base.decode64!(\"$(encode_control_value "$who")\")"
+    [ "$action" = set ] && { if [ "$source" = cli ]; then opts="$opts, source: :cli"; else opts="$opts, source: :\"backfill-agent\""; fi; }
+  elif [ "$count" -gt 0 ]; then
+    opts="$opts, ids: [$ids]"
+  fi
+  [ "$json" -eq 1 ] && opts="$opts, json: true"
+  run_control_rpc "Aiur.AgentControlCLI.epic([$opts])"
+}

package/libexec/aiur-queue.sh

@@ -0,0 +1,93 @@
+# Queue commands shared by the installed CLI and aiurdev.
+queue_usage_error() { echo "aiur: queue $*" >&2; exit 64; }
+queue_string() { printf 'Base.decode64!("%s")' "$(printf '%s' "$1" | base64 | tr -d '\n')"; }
+queue_workspace_guard() {
+  if [ -n "${AIUR_AGENT_WORKSPACE:-}" ] || [[ "$PWD" == */aiur-workspaces/* ]] ||
+     [[ "${AIUR_PROJECT_ROOT:-}" == */aiur-workspaces/* ]] || [[ "${AIUR_REPO_ROOT:-}" == */aiur-workspaces/* ]]; then
+    echo 'aiur queue changes are blocked inside agent workspaces' >&2
+    exit 64
+  fi
+}
+
+cmd_queue() {
+  local verb="${1:-}" json=0 queue="" after="" at="" to="" root="" opts="" id status=0 force=0 remove_markers=0 yes=0
+  local ids=()
+  case "$verb" in
+    show) ;;
+    add|remove|reorder|hold|release|recover|clear) queue_workspace_guard ;;
+    *) queue_usage_error 'expects show, add, remove, reorder, hold, release, recover, or clear' ;;
+  esac
+  shift
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --force) [ "$verb" = recover ] && [ "$force" -eq 0 ] || queue_usage_error '--force requires recover'; force=1 ;;
+      --remove-markers) [ "$verb" = clear ] && [ "$remove_markers" -eq 0 ] || queue_usage_error '--remove-markers requires clear'; remove_markers=1 ;;
+      --yes) [ "$verb" = clear ] && [ "$yes" -eq 0 ] || queue_usage_error '--yes requires clear'; yes=1 ;;
+      --json) [ "$verb" = show ] || queue_usage_error '--json requires show'; json=1 ;;
+      --queue)
+        [ "$#" -ge 2 ] && [ -n "$2" ] && [[ "$2" != -* ]] || queue_usage_error '--queue requires a name'
+        case "$verb" in show|add|hold|release) ;; *) queue_usage_error "--queue is not valid for $verb" ;; esac
+        [ -z "$queue" ] || queue_usage_error 'duplicate --queue'
+        queue="$2"; shift ;;
+      --after)
+        [ "$verb" = add ] && [ "$#" -ge 2 ] && [[ "$2" =~ ^[1-9][0-9]*$ ]] && [ -z "$after" ] || queue_usage_error '--after requires add and a positive ticket ID'
+        after="$2"; shift ;;
+      --at)
+        [ "$verb" = add ] && [ "$#" -ge 2 ] && [[ "$2" =~ ^(0|[1-9][0-9]*)$ ]] && [ -z "$at" ] || queue_usage_error '--at requires add and a non-negative position'
+        at="$2"; shift ;;
+      --to)
+        [ "$verb" = reorder ] && [ "$#" -ge 2 ] && [[ "$2" =~ ^(0|[1-9][0-9]*)$ ]] && [ -z "$to" ] || queue_usage_error '--to requires reorder and a non-negative position'
+        to="$2"; shift ;;
+      --build-order)
+        [ "$verb" = add ] && [ "$#" -ge 2 ] && [[ "$2" =~ ^[1-9][0-9]*$ ]] && [ -z "$root" ] || queue_usage_error '--build-order requires add and a positive root ID'
+        root="$2"; shift ;;
+      -*) queue_usage_error "received an unknown argument: $1" ;;
+      *)
+        [[ "$1" =~ ^[1-9][0-9]*$ ]] || queue_usage_error "invalid ticket ID: $1"
+        for id in "${ids[@]}"; do [ "$id" != "$1" ] || queue_usage_error "duplicate ticket ID: $1"; done
+        ids+=("$1") ;;
+    esac
+    shift
+  done
+  case "$verb" in
+    show) [ "${#ids[@]}" -eq 0 ] || queue_usage_error 'show does not take ticket IDs' ;;
+    add)
+      if [ -n "$root" ]; then
+        [ "${#ids[@]}" -eq 0 ] && [ -z "$after$at" ] || queue_usage_error '--build-order cannot be combined with ticket IDs, --after, or --at'
+      else
+        [ "${#ids[@]}" -gt 0 ] || queue_usage_error 'add requires ticket IDs or --build-order'
+      fi ;;
+    recover) [ "${#ids[@]}" -eq 0 ] || queue_usage_error 'recover does not take ticket IDs' ;;
+    clear)
+      [ "${#ids[@]}" -eq 0 ] && [ "$remove_markers" -eq 1 ] || queue_usage_error 'clear requires --remove-markers and no ticket IDs'
+      [ "$yes" -eq 1 ] || { echo 'aiur: queue clear requires --yes; removes all queue membership and markers, keeping todo' >&2; exit 1; } ;;
+    remove) [ "${#ids[@]}" -gt 0 ] || queue_usage_error 'remove requires ticket IDs' ;;
+    reorder) [ "${#ids[@]}" -eq 1 ] && [ -n "$to" ] || queue_usage_error 'reorder requires one ticket ID and --to POS' ;;
+    hold|release)
+      { [ "${#ids[@]}" -eq 1 ] && [ -z "$queue" ]; } ||
+        { [ "${#ids[@]}" -eq 0 ] && [ -n "$queue" ]; } || queue_usage_error "$verb requires one ticket ID or --queue NAME" ;;
+  esac
+  if [ "$verb" != show ]; then
+    opts="verb: :$verb, caller_agent_workspace: $(queue_string "${AIUR_AGENT_WORKSPACE:-}")"
+  fi
+  [ "$force" -eq 1 ] && opts="$opts, force: true"
+  [ "$remove_markers" -eq 1 ] && opts="$opts, remove_markers: true"
+  [ "$yes" -eq 1 ] && opts="$opts, yes: true"
+  [ "$json" -eq 1 ] && opts="json: true"
+  [ -n "$queue" ] && opts="${opts:+$opts, }queue: $(queue_string "$queue")"
+  [ -n "$root" ] && opts="$opts, build_order: $root"
+  [ -n "$after" ] && opts="$opts, after: \"$after\""
+  [ -n "$at" ] && opts="$opts, at: $at"
+  [ -n "$to" ] && opts="$opts, to: $to"
+  if [ "${#ids[@]}" -gt 0 ]; then
+    opts="$opts, ids: ["
+    for id in "${ids[@]}"; do opts="$opts\"$id\","; done
+    opts="${opts%,}]"
+  fi
+  if [ "$verb" = add ] || [ "$verb" = remove ]; then
+    AIUR_CONTROL_RPC_TIMEOUT_SECONDS="$(todo_rpc_seconds "${#ids[@]}" 0)"
+  fi
+  AIUR_CONTROL_COMMAND="queue $verb" run_control_rpc "Aiur.AgentControlCLI.queue([$opts])" || status=$?
+  if [ "$status" -eq 124 ]; then echo 'aiur: queue outcome unknown; run aiur queue show before retrying' >&2; fi
+  return "$status"
+}

package/package.json

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