aiur-cli 0.0.4 → 0.0.5-nightly.32b9365

package/README.md

@@ -4,6 +4,10 @@
 
 Oversee a fleet of coding agents that **coordinate via events**.
 
+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
@@ -12,73 +16,104 @@ Oversee a fleet of coding agents that **coordinate via events**.
 > 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.
-
-When a newer `aiur-cli` is published, a one-line update notice is printed to
-stderr (checked in the background at most once a day, never blocking your
-command). Set `AIUR_NO_UPDATE_NOTIFIER=1` to silence it; it is also skipped under
-CI (`CI=true`).
-
 ## Get started
 
 ```bash
+npm install -g aiur-cli   # Node.js 18+
+
 cd your-repo
-aiur init     # interactive setup wizard
-aiur          # start agents (foreground); use `aiur --bg` to detach
+aiur init                 # interactive setup wizard
+aiur                      # start the run
 ```
 
-`aiur init` scaffolds `.aiurconfig` and provisions the repo. It walks you through:
+`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.
+
+When setup finishes, label the issues you want worked `agent:todo` and run
+`aiur`.
+
+| 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 |
 
-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.
+## The four surfaces
 
-Re-running resumes from your saved answers. When setup finishes, add `agent:todo`
-to the issues you want worked and run `aiur`.
+| 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 |
 
-## Commands
+### CLI
 
 | Command | What it does |
-|---|---|
-| `aiur init` | Interactive setup wizard (scaffold `.aiurconfig`) |
-| `aiur` | Start the workflow in the foreground (local-only bind) |
-| `aiur --bg` | Start a headless BEAM in one detached tmux lifetime session |
-| `aiur status` | Show active agents and their state |
-| `aiur alerts [--needs-attention]` | Show structured alert feed JSON lines |
-| `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.
-
-Background mode is headless inside Aiur: it skips the interactive agent-list
-pane, chat/prewarm panes, and dashboard unless you explicitly opt into a
-dashboard port. The launcher still keeps one detached tmux session as the BEAM
-lifetime holder. Re-running `aiur --bg` against a live session exits with an
-already-running hint; stale tmux state is cleaned up before restart.
+| --- | --- |
+| `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 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 |
+| `aiur message <id> "<text>"` | Send text into a live agent session |
+| `aiur set max-agents <n>` | Change the concurrency cap without restarting |
+| `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
+
+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._
 
-[github.com/its-everdred/aiur](https://github.com/its-everdred/aiur)
+[github.com/aiur-team/aiur](https://github.com/aiur-team/aiur)

package/bin/aiur.js

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