chore(release): bump version to 1.5.5

fix(run): refuse a run with ETMUXMISSING when the host has no tmux
Starting a run on a machine without tmux surfaced `spawnSync tmux ENOENT` as a 400 — blaming the request for a missing host package, naming no fix, and reaching the user as a raw errno in the console pane. The guard goes in spawnRun, which both spawn paths (POST /api/run and POST /api/lanes/:id/start) already route through, so one check covers them; the message carries the install command. Both routes map the code to 503: the request was fine, the dependency is not installed. The client already renders `error.message` from the body verbatim, so no UI change. Also: README's node advice said "stay on 20/22/24"; 1712 server + 488 client tests are green on v26.8.1, so only 25 is actually the bad one.
2026-09-11 15:35:35 +07:00 · 2026-09-11 15:32:24 +07:00 · 2026-09-11 15:22:11 +07:00 · 2026-09-11 15:20:30 +07:00 · 2026-09-11 10:44:10 +07:00 · 2026-09-10 23:21:45 +07:00
31 changed files with 646 additions and 47 deletions
@@ -354,7 +354,7 @@ graph TD
 | `lib/codex-cli.js`        | Shells out to the `codex` CLI (argv array, never a shell string) for the three surfaces with no on-disk reader: MCP servers (`mcp list\|add\|remove`), plugins (`plugin list\|add\|remove`), and marketplaces (`marketplace list\|add\|remove`). `runCodex()` parses stdout as JSON when possible; empty stdout on a zero-exit is a normal empty list, not a parse failure. A non-zero exit is returned as a structured failure (surfaced by the route as 422, never a 500) with `stdout`/`stderr` preserved |
 | `routes/codex-config.js`  | HTTP surface for the Codex Config panel. Read endpoints for every surface (skills, agents, rules, memory, config, mcp, plugins, marketplaces, file, overview) plus mutation endpoints (`PUT /file`, `DELETE /file` delegating to `codex-mutate.js`; `POST /mcp/{add,remove}`, `/plugins/action`, `/marketplaces/{add,action}` delegating to `codex-cli.js`), plus `GET /backups`. Every successful mutation broadcasts `codex_config_changed` over the WebSocket so an open Codex settings tab refetches without polling. All errors return structured `{error: {code, message}}` shapes |
 | `lib/tmux.js`             | Wrapper around tmux CLI for session management. `createSession(sessionName, cwd)` creates a new tmux session in the specified working directory. `sendCommand(sessionName, command)` sends a command into the session. `killSession(sessionName)` terminates the session. `listSessions()` returns all active sessions. Session management is the foundation for the PTY transport layer |
