docs: document the system prerequisites, and report tmux in both doctors

The READMEs never said tmux was needed, so a fresh install only found out
when Start Run failed with nothing explaining why. Both doctors were silent
about it too.

- README/README.vi: a prerequisites table (node, npm, git, tmux, claude,
  codex, gh, systemd) and per-OS tmux install + verify steps; the feature
  list is regrouped into observe/drive/configure and now covers analytics,
  alerts, import, remote sources, the config explorer and Update all.
- INSTALL: Step 0 for the system packages, plus a troubleshooting entry
  separating "tmux missing" from "the server has a different PATH".
- SETUP/docs/README: the same troubleshooting entry and a pointer to Step 0.
- plugin-doctor: a tmux row, WARN and never FAIL - the run console and
  `lanes shell` break without it, nothing else does. Reuses tmux.js's own
  isTmuxAvailable().
- agenthub doctor: asks GET /api/run/tmux instead, because the PATH that
  decides whether a run starts is the server's, not the caller's shell's.
This commit is contained in:
2026-09-11 10:44:10 +07:00
parent 7000a9c5ce
commit 29858ddccb
11 changed files with 375 additions and 25 deletions
+26 -1
View File
@@ -5,7 +5,8 @@
* npm, free disk on the data dir, bootstrap state, runtime dependencies (every
* declared package, not just that node_modules exists), server liveness,
* duplicate hook entries (the one failure that silently doubles every token and
* cost figure), the `agenthub` CLI launcher and its PATH, whether the slash
* cost figure), the `agenthub` CLI launcher and its PATH, the `tmux` binary
* every browser-started run depends on, whether the slash
* commands the pipeline templates name as node drivers are actually resolvable
* (the `superpowers` plugin, today), and the dashboard bundle — quoting the last
* build error when it is missing.
@@ -82,6 +83,7 @@ function diagnose() {
);
add(...cliStatus());
add(...tmuxStatus());
add(...skillPluginStatus());
add(...dashboardUiStatus(rt));
@@ -218,6 +220,29 @@ function skillPluginStatus() {
];
}
/**
* WARN (never FAIL) when `tmux` is absent: every run the dashboard starts is a
* tmux session (`server/lib/tmux.js`), so without the binary the run console,
* `agenthub lanes shell` and the session-reload keystrokes all fail — while
* sessions, analytics, lanes and the CLI keep working. Same reasoning as the
* skill-plugins row: a partial feature loss must not fail a doctor run.
*
* This checks the doctor's own PATH. A server started as a systemd `--user`
* service can still see a different one — `GET /api/run/tmux` is the server's
* own answer, and `agenthub doctor` reports that.
*/
function tmuxStatus() {
if (require("../server/lib/tmux").isTmuxAvailable()) {
return ["ok", "tmux", "on PATH — the run console can start sessions"];
}
return [
"warn",
"tmux",
"not found — Start Run and `agenthub lanes shell` will fail (everything else is unaffected). " +
"Install it: sudo apt install tmux / brew install tmux (Windows: run AgentHub under WSL2)",
];
}
function countLegacyHookEntries() {
try {
const settings = JSON.parse(fs.readFileSync(getSettingsPath(), "utf8"));