-| `lib/pty-run.js`          | PTY lifecycle for tmux-backed runs. Manages one tmux session per lane, named `agenthub-lane-<lane.id>`. Exports `startRun()` to create/attach a session and return a `runId` opaque handle; internally uses tmux to manage the pseudoterminal. Spawned `claude` processes run inside the session and fire the dashboard's hooks like any other CLI session, so they show up in `/api/sessions`, the analytics, the Kanban board, and the Workflows page automatically. The PTY frames (terminal input/output deltas) are streamed to the client over `/ws-pty/:runId` (see `server/websocket.js`) at binary frame granularity rather than as JSON envelopes; the client's xterm.js terminal widget renders these raw PTY updates live |
+| `lib/pty-run.js`          | PTY lifecycle for tmux-backed runs. Manages one tmux session per lane, named `agenthub-lane-<lane.id>`. Exports `startRun()` to create/attach a session and return a `runId` opaque handle; internally uses tmux to manage the pseudoterminal. Spawned `claude` processes run inside the session and fire the dashboard's hooks like any other CLI session, so they show up in `/api/sessions`, the analytics, the Kanban board, and the Workflows page automatically. The PTY frames (terminal input/output deltas) are streamed to the client over `/ws-pty/:runId` (see `server/websocket.js`) at binary frame granularity rather than as JSON envelopes; the client's xterm.js terminal widget renders these raw PTY updates live. Every spawn also mirrors itself into `dashboard_runs` (cwd, model, prompt preview, `resume_session_id`, lane id, start time) — that row is the ONLY source `publicRun` has for those fields, since the handle itself is recomputed from tmux on every read, so a dropped insert renders as a live run with no cwd, model or start date. `mode` is NOT NULL in that table and `recordRun` swallows insert errors by design, which is why this module passes a literal `"interactive"` rather than null. **Create-or-adopt has one refusal:** a pane already running an agent is adopted silently only when the request asked for nothing but a pane — a `resumeSessionId` or an initial prompt cannot be typed over a live agent, so it throws `ERUNLIVE` (409) rather than reporting a resume that never spawned |
 | `lib/pty-attach.js`       | Client-side PTY attachment via WebSocket. Establishes a `/ws-pty/:runId` connection, receives binary PTY frames, and feeds them to an xterm.js terminal instance. Handles reconnection, resize events (sending `TIOCSWINSZ` ioctl to the tmux pane), and cleanup on disconnect. A single tmux session can have many simultaneous PTY clients (browser Workspace, `agenthub lanes shell` CLI, etc.), all synced live |
 | `routes/run.js`           | HTTP surface for the tmux+PTY Run feature. **Same-origin guard** on every route — browser requests must come from a localhost-ish Origin (`localhost`, `127.0.0.1`, `::1`, `0.0.0.0`); missing-Origin (curl/CLI) requests pass. When `DASHBOARD_TOKEN` is configured it is **also** required on these routes (same as the rest of `/api/*`). `GET /api/run` lists all live runs (computed fresh from tmux state via `tmux list-sessions`). `GET /api/run/tmux` reports whether `tmux` is installed and on PATH (required for the feature to work). `GET /api/run/binary` probes whether `claude` is on `PATH`. `GET /api/run/cwds` suggests cwds (dashboard + home + recent from sessions table). `GET /api/run/history?laneId=...` returns persisted run history, optionally scoped to one lane. `GET /api/run/files?cwd=&q=` powers the Workspace page's `@`-file autocomplete: scoped fuzzy search inside `cwd` skipping `node_modules`, `.git`, `dist`, `build`, `.next`, `.cache`, `coverage`, `vendor`, etc., capped result count, ranked by basename match. `POST /api/run` requires `laneId` in the body and starts/attaches a tmux-backed run. `GET /api/run/:id` returns the run handle. `DELETE /api/run/:id` kills the tmux session (sends SIGTERM to the pane, escalates to SIGKILL after 5 s). The PTY frames are streamed to the client over `/ws-pty/:runId` as binary frames (not JSON), rendering a real interactive terminal in xterm.js on the Workspace page. `tmux` must be installed on the dashboard server's machine (same as better-sqlite3's native-module requirements) |
 | `routes/lanes.js`         | Durable-lane API. `POST /api/lanes/worktree`, `PATCH /api/lanes/:id`, destructive actions, and `DELETE /api/lanes/:id` use the Run route's same-origin guard. Worktree provisioning validates an absolute source git repository, persists a managed lane as `provisioning`, returns `202`, then uses the per-lane lock to resolve the base and add the worktree. Completion broadcasts the existing `lane_update` payload as `idle`; a git failure leaves a row that the non-destructive delete route can forget. `GET /api/lanes/:id/preflight?action=reset\|remove\|purge` produces counted confirmation facts. Confirmed `POST /:id/{reset,remove,purge}` actions require a complete `expect`, run under the same lock, kill a recorded run and wait for the spawner's actual child-exit timestamp (or return `500 ERUNTIMEOUT` before git), clear `run_id`, reject changed facts with `409 ESTALE` including expected/current diagnostics, and require `force` for unpushed managed reset/remove work. Reset and managed removal call the worktree's independent managed-kind, realpath-within-`LANES_ROOT`, and listed-worktree guard; adopted reset is refused, while adopted remove only forgets its row and never modifies its directory, and a managed lane whose directory was deleted by hand takes a prune path that still enforces the managed-kind and inside-`LANES_ROOT` checks. `start` returns `409 ERUNLIVE` rather than overwriting a live `run_id` and orphaning its child. `kind`, `source_repo`, `slug`, `base_branch`, `slot` and `ports` are not patchable — provisioning writes them through `lanesLib.setProvisioningFacts`. Worktree provisioning also runs `lane-runtime.js:provisionLane` (A2) when the repo declares a `.agenthub/profile` — seed `.env`, `bootstrap`, create the database, migrate, seed — before the lane reports `idle`; `reset`/`remove` likewise call `resetLaneData`/`removeLaneData`, with `reset` accepting a body `keepDb: true` to skip the whole drop-recreate-migrate-reseed block. The runtime routes (`GET /:id/runtime`, `POST /:id/up`, `POST /:id/down`, `POST /:id/hook/:name`, `GET /:id/logs/:svc`) are registered **before** the `/:id/:action` catch-all so `up`/`down` are not swallowed as unknown actions, and are deliberately kept out of it: that catch-all drives a lane's Claude run, these drive the application the lane is working on. `GET /api/lanes/pipeline-stats` aggregates per-node pass counts over every lane and every archived feature. |
@@ -2138,6 +2138,7 @@ The same shape is used by `GET /status`, `POST /check`, and the `update_status`
 | Newer release, ordinary checkout | `{update_available:true, situation:"release_available", latest_release:"vX.Y.Z", manual_command:"...git fetch origin --tags && git merge --ff-only vX.Y.Z..."}` | Modal opens titled with the release version, links its notes, and shows **Update now**. |
 | Newer release, plugin-cache install | `{update_available:true, situation:"plugin_managed", install_kind:"plugin", plugin_marketplace:"sg", plugin_name:"agenthub", manual_command:"claude plugin marketplace update sg && ..."}` | Modal opens WITH **Update now**; `POST /apply` answers `200 {applied:true, mode:"plugin"}` and the detached chain pulls the new version and re-bootstraps. The modal notes that an already-open Claude Code session still needs `/reload-plugins` for new skills/commands. |
 | Plugin chain ran but nothing was published | `{last_plugin_update:{ok:true, step:"already_current"}}` | The old server keeps running, untouched; no restart, no error banner. |
+| Plugin chain mid-handover | `{last_plugin_update:{ok:true, step:"bootstrap", note:"the new plugin version is installed; the server is being handed over"}}` | Written BEFORE the handover on purpose: that step retires the process tree the helper hangs off, and a helper killed there would otherwise leave `last_plugin_update: null` for an update that succeeded. Overwritten by `done` when the helper survives. |
 | Plugin chain failed (no `claude` on PATH, `npm ci` broke, bootstrap died) | `{last_plugin_update:{ok:false, step:"resolve_claude"\|"plugin_update"\|"bootstrap", error:"..."}}` | Danger banner in the modal naming the failed step. A `bootstrap` failure means the old server was already stopped, so the verdict says to run `/agenthub-update` to recover — and it is read back by whichever server comes up next, because it lives outside the cache. |
 | Plugin `/apply` with nothing newer published | 409 `{reason:"plugin_managed", release_check:"ok"}` | No chain is spawned. Message names the newest release and points at `/agenthub-update` to force a refresh. |
 | Plugin `/apply` after a failed release check | 409 `{reason:"plugin_managed", release_check:"unreachable"\|"no_local_version"\|...}` | No chain is spawned, and the message says the check did not succeed rather than claiming nothing newer exists — an unknown reported as a negative is how a broken check looks identical to an up-to-date install. |
@@ -30,12 +30,64 @@ dashboard, run it from source, or stay on Node 20.
 | Node.js | 20+ (22+ recommended) | Required for server and client |
 | npm | 9+ | Comes with Node.js |
 | Claude Code | 2.x+ | Required for hook integration |
+| Git | Any | Cloning the repository, and every lane operation (worktrees, branch/status reads) |
+| **tmux** | 3.x | **Required for the run console** — the browser terminal, `agenthub lanes shell`, typing `/reload-plugins` into a live pane, and the Codex nudge. See [Step 0](#step-0--system-packages) |
+| Codex CLI | Any | Optional — only for lanes whose tool is `codex` |
+| GitHub CLI (`gh`) | Any | Optional — only for `agenthub lanes ci status` and the PR stages of `/agenthub:ship-full` |
 | Python | 3.6+ | Optional — only for `scripts/expand-ts-module-docs.py` (doc generation) |
-| Git | Any | For cloning the repository |
 | `superpowers` plugin | Any | Optional — required only by `/agenthub:ship-feature` and `/agenthub:ship-feature-lane`, which drive its skills step by step (and which the built-in pipeline templates name as their per-node commands). Nothing else in AgentHub needs it; `/agenthub-doctor` reports it as `WARN` when absent. **Installed automatically** by the plugin's `SessionStart` bootstrap (opt out with `AGENTHUB_AUTO_INSTALL_PLUGINS=0`); by hand: `claude plugin install superpowers@claude-plugins-official` |

 ---

+## Step 0 — System packages
+
+Node and npm are not enough: `git` backs every lane operation, and **`tmux`
+backs the run console**. The dashboard shells out to the `tmux` binary and has
+no bundled fallback, so without it **Start Run** and `agenthub lanes shell`
+fail while everything else keeps working.
+
+```bash
+sudo apt install git tmux        # Debian / Ubuntu
+sudo dnf install git tmux        # Fedora / RHEL
+brew install git tmux            # macOS
+sudo pacman -S git tmux          # Arch
+```
+
+Windows has no native tmux. Run AgentHub under **WSL2** and install it inside
+the WSL distro — a tmux from Git Bash or MSYS is not what the server executes.
+
+Check it:
+
+```bash
+tmux -V          # e.g. tmux 3.4
+git --version
+node -v          # v20.x / v22.x / v24.x
+```
+
+Once the server is up you can ask it directly — this is the same probe the
+dashboard uses:
+
+```bash
+curl -s localhost:4820/api/run/tmux      # {"available":true}
+```
+
+**No configuration is needed.** AgentHub creates its own session per lane,
+named `agenthub-lane-<id>`, and never reads your `~/.tmux.conf` for anything it
+depends on (mouse mode is set on the session explicitly). You can attach to the
+exact same pane from a normal terminal:
+
+```bash
+agenthub lanes shell             # from inside the lane's directory
+tmux attach -t agenthub-lane-7   # or by name
+tmux ls                          # every dashboard session is prefixed agenthub-lane-
+```
+
+Detaching is `Ctrl-b d` — it leaves the run alive, which is the whole point:
+the browser terminal and your local terminal are two clients on one pane, and
+restarting the dashboard never stops a run.
+
+---
+
 ## Step 1 — Clone the repository

 ```bash
@@ -261,6 +313,27 @@ npm run setup

 The Vite dev server and Express server run on different ports. Make sure both are running (`npm run dev` starts both). Open **http://localhost:5173**, not `http://localhost:4820`, during development.

+### "Start Run" fails, or the terminal never attaches
+
+The run console is tmux-backed. Check, in this order:
+
+```bash
+tmux -V                                   # not installed → see Step 0
+curl -s localhost:4820/api/run/tmux       # {"available":false} → the SERVER cannot see tmux
+curl -s "localhost:4820/api/run/binary?tool=claude"   # {"found":true,"path":"…"}
+```
+
+`{"available":false}` while your own shell finds tmux means the server runs with
+a different `PATH` — most often a systemd `--user` service, which does not read
+your shell profile. Fix it by installing tmux system-wide (`/usr/bin/tmux`)
+rather than into a shell-managed prefix, then `agenthub service uninstall &&
+agenthub service install`.
+
+The same `PATH` rule applies to `claude` and `codex`: a run starts the binary by
+name, so a `claude` installed only through an interactive shell's profile is
+invisible to a service-managed server. `{"found":false}` for the lane's tool is
+that case.
+
 ### No sessions appearing after starting Claude Code

 See [SETUP.md — Troubleshooting](./SETUP.md#troubleshooting) for detailed hook debugging steps.
@@ -13,10 +13,24 @@ Internal build — all rights reserved.

 *(Tiếng Việt: [README.vi.md](README.vi.md))*

-## What it does
+## Main features
+
+**Observe**

 - **Sessions, agents, events.** Everything Claude Code emits, recorded and
  searchable: tool calls, token usage, cost, subagent trees, transcripts.
+- **Analytics and cost.** Per-model token totals and estimated cost, with
+  editable pricing rules; top tools, agent types, and workflow patterns.
+- **Activity feed and alerts.** A live event stream, alert rules, and webhook
+  targets that fire on them.
+- **History import.** Every session under `~/.claude/projects/` is imported on
+  startup; archives from another machine come in through Settings → Import
+  History (idempotent, never double-counts tokens).
+- **Remote sources.** Pull session history from other machines over SSH
+  (`agenthub remote-sources`).
+
+**Drive**
+
 - **Lanes.** One lane per working directory, surviving session restarts. A lane
  moves through pipeline stages and the dashboard shows where it is.
 - **Stage detection.** The stage is inferred from the tool stream, so a session
@@ -26,15 +40,72 @@ Internal build — all rights reserved.
  PTY, rendered with xterm.js) attached to a lane's directory — the exact TUI
  you'd see locally, fully interactive, resumable, and attachable from a real
  terminal too via `agenthub lanes shell`. Which CLI it starts is the lane's own
-  setting.
- **Analytics (in-dashboard tab), alerts, and a workflow view**, plus a CLI.
+  setting. **This is the part that needs `tmux` installed** — see
+  [Prerequisites](#prerequisites).
+- **Per-lane app stacks.** A repo that declares `.agenthub/profile/` gets its own
+  slot, ports and services per lane (`agenthub lanes up|down|logs`).
+- **Ship pipelines.** `/agenthub:ship-full` and `/agenthub:ship-quick` drive a
+  feature from intake to PR, declaring every stage to the dashboard as it goes.

-## Requirements
+**Configure**

-Node **>= 20** (`engines` in `package.json`). Node **24** is what the test suites
-are verified on — node 25 currently breaks 6 server tests through a
+- **Claude Code + Codex configuration explorer.** Settings hosts one panel per
+  tool: every plugin, skill, subagent, slash command, MCP server, hook, settings
+  file, memory file, marketplace, keybinding and statusline Claude Code knows
+  about — read for all of them, edit/create/delete for the text-file surfaces
+  (skills, agents, commands, output styles, `CLAUDE.md`). Plugins, MCP, hooks and
+  `settings.json` stay read-only: they race with the live CLI.
+- **Updates.** Release-based update detection with an in-UI **Update all**
+  (marketplaces → every plugin → AgentHub last → one session reload).
+- **A CLI for all of it** (`agenthub`, plus `agenthub repl`), a PWA install, and
+  a UI in English, Vietnamese, Chinese and Korean.
+
+## Prerequisites
+
+| Need | Version | Required for |
+|---|---|---|
+| **Node.js** | >= 20 (>= 22.5 for a plugin install) | Everything. Both suites are verified green on **24** and **26** |
+| **npm** | 9+ | Ships with Node |
+| **git** | any | Cloning, and every lane operation (worktrees, branch/status reads) |
+| **tmux** | 3.x | The browser run console, `agenthub lanes shell`, typing `/reload-plugins` into a live pane, the Codex nudge |
+| **Claude Code** | 2.x | Hook ingestion — the whole monitoring side |
+| **Codex CLI** | any | Optional — only for `codex` lanes |
+| **GitHub CLI (`gh`)** | any | Optional — only for `agenthub lanes ci status` and the PR stages of the ship pipelines |
+| **systemd (user)** | — | Optional — only for `agenthub service install` (Linux auto-start on boot) |
+
+Node **25** is the one version to avoid: it breaks 6 server tests through a
 better-sqlite3 ABI mismatch and 20 client tests through a global `localStorage`
-change.
+change. Both were gone again by 26 (1712 server + 488 client tests green on
+v26.8.1).
+
+### Installing tmux
+
+The dashboard shells out to the `tmux` binary; there is no bundled fallback, so
+**Start Run** and `agenthub lanes shell` fail without it. Everything else
+(sessions, analytics, lanes, stage detection, the CLI) works fine.
+
+```bash
+sudo apt install tmux        # Debian / Ubuntu
+sudo dnf install tmux        # Fedora / RHEL
+brew install tmux            # macOS
+sudo pacman -S tmux          # Arch
+```
+
+Windows has no native tmux — run AgentHub under WSL2 and install it there.
+
+Verify, both from your shell and from the server's point of view:
+
+```bash
+tmux -V                                      # e.g. tmux 3.4
+curl -s localhost:4820/api/run/tmux          # {"available":true}
+```
+
+A lane's run lives in a tmux session named `agenthub-lane-<id>`, so the browser
+terminal and a local `tmux attach -t agenthub-lane-<id>` (or `agenthub lanes
+shell`) are two clients on the same pane — they stay in sync, and killing the
+dashboard never kills the run.
+
+### The superpowers plugin

 The **`superpowers` plugin is required by the ship-feature pipelines only**, not
 by the dashboard. `/agenthub:ship-feature` and `/agenthub:ship-feature-lane` drive
@@ -13,10 +13,24 @@ Internal build — all rights reserved.

 *(Bản dịch tiếng Việt của [README.md](README.md), tham khảo — README.md gốc là bản chính thức.)*

-## Làm được gì
+## Chức năng chính
+
+**Quan sát**

 - **Session, agent, event.** Mọi thứ Claude Code emit ra, ghi lại và tìm kiếm
  được: tool call, token usage, cost, cây subagent, transcript.
+- **Analytics và chi phí.** Token và cost ước tính theo từng model, với bảng
+  pricing sửa được; top tool, agent type và workflow pattern.
+- **Activity feed và alert.** Luồng event trực tiếp, alert rule, và webhook
+  target bắn khi rule khớp.
+- **Import lịch sử.** Mọi session dưới `~/.claude/projects/` được import lúc
+  khởi động; lịch sử từ máy khác đưa vào qua Settings → Import History
+  (idempotent, không bao giờ đếm trùng token).
+- **Remote source.** Kéo lịch sử session từ máy khác qua SSH
+  (`agenthub remote-sources`).
+
+**Điều khiển**
+
 - **Lane.** Mỗi working directory một lane, sống sót qua session restart. Lane
  đi qua các pipeline stage và dashboard hiển thị nó đang ở đâu.
 - **Stage detection.** Stage được suy luận (infer) từ tool stream, nên một
@@ -26,14 +40,86 @@ Internal build — all rights reserved.
 - **Chạy Claude Code hoặc Codex từ trình duyệt.** Một terminal thật (tmux + PTY
  thật, render bằng xterm.js) gắn vào thư mục của lane — đúng cái TUI bạn thấy ở
  máy, tương tác đầy đủ, resume được, và attach được từ terminal thật qua
-  `agenthub lanes shell`. Chạy CLI nào là thiết lập riêng của từng lane.
- **Analytics (tab trong dashboard), alert và workflow view**, cộng thêm CLI.
+  `agenthub lanes shell`. Chạy CLI nào là thiết lập riêng của từng lane. **Đây
+  chính là phần cần cài `tmux`** — xem [Yêu cầu hệ thống](#yêu-cầu-hệ-thống).
+- **App stack riêng cho từng lane.** Repo khai báo `.agenthub/profile/` thì mỗi
+  lane được cấp slot, port và service riêng (`agenthub lanes up|down|logs`).
+- **Ship pipeline.** `/agenthub:ship-full` và `/agenthub:ship-quick` đưa một
+  feature từ intake tới PR, khai báo từng stage về dashboard trên đường đi.

-## Yêu cầu
+**Cấu hình**

-Node **>= 20** (`engines` trong `package.json`). Node **24** là bản test suite
-được verify — node 25 hiện đang làm gãy 6 test server do lệch ABI
-`better-sqlite3` và 20 test client do thay đổi global `localStorage`.
+- **Trình khám phá cấu hình Claude Code + Codex.** Trang Settings có một panel
+  cho mỗi tool: mọi plugin, skill, subagent, slash command, MCP server, hook,
+  settings file, memory file, marketplace, keybinding và statusline mà Claude
+  Code biết — đọc được tất cả, còn sửa/tạo/xóa thì chỉ cho các bề mặt dạng file
+  text (skill, agent, command, output style, `CLAUDE.md`). Plugin, MCP, hook và
+  `settings.json` để read-only: chúng tranh ghi với CLI đang chạy.
+- **Cập nhật.** Phát hiện bản mới dựa trên release, kèm nút **Update all** ngay
+  trong UI (marketplace → mọi plugin → AgentHub sau cùng → reload session).
+- **CLI cho toàn bộ** (`agenthub`, và `agenthub repl`), cài được như PWA, UI có
+  tiếng Anh, Việt, Trung và Hàn.
+
+## Yêu cầu hệ thống
+
+| Cần | Phiên bản | Dùng cho |
+|---|---|---|
+| **Node.js** | >= 20 (>= 22.5 nếu cài qua plugin) | Tất cả. Cả hai test suite verify xanh trên Node **24** và **26** |
+| **npm** | 9+ | Đi kèm Node |
+| **git** | bất kỳ | Clone repo, và mọi thao tác lane (worktree, đọc branch/status) |
+| **tmux** | 3.x | Run console trên trình duyệt, `agenthub lanes shell`, gõ `/reload-plugins` vào pane đang sống, nhắc nhở Codex |
+| **Claude Code** | 2.x | Hook ingestion — toàn bộ phần monitoring |
+| **Codex CLI** | bất kỳ | Tùy chọn — chỉ cho lane dùng `codex` |
+| **GitHub CLI (`gh`)** | bất kỳ | Tùy chọn — chỉ cho `agenthub lanes ci status` và các stage PR của ship pipeline |
+| **systemd (user)** | — | Tùy chọn — chỉ cho `agenthub service install` (tự khởi động khi boot, Linux) |
+
+Node **25** là bản duy nhất nên tránh: nó làm gãy 6 test server do lệch ABI
+`better-sqlite3` và 20 test client do thay đổi global `localStorage`. Tới 26 thì
+cả hai đã hết (1712 test server + 488 test client xanh trên v26.8.1).
+
+### Cài tmux
+
+Dashboard gọi thẳng binary `tmux`, không có bản dự phòng đi kèm, nên thiếu nó
+thì **Start Run** và `agenthub lanes shell` sẽ lỗi. Phần còn lại (session,
+analytics, lane, stage detection, CLI) vẫn chạy bình thường.
+
+```bash
+sudo apt install tmux        # Debian / Ubuntu
+sudo dnf install tmux        # Fedora / RHEL
+brew install tmux            # macOS
+sudo pacman -S tmux          # Arch
+```
+
+Windows không có tmux native — chạy AgentHub trong WSL2 và cài tmux ở trong đó.
+
+Kiểm tra, cả từ shell của bạn lẫn từ góc nhìn của server:
+
+```bash
+tmux -V                                      # ví dụ: tmux 3.4
+curl -s localhost:4820/api/run/tmux          # {"available":true}
+```
+
+Mỗi lane chạy trong một tmux session tên `agenthub-lane-<id>`, nên terminal
+trên trình duyệt và `tmux attach -t agenthub-lane-<id>` (hoặc `agenthub lanes
+shell`) ở máy là hai client trên cùng một pane — chúng đồng bộ với nhau, và tắt
+dashboard không bao giờ giết run đang chạy. Detach bằng `Ctrl-b d`.
+
+### Plugin superpowers
+
+Plugin **`superpowers` chỉ cần cho ship-feature pipeline**, không cần cho
+dashboard. `/agenthub:ship-feature` và `/agenthub:ship-feature-lane` lái các skill
+của nó theo từng phase. Thiếu nó thì dashboard, hook và CLI vẫn chạy bình thường
+— chỉ hai skill pipeline là dừng giữa chừng; `/agenthub-doctor` báo dòng `WARN`.
+
+**Bình thường bạn không phải tự cài.** Bootstrap `SessionStart` của plugin cài
+giúp một lần trong worker chạy nền, và session hiện tại cần `/reload-plugins`
+thì skill mới resolve được (session sau tự nhận). Cài tay:
+
+```bash
+claude plugin install superpowers@claude-plugins-official
+```
+
+Đặt `AGENTHUB_AUTO_INSTALL_PLUGINS=0` để tắt cài tự động.

 ## Cài như Claude Code plugin

@@ -324,6 +324,26 @@ The SQLite database uses WAL mode with a 5-second busy timeout. If you see lock

 ---

+### The run console won't start a run / the terminal never attaches
+
+Runs are tmux-backed: the server executes the `tmux` binary and has no fallback.
+
+```bash
+tmux -V                                               # missing → sudo apt install tmux
+curl -s http://localhost:4820/api/run/tmux            # {"available":true}
+curl -s "http://localhost:4820/api/run/binary?tool=claude"   # {"found":true,"path":"…"}
+```
+
+`{"available":false}` while your own shell finds tmux means the **server's**
+`PATH` differs from yours — typically a systemd `--user` service, which never
+reads your shell profile. Install tmux system-wide (`/usr/bin/tmux`) and
+re-run `agenthub service uninstall && agenthub service install`. The same
+applies to `claude` / `codex`: a run launches them by name.
+
+Install instructions per OS: [INSTALL.md → Step 0](./INSTALL.md#step-0--system-packages).
+
+---
+
 ### No sessions appearing after starting Claude Code

 **Check 1 — Is the server running?**
@@ -1279,6 +1279,23 @@ async function cmdDoctor() {
  );
  console.log(`${c.green("✔")}  WS connections  ${srv.ws_connections ?? 0}`);

+  // Asked of the SERVER, not of this shell: a run is a tmux session the server
+  // spawns, so the only PATH that decides whether Start Run works is its own —
+  // a systemd --user service never reads your shell profile. Missing tmux is a
+  // warning, not a failure: it costs the run console and `lanes shell`, nothing
+  // else.
+  try {
+    const { available } = await get("/api/run/tmux");
+    console.log(
+      available
+        ? `${c.green("✔")}  tmux  available to the server`
+        : `${c.yellow("!")}  tmux  not on the server's PATH — Start Run and \`agenthub lanes shell\` will fail. ` +
+            `Install it (sudo apt install tmux / brew install tmux), then restart the server`
+    );
+  } catch {
+    console.log(`${c.dim("·")}  tmux  not reported by this server`);
+  }
+
  try {
    const { sources = [] } = await get("/api/remote-sources");
    if (sources.length === 0) {
@@ -2995,7 +3012,7 @@ const COMMAND_GROUPS = [
  [
    "Administration",
    [
-      ["doctor", "", "Connectivity, hooks, database, and remote sources diagnosis"],
+      ["doctor", "", "Connectivity, hooks, database, tmux, and remote sources diagnosis"],
      ["info", "", "Raw system info JSON"],
      ["export", "[file.json]", "Export all data as JSON"],
      ["cleanup", "--hours N --days M", "Abandon stale / purge old sessions"],
@@ -521,14 +521,17 @@ function UnifiedRunRowView({
 }) {
  const { t } = useTranslation("run");
  const startedDate = new Date(row.startedAt);
-  const startedLabel = isNaN(startedDate.getTime())
-    ? "-"
-    : startedDate.toLocaleString(undefined, {
-        month: "short",
-        day: "numeric",
-        hour: "2-digit",
-        minute: "2-digit",
-      });
+  // 0 is "unknown", not the epoch — a run whose persisted row is missing has no
+  // start time, and printing "Jan 1, 08:00 AM" for it reads as real data.
+  const startedLabel =
+    !row.startedAt || isNaN(startedDate.getTime())
+      ? "-"
+      : startedDate.toLocaleString(undefined, {
+          month: "short",
+          day: "numeric",
+          hour: "2-digit",
+          minute: "2-digit",
+        });
  // Without mode distinction, offer resume for any finished run with a session.
  // An external session is live but has no attachable tmux session, so Resume
  // (a new tmux-backed `claude --resume` in its cwd) is what it gets instead.
@@ -242,6 +242,14 @@ describe("ActiveRunsSwitcher", () => {
    expect(screen.queryByText(i18n.t("run:runs.externalBadge"))).toBeNull();
  });

+  it("shows a dash, not the epoch, for a row with no start time", () => {
+    // A run whose persisted row is missing arrives with startedAt 0. Rendering
+    // that as "Jan 1, 08:00 AM" presents a gap in the data as real data.
+    renderModal([row("no-start", { startedAt: 0 })]);
+    expect(screen.getByText("-")).toBeTruthy();
+    expect(screen.queryByText(/Jan 1,/)).toBeNull();
+  });
+
  it("fires attach with the run id of the row that was clicked", () => {
    const { spies } = renderSwitcher();
    openModal();
@@ -9537,7 +9537,7 @@ exports[`screen snapshots > Settings 1`] = `
            <p
              class="text-[10px] text-status-warning/90 mt-1"
            >
-              UI build v1.5.2 (rebuild client to match)
+              UI build v1.5.5 (rebuild client to match)
            </p>
          </div>
          <div
@@ -245,7 +245,9 @@ All fields are optional. The tool (CLI invoked) comes from the lane itself, neve
 - **`approval`** — one of `on-request` or `never`, or omitted/empty for no approval prompt. Passed to `codex -a <value>`.
 - **`resumeSessionId`** or **`resumeLast: true`** — resume an earlier run instead of starting new. For Codex lanes specifically, `resumeLast: true` uses `codex resume --last`; `resumeSessionId` uses `codex resume <sessionId>`. For Claude lanes, `resumeSessionId` re-attaches a Claude session by id.

-Error `409 ERUNLIVE` is returned if the lane already has a live run; stop it first with the `stop` action.
+Error `503 ETMUXMISSING` is returned when the host has no `tmux` binary. Every run the dashboard starts is a tmux session, so this is a missing dependency rather than a bad request — the message carries the install command, and the same code comes back from `POST /api/run`. Nothing else in the dashboard is affected.
+
+Error `409 ERUNLIVE` is returned if the lane already has a live run; stop it first with the `stop` action. The same code and status come back when the lane's tmux pane is already running an agent while a `prompt` or `resumeSessionId` was sent — that argv cannot be typed over a live agent, so the request is refused instead of answered 200 with nothing done. A start that asks for neither still adopts the existing pane silently.

 #### Preflight a destructive lane action

@@ -272,7 +272,7 @@ Because a lane's services are fully detached, restarting the dashboard (or `agen

 | Command | Description |
 | ------- | ----------- |
-| `agenthub doctor` | Diagnosis: API reachability, hook installation status + path, database path/size/row counts, server uptime and Node version, WS connections |
+| `agenthub doctor` | Diagnosis: API reachability, hook installation status + path, database path/size/row counts, server uptime and Node version, WS connections, whether `tmux` is on **the server's** PATH (asked via `GET /api/run/tmux` — a systemd `--user` service does not read your shell profile), remote-source status |
 | `agenthub info` | The raw `/api/settings/info` JSON (pipe it to `jq`) |
 | `agenthub export [file.json]` | Full JSON data export (sessions, agents, events, tokens, workflows, dashboard runs, alert rules, pricing) — defaults to a dated filename. Re-importable via `agenthub import-data` |
 | `agenthub cleanup --hours N --days M` | Abandon active sessions idle for `N` hours and/or purge completed sessions older than `M` days |
@@ -139,6 +139,11 @@ graph TB

 - Node.js >= 20.0.0
 - npm >= 9.0.0
+- git — every lane operation shells out to it
+- tmux — only for the browser run console and `agenthub lanes shell`; both
+  execute the binary directly and have no fallback. Per-OS install commands and
+  the two-sided check (your PATH vs the server's) are in
+  [INSTALL.md → Step 0](../INSTALL.md#step-0--system-packages).

 ### Setup

@@ -134,7 +134,7 @@ waits on an install:
 4. **Install** — `npm install --omit=dev --ignore-scripts` into the runtime dir (never into the plugin cache, which is garbage-collected and replaced on every update). `--ignore-scripts` keeps the root `postinstall` from pulling the whole Vite client toolchain.
 5. **Legacy hook cleanup** — see above.
 6. **CLI** — write the `~/.local/bin/agenthub` launcher, never clobbering a `agenthub` the bootstrap did not write.
-7. **UI build** — `client/` is copied into the runtime dir and built there (`npm install && npm run build`), landing in `runtime/client-dist` — the same directory the server serves from. Skipped when a bundle for the current version already exists; a failure here does not fail the bootstrap (API and MCP still work, and `/agenthub-open` can retry) but does mean `/run` 404s until it's fixed.
+7. **UI build** — `client/` is copied into the runtime dir and built there (`npm ci --include=dev`, falling back to `npm install --include=dev`, then `npm run build`), landing in `runtime/client-dist` — the same directory the server serves from. `--include=dev` is required, not tidy: the entire build toolchain (`vite`, `typescript`, `@vitejs/plugin-react`, `tailwindcss`, `@types/*`) is a devDependency, and npm reads an inherited `NODE_ENV=production` as `--omit=dev`. Every bootstrap descended from the running server carries that env — the self-update chain, and any `SessionStart` fired by a `claude` inside a tmux pane the server started — so without the flag the install drops `vite` and the build dies on missing types. Skipped when a bundle for the current version already exists; a failure here does not fail the bootstrap (API and MCP still work, and `/agenthub-open` can retry) but does mean `/run` 404s until it's fixed — and when a bundle from the PREVIOUS version is still on disk the failure is quieter still: the dashboard keeps serving the old UI against the new API, visible only as the Settings page's `UI build vX (rebuild client to match)` line.
 8. **Server** — on Linux with `systemd --user` available, install/refresh a
   `agenthub.service` unit (see [Auto-start on boot](#auto-start-on-boot)) instead
   of a bare spawn, so the server is supervised and comes back after a reboot
@@ -176,7 +176,7 @@ reboot, same as always.

 | Command | Does |
 |---|---|
-| `/agenthub-doctor` | Node version, bootstrap state, runtime deps, server liveness, duplicate hooks, CLI launcher + PATH, **skill plugins** (see below), MCP build freshness, UI bundle |
+| `/agenthub-doctor` | Node version, bootstrap state, runtime deps, server liveness, duplicate hooks, CLI launcher + PATH, **tmux** (`WARN` when absent — only the run console, `agenthub lanes shell` and session reloads need it), **skill plugins** (see below), MCP build freshness, UI bundle |
 | `/agenthub-update` | Pull the latest `agenthub` release via `claude plugin marketplace update` + `claude plugin update agenthub@<marketplace> -y`, then reinstall dependencies and restart the server (`plugin-bootstrap.js --force`). The plugin pull needs a manual `/reload-plugins` afterward to take effect in the current session — not scriptable from a command. |
 | `/agenthub-open` | Rebuild the UI bundle and print the dashboard URL. Re-runs the bootstrap first when the server is down or still executing a plugin root that a mid-session `/plugin` update retired, so a fresh bundle never talks to an older server's routes |
 | `/ship-full <requirement>` | Put the lane on the 16-node `ship-feature` template, then run `/agenthub:ship-feature-lane` **in this session**. The in-session twin of `agenthub ship-full` (which spawns its own `claude` from a terminal) |
@@ -70,10 +70,12 @@ graph LR

 **Quick Start:**

-1. Read [SETUP.md](../SETUP.md)
-2. Run `npm run setup`
-3. Run `npm run dev`
-4. Open browser to `http://localhost:5173`
+1. Install the system packages — `node` (20+), `git`, and `tmux` (the run
+   console has no fallback without it): [INSTALL.md → Step 0](../INSTALL.md#step-0--system-packages)
+2. Read [SETUP.md](../SETUP.md)
+3. Run `npm run setup`
+4. Run `npm run dev`
+5. Open browser to `http://localhost:5173`

 ---

@@ -3,7 +3,7 @@
 openapi: 3.0.3
 info:
  title: Agent Dashboard for Claude Code API
-  version: 1.5.2
+  version: 1.5.5
  description: HTTP API for real-time Claude Code session monitoring, agent lifecycle tracking, analytics, pricing, hooks ingestion, and workflow intelligence.
  contact:
    name: Nguyễn Ngọc Trí Vĩ
@@ -1,12 +1,12 @@
 {
  "name": "agenthub",
-  "version": "1.5.2",
+  "version": "1.5.5",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "agenthub",
-      "version": "1.5.2",
+      "version": "1.5.5",
      "hasInstallScript": true,
      "license": "UNLICENSED",
      "dependencies": {
@@ -1,6 +1,6 @@
 {
  "name": "agenthub",
-  "version": "1.5.2",
+  "version": "1.5.5",
  "bin": {
    "agenthub": "bin/agenthub.js"
  },
@@ -1,5 +1,5 @@
 ---
-description: Diagnose a plugin-installed AgentHub — Node, npm, disk, bootstrap, server, hooks, CLI, UI build
+description: Diagnose a plugin-installed AgentHub — Node, npm, disk, bootstrap, server, hooks, CLI, tmux, UI build
 ---

 Run the diagnostic and report what it found. Do not fix anything unless the user
@@ -31,6 +31,11 @@ Print the output verbatim, then add at most three lines of guidance based on the
  means that attempt has not run or did not succeed — say `/agenthub-update` retries
  it, and print the `claude plugin install …` line from the output as the manual
  route.
+- `WARN tmux` → only the run console, `agenthub lanes shell` and the
+  session-reload keystrokes are affected; monitoring, lanes and the CLI are not.
+  Print the install command from the output. If the row says `ok` but Start Run
+  still fails, the server has a different PATH than this check — ask it directly
+  with `curl -s localhost:4820/api/run/tmux`.
 - `WARN Dashboard UI` → run `/agenthub-open` to build the bundle. When the row
  quotes a build error, report that error — it is the actual problem.

@@ -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"));
@@ -73,7 +73,17 @@ function buildClient({
    // tarball against the lockfile's integrity hash, so a bad cache entry is
    // refetched instead of silently reused. It needs a lockfile that matches
    // package.json — fall back to `install` when the copy has none or has drifted.
-    const npmFlags = ["--no-audit", "--no-fund"];
+    //
+    // `--include=dev` is not optional here: the whole build toolchain (vite,
+    // typescript, @vitejs/plugin-react, tailwindcss, @types/*) lives in the
+    // client's devDependencies, and npm reads `NODE_ENV=production` as
+    // `--omit=dev`. Every bootstrap descended from the running server inherits
+    // that NODE_ENV — the self-update chain and any SessionStart fired from a
+    // tmux pane the server started — so the install silently dropped `vite`,
+    // `npm run build` failed, and the PREVIOUS bundle stayed in place: the
+    // dashboard kept serving the old version's UI while the API was already the
+    // new one. An explicit CLI flag outranks the env, which is the point.
+    const npmFlags = ["--no-audit", "--no-fund", "--include=dev"];
    if (
      !exec(NPM, ["ci", ...npmFlags], src, stdio) &&
      !exec(NPM, ["install", ...npmFlags], src, stdio)
@@ -157,6 +157,18 @@ function main() {
  }

  log(`new plugin root: ${newRoot}`);
+  // Write the verdict BEFORE the handover, not only after it. The step below
+  // retires the process tree this helper hangs off, and an observed run reached
+  // the new server with no verdict file at all — so the dashboard reported
+  // `last_plugin_update: null` for an update that had in fact succeeded. A
+  // pre-written record is overwritten by the real outcome when this survives,
+  // and is the outcome when it does not.
+  record({
+    ok: true,
+    step: "bootstrap",
+    plugin_root: newRoot,
+    note: "the new plugin version is installed; the server is being handed over",
+  });
  try {
    // Foreground and blocking: this stops the old server (us), waits for the
    // ports, then starts the new one. It must finish before we record success.
@@ -555,7 +555,12 @@ failures return `500` with `error.stderr`.

 `start` returns `409 ERUNLIVE` when the lane's recorded run is still `spawning`
 or `running`: overwriting `run_id` would orphan that child, and a later `reset`
-would then `git clean -fd` a directory the orphan is still writing into.
+would then `git clean -fd` a directory the orphan is still writing into. It
+returns the same code when the lane's tmux pane is running an agent and the
+request carried a `prompt` or `resumeSessionId` — `pty-run.js` will not type
+over a live agent, and adopting the pane silently would answer 200 for a resume
+that never spawned. `POST /api/run` maps that code to `409` too; a start with
+neither field still adopts the pane.

 Besides the stage a skill declares explicitly, every lane also carries a
 server-inferred `detected_stage`: `server/lib/stage-detect.js` matches each
@@ -369,7 +369,7 @@ describe("agenthub CLI — import & administration", () => {
    assert.match(err, /Usage: agenthub import/);
  });

-  it("doctor reports API, hooks, database, remotes, and uptime lines", async () => {
+  it("doctor reports API, hooks, database, tmux, remotes, and uptime lines", async () => {
    const { code, out } = await agenthub("doctor");
    // Exit 1 when hooks are missing (common in the test harness) — still prints a full report.
    assert.ok(code === 0 || code === 1, `unexpected exit ${code}`);
@@ -377,6 +377,10 @@ describe("agenthub CLI — import & administration", () => {
    assert.match(out, /Claude Code hooks/);
    assert.match(out, /Database/);
    assert.match(out, /Server uptime/);
+    // Asked of the server (GET /api/run/tmux), not of this shell: a missing
+    // tmux is why Start Run fails, and the server's PATH is the one that
+    // decides. Reported either way, and never fatal.
+    assert.match(out, /tmux/);
    assert.match(out, /Remote sources/);
  });

@@ -391,6 +391,21 @@ describe("buildClient dependency install", () => {
    );
  });

+  it("installs devDependencies explicitly, because NODE_ENV=production omits them", () => {
+    // The whole client build toolchain (vite, typescript, @types/*) is a
+    // devDependency, and npm turns NODE_ENV=production into --omit=dev. Every
+    // bootstrap descended from the running server inherits that env, so the
+    // install dropped vite, `npm run build` failed, and the dashboard kept
+    // serving the PREVIOUS version's bundle after a self-update.
+    resetRuntime();
+    const calls = [];
+    buildClient({ rt: RT, root: fakeRoot(), exec: fakeExec(calls) });
+
+    for (const call of calls.filter((c) => c.startsWith("ci") || c.startsWith("install"))) {
+      assert.match(call, /--include=dev/, `dependency install must include dev deps: ${call}`);
+    }
+  });
+
  it("fails without building when neither install path works", () => {
    resetRuntime();
    const calls = [];
@@ -0,0 +1,54 @@
+/**
+ * @file Tests the `tmux` row of scripts/plugin-doctor.js — the check that tells
+ * an install its browser run console cannot work, because every run the
+ * dashboard starts is a tmux session (server/lib/tmux.js). The row must WARN
+ * and never FAIL: sessions, analytics, lanes and the CLI all work without the
+ * binary, so failing a doctor run over it would cry wolf. tmux is faked through
+ * the module's own exec seam, so the test never depends on the host having it.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { describe, it, after } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const TMP_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "agenthub-doctor-tmux-"));
+process.env.CLAUDE_HOME = TMP_HOME;
+
+const tmux = require("../lib/tmux");
+const { diagnose } = require("../../scripts/plugin-doctor");
+
+after(() => {
+  tmux.__reset();
+  fs.rmSync(TMP_HOME, { recursive: true, force: true });
+  delete process.env.CLAUDE_HOME;
+});
+
+/** Fake the tmux binary as present or absent, then read back the row. */
+function rowWithTmux(present) {
+  tmux.__setExecImpl(() => {
+    if (!present) throw new Error("spawnSync tmux ENOENT");
+    return "tmux 3.4\n";
+  });
+  const row = diagnose().find((r) => r.label === "tmux");
+  assert.ok(row, "the doctor must always emit a tmux row");
+  return row;
+}
+
+describe("plugin-doctor: tmux row", () => {
+  it("warns, never fails, when tmux is not on PATH", () => {
+    const row = rowWithTmux(false);
+
+    assert.equal(row.level, "warn", "a missing tmux must not fail the doctor run");
+    assert.match(row.detail, /lanes shell/, "the reader needs to know WHAT breaks");
+    assert.match(row.detail, /install/i, "and how to fix it");
+  });
+
+  it("passes when tmux is available", () => {
+    const row = rowWithTmux(true);
+
+    assert.equal(row.level, "ok", row.detail);
+  });
+});
@@ -58,6 +58,29 @@ describe("pty-run", () => {
    assert.ok(newSessionCall.includes("opus"));
  });

+  it("spawnRun refuses with ETMUXMISSING, naming the fix, when tmux is not installed", () => {
+    // Before this guard the ENOENT escaped from three calls down as
+    // `spawnSync tmux ENOENT` and the route answered 400 — blaming the request
+    // for a missing host package, with no hint of what to install.
+    const calls = [];
+    tmux.__setExecImpl((args) => {
+      calls.push(args);
+      const e = new Error("spawnSync tmux ENOENT");
+      e.code = "ENOENT";
+      throw e;
+    });
+
+    assert.throws(
+      () => pty.spawnRun({ laneId: 42, cwd: "/tmp/repo" }),
+      (err) => err.code === "ETMUXMISSING" && /install/i.test(err.message),
+      "a missing tmux must be reported as such, with the install command"
+    );
+    assert.ok(
+      !calls.some((c) => c[0] === "new-session"),
+      "must not attempt a session it already knows cannot be created"
+    );
+  });
+
  it("spawnRun is a no-op (adopts) when the existing session's pane runs claude", () => {
    const calls = [];
    tmux.__setExecImpl((args) => {
@@ -335,4 +358,91 @@ describe("pty-run", () => {
    );
    assert.ok(!call.some((a) => String(a).startsWith("--dangerously-bypass")));
  });
+
+  // `dashboard_runs.mode` is NOT NULL and recordRun swallows insert errors, so a
+  // null there persisted nothing at all while every call still looked fine: the
+  // runs modal rendered a row with no cwd, model, prompt or start time, and a
+  // resumed session kept its separate `external` row because no run row ever
+  // carried its session id. These assert the row actually lands.
+  it("refuses to swallow a resume or a prompt when the pane already runs an agent", () => {
+    // Adopting silently here answered 200 while spawning no `--resume` at all:
+    // the dashboard reported a resumed session that never happened.
+    tmux.__setExecImpl((args) => {
+      if (args[0] === "display-message") return "claude\n";
+      return ""; // has-session succeeds → pane is busy with a live agent
+    });
+    assert.throws(
+      () => pty.spawnRun({ laneId: 51, cwd: "/tmp/repo", resumeSessionId: "abc12345" }),
+      (err) => err.code === "ERUNLIVE"
+    );
+    assert.throws(
+      () => pty.spawnRun({ laneId: 51, cwd: "/tmp/repo", initialPrompt: "do the thing" }),
+      (err) => err.code === "ERUNLIVE"
+    );
+  });
+
+  it("still adopts a busy pane when the request asked for nothing but a pane", () => {
+    const calls = [];
+    tmux.__setExecImpl((args) => {
+      calls.push(args);
+      if (args[0] === "display-message") return "claude\n";
+      return "";
+    });
+    const handle = pty.spawnRun({ laneId: 52, cwd: "/tmp/repo" });
+    assert.equal(handle.id, "agenthub-lane-52");
+    assert.ok(!calls.some((c) => c[0] === "new-session"));
+    assert.ok(!calls.some((c) => c[0] === "send-keys"));
+  });
+
+  describe("run persistence", () => {
+    const dashboardRuns = require("../lib/dashboard-runs");
+
+    it("spawnRun persists the run so the runs list has cwd, model and prompt", () => {
+      tmux.__setExecImpl((args) => {
+        if (args[0] === "has-session") {
+          const e = new Error("gone");
+          e.status = 1;
+          throw e;
+        }
+        return "";
+      });
+      pty.spawnRun({
+        laneId: 71,
+        cwd: "/tmp/persisted",
+        model: "claude-opus-5",
+        initialPrompt: "ship it",
+      });
+
+      const row = dashboardRuns.getRun("agenthub-lane-71");
+      assert.ok(row, "expected a dashboard_runs row for the spawned run");
+      assert.equal(row.cwd, "/tmp/persisted");
+      assert.equal(row.model, "claude-opus-5");
+      assert.equal(row.prompt_preview, "ship it");
+      assert.equal(row.lane_id, 71);
+      assert.ok(row.started_at, "started_at must be set, or the UI dates the row to the epoch");
+      assert.ok(row.mode, "mode is NOT NULL — a null here silently drops the whole insert");
+    });
+
+    it("a resumed run carries the session id, which is what dedupes the external row", () => {
+      tmux.__setExecImpl((args) => {
+        if (args[0] === "has-session") {
+          const e = new Error("gone");
+          e.status = 1;
+          throw e;
+        }
+        return "";
+      });
+      const sessionId = "c2055094-09cf-4735-9712-09e5cdf7023f";
+      const handle = pty.spawnRun({
+        laneId: 72,
+        cwd: "/tmp/resumed",
+        resumeSessionId: sessionId,
+      });
+
+      // The UI reads sessionId off the run list; an external session whose id is
+      // already on a run row is not repeated as its own `external` row.
+      assert.equal(handle.sessionId, sessionId);
+      assert.equal(dashboardRuns.getRun("agenthub-lane-72").resume_session_id, sessionId);
+    });
+  });
 });
@@ -118,6 +118,23 @@ describe("/api/run", () => {
    assert.equal(body.error.code, "EBADCWD");
  });

+  it("POST / answers 503, not 400, when the host has no tmux", async () => {
+    // The request is fine; the dependency is absent. 400 would tell the user to
+    // fix their input, and the body must carry the install line the UI shows.
+    tmux.__setExecImpl(() => {
+      const e = new Error("spawnSync tmux ENOENT");
+      e.code = "ENOENT";
+      throw e;
+    });
+    const { status, body } = await fetchJson("/api/run", {
+      method: "POST",
+      body: { laneId: 9, cwd: TMP },
+    });
+    assert.equal(status, 503);
+    assert.equal(body.error.code, "ETMUXMISSING");
+    assert.match(body.error.message, /install/i);
+  });
+
  it("POST / spawns a tmux session and GET /:id finds it", async () => {
    let hasSessionCalls = 0;
    tmux.__setExecImpl((args) => {
@@ -91,8 +91,12 @@ function recordRun(handle) {
      lane_id: typeof handle.laneId === "number" ? handle.laneId : null,
      tool: handle.tool === "codex" ? "codex" : "claude",
    });
-  } catch {
-    /* persistence is best-effort */
+  } catch (err) {
+    // Best-effort by design (a live run must never fail because sqlite did),
+    // but not silent: a swallowed insert leaves the runs modal showing rows with
+    // no cwd, model, prompt or start time, which reads as a UI bug rather than a
+    // persistence one. Say it once, here, where the cause is known.
+    console.warn(`[dashboard-runs] failed to record run ${handle?.id}: ${err.message}`);
  }
 }

@@ -181,6 +181,21 @@ function spawnRun(args) {
    throw makeErr("EBADSESSION", "resumeSessionId is not a valid session id");
  }

+  // A run IS a tmux session, so an absent binary is a precondition failure, not
+  // a spawn failure. Without this the caller gets `spawnSync tmux ENOENT` from
+  // three directories down — a message that names no fix — and the route maps
+  // it to 400, blaming the request for the host's missing package. Checked here
+  // rather than in each route because both spawn paths (POST /api/run and
+  // POST /api/lanes/:id/start) come through this function.
+  if (!tmux.isTmuxAvailable()) {
+    throw makeErr(
+      "ETMUXMISSING",
+      "tmux is not installed, and every run the dashboard starts is a tmux session. " +
+        "Install it (sudo apt install tmux / brew install tmux; on Windows run AgentHub under WSL2), " +
+        "then restart the dashboard. Everything else keeps working without it."
+    );
+  }
+
  const id = runIdForLane(laneId);
  const startedAt = Date.now();
  const argv = buildArgv({
@@ -200,7 +215,13 @@ function spawnRun(args) {
    dashboardRuns.recordRun({
      id,
      sessionId: resumeSessionId || null,
-      mode: null,
+      // `dashboard_runs.mode` is NOT NULL. Passing null made every insert throw
+      // inside recordRun's best-effort catch, so no tmux-backed run was ever
+      // persisted: publicRun then read its cwd/model/prompt/startedAt off a row
+      // that did not exist (a blank row dated Jan 1 1970 in the runs modal), and
+      // session_id never landed either, so a resumed session stayed listed as a
+      // separate `external` row. Every run here is one interactive pane.
+      mode: "interactive",
      cwd,
      tool: tool === "codex" ? "codex" : "claude",
      model: model || null,
@@ -238,6 +259,18 @@ function spawnRun(args) {
  // Pane is running something (a live `claude`, an editor, a build): adopt
  // silently, same convention as this repo's server port-adoption logic — no
  // error, no duplicate session. Attaching shows the user what is running.
+  //
+  // Adopting is only honest when the request asked for nothing more than a
+  // pane. A Resume or an initial prompt cannot be delivered into a pane that is
+  // already running an agent (typing over it is what the shell-pane branch
+  // above exists to avoid), so answering 200 there reports work that never
+  // happened: the user sees "resumed" while no `--resume` was ever spawned.
+  else if (resumeSessionId || initialPrompt) {
+    throw makeErr(
+      "ERUNLIVE",
+      `lane ${laneId}'s pane is already running \`${tmux.paneCommand(id) || "a process"}\` — stop it before resuming a session or sending a prompt`
+    );
+  }

  return getRun(id);
 }
@@ -898,7 +898,9 @@ function sendLifecycleError(res, err) {
  if (["ENOTMANAGED", "EOUTSIDEROOT", "ENOTWORKTREE", "EEXPECT"].includes(err.code)) {
    return res.status(400).json({ error: { code: err.code, message: err.message } });
  }
-  if (["ESTALE", "EUNPUSHED"].includes(err.code)) {
+  // ERUNLIVE: the lane's pane is busy with a live agent, so a resume/prompt
+  // could not be delivered — a conflict, not a bad request or a server fault.
+  if (["ESTALE", "EUNPUSHED", "ERUNLIVE"].includes(err.code)) {
    return res.status(409).json({
      error: {
        code: err.code,
@@ -1358,6 +1360,12 @@ router.post("/:id/:action", sameOriginGuard, async (req, res) => {
        break;
    }
  } catch (err) {
+    // A host with no tmux cannot start a run, but nothing is broken on this
+    // side — 503 plus the install line, not a 500 the reader can only read as a
+    // dashboard bug.
+    if (err.code === "ETMUXMISSING") {
+      return res.status(503).json({ error: { code: err.code, message: err.message } });
+    }
    return res.status(500).json({ error: { code: err.code, message: err.message } });
  }

@@ -256,6 +256,15 @@ router.post("/", (req, res) => {
    });
    return res.status(201).json(handle);
  } catch (err) {
+    // A busy pane is a conflict with live state, not a malformed request.
+    if (err.code === "ERUNLIVE") {
+      return res.status(409).json({ error: { code: err.code, message: err.message } });
+    }
+    // Nor is a host missing tmux: the request was fine, the dependency is not
+    // installed. 400 would tell the user to fix their input.
+    if (err.code === "ETMUXMISSING") {
+      return res.status(503).json({ error: { code: err.code, message: err.message } });
+    }
    if (err.code && err.code.startsWith("E")) {
      return res.status(400).json({ error: { code: err.code, message: err.message } });
    }
Author	SHA1	Message	Date
nntrivi2001	3ed88062d6	chore(release): bump version to 1.5.5	2026-09-11 15:35:35 +07:00
nntrivi2001	27313d4413	fix(run): refuse a run with ETMUXMISSING when the host has no tmux Starting a run on a machine without tmux surfaced `spawnSync tmux ENOENT` as a 400 — blaming the request for a missing host package, naming no fix, and reaching the user as a raw errno in the console pane. The guard goes in spawnRun, which both spawn paths (POST /api/run and POST /api/lanes/:id/start) already route through, so one check covers them; the message carries the install command. Both routes map the code to 503: the request was fine, the dependency is not installed. The client already renders `error.message` from the body verbatim, so no UI change. Also: README's node advice said "stay on 20/22/24"; 1712 server + 488 client tests are green on v26.8.1, so only 25 is actually the bad one.	2026-09-11 15:32:24 +07:00
nntrivi2001	d4b949a6f4	docs(deployment): list git and tmux beside node in the prerequisites The only prerequisites block that still said node+npm alone.	2026-09-11 15:22:11 +07:00
nntrivi2001	8930865376	test(cli): cover the doctor's tmux line The row was added without a check here, so a regression that dropped it would only surface when someone's Start Run failed silently again.	2026-09-11 15:20:30 +07:00
nntrivi2001	29858ddccb	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.	2026-09-11 10:44:10 +07:00
nntrivi2001	7000a9c5ce	chore(release): bump version to 1.5.4	2026-09-10 23:21:45 +07:00
nntrivi2001	99e718ad91	fix(plugin): build the UI with devDependencies so a self-update ships its own bundle After the 1.5.2 -> 1.5.3 self-update the server ran 1.5.3 while the dashboard still served the 1.5.2 UI. The client build had failed, and `runtime/client-dist` still held the previous version's bundle, so nothing looked broken — the only signal was the Settings page's "UI build v1.5.2 (rebuild client to match)". Cause: the whole client build toolchain (vite, typescript, @vitejs/plugin-react, tailwindcss, @types/*) is a devDependency, and npm reads NODE_ENV=production as --omit=dev (`NODE_ENV=production npm config get omit` -> `dev`). The dashboard server runs with NODE_ENV=production, and every bootstrap descended from it inherits that: the plugin-update chain, and any SessionStart fired by a `claude` running in a tmux pane the server started. So `npm ci` dropped vite, `tsc -b` died on missing type declarations, and buildClient returned "failed" with the stale bundle left in place. `--include=dev` on both install paths — a CLI flag outranks the env, which is the point. Verified by running buildClient with NODE_ENV=production against the installed plugin root: previously "failed", now "built", and the served bundle carries 1.5.3. Also: plugin-update-helper writes its verdict BEFORE the bootstrap handover as well as after. That step retires the process tree the helper hangs off, and the observed run reached the new server with no verdict file at all — the dashboard reported `last_plugin_update: null` for an update that had actually succeeded.	2026-09-10 23:17:33 +07:00
nntrivi2001	67c948bbe2	chore(release): bump version to 1.5.3	2026-09-10 17:09:07 +07:00
nntrivi2001	8b8582f231	fix(runs): persist tmux-backed runs so a resumed session shows its own info `dashboard_runs.mode` is NOT NULL and `recordRun` swallows insert errors by design, so pty-run.js passing `mode: null` meant NO tmux-backed run was ever persisted — the newest row in a live database dated from before pty-run.js replaced run-spawner.js. `publicRun` reads cwd, model, prompt preview, started_at and session_id off that row and the handle itself is recomputed from tmux, so the runs modal rendered a live row with no cwd, no model, no prompt and a start date of Jan 1 1970. The same missing row is why a resumed session kept its separate `external` badge: the client dedupes an external session against the session ids carried by run rows, and no run row ever carried one. - pty-run.js records `mode: "interactive"` — every run here is one pane. - dashboard-runs.js still never fails a live run on a db error, but warns instead of swallowing silently; that silence hid this for six weeks. - RunHistory renders `startedAt: 0` as "-" rather than dating a row with no known start time to the epoch. Also closes the other half of the same lie: adopting a pane that is already running an agent now throws ERUNLIVE (409 from both the lane start action and POST /api/run) when the request carried a prompt or a resumeSessionId. That argv cannot be typed over a live agent, so answering 200 reported a resume that never spawned. A start asking for nothing but a pane still adopts.	2026-09-10 17:07:23 +07:00