chore(release): bump version to 1.5.9

feat(lanes): offer a create/update readme run when adding a lane
An optional checkbox in the Add-lane modal starts the new lane's terminal run right after creation with `/sg-all:sg-md-writing` as its first message, so the lane opens already writing or refreshing its CLAUDE.md/AGENTS.md set. Claude lanes only — codex has no slash commands.
2026-09-14 11:22:11 +07:00 · 2026-09-14 11:20:37 +07:00 · 2026-09-11 16:48:00 +07:00 · 2026-09-11 16:45:47 +07:00 · 2026-09-11 16:32:50 +07:00 · 2026-09-11 16:30:10 +07:00
75 changed files with 5445 additions and 204 deletions
@@ -344,7 +344,9 @@ graph TD
 | `server/lib/scoped-stats.js` | Source-scoped variants of the stats/analytics aggregates, used **only** when a `?sources=` scope filter is active — the unscoped fast paths in `routes/stats.js` / `routes/analytics.js` are untouched when no scope is set |
 | `lib/cc-discovery.js`     | Read-only discovery of every Claude Code config surface for the Config Explorer page. Pure file reads; never writes. Surfaces: skills (`<root>/skills/<name>/SKILL.md`), subagents (`<root>/agents/*.md`), slash commands (`<root>/commands/*.md`), output styles (`<root>/output-styles/*.md`), plugins (`<CLAUDE_HOME>/plugins/installed_plugins.json` joined with `enabledPlugins` in settings + per-plugin `contributes` counts **and** `contributes.items`, which names every skill / subagent / command / output style the plugin ships — each surface read from the conventional install subdirectory *and* from whatever path `plugin.json` declares for that key, with declared paths outside the plugin's own install dir dropped by `isUnder()`, so a plugin that lists its commands explicitly and keeps `commands/` empty no longer reports zero + `plugin.json` metadata), marketplaces (`known_marketplaces.json` enriched with each `marketplace.json`), MCP servers (top-level + per-project from `~/.claude.json`), hooks (across user / project / project-local settings.json), keybindings (`<CLAUDE_HOME>/keybindings.json`), statusline config + `statusline.py` / `statusline-command.sh` content, hook scripts dir (`<CLAUDE_HOME>/hooks/`), settings (with secret-key redaction matching `/token\|secret\|password\|api[_-]?key\|auth/i`), memory (`CLAUDE.md` at user + project **plus** the per-project file-based auto-memory store — every `*.md` under `~/.claude/projects/<slug>/memory/`, returned as `scope:"auto-memory"` items carrying `project`, `name`, `isIndex`, and parsed `frontmatter`, so a `MEMORY.md` index and one file per remembered fact, often 100+, all surface). Path containment via `isUnder()` — every read must resolve under CLAUDE_HOME, project `.claude/`, or be a project CLAUDE.md. 256 KB read cap. Minimal YAML frontmatter parser handles `key: value` + quoted strings + indented continuation lines |
 | `lib/cc-mutate.js`        | Create / overwrite / delete for the **low-risk text-file surfaces only** (skills, subagents, slash commands, output styles, memory — including the per-project file-based auto-memory store, mutated via `scope: "auto-memory"`, `type: "auto-memory"`, `project`, `name`, with its backups landing in `<memory-dir>/.cc-config-backups/auto-memory/`), plus `writeKeybindings()` for the structured `keybindings.json` editor (read-modify-write that preserves top-level metadata, rejects duplicate contexts/keys, and backs up to `<CLAUDE_HOME>/cc-config-backups/keybindings/`). Plugins, MCP, hooks-in-settings, and `settings.json` files are NEVER written from here — they have concurrent-write races with the live Claude Code CLI. Every mutation creates a timestamped backup at `<root>/cc-config-backups/<type>/<base>.<ISO>.bak[.dir]` BEFORE the change — backups land outside the directories Claude Code scans, so a deleted skill cannot resurface as a backup-named one. Writes are atomic: temp file in same dir → fsync → `renameSync`. Tmp removed on every failure path. Skill dirs are backed up whole (preserving bundled assets) before recursive removal. Strict `name` regex (`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`), 256 KB content cap, double-checked path containment via `isUnder()` |
-| `routes/cc-config.js`     | HTTP surface for the Claude Config Explorer. Read endpoints for every surface (skills, agents, commands, output-styles, plugins, marketplaces, mcp, hooks, hook-scripts, keybindings, statusline, settings, memory, file, overview), plus mutation endpoints (`PUT /file`, `DELETE /file`, and a structured `PUT /keybindings`) that delegate to `cc-mutate.js`, plus a `GET /backups` listing for the recovery modal, plus the auth-profile routes (`GET/POST/PATCH/DELETE /profiles`, `POST /profiles/activate`) that delegate to `cc-profiles.js`. After every successful PUT/DELETE the route broadcasts `cc_config_changed` over the WebSocket so any open `/cc-config` tab refetches without polling. All errors return structured `{error: {code, message}}` shapes mapped to 400/404/413/500 statuses |
+| `lib/cc-reload.js`        | Types `/reload-plugins` / `/reload-skills` into the Claude Code sessions the dashboard already has open, over `tmux send-keys` (reusing `tmux.js`'s `sendText`). Both slash commands are scoped BY CLAUDE CODE to the session that runs them, so a session cannot be reloaded from the outside and no background process can do it on a session's behalf — typing into a live pane is the only real mechanism. Deliberately spawns NO `claude` process: a one-shot `claude -p "/reload-plugins"` would reload only its own short-lived session, exit, and leave a junk session in the dashboard's history, so this module creates no sessions at all. Skips panes sitting at a shell prompt (the text would run as a shell command) and addresses `claude` lanes only, since Codex has no such command. Sends to a busy pane on purpose — tmux queues the keystrokes into the REPL's input buffer, so a late reload still lands, where skipping busy panes would leave exactly the sessions in active use running stale code. The command set is a fixed constant, never caller-supplied: a pane's stdin is an arbitrary-code boundary. Never throws |
+| `lib/cc-update-all.js`    | Starts and reports on the "Update all" batch, whose work lives in the detached `scripts/cc-update-all-helper.js`. Detached for a structural reason: the batch ends with the plugin THIS dashboard runs from, and that step's `plugin-bootstrap.js --force` SIGTERMs this very server, so an in-process loop would die with the remaining plugins unrun and nothing left to report. Order is marketplaces → every other plugin → AgentHub last → one reload. The worker journals every step transition to `cc-update-all.json` under the runtime dir — outside the plugin cache the update replaces — so whichever server is alive can serve progress from it; the POST's response is only an acknowledgement. `readUpdateAll()` DERIVES an `abandoned` status for a `running` journal older than `STALE_MS` (1 h), because a detached worker killed by a reboot leaves nobody to write the terminal entry and the button would otherwise stay wedged forever. `isRunning()` gates a concurrent batch, since two `claude plugin update` chains over one config dir race |
+| `routes/cc-config.js`     | HTTP surface for the Claude Config Explorer. Read endpoints for every surface (skills, agents, commands, output-styles, plugins, marketplaces, mcp, hooks, hook-scripts, keybindings, statusline, settings, memory, file, overview), plus mutation endpoints (`PUT /file`, `DELETE /file`, and a structured `PUT /keybindings`) that delegate to `cc-mutate.js`, plus a `GET /backups` listing for the recovery modal, plus the auth-profile routes (`GET/POST/PATCH/DELETE /profiles`, `POST /profiles/activate`) that delegate to `cc-profiles.js`, plus the install-wide update surface: `GET/POST /plugins/update-all` (a DETACHED batch — every marketplace, then every plugin, then a reload, with THIS dashboard's own plugin last because its bootstrap restarts the server; progress is polled from an on-disk journal, never from the POST's response) and `POST /reload` (types `/reload-plugins`+`/reload-skills` into the live lane panes; see `cc-reload.js`). After every successful PUT/DELETE the route broadcasts `cc_config_changed` over the WebSocket so any open `/cc-config` tab refetches without polling. All errors return structured `{error: {code, message}}` shapes mapped to 400/404/413/500 statuses |
 | `lib/cc-profiles.js`      | Named Claude Code **auth profiles** — swap which Anthropic account (and therefore which quota) the local `claude` CLI runs as. A profile is exactly two identity artifacts: `claudeAiOauth` out of `<CLAUDE_HOME>/.credentials.json`, and `oauthAccount` + `userID` out of the `.claude.json` config file(s) (`<CLAUDE_HOME>.json` and `<CLAUDE_HOME>/.claude.json`, each key-merged in place and only when it already exists, so `projects`/`numStartups`/everything else survives). Skills, subagents, commands, memory, plugins, marketplaces, MCP servers and settings are never read or written here — that is what makes a switch keep the whole workspace and change only the account; `mcpOAuth` stays put too (machine MCP tokens, not account identity). Stored one JSON file per profile under `<CLAUDE_HOME>/agenthub-profiles/` (dir `0700`, files `0600`), holding live OAuth tokens, so **no route ever returns token material** — `listProfiles()` answers identity metadata only. A profile carries two names: `name`, the filename and the id every route takes, and `label`, the free-form display name (spaces and diacritics fine, since it never touches a path) that `renameProfile()` edits in place without moving the file. One account is one profile — `saveProfile()` refuses `EDUPLICATE` rather than making a second copy, because duplicates both report themselves active, and `deleteProfile()` blocks only the LAST copy of the live account so a duplicate stays cleanable. Cannot mint credentials (only `claude auth login` can): a new profile is captured by logging in, then snapshotting. `activateProfile()` re-snapshots the outgoing account first so refreshed tokens are not lost, and refuses (`EUNSAVED`) to switch away from an account that was never saved — that would discard the only copy of its credentials. Atomic temp + rename at `0600` |
 | `lib/cc-watcher.js`       | Best-effort `fs.watch` over `~/.claude/` (recursive where the platform / Node version honors it — macOS / Windows always; Linux from Node 20) plus `~/.claude.json`. Coalesces bursts at 500 ms and broadcasts `cc_config_changed` with `{ source: "fs", paths: [...] }` so the Config Explorer picks up changes from external tools (CLI installs a plugin, manual `settings.json` edits, dropping a new skill) without a manual refresh. Started from `server/index.js` after the HTTP server boots; failures are caught and logged so a flaky watcher can't take the server down |
 | `lib/codex-discovery.js`  | Read-only discovery of the Codex CLI's file-backed config surfaces for the Codex Config panel — the Codex counterpart of `cc-discovery.js`. Surfaces: skills (`<root>/skills/<name>/SKILL.md`), agents (`<root>/agents/*.toml`), rules (`<root>/rules/*`), memory (`AGENTS.md` at user `~/.codex` + project root), config (`config.toml` at user + project `.codex/`). No filesystem watcher counterpart to `cc-watcher.js` exists for Codex. `readFileSafe()` re-validates path containment (leaf/ancestor symlink-escape guard) independent of the write side's own check. Codex's scope union is `"user"` \| `"project"` only — it has no `"project-local"` settings layer and no per-project file-based auto-memory store |
@@ -352,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. |
@@ -1961,15 +1963,26 @@ These behaviors are reinforced by explicit `Cache-Control` headers from the prod

 ## Update Notifier Subsystem

-The Update Notifier is a **detection-only** subsystem that tells the user when the dashboard's git checkout is behind its tracked upstream branch. It never mutates the checkout or restarts the server — those actions are intentionally left to the user in a terminal, because a process cannot reliably replace itself without an external supervisor.
+The Update Notifier tells the user when a newer **release** of the dashboard has been published, and — on an ordinary git checkout that can be fast-forwarded — can apply it on one click.
+
+The version signal is the forge's own release list, read over REST at `/api/v1/repos/<owner>/<repo>/releases/latest` (no hardcoded host, no credentials for a public repo). The owner and repo come from one of **two** sources, chosen by install kind: a checkout derives them from its `origin` remote; a plugin-cache install derives them from the marketplace manifest on disk (`pluginMarketplaceUrl`), because it has no remote to read — and often no `.git` at all, since a marketplace entry with `"source": "url"` (this project's own) makes Claude Code unpack an archive rather than clone. The published tag is compared against this install's `package.json` version. When no release can be read — a non-HTTP remote, an offline machine, a repo with no releases — detection falls back to the original commit count against the canonical default branch and puts the reason in `release_check`, so "up to date" never means "we couldn't look".
+
+Two states the release model makes visible that a commit count cannot:
+
+- **`dev_build`** — the install is strictly ahead of the newest release and missing nothing from it. It is a build off the branch, not a shipped version, and the Sidebar says so instead of "Up to date".
+- **`plugin_managed`** — the install runs from `~/.claude/plugins/cache/`. Claude Code owns that directory and replaces it wholesale, so `applyUpdate` will not rewrite it: it refuses with `reason: "plugin_managed"`, decided from the path before any status lookup so the refusal holds offline too. A self-pull would leave a cache directory whose name (a commit sha) no longer matched its contents. **This branch is evaluated before the `.git` probe, and must stay there.** An archive-sourced cache directory is not a clone, so a `.git` check reached first answers "not a git clone; check manually" and skips the release layer entirely — which is exactly what 1.5.1 shipped: `update_available` pinned false however many releases were published, `plugin_marketplace`/`plugin_name` never set, so `/apply`'s plugin branch could never fire and its 409 claimed nothing newer was published. It reads as "up to date", so it stays invisible while the install happens to be current. **The button still works here**, by a different route: `POST /api/updates/apply` catches that refusal and hands the job to the detached chain in `server/lib/plugin-update.js` — `claude plugin marketplace update <mkt>` → `claude plugin update <plugin>@<mkt> -y` → `plugin-bootstrap.js --force` **from the new cache directory**, which stops this server and starts the new one. It answers `200 {applied:true, mode:"plugin"}`. The one thing no background process can do is `/reload-plugins`: that is a REPL action scoped to the session that runs it, so an already-open Claude Code session still needs it for new skills/commands/hooks. The dashboard does not, because `plugin-bootstrap.js` derives `PLUGIN_ROOT` from its own `__dirname` rather than from `${CLAUDE_PLUGIN_ROOT}`.
+
+A **shallow clone** (`--depth`) is the third special case, and the plugin cache is one: history is grafted, so every commit-distance number is a graft artefact rather than a distance. All `commits_*_release` fields are `null` there and `dev_build` is never asserted; the version string is the only signal used.
 ### Module Layout

 ```mermaid
 graph TD
    subgraph Server
-        LIB["update-check.js<br/>getUpdatesStatus"]
+        LIB["update-check.js<br/>getUpdatesStatus + applyUpdate<br/>forge releases API"]
        SCHED["update-scheduler.js<br/>startUpdateScheduler"]
-        ROUTE["routes/updates.js<br/>GET status, POST check"]
+        ROUTE["routes/updates.js<br/>GET status, POST check, POST apply"]
+        PLUG["lib/plugin-update.js<br/>schedulePluginUpdate"]
+        HELPER["scripts/plugin-update-helper.js<br/>detached: claude plugin update<br/>then plugin-bootstrap --force"]
        WS["websocket.js<br/>broadcast update_status"]
    end

@@ -1982,6 +1995,9 @@ graph TD

    SCHED -->|tick every 5 min| LIB
    ROUTE -->|on request| LIB
+    ROUTE -->|apply, plugin install| PLUG
+    PLUG -->|spawn detached| HELPER
+    HELPER -->|verdict file| LIB
    SCHED -->|fingerprint changed| WS
    ROUTE -->|on POST check| WS
    WS -->|update_status frame| API
@@ -2041,11 +2057,12 @@ sequenceDiagram

 | Component | Responsibility |
 | --- | --- |
-| **`server/lib/update-check.js`** | Pure function `getUpdatesStatus(root?, { skipFetch? })`. Runs every git call via `execFile` (no shell, 10s–120s timeouts). **Branch- and fork-aware:** prefers `upstream` over `origin` when both exist (standard fork convention), resolves `<remote>/master`/`/main`/`/HEAD`, reads the current branch and its tracked upstream, and shapes `manual_command` per situation: `git pull --ff-only` only when the local branch tracks the canonical ref; `git fetch <remote> && git merge --ff-only <ref>` for forks (local branch name matches canonical but tracks a different remote); `git fetch <remote>` only on a feature branch or detached HEAD. Non-git installs, missing remotes, fetch failures, and unresolvable upstream refs are returned as soft payloads — never throws. Adds `situation`, `situation_note`, `canonical_remote`, `current_branch`, `tracking_upstream`, and `tracks_canonical` to the response. |
+| **`server/lib/update-check.js`** | `getUpdatesStatus(root?, { skipFetch?, latestRelease? })` + `applyUpdate(root?)`. Runs every git call via `execFile` (no shell, 10s–120s timeouts) and reads the newest release over `fetch` with an `AbortSignal.timeout` — `fetchLatestRelease` NEVER throws, resolving to `{ok:false, reason}` (`no_remote`, `remote_not_http`, `no_releases`, `unreachable`, `bad_payload`, `http_<status>`) so a status poll degrades instead of erroring. `releaseApiUrl` derives the endpoint from a repository URL (https, scp-style and `ssh://` forms) and returns null for anything not owner/repo shaped, which is what keeps local-path remotes off the network entirely. `fetchLatestRelease` finds that URL via the `origin` remote; `fetchReleaseFromUrl` takes one directly, which is how the **git-free plugin path** works: `pluginMarketplaceUrl(mkt, plugin)` reads `known_marketplaces.json` → the marketplace's `.claude-plugin/marketplace.json` → the entry's `source.url`, returning null (never a guessed host) for a `github` `owner/repo` shorthand and never throwing. **Order matters:** `detectPluginInstall` runs FIRST in `getUpdatesStatus`, ahead of the `.git` probe — a plugin cache unpacked from an archive has no `.git`, and probing first is the 1.5.1 bug that made `update_available` permanently false. `compareVersions` orders numeric triples and strips a leading `v`, since this repo carries both `v1.5.0` and `1.4.6`. `isShallowClone` gates every commit-distance calculation; `detectPluginInstall` reads the marketplace and plugin name out of the cache path. **Branch- and fork-aware** as before: resolves `<remote>/master`/`/main`/`/HEAD`, reads the current branch and its tracked upstream, and shapes `manual_command` per situation — the `claude plugin ...` commands for `plugin_managed`; `git fetch <remote> --tags && git merge --ff-only <tag>` for `release_available`; `git pull --ff-only` when the branch tracks the canonical ref; `git fetch <remote> && git merge --ff-only <ref>` for forks; `git fetch <remote>` only on a feature branch or detached HEAD. Non-git installs, missing remotes, fetch failures, and unresolvable upstream refs are returned as soft payloads — never throws. |
 | **`server/update-scheduler.js`** | Ticks the lib every `DASHBOARD_UPDATE_CHECK_INTERVAL_MS` (default 300 000, floor 60 000). First tick is scheduled 8s after server start with `.unref()` so it doesn't block shutdown. Broadcasts only when the fingerprint `{update_available, remote_sha, commits_behind, fetch_error, manual_command}` changes — `manual_command` is included so situation transitions (e.g. user switches branches, or adds an `upstream` remote) trigger a re-broadcast even when the SHA and commit count are unchanged. Emits a framed message to stdout on "up-to-date → behind" transitions, and only suggests "restart the dashboard" when the printed command actually rewrites the working tree. `DASHBOARD_UPDATE_CHECK=0\|false\|off` disables the scheduler entirely. |
-| **`server/routes/updates.js`** | Two endpoints: `GET /status` (read-only check), `POST /check` (check + broadcast). Mounted under `/api/*`, so they ride the default loopback bind as their trust boundary and are gated by `DASHBOARD_TOKEN` when one is set. There is **no** `POST /apply` route. |
-| **`UpdateNotifier.tsx`** | Modal. Hydrates from `api.updates.status()` on mount and mirrors the payload back into the local `eventBus` so the Sidebar can listen without a second git fetch. Subscribes to `update_status` WS frames for ongoing sync. Keeps `dismissedSha` in `localStorage` (`agent-monitor-update-dismissed-sha`) and in React state; a window event `dashboard:reset-update-dismissal` from the Sidebar clears both. ESC / backdrop click dismisses. |
-| **`Sidebar.tsx`** | Always-visible "Check for updates" button in the footer. Subscribes to `update_status` (no own fetch). On click: clears dismissed SHA in localStorage, dispatches `dashboard:reset-update-dismissal`, then calls `api.updates.check()`. Visual state: emerald badge when `update_available`, amber when `fetch_error`, neutral otherwise. |
+| **`server/routes/updates.js`** | Three endpoints: `GET /status` (read-only check), `POST /check` (check + broadcast), `POST /apply`. `/apply` has **two modes**, chosen by how this copy was installed, never by the request body: **checkout** — fast-forward onto the release tag, `npm run setup`, `npm run build` in production, then `scheduleRestart()`; **plugin** — `applyUpdate`'s `plugin_managed` refusal is caught and `schedulePluginUpdate()` runs instead, answering `200 {applied:true, mode:"plugin"}`. The plugin branch fires only when there is genuinely something to pull (`update_available` plus a marketplace and plugin name parsed from the cache path) — a `plugin_managed` refusal with nothing newer published stays a 409 rather than spawning a chain that would stop the server for nothing. Otherwise 409 `UPDATE_NOT_APPLICABLE` with `reason` `"up_to_date"`, `"not_fast_forwardable"`, or `"plugin_managed"`. Both modes write the response BEFORE anything stops the process. Mounted under `/api/*`, so all three ride the default loopback bind as their trust boundary and are gated by `DASHBOARD_TOKEN` when one is set. |
+| **`server/lib/plugin-update.js`** + **`scripts/plugin-update-helper.js`** | The plugin-cache update chain. The lib only spawns the helper detached (cwd = the runtime dir, **not** the plugin root, which is about to be superseded) and clears any previous verdict first so a stale success can't be read back as this run's result. All work is in the helper because its last step SIGTERMs the server that asked for the update — the same split as `self-restart.js`, one step further. The helper re-validates the marketplace and plugin names against `/^[A-Za-z0-9][\w.-]*$/` (they reach an argv across a process boundary), resolves `claude` on PATH or at `~/.local/bin/claude` (a hook-spawned server does not inherit the login shell's PATH), picks the newest cache directory that isn't the old root and does contain `scripts/plugin-bootstrap.js`, and records **every** outcome — including an unexpected throw — to `plugin-update.json` under `~/.claude/agenthub/runtime/`, outside the cache so it survives the swap. Steps: `validate`, `resolve_claude`, `marketplace_update`, `plugin_update`, `already_current` (`ok:true`; nothing was pulled and the old server was left running), `bootstrap`, `done`. `readLastPluginUpdate()` surfaces it as `last_plugin_update` on the status payload — without it a failed chain is indistinguishable from a slow one. |
+| **`UpdateNotifier.tsx`** | Modal. Hydrates from `api.updates.status()` on mount and mirrors the payload back into the local `eventBus` so the Sidebar can listen without a second git fetch. Subscribes to `update_status` WS frames for ongoing sync. Keeps the dismissal key in `localStorage` (`agent-monitor-update-dismissed-sha`) and in React state — the **release tag** when one was read, else the upstream SHA, so a newer release re-opens the prompt while a dismissed one stays dismissed; a window event `dashboard:reset-update-dismissal` from the Sidebar clears both. ESC / backdrop click dismisses. |
+| **`Sidebar.tsx`** | Always-visible "Check for updates" button in the footer. Subscribes to `update_status` (no own fetch). On click: clears dismissed SHA in localStorage, dispatches `dashboard:reset-update-dismissal`, then calls `api.updates.check()`. Visual state: emerald badge when `update_available`, amber when `fetch_error`, neutral otherwise. Label has four resting states, not two — `"<tag> available"`, `"Dev build · N ahead"` (when `dev_build`), `"Up to date"`, or `"Check for updates"` before the first result. |

 ### Payload Shape

@@ -2060,6 +2077,8 @@ interface UpdateStatusPayload {
  tracking_upstream?: string | null;   // e.g. "origin/feature/foo", null if no upstream
  tracks_canonical?: boolean;          // true when branch upstream === remote_ref
  situation?:                          // categorical hint for the UI
+    | "plugin_managed"                 // ~/.claude/plugins/cache — /apply delegates
+    | "release_available"              // fast-forward onto the release tag
    | "tracking_canonical"
    | "fork_or_diverged_tracking"
    | "feature_branch"
@@ -2071,34 +2090,73 @@ interface UpdateStatusPayload {
  manual_command?: string | null;      // shaped for the user's situation
  message?: string | null;
  fetch_error?: string;                // set when git fetch fails
+
+  // ── Release layer ──
+  install_kind?: "plugin" | "checkout";
+  plugin_marketplace?: string | null;  // "sg" — parsed from the cache path
+  plugin_name?: string | null;         // "agenthub" — same source
+  last_plugin_update?: {               // verdict of the previous chain, if any
+    ok: boolean;
+    step: string;                      // "validate" | "resolve_claude" | ...
+    error?: string;
+    note?: string;
+    plugin_root?: string;
+    finished_at?: string;
+  } | null;
+  local_version?: string | null;       // this install's package.json version
+  shallow_clone?: boolean;             // true => every commits_* below is null
+  release_check?: string;              // "ok" | "no_remote" | "remote_not_http"
+                                       //      | "no_releases" | "unreachable"
+                                       //      | "bad_payload" | "http_<status>"
+  latest_release?: string | null;      // tag, e.g. "v1.5.0"
+  latest_release_name?: string | null;
+  latest_release_url?: string | null;
+  latest_release_published_at?: string | null;
+  latest_release_notes?: string | null; // truncated server-side to 4000 chars
+  release_sha?: string | null;         // commit the tag resolves to locally
+  commits_behind_release?: number | null;
+  commits_ahead_of_release?: number | null;
+  dev_build?: boolean;                 // ahead of the newest release, missing nothing
 }
 ```

-The same shape is used by `GET /status`, `POST /check`, and the `update_status` WS message.
+The same shape is used by `GET /status`, `POST /check`, and the `update_status` WS message. `POST /apply` returns it plus `applied: boolean`; in plugin mode it also carries `mode: "plugin"` and `runtime_dir`, and on a 409 a `reason` of `"up_to_date"`, `"not_fast_forwardable"`, or `"plugin_managed"`. `update_available` and `dev_build` are never both true.

 ### Failure Mode Matrix

 | Condition | Returned payload | User-visible effect |
 | --- | --- | --- |
-| Not a git clone | `{git_repo:false, update_available:false, message:"Install directory is not a git clone..."}` | Modal suppressed (`update_available` false). Sidebar stays neutral. |
+| Not a git clone (and not a plugin cache) | `{git_repo:false, update_available:false, message:"Install directory is not a git clone..."}` | Modal suppressed (`update_available` false). Sidebar stays neutral. |
+| Plugin cache with no `.git` (archive-sourced marketplace entry) | `{git_repo:false, install_kind:"plugin", release_check:"ok", latest_release:"vX.Y.Z", update_available:<version compare>}` | Checked normally: the repo URL comes from the marketplace manifest and `package.json` is the only local signal. The `notGit` note is suppressed and **Update now** is offered. |
 | No remotes configured | `{git_repo:true, update_available:false, message:"No git remotes configured..."}` | Same as above. |
 | `git fetch` failed (offline, auth) | `{git_repo:true, update_available:false, canonical_remote, fetch_error:"<stderr>"}` | Sidebar button goes amber; modal stays suppressed until a successful check. |
 | Canonical default branch unresolvable | `{git_repo:true, update_available:false, canonical_remote, message:"Could not resolve <remote>/master..."}` | Modal suppressed. |
 | Healthy, up to date | `{git_repo:true, update_available:false, commits_behind:0, situation:"tracking_canonical"\|...}` | Sidebar neutral, modal suppressed. |
+| Release lookup failed (offline, non-HTTP remote, no releases) | `{release_check:"unreachable"\|"remote_not_http"\|"no_releases"\|..., latest_release:null}` | Detection falls back to the commit count; the modal states the reason so "up to date" is not read as "release checked". |
+| Ahead of the newest release | `{update_available:false, dev_build:true, commits_ahead_of_release:N}` | Sidebar reads `Dev build · N ahead`; modal suppressed (a dev build is not an available update). |
+| Shallow clone (incl. the plugin cache) | `{shallow_clone:true, commits_behind_release:null, commits_ahead_of_release:null, dev_build:false}` | No commit badge is rendered at all — the numbers would be graft artefacts. Version compare still decides `update_available`. |
+| 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. |
 | Healthy, behind, on canonical branch | `{update_available:true, situation:"tracking_canonical", manual_command:"...git pull --ff-only..."}` | Modal opens with `git pull` flow + restart hint. |
 | Healthy, behind, fork (origin = fork, upstream = canonical) | `{update_available:true, situation:"fork_or_diverged_tracking", manual_command:"...git fetch upstream && git merge --ff-only upstream/master..."}` | Modal opens with merge flow + restart hint + `situation_note` explaining the divergence. |
 | Healthy, behind, on a feature branch | `{update_available:true, situation:"feature_branch", manual_command:"...git fetch <remote>"}` | Modal opens; `situation_note` explains the user is off the canonical branch; restart hint suppressed because the working tree isn't being changed. |

-### Why Detection-Only
+### Why Self-Apply Stays Narrow

-The dashboard does not expose an apply/restart endpoint by design. A process cannot reliably replace itself without an external supervisor, and several real constraints make an in-process self-update path strictly worse than letting the user run two commands in a terminal:
+`POST /api/updates/apply` is the one path in this dashboard that mutates its own working tree and restarts the process. It is deliberately narrow: in checkout mode it acts only on `release_available`, `tracking_canonical`, and `fork_or_diverged_tracking`, always with `--ff-only`, and refuses outright on a feature branch or a detached HEAD. A `plugin_managed` install is not a git operation at all — it is delegated to `claude plugin update`, whose own tooling owns that directory. Everywhere else the dashboard prints a command and lets the user run it, because the constraints below are real and an automatic path cannot answer them:

 - **Supervisor ambiguity.** `npm run dev` (concurrently), `npm start`, `pm2`, `systemd`, and `launchd` each need different restart logic; an in-process helper could only encode one of them and would silently mis-restart the rest.
 - **Silent failures.** `npm install` / `npm run build` / port-release timing issues surface as a dead server with no user-facing feedback once the original process has exited.
 - **No rollback.** A partial pull + install leaves a broken checkout with no atomic recovery — the working tree is mutated mid-flight.
- **Branch coverage.** Even with the situation-aware `manual_command` produced by the detection layer, an automatic apply would still need branch-aware integration (rebase vs merge vs switch) and merge-conflict handling. That belongs in the user's shell, not in a background daemon.
+- **Branch coverage.** A feature branch or detached HEAD would need branch-aware integration (rebase vs merge vs switch) and merge-conflict handling. That belongs in the user's shell, not in a background daemon — which is why those situations get a printed `git fetch` and no button.
+- **Ownership.** A plugin-cache install is not ours to rewrite by hand — its directory names are content hashes Claude Code manages. So that case does not fast-forward anything; it calls `claude plugin update` and then re-runs `plugin-bootstrap.js` from the directory that tool produced. The residual limit is only `/reload-plugins`, which is REPL-scoped: an interactive session keeps its old skills/commands until the user reloads, even though the dashboard server has already moved.

-The detection layer carries all of the signal value: the dashboard tells the user *when* to update and *exactly what to run*; the user owns the *how* in their own shell.
+What `--ff-only` buys is the absence of the first three problems inside the supported cases: the move is either a clean fast-forward or it aborts, `npm run setup`/`build` failures reject the request before any restart is scheduled, and the restart itself goes through `self-restart.js` + the detached `scripts/restart-helper.js` rather than an in-process guess at the supervisor.

 ---

@@ -1,15 +1,15 @@
 # Claude Code Working Guide

-_Last synced: 58774f2 (2026-09-04) + per-node run command (`agenthub lanes node`) and its slash commands._ A change that makes any statement in this file, `AGENTS.md`, or a README wrong — a moved path, a new or changed extension point, a retired rule — updates that file in the same change-set and bumps this marker.
+_Last synced: v1.5.6 (2026-09-11) + the systemd handover rule below (`scripts/systemd-service.js`'s `writeUserService`/`restartUserService` split and `plugin-bootstrap.js`'s deferred `pendingSystemdRestart`) + eb63569 (2026-09-10) + release-based update detection (`server/lib/update-check.js` reads the forge releases API — a checkout via its `origin` remote, a plugin-cache install via the marketplace manifest on disk, since an archive-sourced cache dir has no `.git`; a `plugin_managed` install self-updates via the detached `plugin-update` chain) + the install-wide **Update all** batch and session reload (`server/lib/cc-update-all.js`, `server/lib/cc-reload.js`)._ A change that makes any statement in this file, `AGENTS.md`, or a README wrong — a moved path, a new or changed extension point, a retired rule — updates that file in the same change-set and bumps this marker.

 ## Project mission
 - Maintain a reliable local-first dashboard for Claude Code session monitoring.
 - Preserve real-time behavior (hooks -> API -> SQLite -> WebSocket -> UI).

 ## Repo map
- `server/`: Express API, hook ingestion, SQLite access, websocket broadcast (includes optional git upstream checks and `routes/updates.js`, plus `lib/workflow-ingest.js` which ingests on-disk Workflow-tool run journals — fleets that emit no hooks — and `lib/codex-ingest.js`, the same idea for `codex` lanes: it tails Codex's own rollout journals because Codex emits no hooks at all).
+- `server/`: Express API, hook ingestion, SQLite access, websocket broadcast (includes release-based update detection — `lib/update-check.js` reads the repo's own releases API and `routes/updates.js` exposes status/check/apply, refusing to self-update a `~/.claude/plugins/cache/` install, plus `lib/workflow-ingest.js` which ingests on-disk Workflow-tool run journals — fleets that emit no hooks — and `lib/codex-ingest.js`, the same idea for `codex` lanes: it tails Codex's own rollout journals because Codex emits no hooks at all).
 - `client/`: React + Vite UI.
- `scripts/`: hook installer/handler, import, seed, cleanup utilities. (Update detection lives server-side in `server/lib/update-check.js`. `POST /api/updates/apply` (only when the checkout is fast-forwardable) pulls, rebuilds, and self-restarts via `server/lib/self-restart.js` + the detached `scripts/restart-helper.js`; otherwise users run the printed manual command, surfaced in the UI and by `agenthub update-check`.)
+- `scripts/`: hook installer/handler, import, seed, cleanup utilities. (Update detection lives server-side in `server/lib/update-check.js`, keyed on the forge's **newest release** rather than a commit count. `POST /api/updates/apply` has two modes and picks by install kind, never from the request: a fast-forwardable **checkout** merges the release tag `--ff-only`, rebuilds, and self-restarts via `server/lib/self-restart.js` + the detached `scripts/restart-helper.js`; a **plugin-cache** install is handed to `server/lib/plugin-update.js` + the detached `scripts/plugin-update-helper.js`, which runs `claude plugin marketplace update` → `claude plugin update -y` → `plugin-bootstrap.js --force` from the NEW cache dir. Both write the HTTP response before anything stops the process, and every plugin-chain outcome is recorded to `plugin-update.json` in the runtime dir — outside the cache, so it survives the swap and the next server reports it as `last_plugin_update`. Neither mode can run `/reload-plugins`: it is REPL-scoped to the session that invokes it, so an open Claude Code session still reloads by hand for new skills/commands. Elsewhere users run the printed manual command, surfaced in the UI and by `agenthub update-check`. `scripts/cc-update-all-helper.js` is the same detached pattern for the config panel's **Update all** button — marketplaces → every plugin → AgentHub LAST → one reload — journalling each step to `cc-update-all.json` in the runtime dir.)
 - `skills/`: this repo's skills. Because the repo root **is** the `agenthub` plugin root, this is also the plugin's skills directory — every skill here ships to anyone who installs the plugin, addressed as `/agenthub:<name>` (bare `/<name>` works as an alias). Put a skill here only if it should reach plugin users; `agenthub skills install` remains a fallback that copies `ship-feature-lane` into `~/.claude/skills/` for plain checkouts. - `agents/`: the same story for subagents — plugin root, so all four (`qc-local`, `senior-gate-reviewer`, `backend-reviewer`, `frontend-reviewer`) ship as `agenthub:<name>`. This is also the source `agenthub lanes agents install` copies the two pipeline agents from into a lane's `.claude/agents/`, which is what keeps the bare `subagent_type: qc-local` working there. One file per agent, never a second copy.
 - `.claude-plugin/`: the marketplace plus the root `agenthub` plugin manifest (`"source": "./"` — the whole repo is the plugin). Its hooks are inline in `plugin.json`; its commands live in `plugins/agenthub/commands/`, which is NOT a subdirectory plugin. `scripts/plugin-bootstrap.js` runs from `SessionStart` and owns the writable runtime under `~/.claude/agenthub/runtime/` — it never writes into the plugin cache, which Claude Code replaces on every update. See `docs/PLUGINS.md`.
 - **Reporting a required plugin is derived; installing one is allowlisted.** `server/lib/skill-plugins.js` reads the `/plugin:skill` strings out of the loaded pipeline templates — right for the `/agenthub-doctor` row, wrong for an install: a template is a file anyone can drop into `DASHBOARD_PIPELINES_DIR`, so installing whatever name it contains would make "edit a JSON file" mean "run this vendor's install command next session". The bootstrap installs only what `AUTO_INSTALLABLE` (a constant in that file, `superpowers` today) lists, in its DETACHED worker, never in the 10 s hook, recorded once as `state.skillPluginsSettled` (also gating `fastPathOk`), never throwing, and off under `AGENTHUB_AUTO_INSTALL_PLUGINS=0|false|off`. Do not derive an install target from a template.
@@ -43,6 +43,8 @@ A **lane** is a durable unit of parallel agent work — one working directory, m
 See `docs/LANES.md` for full guide: stage reporting, custom templates, lane actions, and the five node states.

 ## Non-negotiable engineering rules
+- **When a `agenthub.service` unit of ours owns the server, nothing else may stop it.** The bootstrap that performs a self-update is spawned by the running server, so it lives in that server's systemd cgroup: SIGTERM-ing the server from there exits 0 (which `Restart=on-failure` read as "meant to stop") AND trips `KillMode=control-group`, reaping the bootstrap before it can repoint the unit or write `state.json` — a dashboard dead after every update until some later session bootstrapped again. So `scripts/systemd-service.js` splits the API: `writeUserService` repoints the unit and starts NOTHING, `restartUserService` uses `--no-block`, and `plugin-bootstrap.js` defers that restart past `writeState` and `releaseLock` (`pendingSystemdRestart`). The unit is `Restart=always`. Do not add a path that stops the dashboard from inside its own cgroup, and do not move the restart earlier. `agenthub service install` may keep using `installUserService` — it runs from a user's shell, outside the cgroup. `systemdOwned` additionally requires the unit to be ACTIVE (an installed-but-stopped unit owns nothing; treating it as owner skips the stop and then binds an occupied port). A unit naming a RETIRED plugin root is invisible until a reboot, so `fastPathOk` rejects it via `unitIsStale` (pure fs — that path may never spawn a process) and the bootstrap rewrites it; repairing the unit is NOT restarting the server (`pendingSystemdRestart = systemdOwned && needsServer`), and the detached-spawn fallback is guarded by `needsServer` so a stale unit alone never starts a second server onto a bound port.
+- **A session reload is typed into a live pane, never spawned.** `/reload-plugins` and `/reload-skills` are scoped BY CLAUDE CODE to the session that runs them, so nothing can reload a session from the outside. `server/lib/cc-reload.js` therefore types them into the dashboard's existing tmux lane panes and spawns NO `claude` process — a one-shot `claude -p "/reload-plugins"` reloads only its own short-lived session, exits, and leaves a junk session in the dashboard's own history. Do not add a path that starts a session in order to reload one.
 - Preserve existing behavior unless explicitly asked to change it.
 - Prefer minimal, reversible diffs.
 - Never silently weaken safety controls around destructive actions.
@@ -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?**
@@ -1190,12 +1190,15 @@ async function cmdPricing(flags, positional) {
 // ── Updates ─────────────────────────────────────────────────────────────────

 async function cmdUpdateCheck() {
-  console.log(c.dim("Checking the canonical remote — this can take a few seconds…"));
+  console.log(c.dim("Checking the repository's latest release — this can take a few seconds…"));
  // POST /check (rather than GET /status) so a dashboard open in the browser
  // sees the same fresh result via the update_status websocket broadcast.
  const s = await post("/api/updates/check");
  heading("Dashboard updates", s.repo_root || baseUrl());
-  if (!s.git_repo) {
+  // A plugin-cache install legitimately has no clone (an archive-sourced
+  // marketplace entry unpacks one), yet it IS checkable and updatable via the
+  // release API — so only a genuine non-git checkout bails out here.
+  if (!s.git_repo && s.install_kind !== "plugin") {
    console.log(`${c.yellow("○")}  ${s.message}`);
    return;
  }
@@ -1203,6 +1206,13 @@ async function cmdUpdateCheck() {
    console.log(`${c.yellow("!")}  ${s.message} ${c.dim(`(${s.fetch_error})`)}`);
    return;
  }
+  // Say WHY the release lookup produced nothing, so a green "up to date" is
+  // never mistaken for "the release list was actually read".
+  if (s.release_check && s.release_check !== "ok") {
+    console.log(
+      c.dim(`   could not read the latest release (${s.release_check}) — compared commits instead`)
+    );
+  }
  if (s.update_available) {
    console.log(`${c.yellow("⬆")}  ${s.message}`);
    if (s.situation_note) console.log(c.dim(`   ${s.situation_note}`));
@@ -1269,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) {
@@ -2985,12 +3012,12 @@ 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"],
      ["reinstall-hooks", "", "Reinstall Claude Code hooks"],
-      ["update-check", "", "Check whether the dashboard checkout is behind upstream"],
+      ["update-check", "", "Check whether a newer release of the dashboard was published"],
      ["clear-data", "--yes", "Delete ALL data (requires --yes)"],
      ["open", "", "Open the dashboard in your browser"],
      ["version", "", "Print the agenthub version (also: --version, -v)"],
@@ -3254,7 +3281,8 @@ const SERVER_ONLY_REASONS = {
  cleanup: "cleanup is a server-side mutation",
  "clear-data": "data wipes must go through the server",
  "reinstall-hooks": "hook installation is performed by the server",
-  "update-check": "the update check runs server-side (git fetch against the canonical remote)",
+  "update-check":
+    "the update check runs server-side (reads the repo's latest release, git fetch as fallback)",
  info: "system info (uptime, memory, WS connections) only exists on a running server",
  health: "health is, by definition, a check against the running server",
 };
@@ -9,7 +9,7 @@
    <meta name="apple-mobile-web-app-capable" content="yes" />
    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
    <meta name="theme-color" content="#6366f1" />
-    <title>Agent Dashboard - Claude Code Monitor</title>
+    <title>Agent Dashboard - SmartGift Solution</title>
    <meta
      name="description"
      content="Real-time monitoring platform for Claude Code agent activity. Track sessions, monitor agents, visualize analytics, manage cost tracking, and receive browser notifications - all with live WebSocket updates."
@@ -24,7 +24,7 @@
    <!-- Open Graph -->
    <meta property="og:type" content="website" />
    <meta property="og:site_name" content="Agent Dashboard" />
-    <meta property="og:title" content="Agent Dashboard - Claude Code Monitor" />
+    <meta property="og:title" content="Agent Dashboard - SmartGift Solution" />
    <meta
      property="og:description"
      content="Real-time monitoring platform for Claude Code agent activity. Track sessions, monitor agents, visualize analytics, manage cost tracking, and receive browser notifications - all with live WebSocket updates."
@@ -37,7 +37,7 @@

    <!-- Twitter / X Card -->
    <meta name="twitter:card" content="summary_large_image" />
-    <meta name="twitter:title" content="Agent Dashboard - Claude Code Monitor" />
+    <meta name="twitter:title" content="Agent Dashboard - SmartGift Solution" />
    <meta
      name="twitter:description"
      content="Real-time monitoring platform for Claude Code agent activity. Sessions, Kanban board, analytics, cost tracking, browser notifications, and WebSocket push."
@@ -353,15 +353,23 @@ export function Sidebar({ wsConnected, collapsed, onToggle }: SidebarProps) {
  };

  const updateAvailable = Boolean(updateStatus?.update_available);
+  // Four resting states, not two: a release is out, this build is ahead of the
+  // newest release (dev build), it matches the newest release, or no release
+  // could be read at all. Collapsing the middle two into "Up to date" is what
+  // made a checkout carrying unreleased commits look shipped.
  const checkTitle = checking
    ? t("nav:checkingForUpdates")
    : checkError
      ? t("nav:checkFailed")
      : updateAvailable
-        ? t("nav:updateAvailable")
-        : updateStatus
-          ? t("nav:upToDate")
-          : t("nav:checkForUpdates");
+        ? updateStatus?.latest_release
+          ? t("nav:releaseAvailable", { version: updateStatus.latest_release })
+          : t("nav:updateAvailable")
+        : updateStatus?.dev_build
+          ? t("nav:devBuild", { count: updateStatus.commits_ahead_of_release ?? 0 })
+          : updateStatus
+            ? t("nav:upToDate")
+            : t("nav:checkForUpdates");
  const currentLanguage = normalizeLanguage(i18n.resolvedLanguage ?? i18n.language);
  const currentIndex = SUPPORTED_LANGUAGES.indexOf(currentLanguage);
  const nextLanguage = SUPPORTED_LANGUAGES[(currentIndex + 1) % SUPPORTED_LANGUAGES.length];
@@ -1,11 +1,22 @@
 /**
 * @file UpdateNotifier.tsx
- * @description Modal surfaced when the dashboard's git checkout is behind its
- * remote tracking branch. Shows how many commits behind, the exact terminal
- * command to update with copy-to-clipboard, and — when the checkout is on a
- * fast-forwardable branch — an "Update now" button that calls
- * `POST /api/updates/apply` to pull, rebuild, and restart the server itself,
- * then polls until it's back and reloads the page.
+ * @description Modal surfaced when a newer RELEASE of the dashboard has been
+ * published (or, when no release can be read, when the checkout is behind its
+ * remote tracking branch). Shows the release version against the running one
+ * with a link to its notes, the exact terminal command with copy-to-clipboard,
+ * and — when the install is fast-forwardable — an "Update now" button that
+ * calls `POST /api/updates/apply` to move onto the release tag, rebuild, and
+ * restart the server itself, then polls until it's back and reloads the page.
+ *
+ * A `plugin_managed` install (running out of `~/.claude/plugins/cache/`) gets
+ * the same button, wired to a different mechanism: the server hands it to a
+ * detached chain (`claude plugin update` then `plugin-bootstrap.js --force`)
+ * which pulls the new cache directory, reinstalls the runtime and restarts the
+ * dashboard. It takes minutes rather than seconds, so the progress text differs
+ * — and the poll waits for the old server to actually go DOWN first, because it
+ * keeps answering while the chain installs. New skills/slash commands still
+ * need `/reload-plugins` in an already-open Claude Code session; nothing a
+ * background process can do for it.
 *
 * ## State sources
 * - Initial fetch via `api.updates.status()` on mount.
@@ -14,8 +25,9 @@
 * - Live refresh from WebSocket `update_status` events on {@link eventBus}.
 *
 * ## Dismissal persistence
- * Dismissals are keyed by `remote_sha` in `localStorage` so a new upstream
- * commit re-opens the prompt. Settings can reset dismissal via the
+ * Dismissals are keyed in `localStorage` by the release tag when there is one,
+ * else the upstream `remote_sha`, so a newer release re-opens the prompt while
+ * a dismissed one stays dismissed. Settings can reset dismissal via the
 * `dashboard:reset-update-dismissal` window event.
 *
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
@@ -66,21 +78,29 @@

 import { useCallback, useEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { Download, X, Copy, Check, RefreshCw, Zap } from "lucide-react";
+import { Download, X, Copy, Check, RefreshCw, Zap, ExternalLink } from "lucide-react";
 import { api } from "../lib/api";
 import { eventBus } from "../lib/eventBus";
 import type { UpdateStatusPayload, WSMessage } from "../lib/types";

-/** `localStorage` key storing the dismissed upstream SHA. */
+/** `localStorage` key storing the dismissed release tag (or upstream SHA). */
 const DISMISS_KEY = "agent-monitor-update-dismissed-sha";

 /** How often to silently re-check for updates in the background. */
 const AUTO_CHECK_INTERVAL_MS = 60 * 60 * 1000;

-/** Situations `POST /api/updates/apply` will actually act on — mirrors the
- *  server-side check in `server/lib/update-check.js`'s `applyUpdate`. */
+/** Situations `POST /api/updates/apply` will actually act on. Mirrors the
+ *  server: `release_available` / `tracking_canonical` / `fork_or_diverged_tracking`
+ *  go through a git fast-forward, and `plugin_managed` goes through the detached
+ *  `plugin-update.js` chain (`claude plugin update` then `plugin-bootstrap --force`),
+ *  which is why it belongs here even though `applyUpdate` itself refuses it. */
 function isAutoApplicable(situation: UpdateStatusPayload["situation"]): boolean {
-  return situation === "tracking_canonical" || situation === "fork_or_diverged_tracking";
+  return (
+    situation === "plugin_managed" ||
+    situation === "release_available" ||
+    situation === "tracking_canonical" ||
+    situation === "fork_or_diverged_tracking"
+  );
 }

 /** Narrow unknown WebSocket payloads to {@link UpdateStatusPayload}. */
@@ -88,7 +108,7 @@ function isUpdatePayload(x: unknown): x is UpdateStatusPayload {
  return typeof x === "object" && x !== null && "git_repo" in x && "update_available" in x;
 }

-/** Read the last dismissed upstream SHA from `localStorage`, or null. */
+/** Read the last dismissed release tag / upstream SHA from `localStorage`. */
 function loadDismissedSha(): string | null {
  try {
    return localStorage.getItem(DISMISS_KEY);
@@ -99,7 +119,7 @@ function loadDismissedSha(): string | null {

 /**
 * Git update availability modal — mounted once in {@link Layout}.
- * @returns `null` when no update is available or the current SHA was dismissed.
+ * @returns `null` when no update is available or this release was dismissed.
 */
 export function UpdateNotifier() {
  const { t } = useTranslation("updates");
@@ -161,19 +181,22 @@ export function UpdateNotifier() {
    return () => window.removeEventListener("dashboard:reset-update-dismissal", handler);
  }, []);

-  const show = Boolean(
-    status?.update_available && status.remote_sha && dismissedSha !== status.remote_sha
-  );
+  // Keyed by the release tag when there is one, so dismissing v1.5.0 doesn't
+  // also swallow v1.6.0 — and so the prompt survives the tag pointing at a
+  // commit the user already has. Falls back to the upstream SHA for the
+  // commit-count path (no release readable).
+  const dismissKey = status?.latest_release || status?.remote_sha || null;
+  const show = Boolean(status?.update_available && dismissKey && dismissedSha !== dismissKey);

  const dismiss = useCallback(() => {
-    if (restarting || !status?.remote_sha) return;
+    if (restarting || !dismissKey) return;
    try {
-      localStorage.setItem(DISMISS_KEY, status.remote_sha);
+      localStorage.setItem(DISMISS_KEY, dismissKey);
    } catch {
      /* ignore */
    }
-    setDismissedSha(status.remote_sha);
-  }, [restarting, status?.remote_sha]);
+    setDismissedSha(dismissKey);
+  }, [restarting, dismissKey]);

  // Escape to dismiss - standard modal affordance.
  useEffect(() => {
@@ -213,12 +236,27 @@ export function UpdateNotifier() {
  // Polls `status()` until the restarted server answers again, then reloads
  // so the tab picks up the new client bundle too — the server can't push
  // this over its own WebSocket since it's mid-restart.
-  const pollUntilBack = useCallback(() => {
+  /**
+   * @param requireDownFirst wait for the server to actually disappear before
+   *   treating a success as "it's back". The git path rebuilds and restarts
+   *   within seconds, but the plugin chain pulls a new cache directory and
+   *   reinstalls dependencies first — the OLD server stays up for that whole
+   *   stretch, so polling naively would get a 200 from the process we are
+   *   waiting to replace and reload onto the same old bundle.
+   */
+  const pollUntilBack = useCallback((requireDownFirst = false) => {
+    let sawDown = !requireDownFirst;
    const attempt = () => {
      api.updates
        .status()
-        .then(() => window.location.reload())
-        .catch(() => setTimeout(attempt, 1500));
+        .then(() => {
+          if (sawDown) window.location.reload();
+          else setTimeout(attempt, 1500);
+        })
+        .catch(() => {
+          sawDown = true;
+          setTimeout(attempt, 1500);
+        });
    };
    setTimeout(attempt, 1500);
  }, []);
@@ -232,11 +270,17 @@ export function UpdateNotifier() {
      if (result.applied) {
        setApplying(false);
        setRestarting(true);
-        pollUntilBack();
+        // mode "plugin": the old server lingers while the chain installs, so
+        // only treat a reachable server as "back" after it has gone away once.
+        pollUntilBack(result.mode === "plugin");
        return;
      }
      setError(
-        result.reason === "not_fast_forwardable" ? t("reasonNotFastForwardable") : t("applyError")
+        result.reason === "plugin_managed"
+          ? t("reasonPluginManaged")
+          : result.reason === "not_fast_forwardable"
+            ? t("reasonNotFastForwardable")
+            : t("applyError")
      );
    } catch (e) {
      setError(e instanceof Error ? e.message : t("applyError"));
@@ -249,6 +293,8 @@ export function UpdateNotifier() {

  const refLabel = status.remote_ref || "origin";
  const behind = status.commits_behind ?? 0;
+  const release = status.latest_release || null;
+  const pluginManaged = status.situation === "plugin_managed";

  return (
    <div
@@ -272,10 +318,14 @@ export function UpdateNotifier() {
                id="update-notifier-title"
                className="text-sm font-semibold text-fg-primary truncate"
              >
-                {t("title")}
+                {release ? t("releaseTitle", { version: release }) : t("title")}
              </h2>
              <p className="text-[11px] text-fg-muted mt-0.5 font-mono truncate">
-                {t("commitsBehind", { count: behind, ref: refLabel })}
+                {/* Never print a commit count on a shallow clone — the number
+                    is a graft artefact, not a distance. */}
+                {release && !status.shallow_clone && status.local_version
+                  ? t("releaseSubtitle", { current: status.local_version })
+                  : t("commitsBehind", { count: behind, ref: refLabel })}
              </p>
            </div>
          </div>
@@ -291,7 +341,30 @@ export function UpdateNotifier() {

        {/* Body */}
        <div className="px-5 py-4 space-y-3">
-          <p className="text-sm text-fg-secondary leading-relaxed">{t("lead")}</p>
+          <p className="text-sm text-fg-secondary leading-relaxed">
+            {pluginManaged ? t("pluginAutoNote") : release ? t("releaseLead") : t("lead")}
+          </p>
+
+          {status.latest_release_url ? (
+            <a
+              href={status.latest_release_url}
+              target="_blank"
+              rel="noreferrer noopener"
+              className="inline-flex items-center gap-1.5 text-xs text-accent hover:underline"
+            >
+              <ExternalLink className="w-3.5 h-3.5" aria-hidden />
+              {t("viewRelease")}
+              {status.latest_release_name ? ` — ${status.latest_release_name}` : null}
+            </a>
+          ) : null}
+
+          {/* Release lookup failed and detection fell back to commit counting:
+              say so, so "up to date" is never read as "release checked". */}
+          {status.release_check && status.release_check !== "ok" ? (
+            <div className="text-xs text-fg-secondary bg-surface-2 border border-border rounded-lg px-3 py-2">
+              {t("releaseUnavailable", { reason: status.release_check })}
+            </div>
+          ) : null}

          {status.fetch_error ? (
            <div className="text-xs text-status-warning/90 bg-status-warning/5 border border-status-warning/20 rounded-lg px-3 py-2">
@@ -299,7 +372,7 @@ export function UpdateNotifier() {
            </div>
          ) : null}

-          {!status.git_repo ? (
+          {!status.git_repo && status.install_kind !== "plugin" ? (
            <div className="text-xs text-fg-secondary bg-surface-2 border border-border rounded-lg px-3 py-2">
              {t("notGit")}
            </div>
@@ -323,7 +396,8 @@ export function UpdateNotifier() {
          {/* The restart hint only applies when the printed command actually
           * rewrites the working tree. Feature-branch / detached-HEAD commands
           * are fetch-only - restarting the dashboard would change nothing. */}
-          {status.situation === "tracking_canonical" ||
+          {status.situation === "release_available" ||
+          status.situation === "tracking_canonical" ||
          status.situation === "fork_or_diverged_tracking" ? (
            <p className="text-[11px] text-fg-muted leading-relaxed">{t("restartNote")}</p>
          ) : null}
@@ -331,7 +405,22 @@ export function UpdateNotifier() {
          {restarting ? (
            <div className="text-xs text-accent bg-accent-muted border border-accent/30 rounded-lg px-3 py-2 flex items-center gap-2">
              <RefreshCw className="w-3.5 h-3.5 animate-spin flex-shrink-0" aria-hidden />
-              {t("restarting")}
+              {/* The plugin chain pulls a new cache directory and reinstalls
+                  dependencies before it restarts, so it takes minutes, not
+                  seconds — saying "restarting" there would look hung. */}
+              {pluginManaged ? t("pluginUpdating") : t("restarting")}
+            </div>
+          ) : null}
+
+          {/* A previous chain that failed: the only place the user would ever
+              learn why, since the server it would have reported from is the one
+              that never came back. */}
+          {status.last_plugin_update && status.last_plugin_update.ok === false ? (
+            <div className="text-xs text-status-danger bg-status-danger/5 border border-status-danger/20 rounded-lg px-3 py-2 leading-relaxed">
+              {t("lastPluginUpdateFailed", {
+                step: status.last_plugin_update.step,
+                error: status.last_plugin_update.error || "",
+              })}
            </div>
          ) : null}

@@ -26,7 +26,7 @@ describe("Sidebar", () => {

  it("should render the subtitle", () => {
    renderSidebar(true);
-    expect(screen.getByText("Claude Code Monitor")).toBeInTheDocument();
+    expect(screen.getByText("SmartGift Solution")).toBeInTheDocument();
  });

  it("should render all navigation links", () => {
@@ -90,6 +90,95 @@ describe("UpdateNotifier — Update now", () => {
    expect(screen.queryByText(i18n.t("updates:updateNow"))).not.toBeInTheDocument();
  });

+  it("offers Update now for a plugin-cache install, noting the session still needs a reload", async () => {
+    // The button works here via the detached `claude plugin update` chain — but
+    // it moves only the dashboard server, so the note about /reload-plugins is
+    // part of the promise, not decoration.
+    statusMock.mockResolvedValue({
+      ...BASE_STATUS,
+      situation: "plugin_managed",
+      install_kind: "plugin",
+      plugin_marketplace: "sg",
+      plugin_name: "agenthub",
+      shallow_clone: true,
+      commits_behind: 0,
+      local_version: "1.5.0",
+      release_check: "ok",
+      latest_release: "v1.6.0",
+      manual_command: "claude plugin marketplace update sg && claude plugin update agenthub@sg -y",
+    });
+    render(<UpdateNotifier />);
+
+    await screen.findByText(i18n.t("updates:releaseTitle", { version: "v1.6.0" }));
+    expect(screen.getByText(i18n.t("updates:updateNow"))).toBeInTheDocument();
+    expect(screen.getByText(i18n.t("updates:pluginAutoNote"))).toBeInTheDocument();
+  });
+
+  it("still offers the button when a plugin install has no git clone at all", async () => {
+    // The 1.5.1 bug: an archive-sourced marketplace entry leaves no .git, so
+    // git_repo is legitimately false. Gating the UI on that reported "not a git
+    // clone; check manually" for an install the dashboard can check AND update.
+    statusMock.mockResolvedValue({
+      ...BASE_STATUS,
+      git_repo: false,
+      situation: "plugin_managed",
+      install_kind: "plugin",
+      plugin_marketplace: "sg",
+      plugin_name: "agenthub",
+      commits_behind: 0,
+      local_version: "1.5.1",
+      release_check: "ok",
+      latest_release: "v1.6.0",
+    });
+    render(<UpdateNotifier />);
+
+    await screen.findByText(i18n.t("updates:releaseTitle", { version: "v1.6.0" }));
+    expect(screen.getByText(i18n.t("updates:updateNow"))).toBeInTheDocument();
+    expect(screen.queryByText(i18n.t("updates:notGit"))).not.toBeInTheDocument();
+  });
+
+  it("surfaces a previous plugin chain's failure so a dead update isn't silent", async () => {
+    statusMock.mockResolvedValue({
+      ...BASE_STATUS,
+      situation: "plugin_managed",
+      install_kind: "plugin",
+      plugin_marketplace: "sg",
+      plugin_name: "agenthub",
+      shallow_clone: true,
+      commits_behind: 0,
+      local_version: "1.5.0",
+      release_check: "ok",
+      latest_release: "v1.6.0",
+      last_plugin_update: {
+        ok: false,
+        step: "resolve_claude",
+        error: "the `claude` CLI is not on this server's PATH",
+        finished_at: new Date().toISOString(),
+      },
+    });
+    render(<UpdateNotifier />);
+
+    await screen.findByText(i18n.t("updates:releaseTitle", { version: "v1.6.0" }));
+    expect(screen.getByText(/resolve_claude/)).toBeInTheDocument();
+  });
+
+  it("titles the modal with the release version when one was read", async () => {
+    statusMock.mockResolvedValue({
+      ...BASE_STATUS,
+      situation: "release_available",
+      release_check: "ok",
+      local_version: "1.5.0",
+      latest_release: "v1.6.0",
+      commits_behind_release: 3,
+      commits_ahead_of_release: 0,
+    });
+    render(<UpdateNotifier />);
+
+    await screen.findByText(i18n.t("updates:releaseTitle", { version: "v1.6.0" }));
+    // A release IS fast-forwardable on a checkout, so the button stays.
+    expect(screen.getByText(i18n.t("updates:updateNow"))).toBeInTheDocument();
+  });
+
  it("surfaces the decline reason instead of restarting on a 409", async () => {
    applyMock.mockResolvedValue({
      ...BASE_STATUS,
@@ -14,6 +14,8 @@
 * the route answers before the actual `git worktree add` runs, so this
 * component polls `GET /api/lanes/:id` until that finishes before running the
 * auto-setup calls against a cwd that must actually exist on disk first.
+ * An optional "Create/update readme file" checkbox starts the lane's terminal
+ * run right after creation with `/sg-all:sg-md-writing` as its first message.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

@@ -94,6 +96,7 @@ export function AddLaneModal({
  const [branches, setBranches] = useState<string[] | null>(null);
  const [base, setBase] = useState("");
  const [pipeline, setPipeline] = useState("default");
+  const [writeDocs, setWriteDocs] = useState(false);
  const [pipelines, setPipelines] = useState<{ id: string; name: string; nodes: unknown[] }[]>([]);
  const [branchesError, setBranchesError] = useState<string | null>(null);
  const [tool, setTool] = useState<LaneTool>("claude");
@@ -114,6 +117,7 @@ export function AddLaneModal({
    setBranches(null);
    setBase("");
    setPipeline("default");
+    setWriteDocs(false);
    setTool("claude");
    setBranchesError(null);
    setError(null);
@@ -177,6 +181,14 @@ export function AddLaneModal({
    return () => window.clearTimeout(timer);
  }, [mode, sourceRepo, t]);

+  // The checkbox below runs the docs skill by opening the lane's own terminal
+  // run with the slash command as its first message — a skill only exists
+  // inside a CLI session, so there is nothing server-side to call instead.
+  // Claude-only: codex has no slash commands (same reason LaneConsolePane
+  // prefills prose for a codex lane).
+  const startDocsRun = (laneId: number, cwd: string) =>
+    api.run.start({ laneId, cwd, initialPrompt: "/sg-all:sg-md-writing" });
+
  const submit = async () => {
    const repo = sourceRepo.trim();
    const name = title.trim();
@@ -192,6 +204,7 @@ export function AddLaneModal({
          pipeline,
          tool,
        });
+        if (writeDocs && tool === "claude") await startDocsRun(result.lane.id, result.lane.cwd);
        onAdded(result.lane);
        reset();
        onClose();
@@ -242,6 +255,10 @@ export function AddLaneModal({
        mcp: mcpOutcome.status === "fulfilled" ? "ok" : "failed",
      });

+      if (writeDocs && tool === "claude") {
+        await startDocsRun(result.lane.id, provisionedLane.cwd);
+      }
+
      if (import.meta.env.DEV) {
        console.info("[add-lane] auto-setup result:", {
          profile:
@@ -390,6 +407,21 @@ export function AddLaneModal({
          <p className="mt-1 text-[10px] text-fg-muted">{t("addLanePipelineHint")}</p>
        </div>

+        {tool === "claude" && (
+          <div>
+            <label className="flex items-center gap-2 text-xs text-fg-secondary">
+              <input
+                type="checkbox"
+                checked={writeDocs}
+                onChange={(e) => setWriteDocs(e.target.checked)}
+                className="h-3.5 w-3.5 accent-accent"
+              />
+              {t("addLaneWriteDocsLabel")}
+            </label>
+            <p className="mt-1 text-[10px] text-fg-muted">{t("addLaneWriteDocsHint")}</p>
+          </div>
+        )}
+
        {mode === "worktree" && branches && (
          <div>
            <label className="mb-1 block text-xs text-fg-secondary" htmlFor="add-lane-base">
@@ -30,6 +30,7 @@ vi.mock("../../../lib/api", () => ({
      agentsInstall: vi.fn(),
      mcpSync: vi.fn(),
    },
+    run: { start: vi.fn() },
  },
 }));

@@ -398,6 +399,42 @@ describe("AddLaneModal — folder browse", () => {
  });
 });

+describe("AddLaneModal — create/update readme", () => {
+  it("opens the new lane's terminal on the docs skill only when the box is ticked", async () => {
+    vi.mocked(api.run.start)
+      .mockReset()
+      .mockResolvedValue({} as never);
+    vi.mocked(api.lanes.ensure).mockResolvedValue({
+      lane: laneFixture({ status: "idle", cwd: "/Users/tester/projects/repo" }),
+      created: true,
+    });
+    renderModal();
+    const user = userEvent.setup();
+
+    await user.click(screen.getByRole("button", { name: "Repo" }));
+    const repoField = screen.getByLabelText("Directory");
+    await focusField(user, repoField);
+    await user.type(repoField, "/Users/tester/projects/repo");
+    await user.click(screen.getByLabelText("Create/update readme file"));
+    await user.click(screen.getByRole("button", { name: "Add lane" }));
+
+    await waitFor(() =>
+      expect(api.run.start).toHaveBeenCalledWith({
+        laneId: 9,
+        cwd: "/Users/tester/projects/repo",
+        initialPrompt: "/sg-all:sg-md-writing",
+      })
+    );
+  });
+
+  it("is hidden for a codex lane, which has no slash commands", async () => {
+    renderModal();
+    const user = userEvent.setup();
+    await user.click(screen.getByRole("button", { name: "Codex" }));
+    expect(screen.queryByLabelText("Create/update readme file")).toBeNull();
+  });
+});
+
 describe("AddLaneModal — pipeline template", () => {
  it("offers every template the server reports and sends the chosen one when adopting a repo", async () => {
    // Creation is the ONLY point the UI can set a template, so a lane born on
@@ -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();
@@ -305,6 +305,21 @@
    "copy": "Copy",
    "copied": "Copied"
  },
+  "updateAll": {
+    "title": "Update everything",
+    "help": "Refreshes every marketplace, then updates all installed plugins, then tells the Claude Code sessions this dashboard has open to pick up the changes. AgentHub itself goes last, because updating it restarts this dashboard.",
+    "button": "Update all",
+    "working": "Updating…",
+    "started": "Update-all started for {{count}} plugin(s).",
+    "failed": "Could not start the update.",
+    "reloadButton": "Reload sessions",
+    "reloaded": "Reload sent to {{count}} open session(s).",
+    "reloadedNone": "No open Claude Code session to reload.",
+    "reloadedCount": "— {{count}} session(s)",
+    "restartWarning": "Keep this tab open. If AgentHub itself is updated, the dashboard restarts at the end and this page reconnects on its own.",
+    "abandoned": "The previous batch stopped without finishing — most likely the machine restarted. Run it again.",
+    "bootstrapFailed": "The dashboard was stopped but did not come back: {{error}}. Run /agenthub-update to recover."
+  },
  "manage": {
    "installTitle": "Install a plugin",
    "installPlaceholder": "owner/repo, https://… or plugin@marketplace",
@@ -40,6 +40,8 @@
  "addLaneToolClaude": "Claude Code",
  "addLaneToolCodex": "Codex",
  "addLaneToolHint": "Which CLI drives this lane. Cannot be changed later.",
+  "addLaneWriteDocsHint": "Opens the lane's terminal on creation and runs the /sg-all:sg-md-writing skill there. Claude lanes only — codex has no slash commands.",
+  "addLaneWriteDocsLabel": "Create/update readme file",
  "mode.repo": "Repo",
  "mode.repoHint": "Adopt this directory as a lane, as-is — no worktree, no new branch.",
  "mode.worktree": "Worktree",
@@ -4,7 +4,7 @@
  "analytics": "Analytics",
  "avg": "avg",
  "brand": "Agent Dashboard",
-  "brandSub": "Claude Code Monitor",
+  "brandSub": "SmartGift Solution",
  "ccConfig": "Claude Config",
  "checkFailed": "Update check failed",
  "checkForUpdates": "Check for updates",
@@ -65,5 +65,7 @@
  "website": "Website",
  "workflows": "Workflows",
  "workspace": "Workspace",
-  "wsEndpoint": "WebSocket"
+  "wsEndpoint": "WebSocket",
+  "releaseAvailable": "{{version}} available",
+  "devBuild": "Dev build · {{count}} ahead"
 }
@@ -8,7 +8,7 @@
  "tagline": "Nothing your agents do stays in the dark.",
  "sub1": "Real-time observability for every Claude Code session.",
  "sub2": "Tokens, tools, costs, and workflows, all live.",
-  "brand": "Claude Code Monitor",
+  "brand": "SmartGift Solution",
  "taglines": [
    "Nothing your agents do stays in the dark.",
    "See every move your agents make.",
@@ -16,5 +16,14 @@
  "updating": "Updating...",
  "restarting": "Rebuilt — restarting the dashboard...",
  "applyError": "Could not apply the update",
-  "reasonNotFastForwardable": "This checkout isn't on the tracked default branch — apply the command above manually."
+  "reasonNotFastForwardable": "This checkout isn't on the tracked default branch — apply the command above manually.",
+  "releaseTitle": "Release {{version}} available",
+  "releaseSubtitle": "You are running {{current}}",
+  "releaseLead": "A new release of the dashboard has been published. \"Update now\" fast-forwards this install onto the release tag, reinstalls dependencies, rebuilds, and restarts the server.",
+  "viewRelease": "Release notes",
+  "reasonPluginManaged": "This install is managed by the Claude Code plugin cache — run /agenthub-update instead.",
+  "releaseUnavailable": "Could not read the latest release from the repository ({{reason}}); fell back to comparing commits.",
+  "pluginAutoNote": "This dashboard is installed as a Claude Code plugin. \"Update now\" pulls the new plugin version, reinstalls the runtime, and restarts the server for you — it takes a few minutes. Newly added skills and slash commands only appear in an already-open Claude Code session after you run /reload-plugins there.",
+  "pluginUpdating": "Pulling the new plugin version and reinstalling the runtime — this takes a few minutes, the page reloads itself when the new server is up...",
+  "lastPluginUpdateFailed": "The last plugin update failed at step \"{{step}}\": {{error}} — run /agenthub-update in Claude Code to recover."
 }
@@ -300,6 +300,21 @@
    "copy": "Sao chép",
    "copied": "Đã sao chép"
  },
+  "updateAll": {
+    "title": "Cập nhật toàn bộ",
+    "help": "Làm mới mọi marketplace, rồi cập nhật tất cả plugin đã cài, sau đó yêu cầu các session Claude Code mà dashboard đang mở nạp lại thay đổi. AgentHub đứng cuối, vì cập nhật nó sẽ khởi động lại dashboard này.",
+    "button": "Cập nhật tất cả",
+    "working": "Đang cập nhật…",
+    "started": "Đã bắt đầu cập nhật {{count}} plugin.",
+    "failed": "Không khởi động được tiến trình cập nhật.",
+    "reloadButton": "Nạp lại session",
+    "reloaded": "Đã gửi lệnh nạp lại tới {{count}} session đang mở.",
+    "reloadedNone": "Không có session Claude Code nào đang mở để nạp lại.",
+    "reloadedCount": "— {{count}} session",
+    "restartWarning": "Giữ tab này mở. Nếu chính AgentHub được cập nhật, dashboard sẽ khởi động lại ở bước cuối và trang tự kết nối lại.",
+    "abandoned": "Đợt cập nhật trước dừng giữa đường — rất có thể do máy khởi động lại. Hãy chạy lại.",
+    "bootstrapFailed": "Dashboard đã bị dừng nhưng không sống lại: {{error}}. Chạy /agenthub-update để khôi phục."
+  },
  "manage": {
    "installTitle": "Cài plugin",
    "installPlaceholder": "owner/repo, https://… hoặc plugin@marketplace",
@@ -40,6 +40,8 @@
  "addLaneToolClaude": "Claude Code",
  "addLaneToolCodex": "Codex",
  "addLaneToolHint": "CLI nào điều khiển lane này. Không thể thay đổi sau này.",
+  "addLaneWriteDocsHint": "Khi tạo lane sẽ mở terminal của lane và chạy skill /sg-all:sg-md-writing tại đó. Chỉ áp dụng cho lane Claude — codex không có slash command.",
+  "addLaneWriteDocsLabel": "Tạo/cập nhật file readme",
  "mode.repo": "Repo",
  "mode.repoHint": "Gắn thẳng thư mục này làm lane, nguyên trạng — không worktree, không nhánh mới.",
  "mode.worktree": "Worktree",
@@ -4,7 +4,7 @@
  "analytics": "Phân tích",
  "avg": "TB",
  "brand": "Bảng điều khiển Agent",
-  "brandSub": "Giám sát Claude Code",
+  "brandSub": "SmartGift Solution",
  "ccConfig": "Cấu hình Claude",
  "checkFailed": "Kiểm tra cập nhật thất bại",
  "checkForUpdates": "Kiểm tra cập nhật",
@@ -65,5 +65,7 @@
  "website": "Website",
  "workflows": "Quy trình",
  "workspace": "Không gian làm việc",
-  "wsEndpoint": "WebSocket"
+  "wsEndpoint": "WebSocket",
+  "releaseAvailable": "Có {{version}}",
+  "devBuild": "Bản dev · trước {{count}} commit"
 }
@@ -8,7 +8,7 @@
  "tagline": "Mọi điều agent của bạn làm đều không ẩn trong bóng tối.",
  "sub1": "Khả năng quan sát thời gian thực cho mọi phiên Claude Code.",
  "sub2": "Token, công cụ, chi phí và workflow, tất cả trực tiếp.",
-  "brand": "Giám sát Claude Code",
+  "brand": "SmartGift Solution",
  "taglines": [
    "Mọi điều agent của bạn làm đều không ẩn trong bóng tối.",
    "Thấy rõ từng bước đi của agent.",
@@ -16,5 +16,14 @@
  "updating": "Đang cập nhật...",
  "restarting": "Đã build xong — đang khởi động lại bảng điều khiển...",
  "applyError": "Không thể áp dụng cập nhật",
-  "reasonNotFastForwardable": "Nhánh hiện tại không phải nhánh mặc định được theo dõi — hãy chạy lệnh ở trên thủ công."
+  "reasonNotFastForwardable": "Nhánh hiện tại không phải nhánh mặc định được theo dõi — hãy chạy lệnh ở trên thủ công.",
+  "releaseTitle": "Đã có bản phát hành {{version}}",
+  "releaseSubtitle": "Bạn đang chạy {{current}}",
+  "releaseLead": "Repo vừa phát hành bản mới. Bấm \"Cập nhật ngay\" để fast-forward install này lên tag của bản phát hành, cài lại dependency, build lại và khởi động lại server.",
+  "viewRelease": "Ghi chú phát hành",
+  "reasonPluginManaged": "Bản cài này do plugin cache của Claude Code quản lý — hãy chạy /agenthub-update.",
+  "releaseUnavailable": "Không đọc được bản phát hành mới nhất từ repo ({{reason}}); đã quay về so sánh theo commit.",
+  "pluginAutoNote": "Dashboard này cài dạng plugin của Claude Code. Bấm \"Cập nhật ngay\" sẽ tự tải bản plugin mới, cài lại runtime và khởi động lại server — mất vài phút. Riêng skill và slash command mới thì session Claude Code đang mở chỉ thấy sau khi bạn chạy /reload-plugins ở đó.",
+  "pluginUpdating": "Đang tải bản plugin mới và cài lại runtime — mất vài phút, trang sẽ tự reload khi server mới lên...",
+  "lastPluginUpdateFailed": "Lần cập nhật plugin trước thất bại ở bước \"{{step}}\": {{error}} — chạy /agenthub-update trong Claude Code để khắc phục."
 }
@@ -1609,11 +1609,45 @@ export const api = {
    /**
     * POST /api/cc-config/plugins/action - enable/disable/update/uninstall an
     * installed plugin by its `<name>@<marketplace>` key.
+     *
+     * `reload` additionally types `/reload-plugins` + `/reload-skills` into the
+     * live Claude Code lane panes, but only when the action itself succeeded —
+     * "update one, reload that one", as opposed to the batch below which
+     * reloads once after everything.
     */
-    pluginAction: (key: string, action: CcPluginAction) =>
-      request<CcCliResult>("/cc-config/plugins/action", {
+    pluginAction: (key: string, action: CcPluginAction, reload?: boolean) =>
+      request<CcCliResult & { reloaded?: CcReloadResult }>("/cc-config/plugins/action", {
        method: "POST",
-        body: JSON.stringify({ key, action }),
+        body: JSON.stringify({ key, action, reload }),
+      }),
+    /**
+     * POST /api/cc-config/reload - tell the Claude Code sessions the dashboard
+     * has open to re-read plugins and/or skills from disk.
+     *
+     * Both slash commands are scoped to the session that runs them, so this
+     * types them into the live lane panes over tmux. Sessions running outside
+     * the dashboard cannot be reached and must run the command themselves.
+     */
+    reload: (kinds?: CcReloadKind[]) =>
+      request<{ ok: true } & CcReloadResult>("/cc-config/reload", {
+        method: "POST",
+        body: JSON.stringify({ kinds }),
+      }),
+    /** GET /api/cc-config/plugins/update-all - progress of the current or last batch. */
+    updateAllStatus: () =>
+      request<{ batch: CcUpdateAllBatch | null }>("/cc-config/plugins/update-all"),
+    /**
+     * POST /api/cc-config/plugins/update-all - update every marketplace, then
+     * every installed plugin, then reload the open sessions.
+     *
+     * Returns as soon as the detached worker is spawned: the batch ends with
+     * AgentHub itself when the dashboard runs from the plugin cache, and that
+     * step restarts this server. Follow it with {@link updateAllStatus}.
+     */
+    updateAll: () =>
+      request<CcUpdateAllStarted>("/cc-config/plugins/update-all", {
+        method: "POST",
+        body: JSON.stringify({}),
      }),
    /**
     * POST /api/cc-config/marketplaces/add - register a marketplace from a
@@ -2761,6 +2795,73 @@ export type CcPluginAction = "enable" | "disable" | "update" | "uninstall";
 /** What POST /api/cc-config/marketplaces/action can do to a marketplace. */
 export type CcMarketplaceAction = "update" | "remove";

+/** Which reload slash command to send. The command strings themselves are
+ *  fixed server-side — a pane's stdin is not a place to forward client input. */
+export type CcReloadKind = "plugins" | "skills";
+
+/** What POST /api/cc-config/reload reached. `lanes_total` counts only panes
+ *  that were running a live `claude`; a lane sitting at a shell prompt has no
+ *  REPL to reload and is skipped rather than reported as failed. */
+export interface CcReloadResult {
+  commands: string[];
+  lanes_total: number;
+  lanes: {
+    id: string;
+    laneId: number | null;
+    /** Commands actually delivered — empty when the pane died mid-send. */
+    sent: string[];
+    error?: string;
+  }[];
+}
+
+/** One step of the update-all batch. `key` is stable (`marketplaces`,
+ *  `plugin:<id>`, `reload`) so the UI can keep a row's identity across polls. */
+export interface CcUpdateAllStep {
+  key: string;
+  label: string;
+  status: "running" | "ok" | "failed" | "skipped";
+  started_at?: string;
+  finished_at?: string;
+  error?: string;
+  note?: string;
+  /** Set on the AgentHub step that triggers the dashboard restart. */
+  restarted?: boolean;
+  /** Set on the reload step — the lane sessions that were typed into. */
+  lanes?: string[];
+  lanes_total?: number;
+}
+
+/**
+ * GET /api/cc-config/plugins/update-all - the batch worker's on-disk journal.
+ *
+ * `abandoned` is derived, not written: the worker is detached, so a host reboot
+ * leaves a `running` journal with nobody to finish it. `partial` means the
+ * batch ran to the end with at least one failed step.
+ */
+export interface CcUpdateAllBatch {
+  status: "running" | "done" | "partial" | "failed" | "abandoned";
+  steps: CcUpdateAllStep[];
+  started_at?: string;
+  finished_at?: string;
+  error?: string;
+  /** Set when the final `plugin-bootstrap --force` failed, i.e. the old server
+   *  was stopped and no replacement came up. */
+  bootstrap_error?: string;
+  note?: string;
+}
+
+/** POST /api/cc-config/plugins/update-all - acknowledgement, not a result. */
+export interface CcUpdateAllStarted {
+  ok: true;
+  spawned: true;
+  runtime_dir: string;
+  /** How many installed plugins the worker will walk. */
+  planned: number;
+  /** The plugin this dashboard itself runs from, updated LAST because its
+   *  bootstrap restarts the server. Null for a plain git checkout. */
+  self_plugin: { marketplace: string; plugin: string } | null;
+}
+
 /** Result of a `claude plugin …` run the dashboard triggered. A non-zero CLI
 *  exit arrives as an HTTP 422 error instead of one of these. */
 export interface CcCliResult {
@@ -1255,6 +1255,8 @@ export interface UpdateStatusPayload {
   * shape (e.g. show "Restart after running" only when the command
   * actually rewrites the working tree). */
  situation?:
+    | "plugin_managed"
+    | "release_available"
    | "tracking_canonical"
    | "fork_or_diverged_tracking"
    | "feature_branch"
@@ -1285,9 +1287,79 @@ export interface UpdateStatusPayload {
   *  restart itself). Absent from `status`/`check` responses. */
  applied?: boolean;
  /** Set alongside `applied: false` on an `/apply` response that declined to
-   *  act - `"up_to_date"` or `"not_fast_forwardable"` (feature branch /
-   *  detached HEAD, where there's no safe automatic move). */
-  reason?: "up_to_date" | "not_fast_forwardable";
+   *  act - `"up_to_date"`, `"not_fast_forwardable"` (feature branch /
+   *  detached HEAD, where there's no safe automatic move), or
+   *  `"plugin_managed"` (the install lives in the Claude Code plugin cache,
+   *  which only `/reload-plugins` can swap - the server must not touch it). */
+  reason?: "up_to_date" | "not_fast_forwardable" | "plugin_managed";
+
+  // ── Release layer ──
+  /** How this copy was installed. `"plugin"` means it runs out of
+   *  `~/.claude/plugins/cache/`, where self-update is refused. */
+  install_kind?: "plugin" | "checkout";
+  /** Marketplace the plugin came from (e.g. `"sg"`), parsed from the cache
+   *  path. null for a checkout install. Used to print the exact
+   *  `claude plugin update <plugin>@<marketplace>` command. */
+  plugin_marketplace?: string | null;
+  /** Version this install declares in its own package.json, e.g. `"1.5.0"`.
+   *  Compared against `latest_release` to decide `update_available`. */
+  local_version?: string | null;
+  /** True for a `--depth` clone, where every commit-distance field is
+   *  meaningless and therefore null - the UI must not render an
+   *  "N commits behind" badge. The Claude Code plugin cache is one. */
+  shallow_clone?: boolean;
+  /** `"ok"`, or why the release lookup produced nothing: `"no_remote"`,
+   *  `"remote_not_http"`, `"no_releases"`, `"unreachable"`, `"bad_payload"`,
+   *  or `"http_<status>"`. Anything but `"ok"` means detection fell back to
+   *  the commit-count comparison. */
+  release_check?: string;
+  /** Tag of the newest published release, e.g. `"v1.5.0"`. null when
+   *  `release_check !== "ok"`. */
+  latest_release?: string | null;
+  /** Human title of that release, when the forge has one. */
+  latest_release_name?: string | null;
+  /** Browser URL of the release page, for a "view release notes" link. */
+  latest_release_url?: string | null;
+  /** ISO timestamp the release was published. */
+  latest_release_published_at?: string | null;
+  /** Release body/changelog, truncated server-side to 4000 chars. */
+  latest_release_notes?: string | null;
+  /** Commit the release tag resolves to locally; null when the tag hasn't
+   *  been fetched yet. */
+  release_sha?: string | null;
+  /** Commits in the release that this install lacks. null on a shallow
+   *  clone (see `shallow_clone`). */
+  commits_behind_release?: number | null;
+  /** Commits this install carries that the release does not. null on a
+   *  shallow clone. Drives the "dev build" label. */
+  commits_ahead_of_release?: number | null;
+  /** True when this install is strictly ahead of the newest release and
+   *  missing nothing from it - a build off the branch, not a shipped
+   *  version. Never true at the same time as `update_available`. */
+  dev_build?: boolean;
+  /** Plugin name parsed from the cache path (e.g. `"agenthub"`). null for a
+   *  checkout install. Combined with `plugin_marketplace` it forms the
+   *  `claude plugin update <plugin>@<marketplace>` target. */
+  plugin_name?: string | null;
+  /** Present only on an `/apply` response. `"plugin"` means the detached
+   *  plugin chain took the job (minutes, and the old server stays up while it
+   *  installs); absent means an in-place git fast-forward + restart. */
+  mode?: "plugin";
+  /** Runtime directory the plugin chain writes its log/verdict into. Present
+   *  only on an `/apply` response with `mode: "plugin"`. */
+  runtime_dir?: string;
+  /** Verdict of the most recent plugin-update chain, or null when there has
+   *  never been one. `ok: false` is the ONLY way a failed chain becomes
+   *  visible - the server that would have reported it is the one that never
+   *  came back. Read on every status poll for a plugin install. */
+  last_plugin_update?: {
+    ok: boolean;
+    step: string;
+    error?: string;
+    note?: string;
+    plugin_root?: string;
+    finished_at?: string;
+  } | null;
 }

 // ───── Terminal run status ─────
@@ -1316,8 +1388,28 @@ export interface CcConfigChangedPayload {
  /** Whether the dashboard itself made the write, or an fs watcher observed
   *  an external change (e.g. the user editing a file directly). */
  source: "dashboard" | "fs";
-  /** Mutation kind; absent for some fs-watcher events that only report scope. */
-  action?: "write" | "delete";
+  /** Mutation kind; absent for some fs-watcher events that only report scope.
+   *  Covers the file editor (`write`/`delete`), settings (`patch`), the
+   *  `claude plugin …` routes
+   *  (`install`/`enable`/`disable`/`update`/`uninstall` for a plugin,
+   *  `add`/`remove`/`update` for a marketplace) and the auth profiles
+   *  (`save`/`rename`/`activate`/`delete`). Keep in step with the `emitChanged`
+   *  call sites in `server/routes/cc-config.js` — the union was previously just
+   *  `write | delete`, which every plugin route already contradicted. */
+  action?:
+    | "write"
+    | "delete"
+    | "patch"
+    | "install"
+    | "enable"
+    | "disable"
+    | "update"
+    | "uninstall"
+    | "add"
+    | "remove"
+    | "save"
+    | "rename"
+    | "activate";
  /** "user" (~/.claude) or "project" (repo's .claude) config root affected.
   *  Lets a listening tab decide whether the change is relevant to its view. */
  scope?: "user" | "project";
@@ -92,6 +92,11 @@ import {
  CircleSlash,
  ChevronDown,
  UserCog,
+  ArrowUpCircle,
+  RotateCw,
+  CheckCircle2,
+  XCircle,
+  MinusCircle,
 } from "lucide-react";
 import { api } from "../lib/api";
 import { FileViewer } from "../components/config/FileViewer";
@@ -133,6 +138,7 @@ import type {
  CcPlugin,
  CcPluginItem,
  CcPluginsResponse,
+  CcUpdateAllBatch,
  CcProfile,
  CcAccountIdentity,
  CcScope,
@@ -1301,6 +1307,172 @@ function ActionButton({
  );
 }

+/** Icon + colour per batch-step state. */
+type StepLook = { Icon: typeof CheckCircle2; className: string };
+const STEP_FALLBACK: StepLook = { Icon: MinusCircle, className: "text-fg-muted" };
+const STEP_LOOK: Record<string, StepLook> = {
+  running: { Icon: RefreshCw, className: "text-accent animate-spin" },
+  ok: { Icon: CheckCircle2, className: "text-status-success" },
+  failed: { Icon: XCircle, className: "text-status-error" },
+  skipped: { Icon: MinusCircle, className: "text-fg-muted" },
+};
+
+/**
+ * "Update all" + "Reload sessions" for the whole Claude Code install.
+ *
+ * The batch runs in a detached server-side worker and is followed by polling
+ * rather than by the POST's response, because the last step restarts the
+ * dashboard when AgentHub is itself a plugin install. Polling therefore has to
+ * tolerate the server disappearing mid-batch: a failed poll is ignored and
+ * retried, never rendered as an error, because the most likely cause is the
+ * successful restart this button asked for.
+ */
+function UpdateAllCard({
+  onToast,
+  onChanged,
+}: {
+  onToast: (t: NonNullable<Toast>) => void;
+  onChanged: () => void;
+}) {
+  const { t } = useTranslation("ccConfig");
+  const [batch, setBatch] = useState<CcUpdateAllBatch | null>(null);
+  const [starting, setStarting] = useState(false);
+  const [reloading, setReloading] = useState(false);
+  const running = batch?.status === "running";
+
+  const poll = useCallback(async () => {
+    try {
+      const res = await api.ccConfig.updateAllStatus();
+      setBatch(res.batch);
+      return res.batch;
+    } catch {
+      // Server is down (very likely the AgentHub restart we triggered) — keep
+      // the last known steps on screen and try again on the next tick.
+      return undefined;
+    }
+  }, []);
+
+  // Pick up a batch already in flight, including one started by the server we
+  // were talking to BEFORE it restarted itself.
+  useEffect(() => {
+    void poll();
+  }, [poll]);
+
+  useEffect(() => {
+    if (!running) return;
+    const id = setInterval(() => void poll(), 2000);
+    return () => clearInterval(id);
+  }, [running, poll]);
+
+  // Refresh the surrounding inventory once the batch stops moving, so version
+  // numbers and install paths catch up without a manual reload.
+  const prevStatus = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (prevStatus.current === "running" && batch?.status !== "running") onChanged();
+    prevStatus.current = batch?.status;
+  }, [batch?.status, onChanged]);
+
+  const start = useCallback(async () => {
+    setStarting(true);
+    try {
+      const res = await api.ccConfig.updateAll();
+      onToast({ kind: "success", message: t("updateAll.started", { count: res.planned }) });
+      await poll();
+    } catch (err: unknown) {
+      onToast({
+        kind: "error",
+        message: err instanceof Error ? err.message : t("updateAll.failed"),
+      });
+    } finally {
+      setStarting(false);
+    }
+  }, [onToast, poll, t]);
+
+  const reloadOnly = useCallback(async () => {
+    setReloading(true);
+    try {
+      const res = await api.ccConfig.reload();
+      onToast({
+        kind: "success",
+        message:
+          res.lanes_total > 0
+            ? t("updateAll.reloaded", { count: res.lanes_total })
+            : t("updateAll.reloadedNone"),
+      });
+    } catch (err: unknown) {
+      onToast({
+        kind: "error",
+        message: err instanceof Error ? err.message : t("updateAll.failed"),
+      });
+    } finally {
+      setReloading(false);
+    }
+  }, [onToast, t]);
+
+  return (
+    <div className="rounded-lg border border-border bg-surface-2 px-3 py-2.5">
+      <div className="flex items-center gap-2 flex-wrap">
+        <div className="text-[11px] font-semibold text-fg-secondary">{t("updateAll.title")}</div>
+        <div className="ml-auto flex items-center gap-1.5">
+          <button
+            type="button"
+            onClick={() => void reloadOnly()}
+            disabled={reloading || running}
+            className="h-8 text-[11px] font-medium px-3 rounded-md border border-border bg-surface-1 hover:bg-surface-3 text-fg-secondary inline-flex items-center gap-1.5 disabled:opacity-50"
+          >
+            <RotateCw className={`w-3 h-3 ${reloading ? "animate-spin" : ""}`} />
+            {t("updateAll.reloadButton")}
+          </button>
+          <button
+            type="button"
+            onClick={() => void start()}
+            disabled={starting || running}
+            className="h-8 text-[11px] font-medium px-3 rounded-md border border-accent/30 bg-accent/10 hover:bg-accent/20 text-accent inline-flex items-center gap-1.5 disabled:opacity-50"
+          >
+            <ArrowUpCircle className="w-3 h-3" />
+            {running || starting ? t("updateAll.working") : t("updateAll.button")}
+          </button>
+        </div>
+      </div>
+      <p className="mt-1.5 text-[10px] text-fg-muted leading-relaxed">{t("updateAll.help")}</p>
+
+      {batch && (
+        <div className="mt-2 space-y-1">
+          {batch.steps.map((step) => {
+            const look = STEP_LOOK[step.status] ?? STEP_FALLBACK;
+            return (
+              <div key={step.key} className="flex items-start gap-1.5 text-[11px]">
+                <look.Icon className={`w-3 h-3 mt-0.5 shrink-0 ${look.className}`} />
+                <span className="font-mono text-fg-secondary truncate">{step.label}</span>
+                {step.note && <span className="text-fg-muted truncate">— {step.note}</span>}
+                {step.error && (
+                  <span className="text-status-error truncate" title={step.error}>
+                    — {step.error}
+                  </span>
+                )}
+                {step.key === "reload" && step.lanes_total !== undefined && (
+                  <span className="text-fg-muted">
+                    {t("updateAll.reloadedCount", { count: step.lanes_total })}
+                  </span>
+                )}
+              </div>
+            );
+          })}
+          {batch.status === "abandoned" && (
+            <p className="text-[10px] text-status-warning">{t("updateAll.abandoned")}</p>
+          )}
+          {batch.bootstrap_error && (
+            <p className="text-[10px] text-status-error">
+              {t("updateAll.bootstrapFailed", { error: batch.bootstrap_error })}
+            </p>
+          )}
+          {running && <p className="text-[10px] text-fg-muted">{t("updateAll.restartWarning")}</p>}
+        </div>
+      )}
+    </div>
+  );
+}
+
 function PluginsPanel({
  data,
  search,
@@ -1373,6 +1545,8 @@ function PluginsPanel({
        commands={[{ cmd: t("explain.plugins.installCmd"), note: "" }]}
      />

+      <UpdateAllCard onToast={onToast} onChanged={onChanged} />
+
      <div className="rounded-lg border border-accent/25 bg-accent/5 px-3 py-2.5">
        <div className="text-[11px] font-semibold text-fg-secondary mb-1.5">
          {t("manage.installTitle")}
@@ -1717,7 +1891,9 @@ function PluginCard({
              onClick={() =>
                void run(
                  p.key,
-                  () => api.ccConfig.pluginAction(p.key, "update"),
+                  // reload=true: updating one plugin reloads the open sessions
+                  // right away. The batch reloads once at the end instead.
+                  () => api.ccConfig.pluginAction(p.key, "update", true),
                  t("manage.updated", { name: p.key })
                )
              }
@@ -0,0 +1,259 @@
+/**
+ * @file Covers the "Update all" card on the Claude Code config panel's plugins
+ * tab: it starts the detached batch, renders the worker's journal as it polls,
+ * survives the dashboard restart the batch's last step causes, and keeps the
+ * per-plugin update button reloading only that one plugin.
+ *
+ * The restart case is the one worth a test: while AgentHub replaces itself the
+ * status endpoint stops answering, and a naive implementation would render that
+ * as a failure right at the moment everything is going to plan.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, act, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+const ccConfigMock = vi.hoisted(() => {
+  const r = (value: unknown) => vi.fn().mockResolvedValue(value);
+  return {
+    overview: r({
+      roots: {
+        claudeHome: "/home/.claude",
+        projectClaudeDir: "/repo/.claude",
+        projectRoot: "/repo",
+      },
+      counts: {
+        skills: { user: 0, project: 0 },
+        agents: { user: 0, project: 0 },
+        commands: { user: 0, project: 0 },
+        outputStyles: { user: 0, project: 0 },
+        mcpServers: { user: 0, project: 0 },
+        hooks: {},
+        plugins: 1,
+        marketplaces: 0,
+        keybindings: 0,
+        settingsFiles: 0,
+        memory: 0,
+      },
+    }),
+    skills: r({ items: [] }),
+    agents: r({ items: [] }),
+    commands: r({ items: [] }),
+    outputStyles: r({ items: [] }),
+    memory: r({ items: [] }),
+    plugins: r({
+      manifestPath: "/home/.claude/plugins/installed_plugins.json",
+      manifestExists: true,
+      plugins: [{ key: "ponytail@ponytail", enabled: true, version: "4.9.0" }],
+    }),
+    marketplaces: r({ marketplaces: [] }),
+    mcp: r({ mcp: [] }),
+    hooks: r({ hooks: [] }),
+    settings: r({ sources: [] }),
+    keybindings: r({ groups: [] }),
+    statusline: r({}),
+    hookScripts: r({ items: [] }),
+    profiles: r({ profiles: [], active: null }),
+    backups: r({ items: [] }),
+    file: r({ ok: true, file: "", size: 0, mtime: 0, truncated: false, text: "" }),
+    pluginsAvailable: r({ installed: [], available: [] }),
+    pluginAction: r({ ok: true, stdout: "", stderr: "" }),
+    updateAllStatus: r({ batch: null }),
+    updateAll: r({
+      ok: true,
+      spawned: true,
+      runtime_dir: "/home/.claude/agenthub/runtime",
+      planned: 7,
+      self_plugin: { marketplace: "sg", plugin: "agenthub" },
+    }),
+    reload: r({ ok: true, commands: ["/reload-plugins"], lanes: [], lanes_total: 2 }),
+  };
+});
+
+vi.mock("../../lib/api", async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    api: { ...(actual.api as Record<string, unknown>), ccConfig: ccConfigMock },
+  };
+});
+
+vi.mock("../../lib/eventBus", () => ({
+  eventBus: {
+    subscribe: () => () => {},
+    publish: () => {},
+    onConnection: () => () => {},
+    connected: true,
+    setConnected: () => {},
+  },
+}));
+
+import { CcConfig } from "../CcConfig";
+
+async function settle() {
+  await act(async () => {
+    await new Promise((res) => setTimeout(res, 0));
+    await new Promise((res) => setTimeout(res, 0));
+  });
+}
+
+/** Open the plugins tab, where the Update all card lives. */
+async function openPlugins() {
+  render(<CcConfig />);
+  await settle();
+  await userEvent.click(screen.getByRole("tab", { name: /plugins/i }));
+  await settle();
+}
+
+afterEach(() => {
+  vi.clearAllMocks();
+  ccConfigMock.updateAllStatus = vi.fn().mockResolvedValue({ batch: null }) as never;
+  ccConfigMock.reload = vi.fn().mockResolvedValue({
+    ok: true,
+    commands: ["/reload-plugins"],
+    lanes: [],
+    lanes_total: 2,
+  }) as never;
+});
+
+describe("CcConfig — Update all", () => {
+  it("starts the batch and reports how many plugins it will walk", async () => {
+    await openPlugins();
+
+    await userEvent.click(screen.getByRole("button", { name: /update all/i }));
+    await settle();
+
+    expect(ccConfigMock.updateAll).toHaveBeenCalledTimes(1);
+    // The count comes from the server's plan, not from the rendered list.
+    expect(await screen.findByText(/7 plugin/i)).toBeInTheDocument();
+  });
+
+  it("renders each step of the worker's journal, including a failure", async () => {
+    ccConfigMock.updateAllStatus = vi.fn().mockResolvedValue({
+      batch: {
+        status: "partial",
+        started_at: new Date().toISOString(),
+        finished_at: new Date().toISOString(),
+        steps: [
+          { key: "marketplaces", label: "Update all marketplaces", status: "ok" },
+          { key: "plugin:ponytail@ponytail", label: "ponytail@ponytail", status: "ok" },
+          {
+            key: "plugin:vercel@claude-plugins-official",
+            label: "vercel@claude-plugins-official",
+            status: "failed",
+            error: "marketplace unreachable",
+          },
+          {
+            key: "reload",
+            label: "Reload open Claude Code sessions",
+            status: "ok",
+            lanes_total: 3,
+          },
+        ],
+      },
+    }) as never;
+
+    await openPlugins();
+
+    expect(await screen.findByText("Update all marketplaces")).toBeInTheDocument();
+    expect(screen.getByText("ponytail@ponytail")).toBeInTheDocument();
+    expect(screen.getByText(/marketplace unreachable/)).toBeInTheDocument();
+    expect(screen.getByText("Reload open Claude Code sessions")).toBeInTheDocument();
+  });
+
+  it("keeps the last known steps on screen when the status endpoint stops answering", async () => {
+    // This is what a successful AgentHub self-update looks like from the tab:
+    // the server it was polling is gone. Rendering an error here would be
+    // wrong — the restart IS the batch working.
+    const runningBatch = {
+      batch: {
+        status: "running",
+        started_at: new Date().toISOString(),
+        steps: [{ key: "marketplaces", label: "Update all marketplaces", status: "ok" }],
+      },
+    };
+    ccConfigMock.updateAllStatus = vi
+      .fn()
+      .mockResolvedValueOnce(runningBatch)
+      .mockRejectedValue(new Error("Failed to fetch")) as never;
+
+    await openPlugins();
+    expect(await screen.findByText("Update all marketplaces")).toBeInTheDocument();
+
+    // Let the polling interval fire into the rejection.
+    await act(async () => {
+      await new Promise((res) => setTimeout(res, 2200));
+    });
+
+    expect(screen.getByText("Update all marketplaces")).toBeInTheDocument();
+    expect(screen.queryByText(/Failed to fetch/)).not.toBeInTheDocument();
+  });
+
+  it("disables both buttons while a batch is running, so two can't overlap", async () => {
+    ccConfigMock.updateAllStatus = vi.fn().mockResolvedValue({
+      batch: {
+        status: "running",
+        started_at: new Date().toISOString(),
+        steps: [{ key: "marketplaces", label: "Update all marketplaces", status: "running" }],
+      },
+    }) as never;
+
+    await openPlugins();
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /updating/i })).toBeDisabled();
+    });
+    expect(screen.getByRole("button", { name: /reload sessions/i })).toBeDisabled();
+  });
+
+  it("re-enables the button for an abandoned batch instead of spinning forever", async () => {
+    // A detached worker killed by a reboot leaves a `running` journal; the
+    // server reports it as abandoned so the button is usable again.
+    ccConfigMock.updateAllStatus = vi.fn().mockResolvedValue({
+      batch: {
+        status: "abandoned",
+        started_at: new Date(Date.now() - 7200_000).toISOString(),
+        steps: [{ key: "marketplaces", label: "Update all marketplaces", status: "running" }],
+      },
+    }) as never;
+
+    await openPlugins();
+
+    expect(await screen.findByRole("button", { name: /update all/i })).not.toBeDisabled();
+  });
+
+  it("reload-only sends the slash commands without starting a batch", async () => {
+    await openPlugins();
+
+    await userEvent.click(screen.getByRole("button", { name: /reload sessions/i }));
+    await settle();
+
+    expect(ccConfigMock.reload).toHaveBeenCalledTimes(1);
+    expect(ccConfigMock.updateAll).not.toHaveBeenCalled();
+    expect(await screen.findByText(/2 open session/i)).toBeInTheDocument();
+  });
+
+  it("says so plainly when there is no open session to reload", async () => {
+    ccConfigMock.reload = vi
+      .fn()
+      .mockResolvedValue({ ok: true, commands: [], lanes: [], lanes_total: 0 }) as never;
+    await openPlugins();
+
+    await userEvent.click(screen.getByRole("button", { name: /reload sessions/i }));
+    await settle();
+
+    expect(await screen.findByText(/no open claude code session/i)).toBeInTheDocument();
+  });
+
+  it("updating one plugin asks for a reload of just that change", async () => {
+    // The batch reloads once at the end; a single update reloads immediately.
+    await openPlugins();
+
+    const [firstUpdate] = screen.getAllByRole("button", { name: /^update$/i });
+    await userEvent.click(firstUpdate!);
+    await settle();
+
+    expect(ccConfigMock.pluginAction).toHaveBeenCalledWith("ponytail@ponytail", "update", true);
+  });
+});
@@ -9537,7 +9537,7 @@ exports[`screen snapshots > Settings 1`] = `
            <p
              class="text-[10px] text-status-warning/90 mt-1"
            >
-              UI build v1.5.0 (rebuild client to match)
+              UI build v1.5.9 (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

@@ -1605,7 +1607,10 @@ POST /api/cc-config/project-memory        Body: { dir, content }
 PATCH /api/cc-config/settings  Body: { scope, set?: { "dotted.key": value }, unset?: ["dotted.key"] }
 GET /api/cc-config/plugins/available
 POST /api/cc-config/plugins/install       Body: { spec, scope? }
-POST /api/cc-config/plugins/action        Body: { key, action: enable|disable|update|uninstall }
+POST /api/cc-config/plugins/action        Body: { key, action: enable|disable|update|uninstall, reload? }
+GET /api/cc-config/plugins/update-all
+POST /api/cc-config/plugins/update-all    Body: { reload? }
+POST /api/cc-config/reload                Body: { kinds?: ["plugins"|"skills"] }
 POST /api/cc-config/marketplaces/add      Body: { source, scope? }
 POST /api/cc-config/marketplaces/action   Body: { name, action: update|remove }
 POST /api/cc-config/mcp/add               Body: { name, scope, transport?, url?, headers?, command?, args?, env? }
@@ -1616,6 +1621,18 @@ POST /api/cc-config/mcp/remove            Body: { name, scope? }

 `GET /api/cc-config/plugins` returns each installed plugin's `contributes` block: the `skills` / `agents` / `commands` / `outputStyles` / `hooks` counts, plus `contributes.items` listing the first four surfaces **by name** (`[{ name, description, file }]`) so the UI can show *which* artifacts a plugin ships, not only how many. `name` is the file's frontmatter `name` when it declares one — the string Claude Code actually addresses it by — otherwise the filename. Each surface covers both the conventional directory (`skills/`, `agents/`, `commands/`, `output-styles/`) **and** any path `plugin.json` declares under that key: a plugin that lists its commands explicitly and keeps nothing in `commands/` (this repo's own `agenthub` does) previously reported zero. A declared path that resolves outside the plugin's install directory is ignored — a third-party manifest must not make the dashboard read arbitrary files. The counts are always the matching list's length. `hooks` has no `items` list: a plugin's hooks are matcher/command pairs declared inline in `plugin.json`, not named artifacts.

+### Updating everything, and reloading sessions
+
+`POST /api/cc-config/plugins/update-all` refreshes every marketplace, then updates every installed plugin, then tells the open Claude Code sessions to pick the changes up. It **returns as soon as a detached worker is spawned** — the response is an acknowledgement, not a result — and progress is polled from `GET` on the same path, which reads the worker's journal at `~/.claude/agenthub/runtime/cc-update-all.json`.
+
+That indirection is structural, not stylistic: the plugin this dashboard *itself* runs from is updated **last**, followed by `plugin-bootstrap.js --force`, which stops this server and starts the replacement. A request handler doing the work would die partway through with the remaining plugins unrun and nothing able to report why, so the journal lives outside the plugin cache the update replaces and whichever server is alive serves it. Plugin ids come from `claude plugin list --json`, never from the request body, and the "self" plugin is derived from the server's own path — no caller can nominate a different plugin for the restart. A second concurrent batch is refused with 409 `EBUSY`.
+
+Batch `status` is `running`, `done`, `partial` (finished, at least one step failed), `failed`, or `abandoned`. `abandoned` is **derived, not stored**: the worker is detached, so a reboot leaves a `running` journal with nobody to finish it, and after an hour it is reported as abandoned so the button is usable again.
+
+`POST /api/cc-config/reload` is the reload step on its own. It types `/reload-plugins` and `/reload-skills` into the dashboard's live lane panes via `tmux send-keys`. **Both commands are scoped by Claude Code to the session that runs them** (`/reload-plugins` activates pending plugin changes "in the current session"; `/reload-skills` picks up skills changed on disk "during this session"), so nothing can reload a session from the outside — typing into a session that is already running is the only real mechanism, and it is what this does. It never spawns a `claude` process: a one-shot `claude -p "/reload-plugins"` would reload its own short-lived session, exit, and leave a junk session behind. Panes sitting at a shell prompt are skipped, since the text would run as a shell command instead; only `claude` lanes are addressed, as Codex has no equivalent. `lanes_total: 0` is a normal outcome, not an error. Sessions running outside the dashboard cannot be reached and must run the command themselves.
+
+`POST /api/cc-config/plugins/action` accepts `reload: true` for the counterpart behaviour: update one plugin, reload immediately. The batch reloads once at the end instead — one reload picks up every pending change, where N of them would re-scan the same directory N times. A reload is never sent after a *failed* action.
+
 `GET /api/cc-config/memory` also surfaces the per-project file-based memory store — every `*.md` under `~/.claude/projects/<slug>/memory/` (the common pattern of a `MEMORY.md` index plus one file per remembered fact). Those items have `scope: "auto-memory"` and carry `project` (the `projects/<slug>` dir name), `name` (filename), `isIndex` (true for `MEMORY.md` / `INDEX-*.md`, which sort first), and parsed `frontmatter`. They are **editable**: `PUT`/`DELETE /api/cc-config/file` accept `{ scope: "auto-memory", type: "auto-memory", project, name, content? }` and create a timestamped backup under `<memory-dir>/.cc-config-backups/auto-memory/` before mutating (an invalid `project` slug returns `EBADPROJECT`). `GET /api/cc-config/backups` lists these with `scope: "auto-memory"` and `project` set. Bodies are also readable via `GET /api/cc-config/file` (they live under `CLAUDE_HOME`).

 **`POST /api/{cc,codex}-config/project-memory` (a new project's memory file).** Creates `CLAUDE.md` (Claude) or `AGENTS.md` (Codex) inside the directory named by `dir` — the one write path that honours a caller-supplied directory, because bootstrapping a project the dashboard has never run in is impossible from a writer pinned to the server's own cwd (which is what `PUT /file`'s `"project"` scope means). It stays narrow: `dir` must be absolute and already exist (nothing is created for you), the filename comes from the route and is never taken from the body, and an existing file — including a symlink under that name — returns **409 `EEXISTS`** rather than being overwritten, so this endpoint can only ever create. Bad or missing directories return 400 `EBADDIR`. Unlike the other config routes it sits behind the same loopback-`Origin` guard `/api/run` uses (403 `EBADORIGIN`): a page in the user's browser could otherwise plant agent instructions in a project directory. Returns `{ file, size, created: true }`, where `file` is the realpath'd target, and broadcasts `cc_config_changed`.
@@ -272,12 +272,12 @@ 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 |
 | `agenthub reinstall-hooks` | Rewrite the Claude Code hook entries in `~/.claude/settings.json` |
-| `agenthub update-check` | Ask the server whether the dashboard checkout is behind the canonical remote (branch- and fork-aware). Prints the behind-by count, a situation note for fork/feature-branch checkouts, and the **copy-paste update command**. When the checkout is fast-forwardable, the dashboard UI can also self-apply (`POST /api/updates/apply`: pull, rebuild, self-restart) instead of running the command by hand. Also refreshes the update banner in any open dashboard tab (same `update_status` broadcast) |
+| `agenthub update-check` | Ask the server whether a newer **release** has been published, read from the forge's own releases API (a checkout derives the repo from its `origin` remote; a plugin-cache install, which has no clone and often no `.git` at all, derives it from the marketplace manifest on disk); falls back to a commit count against the canonical remote when no release can be read, with the reason in `release_check`. Prints the release tag against the running version, a situation note for fork/feature-branch checkouts, and the **copy-paste update command**. Reports `dev_build` when the install is ahead of the newest release, and `plugin_managed` for an install under `~/.claude/plugins/cache/`. The dashboard UI can self-apply either kind (`POST /api/updates/apply`): a fast-forwardable checkout is fast-forwarded onto the release tag, rebuilt and self-restarted; a plugin install is handed to a detached `claude plugin marketplace update` → `claude plugin update` → `plugin-bootstrap.js --force` chain instead. `/agenthub-update` remains the manual equivalent, and an already-open Claude Code session still needs `/reload-plugins` to pick up new skills and commands. Also refreshes the update banner in any open dashboard tab (same `update_status` broadcast) |
 | `agenthub clear-data --yes` | Delete **all** data (schema preserved). Refuses to run without `--yes` |
 | `agenthub open` | Open the dashboard in your default browser (`open` / `xdg-open` / `start`) |
 | `agenthub version` | Print the agenthub version (also `--version` / `-v`) |
@@ -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

@@ -451,7 +456,10 @@ Environment=NODE_ENV=production
 Environment=PORT=4820
 Environment=DASHBOARD_DB_PATH=/var/lib/agenthub/dashboard.db
 ExecStart=/usr/bin/node server/index.js
-Restart=on-failure
+# `always`, not `on-failure`: a graceful SIGTERM exits 0, which `on-failure`
+# reads as "meant to stop" — one stray kill and the dashboard stays down.
+# `systemctl stop` still stops it. Same reasoning as the plugin's own unit.
+Restart=always
 RestartSec=10
 StandardOutput=journal
 StandardError=journal
@@ -43,6 +43,8 @@ The modal has a segmented toggle mirroring the CLI's two modes:
 - **Repo** — adopts the given directory as-is (maps to `agenthub lanes add --cwd`). No branch fields; the auto-setup summary above does not run (adopting is instant, nothing to wait on).
 - **Worktree** (default) — provisions a managed worktree (maps to `agenthub lanes add --repo`). Unlike the CLI, the modal requires you to type the new branch's name yourself rather than deriving one from the title — the underlying route still derives one when `branch` is omitted, so the CLI's behavior is unchanged.

+Under the *Pipeline template* select, a **Create/update readme file** checkbox (Claude lanes only — Codex has no slash commands) starts the new lane's terminal run right after creation with `/sg-all:sg-md-writing` as its first message, so the lane opens already writing/refreshing its `CLAUDE.md`/`AGENTS.md` set. It requires the `sg-all` plugin to be installed in Claude Code; without it the session simply reports an unknown command. Leave it unticked to create the lane without starting a run.
+
 Both modes' path field has a **Browse** button next to it, opening a small folder browser (`GET /api/lanes/browse?path=<abs>`) instead of a native OS picker — a browser cannot hand a web page an absolute filesystem path from a native dialog, so this dashboard (local-first, server and browser on the same machine) lists directories server-side instead: click a subfolder to descend, ".." to go up, "Select this folder" to fill the path field. Git repos are marked in the listing.

 ## Lane tool: Claude or Codex
@@ -1,6 +1,6 @@
 # AgentHub — Plugin Marketplace

-Official Claude Code plugins for the Agent Monitor dashboard. The **`agenthub`** plugin _is_ the dashboard — hooks, server, `agenthub` CLI and MCP tools, no checkout required. On top of it, **10 focused plugins** extend Claude Code with skills, agents, slash commands, hooks, and CLI tools for deep analytics, cost guardrails, productivity automation, developer tools, AI-powered insights, session forensics, workflow/fleet intelligence, reliability & SLOs, config & memory governance, and dashboard connectivity.
+Official Claude Code plugins for the Agent Monitor dashboard. The **`agenthub`** plugin _is_ the dashboard — hooks, server and the `agenthub` CLI, no checkout required. (It shipped an MCP server until `c7dbaf2`, which dropped it; the dashboard reads Claude Code's MCP configuration in the config explorer but no longer serves one.) On top of it, **10 focused plugins** extend Claude Code with skills, agents, slash commands, hooks, and CLI tools for deep analytics, cost guardrails, productivity automation, developer tools, AI-powered insights, session forensics, workflow/fleet intelligence, reliability & SLOs, config & memory governance, and dashboard connectivity.

 Every plugin is powered by the local Agent Monitor REST API at `http://localhost:4820`. They are read-only advisors unless a skill explicitly documents a mutating endpoint (and those preview + confirm before acting).

@@ -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 (the API still works, 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
@@ -144,6 +144,9 @@ waits on an install:
   `client-dist` — scoped to this session, same as before this fell back to
   systemd.
 9. **Record state** — `runtime/state.json`.
+10. **Hand over to systemd** — only when a unit of ours already owns the server
+    (see [Who may stop the server](#who-may-stop-the-server)). Deliberately
+    after step 9.

 The first run takes a few minutes — most of it is the UI build, which is what
 makes client-only routes (`http://localhost:4820/run`, and every other page)
@@ -172,11 +175,68 @@ On macOS, Windows, or a Linux box without systemd, nothing changes: the
 server is a detached spawn started fresh on the next `SessionStart` after a
 reboot, same as always.

+### Who may stop the server
+
+**When a `agenthub.service` unit of ours exists, nothing else may stop the
+dashboard.** The bootstrap that performs a self-update is spawned by the
+running server, so it lives inside that server's systemd cgroup. SIGTERM-ing
+the server from there breaks two ways at once:
+
+- the server exits **0**, and the unit's old `Restart=on-failure` read a clean
+  exit as "meant to stop" — so systemd did not bring it back;
+- `KillMode=control-group` (systemd's default) reaps **every** process in the
+  cgroup when the main process exits, including the bootstrap itself — mid-run,
+  before it could repoint the unit at the new plugin root or write
+  `runtime/state.json`.
+
+The result was a dashboard that went down on every self-update and stayed down
+until some later Claude Code session happened to bootstrap again, leaving a
+stale `.bootstrap.lock` and a `state.json` still naming the previous version.
+
+So the order is fixed, and `scripts/systemd-service.js` splits its API to
+enforce it:
+
+| Situation | What the bootstrap does |
+|---|---|
+| A unit of ours owns the server (`unitIsOurs`) | Never stops it. `writeUserService` repoints the unit at the new plugin root **without starting anything**, the rest of the bootstrap runs, state is written, the lock is released — and only then `restartUserService` asks systemd to restart, with `--no-block` so being killed by its own request costs nothing. |
+| No unit, or a foreign one | Unchanged: stop the old server, then `installUserService` (or a detached spawn where there is no systemd). Nothing here is inside a unit's cgroup, so the stop is safe. |
+
+The unit is written with **`Restart=always`**, not `on-failure`: a graceful
+SIGTERM from anything at all would otherwise leave the dashboard down for good.
+An explicit `systemctl stop` — which is what `agenthub service uninstall` and
+the Settings panel do — still stops it.
+
+`agenthub service install` (the checkout path) keeps using `installUserService`:
+it runs from your own shell, outside the unit's cgroup, so it may block and
+start in one step.
+
+**A unit pointing at a retired plugin root repairs itself on the next session.**
+This is the residue an interrupted update leaves behind, and it is invisible
+while the dashboard is up: the server runs fine, every doctor row reads OK, and
+then a reboot starts a cache directory Claude Code deleted during the update —
+so the dashboard never comes back, for a reason nothing recorded. The fast path
+therefore checks it (`unitIsStale`, pure fs — it may not spawn a process on
+every `SessionStart`) and refuses to short-circuit, and the bootstrap rewrites
+the unit.
+
+Repairing the *unit* is not restarting the *server*: when the running server is
+current and healthy, the corrected unit is simply left to take effect at the
+next start (`pendingSystemdRestart = systemdOwned && needsServer`). Restarting
+a working dashboard to fix a file that only matters at boot would be churn the
+user feels for nothing. For the same reason the detached-spawn fallback is
+guarded by `needsServer` — entering that branch for a stale unit alone would
+start a second server onto a port the live one already holds.
+
+`systemdOwned` requires the unit to be **active**, not merely present: an
+installed-but-stopped unit owns nothing, and treating it as the owner would
+skip the stop and then ask systemd to bind an occupied port — a crash loop,
+courtesy of `Restart=always`.
+
 ### Commands

 | 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, **systemd** (`WARN` when the unit names a retired plugin root — the dashboard will not survive a reboot — or when it is installed but stopped; no unit at all is fine), **tmux** (`WARN` when absent — only the run console, `agenthub lanes shell` and session reloads need it), **skill plugins** (see below), 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) |
@@ -268,8 +328,8 @@ not assumed. It does **not**:
 For a clean machine, do all of this yourself:

 ```bash
-# 1. Stop the server. On Linux, check for the systemd unit first — a bare
-#    `kill` just gets restarted by it (Restart=on-failure).
+# 1. Stop the server. On Linux, disable the systemd unit FIRST — the unit is
+#    Restart=always, so a bare `kill` is always undone by systemd.
 systemctl --user disable --now agenthub.service 2>/dev/null
 rm -f ~/.config/systemd/user/agenthub.service && systemctl --user daemon-reload 2>/dev/null
 # Fallback for a detached (non-systemd) server, or if the unit above was absent:
@@ -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.0
+  version: 1.5.9
  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ĩ
@@ -6788,17 +6788,18 @@ paths:
    post:
      tags:
        - Updates
-      summary: Pull, rebuild, and restart the dashboard when fast-forwardable
+      summary: Update this install to the newest release and restart the dashboard
+      description: 'Two modes, chosen by how this copy was installed and never by the request body (which is ignored). checkout: fast-forward onto the release tag, npm run setup, npm run build in production, then self-restart. plugin: the install runs from ~/.claude/plugins/cache/, so a detached helper runs `claude plugin marketplace update`, `claude plugin update -y`, then plugin-bootstrap.js --force from the NEW cache directory, which stops this server and starts the new one. In both modes the response is written before anything stops the process.'
      operationId: applyUpdate
      responses:
        '200':
-          description: Checkout fast-forwarded and rebuilt; the process is about to self-restart
+          description: 'Update is being applied; the process is about to be replaced. mode: "plugin" means the detached plugin chain is running, otherwise the checkout was fast-forwarded and rebuilt in-place'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
-                description: 'Same shape as GET /api/updates/status, plus applied: true.'
+                description: 'Same shape as GET /api/updates/status, plus applied: true. In plugin mode also mode: "plugin" and runtime_dir (where the chain writes its verdict, read back afterwards as last_plugin_update).'
        '409':
          description: Declined - nothing to apply, or the checkout isn't safely fast-forwardable
          content:
@@ -6806,7 +6807,7 @@ paths:
              schema:
                type: object
                additionalProperties: true
-                description: 'applied: false plus reason: "up_to_date" | "not_fast_forwardable".'
+                description: 'applied: false plus reason: "up_to_date" | "not_fast_forwardable" | "plugin_managed". plugin_managed appears here only when a plugin-cache install has nothing to pull: either release_check is "ok" and the published release is already installed, or the release check did not succeed (the message says which — an unknown is never reported as "nothing newer"). When a newer release exists the plugin chain runs and the answer is 200 instead. Run /agenthub-update to force a refresh.'
        '500':
          description: Update apply failed
          content:
@@ -7975,6 +7976,102 @@ paths:
                      pluginJson:
                        name: superpowers
                        version: 1.2.0
+  /api/cc-config/plugins/update-all:
+    get:
+      tags:
+        - CcConfig
+      summary: Progress of the current or last update-all batch
+      description: Read-only. Returns the detached batch worker's on-disk journal from ~/.claude/agenthub/runtime/cc-update-all.json, or `{batch:null}` when no batch has ever run. `status` is `running`|`done`|`partial`|`failed`|`abandoned`; `abandoned` is DERIVED, not stored — a `running` journal older than one hour is reported that way because the worker is detached and a host reboot leaves nobody to write the terminal entry. `partial` means the batch finished with at least one failed step. Malformed or half-written journals return null rather than erroring, since the UI polls this endpoint.
+      operationId: ccConfigGetUpdateAll
+      responses:
+        '200':
+          description: The batch journal, or null.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+              example:
+                batch:
+                  status: partial
+                  started_at: '2026-09-10T08:30:00.000Z'
+                  finished_at: '2026-09-10T08:34:12.000Z'
+                  steps:
+                    - key: marketplaces
+                      label: Update all marketplaces
+                      status: ok
+                    - key: plugin:ponytail@ponytail
+                      label: ponytail@ponytail
+                      status: ok
+                    - key: plugin:vercel@claude-plugins-official
+                      label: vercel@claude-plugins-official
+                      status: failed
+                      error: marketplace unreachable
+                    - key: reload
+                      label: Reload open Claude Code sessions
+                      status: ok
+                      lanes_total: 2
+    post:
+      tags:
+        - CcConfig
+      summary: Update every marketplace and plugin, then reload the open sessions
+      description: 'Mutating. Spawns a DETACHED worker and returns immediately — the response is an acknowledgement, not a result; poll GET on this path to follow it. Order: `claude plugin marketplace update` (no name = all), then `claude plugin update <id> -y` for every installed plugin, then `/reload-plugins` + `/reload-skills` typed into the live lane panes. The plugin this dashboard itself runs from is updated LAST and followed by `plugin-bootstrap.js --force`, which stops this server and starts the replacement — which is why the work cannot happen in the request handler and why the journal lives outside the plugin cache. Plugin ids come from `claude plugin list --json`, never from the body, and the "self" plugin is derived from this server''s own path, so no caller can nominate a different plugin for the restart. Answers 409 EBUSY when a batch is already in flight; the body is ignored apart from an optional `reload:false`.'
+      operationId: ccConfigUpdateAll
+      responses:
+        '200':
+          description: Batch worker spawned.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+              example:
+                ok: true
+                spawned: true
+                runtime_dir: /Users/son/.claude/agenthub/runtime
+                planned: 7
+                self_plugin:
+                  marketplace: sg
+                  plugin: agenthub
+        '409':
+          description: A batch is already running.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/cc-config/reload:
+    post:
+      tags:
+        - CcConfig
+      summary: Tell the open Claude Code sessions to re-read plugins and skills
+      description: 'Types `/reload-plugins` and `/reload-skills` into the dashboard''s live lane panes over `tmux send-keys`. Both commands are scoped BY CLAUDE CODE to the session that runs them, so there is no way to reload a session from outside — typing into a session that is already running is what a human would do, and it is what this does. It spawns no `claude` process: a one-shot `claude -p "/reload-plugins"` would reload only its own short-lived session and leave a junk session behind. Changes nothing on disk, so it does not queue on the CLI mutation chain and emits no `cc_config_changed`. Panes sitting at a shell prompt are skipped (the text would run as a shell command); only `claude` lanes are addressed, since Codex has no such command. Optional body `{kinds:["plugins"|"skills"]}` narrows which commands are sent; unknown kinds are ignored, as the command strings are fixed server-side.'
+      operationId: ccConfigReload
+      responses:
+        '200':
+          description: Commands delivered. `lanes_total` counts only panes running a live claude; zero is a normal outcome, not a failure.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+              example:
+                ok: true
+                commands:
+                  - /reload-plugins
+                  - /reload-skills
+                lanes_total: 1
+                lanes:
+                  - id: agenthub-lane-3
+                    laneId: 3
+                    sent:
+                      - /reload-plugins
+                      - /reload-skills
+        '400':
+          description: '`kinds` was present but not an array.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
  /api/cc-config/mcp:
    get:
      tags:
@@ -1,12 +1,12 @@
 {
  "name": "agenthub",
-  "version": "1.5.0",
+  "version": "1.5.9",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "agenthub",
-      "version": "1.5.0",
+      "version": "1.5.9",
      "hasInstallScript": true,
      "license": "UNLICENSED",
      "dependencies": {
@@ -1,6 +1,6 @@
 {
  "name": "agenthub",
-  "version": "1.5.0",
+  "version": "1.5.9",
  "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, systemd, tmux, UI build
 ---

 Run the diagnostic and report what it found. Do not fix anything unless the user
@@ -31,6 +31,16 @@ 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 systemd` → when it says the unit names a **previous plugin version**,
+  the dashboard is running now but will NOT come back after a reboot. Starting
+  a new Claude Code session repairs it; print the `--force` command from the
+  output as the immediate fix. "installed but not running" just needs
+  `systemctl --user start agenthub`.
+- `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.

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * @file Detached worker for the dashboard's "Update all" button. Runs the whole
+ * batch and writes each step's outcome to `cc-update-all.json` in the runtime
+ * directory as it goes, so the UI can follow along by polling.
+ *
+ * Order, and why:
+ *   1. `claude plugin marketplace update` (no name = every marketplace) — a
+ *      plugin update can only see a version its marketplace already knows about.
+ *   2. `claude plugin update <id> -y` for every installed plugin EXCEPT the one
+ *      the dashboard itself runs from.
+ *   3. That one last, followed by `plugin-bootstrap.js --force` from the NEW
+ *      cache directory — this stops the dashboard server and starts the
+ *      replacement. Anything ordered after it would run while the server is
+ *      down, which is exactly why it is last.
+ *   4. `/reload-plugins` + `/reload-skills` typed into the live lane panes.
+ *      Deliberately after everything: one reload picks up every pending change.
+ *
+ * Spawned detached precisely because step 3 kills its parent. It must never
+ * throw its way out without a terminal journal entry — a silent death would
+ * leave the UI polling a batch that says "running" forever.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync, spawnSync } = require("child_process");
+
+const [, , runtimeDirArg, planJson] = process.argv;
+
+const JOURNAL = path.join(runtimeDirArg || ".", "cc-update-all.json");
+const LOG_FILE = path.join(runtimeDirArg || ".", "cc-update-all.log");
+
+// Ids reach an argv, so they are re-validated here rather than trusted across
+// the process boundary — same reasoning as scripts/plugin-update-helper.js.
+const PLUGIN_SPEC_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*(@[A-Za-z0-9][A-Za-z0-9._-]*)?$/;
+const SAFE_NAME = /^[A-Za-z0-9][\w.-]*$/;
+const SHELL_COMMANDS = new Set(["sh", "bash", "zsh", "fish", "dash", "ksh", "csh", "tcsh"]);
+
+/** @type {{status: string, started_at: string, finished_at?: string, steps: object[]}} */
+const state = { status: "running", started_at: new Date().toISOString(), steps: [] };
+
+function log(line) {
+  try {
+    fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${line}\n`);
+  } catch {
+    /* best effort */
+  }
+}
+
+/** Persist after every transition — the UI polls this file, and the process can
+ *  be SIGTERMed at step 3 without warning. */
+function flush() {
+  try {
+    fs.mkdirSync(runtimeDirArg, { recursive: true });
+    fs.writeFileSync(JOURNAL, JSON.stringify(state, null, 2));
+  } catch {
+    /* best effort */
+  }
+}
+
+function addStep(key, label) {
+  const step = { key, label, status: "running", started_at: new Date().toISOString() };
+  state.steps.push(step);
+  flush();
+  return step;
+}
+
+function finishStep(step, status, extra = {}) {
+  step.status = status;
+  step.finished_at = new Date().toISOString();
+  Object.assign(step, extra);
+  flush();
+}
+
+function resolveClaude() {
+  const candidates = ["claude", path.join(require("os").homedir(), ".local", "bin", "claude")];
+  for (const cmd of candidates) {
+    const probe = spawnSync(cmd, ["--version"], { stdio: "ignore", timeout: 20_000 });
+    if (!probe.error && probe.status === 0) return cmd;
+  }
+  return null;
+}
+
+function run(cmd, args, timeout) {
+  log(`$ ${cmd} ${args.join(" ")}`);
+  const out = execFileSync(cmd, args, {
+    encoding: "utf8",
+    timeout,
+    maxBuffer: 10_000_000,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (out) log(out.trim().slice(0, 2000));
+  return out;
+}
+
+/** Newest cache dir for the self plugin, excluding the one being replaced. */
+function findNewRoot(marketplace, plugin, exclude) {
+  const base = path.join(
+    require("os").homedir(),
+    ".claude",
+    "plugins",
+    "cache",
+    marketplace,
+    plugin
+  );
+  let entries;
+  try {
+    entries = fs.readdirSync(base, { withFileTypes: true }).filter((e) => e.isDirectory());
+  } catch {
+    return null;
+  }
+  const candidates = entries
+    .map((e) => path.join(base, e.name))
+    .filter((p) => p !== exclude)
+    .filter((p) => fs.existsSync(path.join(p, "scripts", "plugin-bootstrap.js")))
+    .map((p) => ({ p, mtime: fs.statSync(p).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  return candidates.length ? candidates[0].p : null;
+}
+
+/**
+ * Type the reload commands into every live `claude` lane pane. Uses tmux
+ * directly rather than the server's lib: by this point the server may be a
+ * different process than the one that started the batch.
+ */
+function reloadPanes() {
+  const step = addStep("reload", "Reload open Claude Code sessions");
+  let names;
+  try {
+    const out = execFileSync("tmux", ["list-sessions", "-F", "#{session_name}"], {
+      encoding: "utf8",
+      timeout: 15_000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    names = out
+      .split("\n")
+      .map((s) => s.trim())
+      .filter((s) => s.startsWith("agenthub-lane-"));
+  } catch {
+    // No tmux server at all means no open sessions — nothing to reload, which
+    // is a normal outcome and not a batch failure.
+    finishStep(step, "skipped", { note: "no tmux sessions are open" });
+    return;
+  }
+
+  const reloaded = [];
+  for (const name of names) {
+    let paneCmd = null;
+    try {
+      paneCmd = execFileSync(
+        "tmux",
+        ["display-message", "-p", "-t", name, "#{pane_current_command}"],
+        { encoding: "utf8", timeout: 15_000, stdio: ["ignore", "pipe", "pipe"] }
+      ).trim();
+    } catch {
+      continue; // pane vanished between listing and probe
+    }
+    // A pane at a shell prompt has no REPL to reload; the text would be run as
+    // a shell command instead.
+    if (SHELL_COMMANDS.has(paneCmd)) continue;
+    try {
+      for (const command of ["/reload-plugins", "/reload-skills"]) {
+        execFileSync("tmux", ["send-keys", "-t", name, "-l", command], { timeout: 15_000 });
+        execFileSync("tmux", ["send-keys", "-t", name, "Enter"], { timeout: 15_000 });
+      }
+      reloaded.push(name);
+    } catch {
+      /* pane died mid-send; the rest of the batch stands */
+    }
+  }
+  finishStep(step, "ok", { lanes: reloaded, lanes_total: reloaded.length });
+}
+
+function main() {
+  let plan;
+  try {
+    plan = JSON.parse(planJson);
+  } catch {
+    state.status = "failed";
+    state.error = "unreadable plan";
+    state.finished_at = new Date().toISOString();
+    flush();
+    return;
+  }
+
+  const claude = resolveClaude();
+  if (!claude) {
+    const step = addStep("resolve_claude", "Locate the claude CLI");
+    finishStep(step, "failed", {
+      error: "the `claude` CLI is not on this server's PATH; run the update from a terminal",
+    });
+    state.status = "failed";
+    state.finished_at = new Date().toISOString();
+    flush();
+    return;
+  }
+
+  // 1. Every marketplace, in one call (no name = all).
+  const mktStep = addStep("marketplaces", "Update all marketplaces");
+  try {
+    run(claude, ["plugin", "marketplace", "update"], 300_000);
+    finishStep(mktStep, "ok");
+  } catch (err) {
+    // A marketplace that can't be refreshed (offline, auth) does not stop the
+    // batch: the plugins may still have updates from the marketplaces that did.
+    finishStep(mktStep, "failed", { error: String(err.stderr || err.message).slice(0, 2000) });
+  }
+
+  const self = plan.selfPlugin;
+  const selfId = self ? `${self.plugin}@${self.marketplace}` : null;
+  const others = (plan.plugins || []).filter((id) => PLUGIN_SPEC_RE.test(id) && id !== selfId);
+
+  // 2. Every other plugin.
+  for (const id of others) {
+    const step = addStep(`plugin:${id}`, id);
+    try {
+      run(claude, ["plugin", "update", id, "-y"], 600_000);
+      finishStep(step, "ok");
+    } catch (err) {
+      finishStep(step, "failed", { error: String(err.stderr || err.message).slice(0, 2000) });
+    }
+  }
+
+  // 3. AgentHub itself, last — its bootstrap stops this server.
+  if (self && SAFE_NAME.test(self.marketplace) && SAFE_NAME.test(self.plugin)) {
+    const step = addStep(`plugin:${selfId}`, `${selfId} (this dashboard)`);
+    try {
+      run(claude, ["plugin", "update", selfId, "-y"], 600_000);
+    } catch (err) {
+      finishStep(step, "failed", { error: String(err.stderr || err.message).slice(0, 2000) });
+      reloadPanes();
+      state.status = "failed";
+      state.finished_at = new Date().toISOString();
+      flush();
+      return;
+    }
+    const newRoot = findNewRoot(self.marketplace, self.plugin, plan.selfRoot);
+    if (!newRoot) {
+      // Nothing newer was published: the running server is correct as-is.
+      finishStep(step, "ok", { note: "already on the newest version; server left running" });
+    } else {
+      // Mark the step done BEFORE the restart: bootstrap SIGTERMs us mid-call,
+      // so a journal entry written afterwards may never be written at all.
+      finishStep(step, "ok", { note: `restarting the dashboard from ${newRoot}`, restarted: true });
+      reloadPanes();
+      state.status = "done";
+      state.finished_at = new Date().toISOString();
+      flush();
+      try {
+        run(
+          process.execPath,
+          [path.join(newRoot, "scripts", "plugin-bootstrap.js"), "--force"],
+          900_000
+        );
+      } catch (err) {
+        log(`bootstrap failed: ${err.message}`);
+        state.status = "failed";
+        state.bootstrap_error = String(err.stderr || err.message).slice(0, 2000);
+        state.note = "the old server was stopped; run /agenthub-update to recover";
+        flush();
+      }
+      return;
+    }
+  }
+
+  // 4. Reload, once, after every update.
+  if (plan.reload !== false) reloadPanes();
+
+  state.status = state.steps.some((s) => s.status === "failed") ? "partial" : "done";
+  state.finished_at = new Date().toISOString();
+  flush();
+}
+
+try {
+  main();
+} catch (err) {
+  // A worker that dies without a terminal entry leaves the UI polling forever.
+  state.status = "failed";
+  state.error = err.message || String(err);
+  state.finished_at = new Date().toISOString();
+  flush();
+}
@@ -107,6 +107,12 @@ function fastPathOk(rt = runtimeDir()) {
  // pipelines drive. Reading one recorded flag keeps this hot path cheap — the
  // actual check (manifest + every user SKILL.md) runs once, in the worker.
  if (!state.skillPluginsSettled) return false;
+  // A live server says nothing about whether it will come back. When our unit
+  // still names a previous plugin cache directory, everything looks healthy
+  // until the next reboot — and then the dashboard is simply gone, from a path
+  // Claude Code deleted long ago. Reading one file is cheap enough for a hot
+  // path; `unitIsStale` deliberately spawns nothing.
+  if (require("./systemd-service").unitIsStale("agenthub", PLUGIN_ROOT)) return false;
  return serverIsLive();
 }

@@ -465,6 +471,11 @@ function bootstrap(rt = runtimeDir(), { force = false } = {}) {
    return "locked";
  }

+  // Declared out here because the restart it guards has to happen in the
+  // `finally`, after the lock is released and the state is on disk: it is the
+  // step that may cost this process its own life.
+  let pendingSystemdRestart = false;
+
  try {
    const wantDeps = depsHash();
    const state = readState(rt) || {};
@@ -504,44 +515,85 @@ function bootstrap(rt = runtimeDir(), { force = false } = {}) {
      log(rt, "built the dashboard UI bundle");
    }

+    const svc = require("./systemd-service");
+    // Who owns the running server decides how it may be retired. A unit of
+    // ours means systemd owns it — and this process is a descendant of that
+    // server, so it sits in the unit's cgroup. SIGTERM-ing the main process
+    // there does two fatal things at once: the clean exit(0) tells systemd
+    // "meant to stop", and `KillMode=control-group` reaps this bootstrap
+    // before it can write state or point the unit at the new cache dir. That
+    // is the bug that left a dashboard dead after every self-update until the
+    // next Claude Code session happened to bootstrap again.
+    // ACTIVE matters, not merely present: a unit of ours that is installed but
+    // stopped owns nothing right now. If a detached server is holding the port
+    // in that state, treating systemd as the owner would skip the stop and then
+    // ask systemd to start a second server onto a bound port — a crash loop,
+    // courtesy of Restart=always.
+    const systemdOwned =
+      svc.systemctlAvailable() && svc.unitIsOurs("agenthub") && svc.unitIsActive("agenthub");
+
    // After a plugin update the running server executes code from a cache
-    // directory Claude Code has already discarded — retire it first.
+    // directory Claude Code has already discarded — retire it first. Only
+    // when nothing else owns its lifecycle; otherwise systemd retires it, in
+    // one restart job, once everything below is durable.
    const movedRoot = force || (state.pluginRoot && state.pluginRoot !== PLUGIN_ROOT);
-    if (movedRoot && stopDashboard()) {
+    if (movedRoot && !systemdOwned && stopDashboard()) {
      log(rt, "stopped the server started from the previous plugin version");
      waitForPortsFree();
    }

-    if (movedRoot || !serverIsLive()) {
-      const svc = require("./systemd-service");
-      const result = svc.systemctlAvailable()
-        ? svc.installUserService({
-            name: "agenthub",
-            description: "AgentHub dashboard server (Claude Code plugin)",
-            workingDir: PLUGIN_ROOT,
-            execStart: `${process.execPath} ${path.join(PLUGIN_ROOT, "server", "index.js")}`,
-            env: {
-              NODE_ENV: "production",
-              NODE_PATH: path.join(rt, "node_modules"),
-              DASHBOARD_CLIENT_DIST: path.join(rt, "client-dist"),
-              // systemd --user units get systemd's own minimal PATH, not the
-              // shell's — forward it so the server can find `claude`/`codex`.
-              PATH: process.env.PATH || "",
-            },
-          })
-        : "unavailable";
+    // Two different needs, deliberately not collapsed. `needsServer` is "the
+    // running process must be replaced"; `unitStale` is "the unit names a cache
+    // directory that is no longer this one", which is invisible until a reboot
+    // and must be repaired even while a perfectly healthy server is up.
+    const needsServer = movedRoot || !serverIsLive();
+    const unitStale = svc.unitIsStale("agenthub", PLUGIN_ROOT);
+    if (needsServer || unitStale) {
+      const unit = {
+        name: "agenthub",
+        description: "AgentHub dashboard server (Claude Code plugin)",
+        workingDir: PLUGIN_ROOT,
+        execStart: `${process.execPath} ${path.join(PLUGIN_ROOT, "server", "index.js")}`,
+        env: {
+          NODE_ENV: "production",
+          NODE_PATH: path.join(rt, "node_modules"),
+          DASHBOARD_CLIENT_DIST: path.join(rt, "client-dist"),
+          // systemd --user units get systemd's own minimal PATH, not the
+          // shell's — forward it so the server can find `claude`/`codex`.
+          PATH: process.env.PATH || "",
+        },
+      };
+      // Two shapes of the same step. When systemd already owns the server the
+      // unit is only REWRITTEN here — pointing at the new plugin root — and
+      // the restart is deferred to `pendingSystemdRestart` below, because
+      // starting it now would kill this process mid-bootstrap. Otherwise
+      // there is no cgroup to be reaped by, and install-and-start is fine.
+      const result = systemdOwned
+        ? svc.writeUserService(unit)
+        : svc.systemctlAvailable()
+          ? svc.installUserService(unit)
+          : "unavailable";
      if (result === "written" || result === "unchanged") {
        if (result === "written") svc.enableLinger();
+        // Only when the RUNNING process has to change. A stale unit beside a
+        // healthy server is now corrected on disk and left to take effect at
+        // the next start — restarting a working dashboard to fix a file that
+        // only matters at boot would be churn the user feels for no reason.
+        pendingSystemdRestart = systemdOwned && needsServer;
        log(
          rt,
-          result === "written"
-            ? "installed a systemd --user service — the dashboard now survives reboots without Claude Code"
-            : "systemd --user service already up to date"
+          result === "unchanged"
+            ? "systemd --user service already up to date"
+            : unitStale && !needsServer
+              ? "repointed the systemd --user service at the current plugin version (it named a retired one)"
+              : "installed a systemd --user service — the dashboard now survives reboots without Claude Code"
        );
-      } else {
+      } else if (needsServer) {
        // No systemd (macOS/Windows/WSL without it), or the unit exists but
        // wasn't ours to touch — same detached-spawn fallback as before,
-        // scoped to this session only.
+        // scoped to this session only. Guarded by `needsServer`: entering this
+        // block for a stale unit alone must never spawn a second server onto
+        // the port the live one already holds.
        const pid = startDashboard(rt);
        log(
          rt,
@@ -572,6 +624,15 @@ function bootstrap(rt = runtimeDir(), { force = false } = {}) {
    return "ok";
  } finally {
    releaseLock(rt);
+    // LAST, and after the lock: systemd stops the old main process to start
+    // the new one, and this process shares its cgroup, so it may not outlive
+    // this call. Everything that had to be durable already is — the state
+    // file is written and the lock is gone, so even being killed here leaves
+    // no debris and no half-recorded bootstrap.
+    if (pendingSystemdRestart) {
+      log(rt, "handing the server over to systemd (restarting the unit)");
+      require("./systemd-service").restartUserService("agenthub");
+    }
  }
 }

@@ -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,8 @@ function diagnose() {
  );

  add(...cliStatus());
+  add(...systemdStatus());
+  add(...tmuxStatus());
  add(...skillPluginStatus());

  add(...dashboardUiStatus(rt));
@@ -218,6 +221,76 @@ function skillPluginStatus() {
  ];
 }

+/**
+ * The failure this row exists for is silent by construction: a unit still
+ * naming a retired plugin cache directory keeps a running dashboard looking
+ * perfectly healthy, and only bites at the next reboot — when the server does
+ * not come back, from a path Claude Code deleted weeks earlier. Nothing else
+ * in this report would show it.
+ *
+ * WARN, never FAIL: the dashboard in front of you is working, and on macOS,
+ * Windows or a Linux box without systemd there is no unit to have an opinion
+ * about.
+ */
+function systemdStatus() {
+  const svc = require("./systemd-service");
+  const unit = svc.unitPath("agenthub");
+
+  if (!svc.unitIsOurs("agenthub")) {
+    if (fs.existsSync(unit)) {
+      return ["warn", "systemd", `${unit} exists but was not written by AgentHub — left untouched`];
+    }
+    return [
+      "ok",
+      "systemd",
+      svc.systemctlAvailable()
+        ? "no unit — the server is started per session (install one with `agenthub service install`)"
+        : "not available on this platform — the server is started per session",
+    ];
+  }
+
+  if (svc.unitIsStale("agenthub", PLUGIN_ROOT)) {
+    return [
+      "warn",
+      "systemd",
+      `${unit} still points at a previous plugin version — the dashboard will NOT come back after a reboot. ` +
+        `Starting a new Claude Code session repairs it; or run: node ${path.join(PLUGIN_ROOT, "scripts", "plugin-bootstrap.js")} --force`,
+    ];
+  }
+
+  if (!svc.unitIsActive("agenthub")) {
+    return [
+      "warn",
+      "systemd",
+      "unit is installed and current but not running — start it with `systemctl --user start agenthub`",
+    ];
+  }
+  return ["ok", "systemd", "unit is current and running — the dashboard survives reboots"];
+}
+
+/**
+ * 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)
@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * @file Detached helper that performs a full plugin-cache update end to end, so
+ * the dashboard's "Update now" button works for an install running out of
+ * `~/.claude/plugins/cache/`. Spawned by `server/lib/plugin-update.js` after the
+ * HTTP response is written, because step 3 SIGTERMs the very server that asked
+ * for the update — an in-process version would kill itself mid-flight.
+ *
+ * The three steps:
+ *   1. `claude plugin marketplace update <marketplace>`
+ *   2. `claude plugin update <plugin>@<marketplace> -y`  → new cache dir appears
+ *   3. `node <newRoot>/scripts/plugin-bootstrap.js --force` → stops the old
+ *      server, waits for the ports, installs deps and starts the new one
+ *
+ * Step 3 is what makes `/reload-plugins` unnecessary here: `plugin-bootstrap.js`
+ * derives its own `PLUGIN_ROOT` from `__dirname`, not from `${CLAUDE_PLUGIN_ROOT}`,
+ * so running it out of the NEW cache directory is enough to move the dashboard
+ * onto the new code. `/reload-plugins` remains needed only for an interactive
+ * Claude Code session to pick up new skills/commands/hooks — a thing no
+ * background process can do on that session's behalf.
+ *
+ * Every outcome, including failure, is recorded in `plugin-update.json` under the
+ * runtime directory (outside the plugin cache, so it survives the swap) and the
+ * new server reports it back as `last_plugin_update`. Without that, a failed
+ * chain would look identical to a slow one: the tab would poll a server that
+ * never comes back and say nothing about why.
+ *
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync, spawnSync } = require("child_process");
+
+const [, , marketplace, plugin, oldRoot, runtimeDirArg] = process.argv;
+
+const RESULT_FILE = path.join(runtimeDirArg, "plugin-update.json");
+const LOG_FILE = path.join(runtimeDirArg, "plugin-update.log");
+
+// Names come from the local cache PATH, never from an HTTP body, but they still
+// reach an argv — so they are re-validated here rather than trusted across the
+// process boundary. Anything else is a bug or tampering, and either way this
+// helper must not run.
+const SAFE_NAME = /^[A-Za-z0-9][\w.-]*$/;
+
+function log(line) {
+  try {
+    fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${line}\n`);
+  } catch {
+    /* best effort */
+  }
+}
+
+function record(result) {
+  try {
+    fs.mkdirSync(runtimeDirArg, { recursive: true });
+    fs.writeFileSync(
+      RESULT_FILE,
+      JSON.stringify({ ...result, finished_at: new Date().toISOString() }, null, 2)
+    );
+  } catch {
+    /* best effort */
+  }
+}
+
+/** Resolve the `claude` CLI. The server is started detached from a hook, so its
+ *  PATH is not the user's login shell PATH — check the documented install
+ *  location before giving up. */
+function resolveClaude() {
+  const candidates = ["claude", path.join(require("os").homedir(), ".local", "bin", "claude")];
+  for (const cmd of candidates) {
+    const probe = spawnSync(cmd, ["--version"], { stdio: "ignore", timeout: 20_000 });
+    if (!probe.error && probe.status === 0) return cmd;
+  }
+  return null;
+}
+
+/** Newest cache directory for this plugin, excluding `exclude`. */
+function findNewRoot(exclude) {
+  const base = path.join(
+    require("os").homedir(),
+    ".claude",
+    "plugins",
+    "cache",
+    marketplace,
+    plugin
+  );
+  let entries;
+  try {
+    entries = fs.readdirSync(base, { withFileTypes: true }).filter((e) => e.isDirectory());
+  } catch {
+    return null;
+  }
+  const candidates = entries
+    .map((e) => path.join(base, e.name))
+    .filter((p) => p !== exclude)
+    // A cache directory without the bootstrap script is not a usable root.
+    .filter((p) => fs.existsSync(path.join(p, "scripts", "plugin-bootstrap.js")))
+    .map((p) => ({ p, mtime: fs.statSync(p).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  return candidates.length ? candidates[0].p : null;
+}
+
+function run(cmd, args, timeout) {
+  log(`$ ${cmd} ${args.join(" ")}`);
+  const out = execFileSync(cmd, args, {
+    encoding: "utf8",
+    timeout,
+    maxBuffer: 10_000_000,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (out) log(out.trim().slice(0, 4000));
+  return out;
+}
+
+function main() {
+  if (!SAFE_NAME.test(marketplace || "") || !SAFE_NAME.test(plugin || "")) {
+    record({ ok: false, step: "validate", error: "unsafe marketplace or plugin name" });
+    return;
+  }
+
+  const claude = resolveClaude();
+  if (!claude) {
+    record({
+      ok: false,
+      step: "resolve_claude",
+      error: "the `claude` CLI is not on this server's PATH; run /agenthub-update instead",
+    });
+    return;
+  }
+
+  try {
+    run(claude, ["plugin", "marketplace", "update", marketplace], 300_000);
+  } catch (err) {
+    record({ ok: false, step: "marketplace_update", error: String(err.stderr || err.message) });
+    return;
+  }
+
+  try {
+    run(claude, ["plugin", "update", `${plugin}@${marketplace}`, "-y"], 600_000);
+  } catch (err) {
+    record({ ok: false, step: "plugin_update", error: String(err.stderr || err.message) });
+    return;
+  }
+
+  const newRoot = findNewRoot(oldRoot);
+  if (!newRoot) {
+    // Already newest: the marketplace had nothing to pull. Not a failure — the
+    // old server is still running and untouched, so say so plainly.
+    record({
+      ok: true,
+      step: "already_current",
+      note: "no new plugin version appeared; the running server was left alone",
+      plugin_root: oldRoot,
+    });
+    return;
+  }
+
+  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.
+    run(
+      process.execPath,
+      [path.join(newRoot, "scripts", "plugin-bootstrap.js"), "--force"],
+      900_000
+    );
+  } catch (err) {
+    record({
+      ok: false,
+      step: "bootstrap",
+      error: String(err.stderr || err.message),
+      plugin_root: newRoot,
+      note: "the old server was stopped; run /agenthub-update to recover",
+    });
+    return;
+  }
+
+  record({ ok: true, step: "done", plugin_root: newRoot });
+}
+
+try {
+  main();
+} catch (err) {
+  // A helper that dies without a verdict is the failure mode this file exists
+  // to prevent, so even an unexpected throw gets recorded.
+  record({ ok: false, step: "unexpected", error: err.message || String(err) });
+}
@@ -26,9 +26,71 @@ function unitPath(name) {
  return path.join(unitDir(), `${name}.service`);
 }

+// Test seam: swap the systemctl implementation so unit tests never talk to a
+// real service manager. Mirrors tmux.js's __setExecImpl/__reset style.
+let execImpl = (args, opts) => spawnSync("systemctl", ["--user", ...args], opts);
+
+function __setExecImpl(fn) {
+  execImpl = fn;
+}
+function __reset() {
+  execImpl = (args, opts) => spawnSync("systemctl", ["--user", ...args], opts);
+}
+
 function systemctlAvailable() {
  if (process.platform !== "linux") return false;
-  return spawnSync("systemctl", ["--user", "--version"], { stdio: "ignore" }).status === 0;
+  return execImpl(["--version"], { stdio: "ignore" }).status === 0;
+}
+
+/**
+ * Is there a unit by this name, and did WE write it? The distinction decides
+ * whether the dashboard may be stopped by hand: a unit of ours means systemd
+ * owns the process, and SIGTERM-ing it out of band is the one thing that must
+ * never happen (see `restartUserService`).
+ */
+function unitIsOurs(name) {
+  try {
+    return fs.readFileSync(unitPath(name), "utf8").includes(MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `Restart=always`, not `on-failure`: a graceful SIGTERM exits 0, which
+ * `on-failure` reads as "meant to stop". One stray kill — or an out-of-band
+ * stop during a plugin self-update — then left the dashboard down until some
+ * later Claude Code session happened to run the bootstrap. An explicit
+ * `systemctl stop` (what uninstall does) still stops it for good.
+ */
+/**
+ * Does our unit still point at `root`? A plugin update moves the install to a
+ * new cache directory, and a unit left naming the old one is a failure that
+ * shows NOTHING until the next reboot — the dashboard simply does not come
+ * back, from a path Claude Code garbage-collected weeks earlier.
+ *
+ * Pure fs, no `systemctl`: this is called from the bootstrap's fast path, which
+ * runs on every single SessionStart and may not spawn a process.
+ *
+ * A foreign unit is never "stale" — it is not ours to judge or rewrite.
+ */
+function unitIsStale(name, root) {
+  let body;
+  try {
+    body = fs.readFileSync(unitPath(name), "utf8");
+  } catch {
+    return false; // no unit at all: nothing to be stale
+  }
+  if (!body.includes(MARKER)) return false;
+  return !body.includes(`\nWorkingDirectory=${root}\n`);
+}
+
+/** Is the unit currently running? Costs a `systemctl` call — never call it
+ *  from the fast path. */
+function unitIsActive(name) {
+  if (!systemctlAvailable()) return false;
+  const res = execImpl(["is-active", `${name}.service`], { encoding: "utf8", stdio: "pipe" });
+  return String(res.stdout || "").trim() === "active";
 }

 function unitContent({ description, workingDir, execStart, env }) {
@@ -44,7 +106,7 @@ After=network.target
 Type=simple
 WorkingDirectory=${workingDir}
 ExecStart=${execStart}
-Restart=on-failure
+Restart=always
 RestartSec=3
 ${envLines}

@@ -54,17 +116,18 @@ WantedBy=default.target
 }

 function systemctl(args) {
-  return spawnSync("systemctl", ["--user", ...args], { stdio: "inherit" });
+  return execImpl(args, { stdio: "inherit" });
 }

 /**
- * Writes (or refreshes) the unit file and enables + starts it. Idempotent:
- * an unchanged unit is left running as-is; a changed one (e.g. a plugin
- * cache path after an update) is reloaded and restarted.
+ * Writes (or refreshes) the unit file and enables it for boot — but starts
+ * nothing. Split out of `installUserService` for the plugin self-update, which
+ * must be able to point the unit at the new cache directory *before* anything
+ * stops the running server, and defer the restart to its very last act.
 *
 * @returns {"written"|"unchanged"|"foreign"|"unavailable"|"failed"}
 */
-function installUserService({ name, description, workingDir, execStart, env = {} }) {
+function writeUserService({ name, description, workingDir, execStart, env = {} }) {
  if (!systemctlAvailable()) return "unavailable";
  const body = unitContent({ description, workingDir, execStart, env });
  const target = unitPath(name);
@@ -72,22 +135,56 @@ function installUserService({ name, description, workingDir, execStart, env = {}
    if (fs.existsSync(target)) {
      const current = fs.readFileSync(target, "utf8");
      if (!current.includes(MARKER)) return "foreign";
-      if (current === body) {
-        systemctl(["enable", "--now", `${name}.service`]);
-        return "unchanged";
-      }
+      if (current === body) return "unchanged";
    }
    fs.mkdirSync(unitDir(), { recursive: true });
    fs.writeFileSync(target, body, "utf8");
    systemctl(["daemon-reload"]);
-    systemctl(["enable", "--now", `${name}.service`]);
-    systemctl(["restart", `${name}.service`]);
+    systemctl(["enable", `${name}.service`]);
    return "written";
  } catch {
    return "failed";
  }
 }

+/**
+ * Ask systemd to restart the unit and do NOT wait for it.
+ *
+ * `--no-block` is the whole point, not a nicety. The caller is the bootstrap
+ * spawned by the running server, so it lives in that server's cgroup; the
+ * moment systemd stops the old main process, `KillMode=control-group` reaps
+ * the caller too. Blocking here means being killed mid-call, which is why the
+ * restart must be the last thing the bootstrap does — by then there is nothing
+ * left to lose.
+ */
+function restartUserService(name) {
+  if (!systemctlAvailable()) return "unavailable";
+  const res = systemctl(["restart", "--no-block", `${name}.service`]);
+  return res.status === 0 ? "restarted" : "failed";
+}
+
+/**
+ * Writes (or refreshes) the unit file and enables + starts it. Idempotent:
+ * an unchanged unit is left running as-is; a changed one (e.g. a plugin
+ * cache path after an update) is reloaded and restarted.
+ *
+ * Safe for `agenthub service install`, which is invoked from a user's own
+ * shell and is therefore not inside the unit's cgroup. The plugin bootstrap
+ * is, and uses `writeUserService` + `restartUserService` instead.
+ *
+ * @returns {"written"|"unchanged"|"foreign"|"unavailable"|"failed"}
+ */
+function installUserService(opts) {
+  const result = writeUserService(opts);
+  if (result === "unchanged") {
+    systemctl(["enable", "--now", `${opts.name}.service`]);
+  } else if (result === "written") {
+    systemctl(["enable", "--now", `${opts.name}.service`]);
+    systemctl(["restart", `${opts.name}.service`]);
+  }
+  return result;
+}
+
 /** @returns {"removed"|"absent"|"foreign"|"unavailable"} */
 function uninstallUserService(name) {
  if (!systemctlAvailable()) return "unavailable";
@@ -110,8 +207,15 @@ function enableLinger() {

 module.exports = {
  systemctlAvailable,
+  unitIsOurs,
+  unitIsStale,
+  unitIsActive,
+  writeUserService,
+  restartUserService,
  installUserService,
  uninstallUserService,
  enableLinger,
  unitPath,
+  __setExecImpl,
+  __reset,
 };
@@ -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/);
  });

@@ -151,10 +151,13 @@ describe("cc-plugin-cli argv construction", () => {
        "disable",
        "demo@m",
      ]);
+      // `-y` is mandatory, not cosmetic: runClaude closes stdin, and the CLI
+      // refuses to update without it whenever stdin is not a TTY.
      assert.deepEqual(argvOf(await cli.pluginUpdate({ spec: "demo@m" })), [
        "plugin",
        "update",
        "demo@m",
+        "-y",
      ]);
      assert.deepEqual(argvOf(await cli.marketplaceRemove({ name: "m" })), [
        "plugin",
@@ -0,0 +1,167 @@
+/**
+ * @file Unit tests for typing `/reload-plugins` / `/reload-skills` into the
+ * live Claude Code lane panes. Uses tmux.js's exec seam, so no real tmux binary
+ * is invoked and no real session is ever typed into.
+ *
+ * The behaviours worth locking down are the ones that would silently do the
+ * wrong thing: sending to a pane sitting at a shell prompt (the slash command
+ * would run as a shell command instead), forwarding a caller-supplied string
+ * into a REPL, and letting one dead pane fail the whole batch. The `tool ===
+ * "claude"` filter is not covered here — it reads a dashboard-runs DB row,
+ * which these stubs do not populate.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { describe, it, beforeEach, after } = require("node:test");
+const assert = require("node:assert/strict");
+const path = require("node:path");
+const fs = require("node:fs");
+const os = require("node:os");
+
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), "cc-reload-test-"));
+process.env.DASHBOARD_DB_PATH = path.join(TMP, "dashboard.db");
+
+const tmux = require("../lib/tmux");
+const { reloadOpenSessions, reloadableLanes } = require("../lib/cc-reload");
+
+after(() => {
+  try {
+    fs.rmSync(TMP, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  } catch {
+    /* best effort */
+  }
+});
+
+/**
+ * Stub tmux so `listRuns()` sees `sessions` and each pane reports the command
+ * given in `panes` (defaulting to a live `claude`).
+ * @returns {any[][]} the recorded argv arrays
+ */
+function stubTmux(sessions, panes = {}) {
+  const calls = [];
+  tmux.__setExecImpl((args) => {
+    calls.push(args);
+    if (args[0] === "list-sessions") return sessions.join("\n");
+    if (args[0] === "has-session") {
+      if (sessions.includes(args[2])) return "";
+      const e = new Error("no such session");
+      e.status = 1;
+      throw e;
+    }
+    if (args[0] === "display-message") {
+      const name = args[3];
+      const cmd = panes[name] ?? "claude";
+      if (cmd === null) {
+        const e = new Error("pane gone");
+        e.status = 1;
+        throw e;
+      }
+      return `${cmd}\n`;
+    }
+    if (args[0] === "send-keys") {
+      if (panes[args[2]] === "__send-fails__") throw new Error("pane died mid-send");
+      return "";
+    }
+    return "";
+  });
+  return calls;
+}
+
+describe("reloadableLanes", () => {
+  beforeEach(() => tmux.__reset());
+
+  it("lists a lane whose pane is running claude", () => {
+    stubTmux(["agenthub-lane-1"]);
+    const lanes = reloadableLanes();
+    assert.equal(lanes.length, 1);
+    assert.equal(lanes[0].id, "agenthub-lane-1");
+    assert.equal(lanes[0].laneId, 1);
+  });
+
+  it("skips a pane sitting at a shell prompt", () => {
+    // The claude process there has exited, so `/reload-plugins` would be typed
+    // at a bash prompt and run as a shell command instead.
+    stubTmux(["agenthub-lane-1"], { "agenthub-lane-1": "bash" });
+    assert.deepEqual(reloadableLanes(), []);
+  });
+
+  it("skips every shell name, not just bash", () => {
+    stubTmux(["agenthub-lane-1", "agenthub-lane-2", "agenthub-lane-3"], {
+      "agenthub-lane-1": "zsh",
+      "agenthub-lane-2": "fish",
+      "agenthub-lane-3": "dash",
+    });
+    assert.deepEqual(reloadableLanes(), []);
+  });
+
+  it("returns nothing when no lane sessions exist at all", () => {
+    stubTmux([]);
+    assert.deepEqual(reloadableLanes(), []);
+  });
+});
+
+describe("reloadOpenSessions", () => {
+  beforeEach(() => tmux.__reset());
+
+  it("types both reload commands, plugins before skills", () => {
+    // Order matters: a skill shipped BY a plugin only exists on disk once the
+    // plugin itself has been reloaded.
+    const calls = stubTmux(["agenthub-lane-7"]);
+    const out = reloadOpenSessions();
+
+    assert.deepEqual(out.commands, ["/reload-plugins", "/reload-skills"]);
+    assert.equal(out.lanes_total, 1);
+    assert.deepEqual(out.lanes[0].sent, ["/reload-plugins", "/reload-skills"]);
+
+    const typed = calls.filter((c) => c[0] === "send-keys" && c[3] === "-l").map((c) => c[4]);
+    assert.deepEqual(typed, ["/reload-plugins", "/reload-skills"]);
+    // Each command must be submitted, or it just sits in the input box.
+    assert.equal(calls.filter((c) => c[0] === "send-keys" && c[3] === "Enter").length, 2);
+  });
+
+  it("honours a narrowed kinds list", () => {
+    const calls = stubTmux(["agenthub-lane-1"]);
+    const out = reloadOpenSessions({ kinds: ["skills"] });
+    assert.deepEqual(out.commands, ["/reload-skills"]);
+    const typed = calls.filter((c) => c[0] === "send-keys" && c[3] === "-l").map((c) => c[4]);
+    assert.deepEqual(typed, ["/reload-skills"]);
+  });
+
+  it("ignores an unknown kind rather than typing it into a REPL", () => {
+    // The command set is fixed in the module; a pane's stdin is not a place to
+    // forward caller-supplied strings.
+    const calls = stubTmux(["agenthub-lane-1"]);
+    const out = reloadOpenSessions({ kinds: ["plugins", "rm -rf /"] });
+    assert.deepEqual(out.commands, ["/reload-plugins"]);
+    const typed = calls.filter((c) => c[0] === "send-keys" && c[3] === "-l").map((c) => c[4]);
+    assert.deepEqual(typed, ["/reload-plugins"]);
+  });
+
+  it("types into several lanes in one call", () => {
+    stubTmux(["agenthub-lane-1", "agenthub-lane-2"]);
+    const out = reloadOpenSessions();
+    assert.equal(out.lanes_total, 2);
+    assert.deepEqual(
+      out.lanes.map((l) => l.laneId).sort((a, b) => a - b),
+      [1, 2]
+    );
+  });
+
+  it("records a pane that dies mid-send without failing the others", () => {
+    stubTmux(["agenthub-lane-1", "agenthub-lane-2"], { "agenthub-lane-1": "__send-fails__" });
+    const out = reloadOpenSessions();
+    const failed = out.lanes.find((l) => l.id === "agenthub-lane-1");
+    const ok = out.lanes.find((l) => l.id === "agenthub-lane-2");
+    assert.match(failed.error, /died mid-send/);
+    assert.deepEqual(failed.sent, [], "nothing was delivered to the dead pane");
+    assert.deepEqual(ok.sent, ["/reload-plugins", "/reload-skills"]);
+    assert.equal(ok.error, undefined);
+  });
+
+  it("reports an empty result instead of throwing when nothing is open", () => {
+    stubTmux([]);
+    const out = reloadOpenSessions();
+    assert.equal(out.lanes_total, 0);
+    assert.deepEqual(out.lanes, []);
+  });
+});
@@ -0,0 +1,165 @@
+/**
+ * @file Unit tests for the "Update all" batch journal — the only channel the UI
+ * has for following a batch that deliberately outlives the server process.
+ *
+ * The batch worker itself is never run to completion here: with a valid plan it
+ * would really update this machine's plugins and stop its dashboard. Only the
+ * paths that must terminate WITHOUT touching anything are exercised against the
+ * real script, because a worker that dies without a terminal journal entry
+ * leaves the UI polling "running" forever — the exact failure this journal
+ * exists to prevent.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { describe, it, before, 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 { execFileSync } = require("node:child_process");
+
+const HELPER = path.join(__dirname, "..", "..", "scripts", "cc-update-all-helper.js");
+
+let tmpDir;
+let prevDataDir;
+
+before(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "cc-update-all-"));
+  prevDataDir = process.env.DASHBOARD_DATA_DIR;
+  // Redirect the runtime dir: these tests must never read or write the real
+  // ~/.claude/agenthub/runtime of whoever runs the suite.
+  process.env.DASHBOARD_DATA_DIR = path.join(tmpDir, "data");
+});
+
+after(() => {
+  if (prevDataDir === undefined) delete process.env.DASHBOARD_DATA_DIR;
+  else process.env.DASHBOARD_DATA_DIR = prevDataDir;
+  try {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {
+    /* best effort */
+  }
+});
+
+const {
+  readUpdateAll,
+  isRunning,
+  journalPath,
+  runtimeDir,
+  STALE_MS,
+} = require("../lib/cc-update-all");
+
+/** Write a journal into a fresh runtime dir and return that dir. */
+function withJournal(name, body) {
+  const rt = path.join(tmpDir, name);
+  fs.mkdirSync(rt, { recursive: true });
+  fs.writeFileSync(
+    path.join(rt, "cc-update-all.json"),
+    typeof body === "string" ? body : JSON.stringify(body)
+  );
+  return rt;
+}
+
+describe("readUpdateAll", () => {
+  it("returns null when no batch has ever run", () => {
+    const rt = path.join(tmpDir, "never");
+    fs.mkdirSync(rt, { recursive: true });
+    assert.equal(readUpdateAll(rt), null);
+  });
+
+  it("returns null for malformed JSON rather than throwing on a poll", () => {
+    assert.equal(readUpdateAll(withJournal("bad", "{nope")), null);
+  });
+
+  it("returns null for JSON without a steps array", () => {
+    // Guards against reporting a half-written file as a batch.
+    assert.equal(readUpdateAll(withJournal("nosteps", { status: "running" })), null);
+  });
+
+  it("reads back a finished batch with its per-step outcomes", () => {
+    const rt = withJournal("done", {
+      status: "partial",
+      started_at: new Date().toISOString(),
+      finished_at: new Date().toISOString(),
+      steps: [
+        { key: "marketplaces", label: "Update all marketplaces", status: "ok" },
+        {
+          key: "plugin:ponytail@ponytail",
+          label: "ponytail@ponytail",
+          status: "failed",
+          error: "boom",
+        },
+      ],
+    });
+    const batch = readUpdateAll(rt);
+    assert.equal(batch.status, "partial");
+    assert.equal(batch.steps.length, 2);
+    assert.equal(batch.steps[1].status, "failed");
+    assert.match(batch.steps[1].error, /boom/);
+  });
+
+  it("reports a fresh running batch as running", () => {
+    const rt = withJournal("fresh", {
+      status: "running",
+      started_at: new Date().toISOString(),
+      steps: [{ key: "marketplaces", status: "running" }],
+    });
+    assert.equal(readUpdateAll(rt).status, "running");
+    assert.equal(isRunning(rt), true);
+  });
+
+  it("reports a long-stale running batch as abandoned, so the button unwedges", () => {
+    // The worker is detached: a reboot leaves nobody to write the terminal
+    // entry, and the UI would otherwise spin forever.
+    const rt = withJournal("stale", {
+      status: "running",
+      started_at: new Date(Date.now() - STALE_MS - 60_000).toISOString(),
+      steps: [{ key: "marketplaces", status: "running" }],
+    });
+    assert.equal(readUpdateAll(rt).status, "abandoned");
+    assert.equal(isRunning(rt), false, "an abandoned batch must not block a new one");
+  });
+
+  it("treats an unparseable started_at as running rather than abandoned", () => {
+    // Better to show a spinner than to start a second concurrent batch against
+    // the same config dir on the strength of a garbled timestamp.
+    const rt = withJournal("nodate", {
+      status: "running",
+      started_at: "not a date",
+      steps: [{ key: "marketplaces", status: "running" }],
+    });
+    assert.equal(readUpdateAll(rt).status, "running");
+  });
+});
+
+describe("runtimeDir / journalPath", () => {
+  it("puts the journal under the data dir's runtime folder, outside any plugin cache", () => {
+    // The batch replaces the plugin cache directory it may be running from, so
+    // a journal stored in there would vanish exactly when it is needed.
+    const p = journalPath();
+    assert.equal(p, path.join(runtimeDir(), "cc-update-all.json"));
+    assert.ok(!p.includes(`${path.sep}cache${path.sep}`), p);
+  });
+});
+
+describe("cc-update-all-helper", () => {
+  it("records a terminal failure for an unreadable plan without running anything", () => {
+    const rt = path.join(tmpDir, "badplan");
+    fs.mkdirSync(rt, { recursive: true });
+
+    execFileSync(process.execPath, [HELPER, rt, "{not json"], {
+      stdio: "ignore",
+      timeout: 30_000,
+    });
+
+    const batch = JSON.parse(fs.readFileSync(path.join(rt, "cc-update-all.json"), "utf8"));
+    assert.equal(batch.status, "failed");
+    assert.match(batch.error, /unreadable plan/);
+    assert.ok(batch.finished_at, "a terminal entry is always timestamped");
+    // Nothing was attempted, so there is no step log and no claude invocation.
+    assert.deepEqual(batch.steps, []);
+    const logPath = path.join(rt, "cc-update-all.log");
+    const log = fs.existsSync(logPath) ? fs.readFileSync(logPath, "utf8") : "";
+    assert.doesNotMatch(log, /claude plugin/, "no claude command may be logged");
+  });
+});
@@ -129,6 +129,71 @@ describe("fast path", () => {
    );
    assert.equal(boot.fastPathOk(RT), false);
  });
+
+  it("is false when the systemd unit still names a retired plugin root", () => {
+    // The one failure a live server hides completely: everything is healthy
+    // until the next reboot, and then the dashboard never comes back because
+    // its unit points into a cache directory Claude Code has deleted. The fast
+    // path has to reject it, or no SessionStart ever repairs it.
+    //
+    // Everything else here is deliberately HEALTHY — including a live server,
+    // without which `fastPathOk` is false anyway and this test would pass
+    // against the unfixed code.
+    const ROOT = path.resolve(__dirname, "..", "..");
+    const pkg = require("../../package.json");
+    const infoPath = path.join(TMP_HOME, ".agenthub.json");
+    const prevHome = process.env.HOME;
+    // HOME first: `unitPath()` resolves against it, and computing the path
+    // before this line points every write in this test at the REAL
+    // ~/.config/systemd/user/agenthub.service — which the cleanup below then
+    // deletes. (Asked how I know.)
+    process.env.HOME = TMP_HOME;
+    const unit = require("../../scripts/systemd-service").unitPath("agenthub");
+    assert.ok(
+      unit.startsWith(TMP_HOME + path.sep),
+      `refusing to touch a unit outside the temp home: ${unit}`
+    );
+
+    const writeUnit = (workingDir) => {
+      fs.mkdirSync(path.dirname(unit), { recursive: true });
+      fs.writeFileSync(
+        unit,
+        "[Unit]\n# agenthub-managed-unit — regenerated on install, do not edit by hand\n" +
+          `[Service]\nWorkingDirectory=${workingDir}\n`,
+        "utf8"
+      );
+    };
+
+    try {
+      fs.mkdirSync(path.join(RT, "node_modules"), { recursive: true });
+      fs.writeFileSync(
+        infoPath,
+        JSON.stringify({ servers: [{ port: 4820, pid: process.pid, startedAt: "x" }] })
+      );
+      boot.writeState(
+        {
+          pluginVersion: pkg.version,
+          depsHash: boot.depsHash(),
+          pluginRoot: ROOT,
+          skillPluginsSettled: "nothing-missing",
+        },
+        RT
+      );
+
+      // Control: a unit naming THIS root is the steady state — fast path taken.
+      writeUnit(ROOT);
+      assert.equal(boot.fastPathOk(RT), true, "a current unit must not block the fast path");
+
+      // The regression: same healthy install, unit left on a retired root.
+      writeUnit("/plugins/cache/agenthub/deadbeef");
+      assert.equal(boot.fastPathOk(RT), false);
+    } finally {
+      fs.rmSync(infoPath, { force: true });
+      fs.rmSync(unit, { force: true });
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
+    }
+  });
 });

 describe("skill-plugin auto-install gate", () => {
@@ -391,6 +456,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,121 @@
+/**
+ * @file Tests the `systemd` row of scripts/plugin-doctor.js.
+ *
+ * The row exists for a failure nothing else in the report can see: a unit still
+ * naming a retired plugin cache directory leaves a running, healthy-looking
+ * dashboard that simply does not come back after the next reboot — it starts a
+ * path Claude Code deleted during the update. Every other row would read OK.
+ *
+ * WARN and never FAIL: the dashboard in front of the user works, and plenty of
+ * machines legitimately have no unit at all.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { describe, it, beforeEach, 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-systemd-"));
+const prevHome = process.env.HOME;
+// Before anything resolves a unit path: `unitPath()` reads HOME, and a path
+// computed against the real one makes these tests rewrite the developer's own
+// ~/.config/systemd/user/agenthub.service.
+process.env.HOME = TMP_HOME;
+process.env.CLAUDE_HOME = path.join(TMP_HOME, ".claude");
+
+const svc = require("../../scripts/systemd-service");
+const { diagnose } = require("../../scripts/plugin-doctor");
+
+const UNIT = svc.unitPath("agenthub");
+const PLUGIN_ROOT = path.resolve(__dirname, "..", "..");
+
+assert.ok(UNIT.startsWith(TMP_HOME + path.sep), `refusing to touch ${UNIT}`);
+
+beforeEach(() => {
+  fs.rmSync(UNIT, { force: true });
+  // Claim systemd exists and the unit is running, so each test varies exactly
+  // one thing: the unit file on disk.
+  svc.__setExecImpl((args) => ({
+    status: 0,
+    stdout: args[0] === "is-active" ? "active\n" : "",
+  }));
+});
+
+after(() => {
+  svc.__reset();
+  if (prevHome === undefined) delete process.env.HOME;
+  else process.env.HOME = prevHome;
+  delete process.env.CLAUDE_HOME;
+  fs.rmSync(TMP_HOME, { recursive: true, force: true });
+});
+
+function row() {
+  const found = diagnose().find((r) => r.label === "systemd");
+  assert.ok(found, "the doctor must always emit a systemd row");
+  return found;
+}
+
+function writeUnit(workingDir) {
+  fs.mkdirSync(path.dirname(UNIT), { recursive: true });
+  fs.writeFileSync(
+    UNIT,
+    "[Unit]\n# agenthub-managed-unit — regenerated on install, do not edit by hand\n" +
+      `[Service]\nWorkingDirectory=${workingDir}\n`,
+    "utf8"
+  );
+}
+
+const linuxOnly = { skip: process.platform !== "linux" ? "systemd is Linux-only" : false };
+
+describe("plugin-doctor: systemd row", linuxOnly, () => {
+  it("warns, never fails, when the unit names a retired plugin root", () => {
+    writeUnit("/plugins/cache/sg/agenthub/deadbeef");
+    const r = row();
+
+    assert.equal(r.level, "warn", "a working dashboard must not fail the doctor run");
+    assert.match(r.detail, /previous plugin version/i);
+    // The consequence is the whole point — a reader who does not know it will
+    // ignore the row.
+    assert.match(r.detail, /reboot/i);
+    assert.match(r.detail, /plugin-bootstrap\.js --force|new Claude Code session/);
+  });
+
+  it("passes when the unit is current and running", () => {
+    writeUnit(PLUGIN_ROOT);
+    const r = row();
+
+    assert.equal(r.level, "ok", r.detail);
+    assert.match(r.detail, /current and running/i);
+  });
+
+  it("warns when the unit is current but stopped", () => {
+    writeUnit(PLUGIN_ROOT);
+    svc.__setExecImpl((args) => ({
+      status: 3,
+      stdout: args[0] === "is-active" ? "inactive\n" : "",
+    }));
+
+    const r = row();
+    assert.equal(r.level, "warn");
+    assert.match(r.detail, /not running/i);
+  });
+
+  it("reports no unit as fine, not as a problem", () => {
+    // A plugin install without `agenthub service install` is a normal setup:
+    // the server is started per session.
+    const r = row();
+    assert.equal(r.level, "ok", r.detail);
+    assert.match(r.detail, /no unit/i);
+  });
+
+  it("warns about a unit it did not write, and never claims it is stale", () => {
+    fs.mkdirSync(path.dirname(UNIT), { recursive: true });
+    fs.writeFileSync(UNIT, "[Service]\nExecStart=/opt/someone-elses-agenthub\n", "utf8");
+
+    const r = row();
+    assert.equal(r.level, "warn");
+    assert.match(r.detail, /not written by AgentHub|left untouched/i);
+  });
+});
@@ -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);
+  });
+});
@@ -0,0 +1,171 @@
+/**
+ * @file Tests for the plugin-cache update chain: the verdict file the detached
+ * helper leaves behind (the only channel through which a failed chain becomes
+ * visible, since the server that would report it is the one being replaced),
+ * and the helper's own name guard.
+ *
+ * The guard test runs the REAL helper, deliberately, with a name that must be
+ * rejected — that is the one execution path safe to exercise, because it must
+ * bail out before invoking the `claude` CLI. No test here ever runs the chain
+ * with a valid name: that would pull a plugin version onto the machine running
+ * the suite and stop the developer's own dashboard.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { describe, it, before, after } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const { readLastPluginUpdate, schedulePluginUpdate, runtimeDir } = require("../lib/plugin-update");
+
+const HELPER = path.join(__dirname, "..", "..", "scripts", "plugin-update-helper.js");
+
+let tmpDir;
+
+before(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pluginupd-"));
+});
+
+after(() => {
+  try {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+});
+
+/** Wait for `file` to exist, polling — the helper is a separate process. */
+function waitForFile(file, timeoutMs = 20_000) {
+  const deadline = Date.now() + timeoutMs;
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  while (!fs.existsSync(file) && Date.now() < deadline) {
+    Atomics.wait(sleeper, 0, 0, 100);
+  }
+  return fs.existsSync(file);
+}
+
+describe("readLastPluginUpdate", () => {
+  it("returns null when the verdict file has never been written", () => {
+    const rt = path.join(tmpDir, "empty");
+    fs.mkdirSync(rt, { recursive: true });
+    assert.equal(readLastPluginUpdate(rt), null);
+  });
+
+  it("returns null for malformed JSON rather than throwing on a status poll", () => {
+    // This is read on EVERY status request for a plugin install, so a corrupt
+    // file must degrade to "nothing to report", never break the endpoint.
+    const rt = path.join(tmpDir, "malformed");
+    fs.mkdirSync(rt, { recursive: true });
+    fs.writeFileSync(path.join(rt, "plugin-update.json"), "{not json");
+    assert.equal(readLastPluginUpdate(rt), null);
+  });
+
+  it("returns null for valid JSON that isn't an object", () => {
+    const rt = path.join(tmpDir, "notobj");
+    fs.mkdirSync(rt, { recursive: true });
+    fs.writeFileSync(path.join(rt, "plugin-update.json"), "42");
+    assert.equal(readLastPluginUpdate(rt), null);
+  });
+
+  it("reads back a recorded failure, including the step it died at", () => {
+    const rt = path.join(tmpDir, "failed");
+    fs.mkdirSync(rt, { recursive: true });
+    fs.writeFileSync(
+      path.join(rt, "plugin-update.json"),
+      JSON.stringify({ ok: false, step: "bootstrap", error: "npm ci exploded" })
+    );
+    const v = readLastPluginUpdate(rt);
+    assert.equal(v.ok, false);
+    assert.equal(v.step, "bootstrap");
+    assert.match(v.error, /npm ci exploded/);
+  });
+});
+
+describe("schedulePluginUpdate", () => {
+  it("clears a stale verdict before spawning, so an old success can't be read as this run's result", () => {
+    // Redirect the runtime dir into the temp tree — this must not touch the
+    // real ~/.claude/agenthub/runtime of whoever runs the suite.
+    const dataDir = path.join(tmpDir, "datadir");
+    const prev = process.env.DASHBOARD_DATA_DIR;
+    process.env.DASHBOARD_DATA_DIR = dataDir;
+
+    // Point it at a root with no helper script: the spawn fails harmlessly
+    // (detached, stdio ignored) and nothing can rewrite the verdict, which is
+    // exactly what makes the clearing observable.
+    const fakeRoot = path.join(tmpDir, "noscripts");
+    fs.mkdirSync(fakeRoot, { recursive: true });
+
+    try {
+      const rt = runtimeDir();
+      fs.mkdirSync(rt, { recursive: true });
+      const verdict = path.join(rt, "plugin-update.json");
+      fs.writeFileSync(verdict, JSON.stringify({ ok: true, step: "done" }));
+
+      const res = schedulePluginUpdate({ marketplace: "sg", plugin: "agenthub", root: fakeRoot });
+      assert.equal(res.spawned, true);
+      assert.equal(res.runtime_dir, rt);
+      assert.equal(fs.existsSync(verdict), false, "stale verdict must be removed");
+      assert.equal(readLastPluginUpdate(rt), null);
+    } finally {
+      if (prev === undefined) delete process.env.DASHBOARD_DATA_DIR;
+      else process.env.DASHBOARD_DATA_DIR = prev;
+    }
+  });
+});
+
+describe("plugin-update-helper name guard", () => {
+  it("refuses a path-traversal marketplace name without invoking the claude CLI", () => {
+    const rt = path.join(tmpDir, "guard");
+    fs.mkdirSync(rt, { recursive: true });
+
+    // Run synchronously and let it record its own verdict. A name like this can
+    // only arrive from a bug or tampering; either way the helper must stop
+    // before it builds an argv for `claude`.
+    execFileSync(process.execPath, [HELPER, "../../../evil", "agenthub", "/nonexistent/root", rt], {
+      stdio: "ignore",
+      timeout: 30_000,
+    });
+
+    assert.ok(waitForFile(path.join(rt, "plugin-update.json")), "helper must record a verdict");
+    const v = JSON.parse(fs.readFileSync(path.join(rt, "plugin-update.json"), "utf8"));
+    assert.equal(v.ok, false);
+    assert.equal(v.step, "validate");
+
+    // And it must not have gotten as far as running a command.
+    const logPath = path.join(rt, "plugin-update.log");
+    const log = fs.existsSync(logPath) ? fs.readFileSync(logPath, "utf8") : "";
+    assert.doesNotMatch(log, /claude plugin/, "no claude invocation may be logged");
+  });
+
+  it("refuses an empty plugin name the same way", () => {
+    const rt = path.join(tmpDir, "guard2");
+    fs.mkdirSync(rt, { recursive: true });
+    execFileSync(process.execPath, [HELPER, "sg", "", "/nonexistent/root", rt], {
+      stdio: "ignore",
+      timeout: 30_000,
+    });
+    const v = JSON.parse(fs.readFileSync(path.join(rt, "plugin-update.json"), "utf8"));
+    assert.equal(v.ok, false);
+    assert.equal(v.step, "validate");
+  });
+
+  it("stamps every verdict with a finish time", () => {
+    // The failure mode this file exists to prevent is a helper that dies
+    // silently: the tab would poll a server that never returns and say nothing.
+    // Only the rejected-name path is exercised — running the helper with a
+    // valid name would really update this machine's plugin and stop its server.
+    const rt = path.join(tmpDir, "guard3");
+    fs.mkdirSync(rt, { recursive: true });
+    execFileSync(process.execPath, [HELPER, "sg", "agent hub", "/nonexistent/root", rt], {
+      stdio: "ignore",
+      timeout: 30_000,
+    });
+    const v = JSON.parse(fs.readFileSync(path.join(rt, "plugin-update.json"), "utf8"));
+    assert.equal(v.step, "validate");
+    assert.ok(v.finished_at, "every verdict is timestamped");
+    assert.ok(!Number.isNaN(Date.parse(v.finished_at)));
+  });
+});
@@ -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) => {
@@ -0,0 +1,194 @@
+/**
+ * @file Tests scripts/systemd-service.js, and specifically the split that
+ * exists because of one incident: the plugin self-update killed the dashboard
+ * and left it dead.
+ *
+ * The bootstrap that performs an update is spawned by the running server, so
+ * it lives in that server's systemd cgroup. The old code SIGTERM-ed the server
+ * from inside that cgroup, which (a) exits 0, and `Restart=on-failure` reads a
+ * clean exit as "meant to stop", and (b) trips `KillMode=control-group`, so
+ * systemd reaped the bootstrap before it could write state or repoint the unit
+ * at the new plugin root. The dashboard then stayed down until some later
+ * Claude Code session happened to bootstrap again.
+ *
+ * Hence: writing the unit must not start anything, restarting must not block,
+ * and a clean exit must no longer be read as "leave it stopped".
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { describe, it, beforeEach, 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-systemd-"));
+const prevHome = process.env.HOME;
+process.env.HOME = TMP_HOME;
+
+const svc = require("../../scripts/systemd-service");
+
+/** Every systemctl invocation this test saw, as flat argv strings. */
+let calls = [];
+
+beforeEach(() => {
+  calls = [];
+  // Each test starts from "no unit on disk" — otherwise a previous test's
+  // write turns the next one's `written` into `unchanged`.
+  fs.rmSync(svc.unitPath("agenthub"), { force: true });
+  svc.__setExecImpl((args) => {
+    // `--version` is the availability probe every entry point runs first, not
+    // an action — recording it would bury the calls these tests are about.
+    if (args[0] !== "--version") calls.push(args.join(" "));
+    return { status: 0 };
+  });
+});
+
+after(() => {
+  svc.__reset();
+  if (prevHome === undefined) delete process.env.HOME;
+  else process.env.HOME = prevHome;
+  fs.rmSync(TMP_HOME, { recursive: true, force: true });
+});
+
+const UNIT = {
+  name: "agenthub",
+  description: "AgentHub dashboard server (Claude Code plugin)",
+  workingDir: "/plugin/root/new",
+  execStart: "/usr/bin/node /plugin/root/new/server/index.js",
+  env: { NODE_ENV: "production" },
+};
+
+function unitFile() {
+  return fs.readFileSync(svc.unitPath("agenthub"), "utf8");
+}
+
+const linuxOnly = { skip: process.platform !== "linux" ? "systemd is Linux-only" : false };
+
+describe("systemd-service — unit content", linuxOnly, () => {
+  it("restarts always, because a graceful SIGTERM exits 0", () => {
+    svc.writeUserService(UNIT);
+    const body = unitFile();
+
+    // `on-failure` is what let one stray kill (or an out-of-band stop during
+    // an update) leave the dashboard down indefinitely.
+    assert.match(body, /^Restart=always$/m);
+    assert.doesNotMatch(body, /^Restart=on-failure$/m);
+  });
+
+  it("carries the ownership marker, so a hand-written unit is never clobbered", () => {
+    svc.writeUserService(UNIT);
+    assert.match(unitFile(), /agenthub-managed-unit/);
+  });
+});
+
+describe("systemd-service — writeUserService", linuxOnly, () => {
+  it("writes and enables the unit but starts NOTHING", () => {
+    // The point of the split: the update must be able to repoint the unit at
+    // the new plugin root while the old server is still serving requests.
+    const result = svc.writeUserService(UNIT);
+
+    assert.equal(result, "written");
+    assert.ok(
+      calls.some((c) => c.startsWith("daemon-reload")),
+      "a rewritten unit must be reloaded"
+    );
+    assert.ok(
+      calls.some((c) => c === "enable agenthub.service"),
+      "it must still be enabled for boot"
+    );
+    assert.ok(
+      !calls.some((c) => c.includes("--now") || c.startsWith("restart") || c.startsWith("start")),
+      `nothing may be started here, got: ${JSON.stringify(calls)}`
+    );
+  });
+
+  it("reports an identical unit as unchanged and touches systemd not at all", () => {
+    svc.writeUserService(UNIT);
+    calls = [];
+
+    assert.equal(svc.writeUserService(UNIT), "unchanged");
+    assert.deepEqual(calls, [], "an unchanged unit needs no systemctl call");
+  });
+
+  it("refuses a unit it did not write", () => {
+    fs.mkdirSync(path.dirname(svc.unitPath("agenthub")), { recursive: true });
+    fs.writeFileSync(svc.unitPath("agenthub"), "[Service]\nExecStart=/opt/mine\n", "utf8");
+
+    assert.equal(svc.writeUserService(UNIT), "foreign");
+    assert.equal(svc.unitIsOurs("agenthub"), false);
+  });
+});
+
+describe("systemd-service — restartUserService", linuxOnly, () => {
+  it("never blocks, because the caller is inside the cgroup being restarted", () => {
+    assert.equal(svc.restartUserService("agenthub"), "restarted");
+    assert.deepEqual(calls, ["restart --no-block agenthub.service"]);
+  });
+
+  it("reports failure rather than throwing when systemctl refuses", () => {
+    // Available, but the restart itself is rejected — distinct from "no
+    // systemd here", which must not be reported as a failure.
+    svc.__setExecImpl((args) => ({ status: args[0] === "--version" ? 0 : 1 }));
+    assert.equal(svc.restartUserService("agenthub"), "failed");
+  });
+});
+
+describe("systemd-service — unitIsStale", linuxOnly, () => {
+  it("is true when the unit names a plugin root that is no longer the current one", () => {
+    // Invisible while the server runs, fatal at the next reboot: the unit
+    // starts a path Claude Code garbage-collected after the update.
+    svc.writeUserService({ ...UNIT, workingDir: "/plugin/root/old" });
+    assert.equal(svc.unitIsStale("agenthub", "/plugin/root/new"), true);
+  });
+
+  it("is false for a unit already naming the current root", () => {
+    svc.writeUserService(UNIT);
+    assert.equal(svc.unitIsStale("agenthub", "/plugin/root/new"), false);
+  });
+
+  it("is false when there is no unit, and for one we do not own", () => {
+    assert.equal(svc.unitIsStale("agenthub", "/plugin/root/new"), false);
+
+    fs.mkdirSync(path.dirname(svc.unitPath("agenthub")), { recursive: true });
+    fs.writeFileSync(svc.unitPath("agenthub"), "[Service]\nWorkingDirectory=/opt/mine\n", "utf8");
+    assert.equal(
+      svc.unitIsStale("agenthub", "/plugin/root/new"),
+      false,
+      "a foreign unit is not ours to call stale, or to rewrite"
+    );
+  });
+
+  it("spawns nothing — the bootstrap fast path runs it on every SessionStart", () => {
+    svc.writeUserService(UNIT);
+    calls = [];
+
+    svc.unitIsStale("agenthub", "/plugin/root/new");
+    assert.deepEqual(calls, []);
+  });
+});
+
+describe("systemd-service — unitIsActive", linuxOnly, () => {
+  it("is true only for `active`", () => {
+    svc.__setExecImpl((args) => ({ status: 0, stdout: args[0] === "is-active" ? "active\n" : "" }));
+    assert.equal(svc.unitIsActive("agenthub"), true);
+
+    svc.__setExecImpl((args) => ({
+      status: 3,
+      stdout: args[0] === "is-active" ? "inactive\n" : "",
+    }));
+    assert.equal(svc.unitIsActive("agenthub"), false);
+  });
+});
+
+describe("systemd-service — unitIsOurs", linuxOnly, () => {
+  it("is false when no unit exists at all", () => {
+    fs.rmSync(svc.unitPath("agenthub"), { force: true });
+    assert.equal(svc.unitIsOurs("agenthub"), false);
+  });
+
+  it("is true for a unit this code wrote", () => {
+    svc.writeUserService(UNIT);
+    assert.equal(svc.unitIsOurs("agenthub"), true);
+  });
+});
@@ -0,0 +1,352 @@
+/**
+ * @file Regression tests for update detection on a plugin-cache install that is
+ * NOT a git clone.
+ *
+ * This is the case 1.5.1 shipped broken. When a marketplace entry declares
+ * `"source": "url"` — this project's own does — Claude Code unpacks an archive,
+ * so the cache directory has no `.git`. `getUpdatesStatus` probed for `.git`
+ * first and returned "Install directory is not a git clone; check for updates
+ * manually", skipping the entire release layer: `update_available` was
+ * permanently false however many releases were published, `plugin_marketplace`
+ * and `plugin_name` were never set, so `POST /api/updates/apply`'s plugin branch
+ * could never fire either. The bug read as "up to date" and was therefore
+ * invisible for as long as the install happened to be current.
+ *
+ * These tests pin the git-free path: the repository URL comes from the
+ * marketplace manifest on disk, version comparison is the only signal, and a
+ * newer release must flip `update_available` to true.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { describe, it, before, after, beforeEach } = 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 {
+  getUpdatesStatus,
+  pluginMarketplaceUrl,
+  fetchReleaseFromUrl,
+  detectPluginInstall,
+} = require("../lib/update-check");
+
+let tmpDir;
+let prevHome;
+
+before(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "upd-nogit-"));
+  prevHome = process.env.CLAUDE_HOME;
+});
+
+after(() => {
+  if (prevHome === undefined) delete process.env.CLAUDE_HOME;
+  else process.env.CLAUDE_HOME = prevHome;
+  try {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {
+    /* best effort */
+  }
+});
+
+/**
+ * Build a fake Claude home containing a marketplace manifest and an
+ * archive-style plugin cache directory — no `.git` anywhere.
+ *
+ * @param {object} opts
+ * @param {any} [opts.source] the marketplace entry's `source` value
+ * @param {string|null} [opts.version] package.json version, or null to omit the file
+ * @param {boolean} [opts.knownMarketplaces] write known_marketplaces.json
+ * @returns {{root: string, home: string}} the plugin cache root
+ */
+function makePluginInstall(name, opts = {}) {
+  const {
+    source = { source: "url", url: "https://forge.example.com/Owner/Repo.git", ref: "main" },
+    version = "1.5.1",
+    knownMarketplaces = true,
+  } = opts;
+
+  const home = path.join(tmpDir, name, ".claude");
+  const mktDir = path.join(home, "plugins", "marketplaces", "sg");
+  const root = path.join(home, "plugins", "cache", "sg", "agenthub", "d4052ed23506");
+  fs.mkdirSync(path.join(mktDir, ".claude-plugin"), { recursive: true });
+  fs.mkdirSync(root, { recursive: true });
+
+  fs.writeFileSync(
+    path.join(mktDir, ".claude-plugin", "marketplace.json"),
+    JSON.stringify({ name: "sg", plugins: [{ name: "agenthub", source }] })
+  );
+  if (knownMarketplaces) {
+    fs.writeFileSync(
+      path.join(home, "plugins", "known_marketplaces.json"),
+      JSON.stringify({ sg: { installLocation: mktDir } })
+    );
+  }
+  if (version !== null) {
+    fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ version }));
+  }
+
+  process.env.CLAUDE_HOME = home;
+  return { root, home };
+}
+
+/** A resolved release, as fetchReleaseFromUrl would return it. */
+function release(tag) {
+  return {
+    ok: true,
+    tag,
+    name: tag.replace(/^v/, ""),
+    url: `https://forge.example.com/Owner/Repo/releases/tag/${tag}`,
+    published_at: "2026-09-10T09:18:48Z",
+    notes: "notes",
+  };
+}
+
+describe("pluginMarketplaceUrl", () => {
+  it("reads the plugin's repository URL out of the marketplace manifest", () => {
+    makePluginInstall("ok");
+    assert.equal(
+      pluginMarketplaceUrl("sg", "agenthub"),
+      "https://forge.example.com/Owner/Repo.git"
+    );
+  });
+
+  it("falls back to the conventional marketplace location when the index is missing", () => {
+    // known_marketplaces.json is an index, not the authority — the manifest is.
+    makePluginInstall("noindex", { knownMarketplaces: false });
+    assert.equal(
+      pluginMarketplaceUrl("sg", "agenthub"),
+      "https://forge.example.com/Owner/Repo.git"
+    );
+  });
+
+  it("accepts a bare URL string as the source", () => {
+    makePluginInstall("strsrc", { source: "https://forge.example.com/Owner/Repo.git" });
+    assert.equal(
+      pluginMarketplaceUrl("sg", "agenthub"),
+      "https://forge.example.com/Owner/Repo.git"
+    );
+  });
+
+  it("returns null for a github owner/repo shorthand rather than guessing a host", () => {
+    // Inventing github.com here would produce an API URL that 404s and a
+    // confidently wrong "up to date".
+    makePluginInstall("ghshort", { source: { source: "github", repo: "Owner/Repo" } });
+    assert.equal(pluginMarketplaceUrl("sg", "agenthub"), null);
+  });
+
+  it("returns null when the manifest has no entry for that plugin", () => {
+    const { home } = makePluginInstall("nomatch");
+    const manifest = path.join(
+      home,
+      "plugins",
+      "marketplaces",
+      "sg",
+      ".claude-plugin",
+      "marketplace.json"
+    );
+    fs.writeFileSync(manifest, JSON.stringify({ name: "sg", plugins: [{ name: "other" }] }));
+    assert.equal(pluginMarketplaceUrl("sg", "agenthub"), null);
+  });
+
+  it("returns null instead of throwing on a malformed manifest", () => {
+    const { home } = makePluginInstall("badjson");
+    const manifest = path.join(
+      home,
+      "plugins",
+      "marketplaces",
+      "sg",
+      ".claude-plugin",
+      "marketplace.json"
+    );
+    fs.writeFileSync(manifest, "{not json");
+    assert.equal(pluginMarketplaceUrl("sg", "agenthub"), null);
+  });
+
+  it("returns null when nothing is on disk at all", () => {
+    process.env.CLAUDE_HOME = path.join(tmpDir, "empty-home");
+    assert.equal(pluginMarketplaceUrl("sg", "agenthub"), null);
+  });
+});
+
+describe("getUpdatesStatus — plugin cache with no .git", () => {
+  it("checks the release API instead of reporting 'not a git clone'", async () => {
+    const { root } = makePluginInstall("regression");
+    assert.equal(fs.existsSync(path.join(root, ".git")), false, "fixture must have no .git");
+
+    const s = await getUpdatesStatus(root, { latestRelease: release("v1.5.1") });
+
+    // The old behaviour: the not-a-git-clone message, everything else absent.
+    // Asserted on the message's CONTENT, not on it being null — a plugin
+    // install now carries its own sentence, and null was only ever a proxy for
+    // "did not fall through here".
+    assert.doesNotMatch(
+      s.message,
+      /not a git clone/i,
+      "must not fall through to the not-a-git-clone payload"
+    );
+    assert.equal(s.release_check, "ok", "the release layer must actually run");
+    assert.equal(s.install_kind, "plugin");
+    assert.equal(s.plugin_marketplace, "sg");
+    assert.equal(s.plugin_name, "agenthub");
+    assert.equal(s.local_version, "1.5.1");
+    assert.equal(s.latest_release, "v1.5.1");
+    assert.equal(s.situation, "plugin_managed");
+  });
+
+  it("reports up-to-date for the RIGHT reason when versions match", async () => {
+    const { root } = makePluginInstall("current");
+    const s = await getUpdatesStatus(root, { latestRelease: release("v1.5.1") });
+    assert.equal(s.update_available, false);
+    // The distinction that matters: false because it looked and found nothing,
+    // not false because it never looked.
+    assert.equal(s.release_check, "ok");
+    assert.equal(s.latest_release, "v1.5.1");
+  });
+
+  it("flips update_available to true when a newer release is published", async () => {
+    // The whole point: before the fix this stayed false forever.
+    const { root } = makePluginInstall("newer");
+    const s = await getUpdatesStatus(root, { latestRelease: release("v1.6.0") });
+    assert.equal(s.update_available, true);
+    assert.equal(s.latest_release, "v1.6.0");
+    // The fields POST /apply's plugin branch requires must all be present, or
+    // the batch can never be spawned.
+    assert.ok(s.plugin_marketplace && s.plugin_name && s.repo_root);
+  });
+
+  it("carries a human-readable message in every outcome, never a null", async () => {
+    // `agenthub update-check` prints `message` as its headline. Null here made
+    // it print the literal "null" on every plugin-cache install — the one kind
+    // that has no commit count to fall back on.
+    const cases = [
+      [makePluginInstall("msg-newer").root, { latestRelease: release("v1.6.0") }, /v1\.6\.0/],
+      [makePluginInstall("msg-current").root, { latestRelease: release("v1.5.0") }, /newest/i],
+      [
+        makePluginInstall("msg-failed").root,
+        { latestRelease: { ok: false, reason: "unreachable" } },
+        /unreachable/,
+      ],
+      [
+        makePluginInstall("msg-noversion", { version: null }).root,
+        { latestRelease: release("v1.6.0") },
+        /no version|cannot be compared/i,
+      ],
+    ];
+    for (const [root, opts, expected] of cases) {
+      const s = await getUpdatesStatus(root, opts);
+      assert.equal(typeof s.message, "string", `message must be a string, got ${s.message}`);
+      assert.match(s.message, expected);
+    }
+  });
+
+  it("does not treat an older published release as an update", async () => {
+    const { root } = makePluginInstall("older");
+    const s = await getUpdatesStatus(root, { latestRelease: release("v1.4.0") });
+    assert.equal(s.update_available, false);
+    // Not a dev_build either: a plugin install is whatever shipped, it cannot
+    // be "ahead" in the way a checkout can.
+    assert.equal(s.dev_build, false);
+  });
+
+  it("never claims to have checked when the release lookup failed", async () => {
+    const { root } = makePluginInstall("unreachable");
+    const s = await getUpdatesStatus(root, {
+      latestRelease: { ok: false, reason: "unreachable" },
+    });
+    assert.equal(s.release_check, "unreachable");
+    assert.equal(s.update_available, false);
+    assert.equal(s.latest_release, null);
+  });
+
+  it("reports no_local_version when package.json cannot be read", async () => {
+    // With nothing to compare against, "up to date" would be a guess.
+    const { root } = makePluginInstall("noversion", { version: null });
+    const s = await getUpdatesStatus(root, { latestRelease: release("v1.6.0") });
+    assert.equal(s.release_check, "no_local_version");
+    assert.equal(s.update_available, false);
+  });
+
+  it("reports no git-derived numbers rather than fabricating them", async () => {
+    const { root } = makePluginInstall("nonumbers");
+    const s = await getUpdatesStatus(root, { latestRelease: release("v1.6.0") });
+    assert.equal(s.git_repo, false, "honest: there is no clone here");
+    assert.equal(s.shallow_clone, false);
+    assert.equal(s.commits_behind_release, null);
+    assert.equal(s.commits_ahead_of_release, null);
+    assert.equal(s.release_sha, null);
+  });
+
+  it("prints the claude plugin commands as the manual fallback", async () => {
+    const { root } = makePluginInstall("manual");
+    const s = await getUpdatesStatus(root, { latestRelease: release("v1.6.0") });
+    assert.match(s.manual_command, /claude plugin marketplace update sg/);
+    assert.match(s.manual_command, /claude plugin update agenthub@sg -y/);
+    // No git command may be suggested for a directory that is not a clone.
+    assert.doesNotMatch(s.manual_command, /git /);
+  });
+
+  it("takes the marketplace and plugin from the path, not from a caller", async () => {
+    const { root } = makePluginInstall("frompath");
+    assert.deepEqual(detectPluginInstall(root), { marketplace: "sg", plugin: "agenthub" });
+  });
+});
+
+describe("fetchReleaseFromUrl", () => {
+  let realFetch;
+  beforeEach(() => {
+    realFetch = global.fetch;
+  });
+
+  it("never touches the network for a URL that isn't owner/repo shaped", async () => {
+    global.fetch = () => {
+      throw new Error("must not fetch for an unusable URL");
+    };
+    try {
+      const res = await fetchReleaseFromUrl("/some/local/path");
+      assert.equal(res.ok, false);
+      assert.equal(res.reason, "remote_not_http");
+    } finally {
+      global.fetch = realFetch;
+    }
+  });
+
+  it("reports no_remote for a missing URL instead of throwing", async () => {
+    global.fetch = () => {
+      throw new Error("must not fetch without a URL");
+    };
+    try {
+      const res = await fetchReleaseFromUrl(null);
+      assert.equal(res.ok, false);
+      assert.equal(res.reason, "no_remote");
+    } finally {
+      global.fetch = realFetch;
+    }
+  });
+
+  it("resolves the tag from a Gitea-shaped releases payload", async () => {
+    global.fetch = async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ tag_name: "v9.9.9", name: "9.9.9", html_url: "u", body: "b" }),
+    });
+    try {
+      const res = await fetchReleaseFromUrl("https://forge.example.com/Owner/Repo.git");
+      assert.equal(res.ok, true);
+      assert.equal(res.tag, "v9.9.9");
+    } finally {
+      global.fetch = realFetch;
+    }
+  });
+
+  it("treats 404 as 'no releases yet', not a fault", async () => {
+    global.fetch = async () => ({ ok: false, status: 404, json: async () => ({}) });
+    try {
+      const res = await fetchReleaseFromUrl("https://forge.example.com/Owner/Repo.git");
+      assert.equal(res.ok, false);
+      assert.equal(res.reason, "no_releases");
+    } finally {
+      global.fetch = realFetch;
+    }
+  });
+});
@@ -0,0 +1,481 @@
+/**
+ * @file Tests for the RELEASE layer of update detection: version comparison,
+ * forge-API URL derivation from a git remote, plugin-cache recognition, and the
+ * shallow-clone guard. Every scenario injects `options.latestRelease` instead of
+ * letting the module reach the network, so the suite is offline and
+ * deterministic; the one case that must NOT be reachable (a local file-path
+ * remote) is asserted to short-circuit before any request is attempted.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { describe, it, before, after } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const {
+  getUpdatesStatus,
+  applyUpdate,
+  compareVersions,
+  releaseApiUrl,
+  detectPluginInstall,
+  fetchLatestRelease,
+  isShallowClone,
+} = require("../lib/update-check");
+
+// Same scrub as update-check.test.js: a parent git hook's GIT_* vars override
+// an explicit cwd, which would point these commands at the real repo.
+const GIT_ENV = { ...process.env };
+for (const k of [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_COMMON_DIR",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_PREFIX",
+  "GIT_NAMESPACE",
+  "GIT_CONFIG_PARAMETERS",
+]) {
+  delete GIT_ENV[k];
+}
+
+const IDENT = ["-c", "user.email=t@t", "-c", "user.name=t"];
+
+function git(cwd, args) {
+  return execFileSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    env: GIT_ENV,
+  }).trim();
+}
+
+/**
+ * A repo with `version` in package.json, one commit, an optional tag, and a
+ * real pushed `origin` so `origin/main` resolves — without remote-tracking
+ * refs, getUpdatesStatus returns its "could not resolve remote ref" payload
+ * and never reaches the release layer under test. The remote is a local bare
+ * path on purpose: `releaseApiUrl` rejects it, so nothing here can touch the
+ * network even if a test forgets to inject `latestRelease`.
+ */
+function makeVersionedRepo(parent, dir, version, tag) {
+  const remote = path.join(parent, `${dir}-remote.git`);
+  fs.mkdirSync(remote, { recursive: true });
+  execFileSync("git", ["-c", "init.defaultBranch=main", "init", "--bare", remote], {
+    stdio: "ignore",
+    env: GIT_ENV,
+  });
+
+  const repo = path.join(parent, dir);
+  fs.mkdirSync(repo, { recursive: true });
+  execFileSync("git", ["-c", "init.defaultBranch=main", "init", repo], {
+    stdio: "ignore",
+    env: GIT_ENV,
+  });
+  fs.writeFileSync(path.join(repo, "package.json"), JSON.stringify({ name: "fx", version }));
+  git(repo, [...IDENT, "add", "."]);
+  git(repo, [...IDENT, "commit", "-m", "release commit"]);
+  if (tag) git(repo, ["tag", tag]);
+  git(repo, ["remote", "add", "origin", remote]);
+  git(repo, ["push", "-u", "origin", "main"]);
+  return repo;
+}
+
+/**
+ * Repoints `origin` at an https URL AFTER the push, so `origin/main` still
+ * resolves (the refs survive a URL change) while `releaseApiUrl` now produces
+ * an endpoint — which is what lets a stubbed `fetch` be reached at all.
+ */
+function setHttpOrigin(repo) {
+  git(repo, ["remote", "set-url", "origin", "https://git.example.com/Owner/Repo.git"]);
+  return repo;
+}
+
+let tmpDir;
+
+before(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "updrel-"));
+});
+
+after(() => {
+  try {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+});
+
+describe("compareVersions", () => {
+  it("orders numeric triples", () => {
+    assert.equal(compareVersions("1.6.0", "1.5.0"), 1);
+    assert.equal(compareVersions("1.5.0", "1.6.0"), -1);
+    assert.equal(compareVersions("1.5.0", "1.5.0"), 0);
+    assert.equal(compareVersions("1.5.1", "1.5.0"), 1);
+    assert.equal(compareVersions("2.0.0", "1.99.99"), 1);
+  });
+
+  it("treats a leading v as noise — this repo tags both ways", () => {
+    // Real tags in this repository: `v1.5.0` and `1.4.6`.
+    assert.equal(compareVersions("v1.5.0", "1.5.0"), 0);
+    assert.equal(compareVersions("v1.5.0", "1.4.6"), 1);
+    assert.equal(compareVersions("1.4.6", "v1.5.0"), -1);
+  });
+
+  it("compares only the release triple, ignoring prerelease/build suffixes", () => {
+    assert.equal(compareVersions("1.5.0-rc.1", "1.5.0"), 0);
+    assert.equal(compareVersions("1.5.0+build9", "1.5.0"), 0);
+  });
+
+  it("treats missing or junk components as zero rather than NaN", () => {
+    assert.equal(compareVersions("2", "1.9.9"), 1);
+    assert.equal(compareVersions("1.5", "1.5.0"), 0);
+    assert.equal(compareVersions("junk", "0.0.0"), 0);
+  });
+});
+
+describe("releaseApiUrl", () => {
+  it("derives the Gitea endpoint from an https remote", () => {
+    assert.equal(
+      releaseApiUrl("https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git"),
+      "https://git.smartgift.io.vn/api/v1/repos/Smartgift-AI/AgentHub/releases/latest"
+    );
+  });
+
+  it("handles a missing .git suffix, a trailing slash, and embedded credentials", () => {
+    const want = "https://git.example.com/api/v1/repos/Owner/Repo/releases/latest";
+    assert.equal(releaseApiUrl("https://git.example.com/Owner/Repo"), want);
+    assert.equal(releaseApiUrl("https://git.example.com/Owner/Repo/"), want);
+    assert.equal(releaseApiUrl("https://oauth2:tok@git.example.com/Owner/Repo.git"), want);
+  });
+
+  it("converts scp-style and ssh:// remotes to the https API host", () => {
+    const want = "https://git.example.com/api/v1/repos/Owner/Repo/releases/latest";
+    assert.equal(releaseApiUrl("git@git.example.com:Owner/Repo.git"), want);
+    assert.equal(releaseApiUrl("ssh://git@git.example.com:2222/Owner/Repo.git"), want);
+  });
+
+  it("returns null for anything not owner/repo shaped — this is what keeps local-path remotes offline", () => {
+    assert.equal(releaseApiUrl("/tmp/some/bare-remote.git"), null);
+    assert.equal(releaseApiUrl("../relative/remote"), null);
+    assert.equal(releaseApiUrl(""), null);
+    // No dot in the host: a bare hostname is not a forge we can call.
+    assert.equal(releaseApiUrl("https://localhost/Owner/Repo.git"), null);
+  });
+});
+
+describe("fetchLatestRelease", () => {
+  it("reports remote_not_http for a local file-path remote, without a network call", async () => {
+    const repo = path.join(tmpDir, "localremote");
+    fs.mkdirSync(repo, { recursive: true });
+    execFileSync("git", ["-c", "init.defaultBranch=main", "init", repo], {
+      stdio: "ignore",
+      env: GIT_ENV,
+    });
+    git(repo, ["remote", "add", "origin", path.join(tmpDir, "nowhere.git")]);
+
+    // Any attempt to reach the network would throw here, since fetch is gone.
+    const realFetch = global.fetch;
+    global.fetch = () => {
+      throw new Error("fetchLatestRelease must not call fetch for a non-http remote");
+    };
+    try {
+      const res = await fetchLatestRelease(repo);
+      assert.equal(res.ok, false);
+      assert.equal(res.reason, "remote_not_http");
+    } finally {
+      global.fetch = realFetch;
+    }
+  });
+
+  it("reports no_remote when the repo has no remotes at all", async () => {
+    const repo = path.join(tmpDir, "noremote");
+    fs.mkdirSync(repo, { recursive: true });
+    execFileSync("git", ["-c", "init.defaultBranch=main", "init", repo], {
+      stdio: "ignore",
+      env: GIT_ENV,
+    });
+    const res = await fetchLatestRelease(repo);
+    assert.equal(res.ok, false);
+    assert.equal(res.reason, "no_remote");
+  });
+
+  it("maps a 404 to no_releases rather than an error — a repo with no releases is normal", async () => {
+    const repo = setHttpOrigin(makeVersionedRepo(tmpDir, "rel404", "1.0.0", null));
+    const realFetch = global.fetch;
+    global.fetch = async () => ({ ok: false, status: 404, json: async () => ({}) });
+    try {
+      const res = await fetchLatestRelease(repo);
+      assert.equal(res.ok, false);
+      assert.equal(res.reason, "no_releases");
+    } finally {
+      global.fetch = realFetch;
+    }
+  });
+
+  it("never throws when the request fails — it resolves to unreachable", async () => {
+    const repo = setHttpOrigin(makeVersionedRepo(tmpDir, "relboom", "1.0.0", null));
+    const realFetch = global.fetch;
+    global.fetch = async () => {
+      throw new Error("ENOTFOUND");
+    };
+    try {
+      const res = await fetchLatestRelease(repo);
+      assert.equal(res.ok, false);
+      assert.equal(res.reason, "unreachable");
+    } finally {
+      global.fetch = realFetch;
+    }
+  });
+
+  it("caps release notes so a huge changelog can't bloat every status poll", async () => {
+    const repo = setHttpOrigin(makeVersionedRepo(tmpDir, "relbig", "1.0.0", null));
+    const realFetch = global.fetch;
+    global.fetch = async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ tag_name: "v9.0.0", body: "x".repeat(10_000) }),
+    });
+    try {
+      const res = await fetchLatestRelease(repo);
+      assert.equal(res.ok, true);
+      assert.equal(res.notes.length, 4000);
+    } finally {
+      global.fetch = realFetch;
+    }
+  });
+});
+
+describe("detectPluginInstall", () => {
+  it("extracts the marketplace and plugin name from a plugin cache path", () => {
+    assert.deepEqual(
+      detectPluginInstall("/home/u/.claude/plugins/cache/sg/agenthub/eb6356932438"),
+      {
+        marketplace: "sg",
+        plugin: "agenthub",
+      }
+    );
+  });
+
+  it("returns null for an ordinary checkout", () => {
+    assert.equal(detectPluginInstall("/home/u/Projects/agenthub"), null);
+    // A directory merely NAMED like the cache is not the cache.
+    assert.equal(detectPluginInstall("/home/u/plugins/cache/sg/agenthub"), null);
+  });
+});
+
+describe("getUpdatesStatus — release drives update_available", () => {
+  it("reports the release as available when its tag outranks the local version", async () => {
+    const repo = makeVersionedRepo(tmpDir, "behind", "1.5.0", "v1.5.0");
+    const status = await getUpdatesStatus(repo, {
+      skipFetch: true,
+      latestRelease: {
+        ok: true,
+        tag: "v1.6.0",
+        name: "1.6.0",
+        url: "u",
+        published_at: null,
+        notes: null,
+      },
+    });
+
+    assert.equal(status.update_available, true);
+    assert.equal(status.situation, "release_available");
+    assert.equal(status.latest_release, "v1.6.0");
+    assert.equal(status.local_version, "1.5.0");
+    assert.equal(status.dev_build, false);
+    // Moves onto the TAG, and fetches tags first so the tag exists locally.
+    assert.match(status.manual_command, /git fetch origin --tags/);
+    assert.match(status.manual_command, /git merge --ff-only v1\.6\.0/);
+  });
+
+  it("is up to date — not a dev build — when local version equals the release and no commits are ahead", async () => {
+    const repo = makeVersionedRepo(tmpDir, "level", "1.5.0", "v1.5.0");
+    const status = await getUpdatesStatus(repo, {
+      skipFetch: true,
+      latestRelease: {
+        ok: true,
+        tag: "v1.5.0",
+        name: "1.5.0",
+        url: null,
+        published_at: null,
+        notes: null,
+      },
+    });
+
+    assert.equal(status.update_available, false);
+    assert.equal(status.dev_build, false);
+    assert.equal(status.commits_ahead_of_release, 0);
+    assert.equal(status.commits_behind_release, 0);
+  });
+
+  it("reports dev_build with a commit count when the checkout is ahead of the newest release", async () => {
+    const repo = makeVersionedRepo(tmpDir, "ahead", "1.5.0", "v1.5.0");
+    fs.writeFileSync(path.join(repo, "extra.txt"), "unreleased work\n");
+    git(repo, [...IDENT, "add", "."]);
+    git(repo, [...IDENT, "commit", "-m", "unreleased"]);
+
+    const status = await getUpdatesStatus(repo, {
+      skipFetch: true,
+      latestRelease: {
+        ok: true,
+        tag: "v1.5.0",
+        name: "1.5.0",
+        url: null,
+        published_at: null,
+        notes: null,
+      },
+    });
+
+    assert.equal(status.update_available, false, "a dev build is not an available update");
+    assert.equal(status.dev_build, true);
+    assert.equal(status.commits_ahead_of_release, 1);
+    assert.equal(status.commits_behind_release, 0);
+    assert.match(status.message, /Dev build: 1 commit/);
+  });
+
+  it("does not call a release ahead when the local version already outranks it", async () => {
+    const repo = makeVersionedRepo(tmpDir, "newer", "2.0.0", "v2.0.0");
+    const status = await getUpdatesStatus(repo, {
+      skipFetch: true,
+      latestRelease: {
+        ok: true,
+        tag: "v1.5.0",
+        name: "1.5.0",
+        url: null,
+        published_at: null,
+        notes: null,
+      },
+    });
+    assert.equal(status.update_available, false);
+  });
+
+  it("records why the release lookup failed and falls back to the commit count", async () => {
+    const repo = makeVersionedRepo(tmpDir, "fallback", "1.5.0", "v1.5.0");
+    const status = await getUpdatesStatus(repo, {
+      skipFetch: true,
+      latestRelease: { ok: false, reason: "unreachable" },
+    });
+
+    assert.equal(status.release_check, "unreachable");
+    assert.equal(status.latest_release, null);
+    assert.equal(status.dev_build, false);
+    // Not "up to date" by silence: the reason is on the payload for the UI.
+    assert.match(status.message, /tip of the canonical default branch|commit\(s\) on/);
+  });
+});
+
+describe("getUpdatesStatus — shallow clone", () => {
+  it("returns null commit distances and never claims a dev build", async () => {
+    // The Claude Code plugin cache is a depth-1 clone. Before this guard it
+    // reported "306 behind AND 1 ahead" of a tag that is a plain ancestor.
+    const origin = makeVersionedRepo(tmpDir, "deep-origin", "1.5.0", "v1.5.0");
+    for (let i = 0; i < 3; i += 1) {
+      fs.writeFileSync(path.join(origin, `f${i}.txt`), `${i}\n`);
+      git(origin, [...IDENT, "add", "."]);
+      git(origin, [...IDENT, "commit", "-m", `c${i}`]);
+    }
+    const shallow = path.join(tmpDir, "shallow-clone");
+    execFileSync("git", ["clone", "--depth", "1", `file://${origin}`, shallow], {
+      stdio: "ignore",
+      env: GIT_ENV,
+    });
+
+    assert.equal(await isShallowClone(shallow), true, "fixture must actually be shallow");
+    assert.equal(await isShallowClone(origin), false);
+
+    const status = await getUpdatesStatus(shallow, {
+      skipFetch: true,
+      latestRelease: {
+        ok: true,
+        tag: "v1.5.0",
+        name: "1.5.0",
+        url: null,
+        published_at: null,
+        notes: null,
+      },
+    });
+
+    assert.equal(status.shallow_clone, true);
+    assert.equal(status.commits_behind_release, null);
+    assert.equal(status.commits_ahead_of_release, null);
+    assert.equal(status.dev_build, false);
+    // Version compare still works, and it is the only signal used here.
+    assert.equal(status.update_available, false);
+  });
+
+  it("still reports a newer release on a shallow clone, from versions alone", async () => {
+    const origin = makeVersionedRepo(tmpDir, "deep-origin2", "1.5.0", "v1.5.0");
+    const shallow = path.join(tmpDir, "shallow-clone2");
+    execFileSync("git", ["clone", "--depth", "1", `file://${origin}`, shallow], {
+      stdio: "ignore",
+      env: GIT_ENV,
+    });
+
+    const status = await getUpdatesStatus(shallow, {
+      skipFetch: true,
+      latestRelease: {
+        ok: true,
+        tag: "v1.7.0",
+        name: "1.7.0",
+        url: null,
+        published_at: null,
+        notes: null,
+      },
+    });
+
+    assert.equal(status.shallow_clone, true);
+    assert.equal(status.update_available, true);
+    assert.equal(status.commits_behind_release, null);
+  });
+});
+
+describe("applyUpdate — plugin cache is Claude Code's to replace", () => {
+  it("refuses with reason plugin_managed and touches nothing", async () => {
+    // Build the repo underneath a path that looks like the plugin cache, since
+    // that path IS the signal (see detectPluginInstall).
+    const cacheRoot = path.join(tmpDir, "home", ".claude", "plugins", "cache", "sg", "agenthub");
+    fs.mkdirSync(cacheRoot, { recursive: true });
+    const repo = setHttpOrigin(makeVersionedRepo(cacheRoot, "abc123def456", "1.5.0", "v1.5.0"));
+    const headBefore = git(repo, ["rev-parse", "HEAD"]);
+
+    const status = await getUpdatesStatus(repo, {
+      skipFetch: true,
+      latestRelease: {
+        ok: true,
+        tag: "v1.9.0",
+        name: "1.9.0",
+        url: null,
+        published_at: null,
+        notes: null,
+      },
+    });
+    assert.equal(status.install_kind, "plugin");
+    assert.equal(status.plugin_marketplace, "sg");
+    assert.equal(status.situation, "plugin_managed");
+    assert.equal(status.update_available, true);
+    // The printed commands are Claude Code's own update path, not git.
+    assert.match(status.manual_command, /claude plugin marketplace update sg/);
+    assert.match(status.manual_command, /claude plugin update agenthub@sg -y/);
+    assert.match(status.situation_note, /reload-plugins/);
+
+    // applyUpdate hits the network-free path only because it re-reads status;
+    // stub fetch so the refusal is decided by the path, not by connectivity.
+    const realFetch = global.fetch;
+    global.fetch = async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ tag_name: "v1.9.0" }),
+    });
+    try {
+      const result = await applyUpdate(repo);
+      assert.equal(result.applied, false);
+      assert.equal(result.reason, "plugin_managed");
+    } finally {
+      global.fetch = realFetch;
+    }
+    assert.equal(git(repo, ["rev-parse", "HEAD"]), headBefore, "HEAD must be untouched");
+  });
+});
@@ -95,12 +95,22 @@ describe("POST /api/updates/apply", () => {
    // The test repo checkout has no update pending (or isn't fast-forwardable
    // from a bare test run), so this exercises the decline path only — it must
    // never touch the working tree or process in a test run.
+    //
+    // The `plugin_managed` branch cannot fire from a checkout: it additionally
+    // requires plugin_marketplace/plugin_name, which only a path under
+    // ~/.claude/plugins/cache/ produces. A suite run from such a copy would get
+    // 200 + mode:"plugin" and spawn the update chain, so guard on the shape
+    // rather than the status code alone.
    const res = await httpFetch("/api/updates/apply", {
      method: "POST",
      body: "{}",
    });
+    assert.equal(res.body.install_kind, "checkout", "suite must run from a git checkout");
    assert.equal(res.status, 409);
    assert.equal(res.body.applied, false);
-    assert.ok(["up_to_date", "not_fast_forwardable"].includes(res.body.reason));
+    assert.ok(
+      ["up_to_date", "not_fast_forwardable", "plugin_managed"].includes(res.body.reason),
+      `unexpected reason: ${res.body.reason}`
+    );
  });
 });
@@ -226,7 +226,10 @@ async function pluginDisable({ spec }) {

 async function pluginUpdate({ spec }) {
  const s = assertPluginSpec(spec);
-  return serialize(() => runClaude(["plugin", "update", s]));
+  // `-y` for the same reason as pluginInstall: the CLI requires it whenever
+  // stdin is not a TTY (runClaude closes stdin), and without it an update whose
+  // marketplace declares an install command fails on a prompt nobody can answer.
+  return serialize(() => runClaude(["plugin", "update", s, "-y"]));
 }

 /**
@@ -0,0 +1,102 @@
+/**
+ * @file Types `/reload-plugins` and `/reload-skills` into the Claude Code
+ * sessions the dashboard already has open, so a plugin or skill update takes
+ * effect without the user switching to a terminal.
+ *
+ * Both commands are, by Claude Code's own definition, scoped to the session
+ * that runs them — `/reload-plugins` "activates pending plugin changes in the
+ * current session", `/reload-skills` "picks up skills added or changed on disk
+ * during this session". There is therefore NO way to reload a session from the
+ * outside, and no background process can do it on a session's behalf. What a
+ * dashboard CAN do is what a human would: type the command into a session that
+ * is already running. Every lane pane is a tmux session (`agenthub-lane-<id>`),
+ * so `tmux send-keys` reaches a live REPL's stdin directly.
+ *
+ * This deliberately never spawns a `claude` process. A one-shot
+ * `claude -p "/reload-plugins"` would reload only its own short-lived session
+ * and then exit — no effect on anything the user is using — while still costing
+ * an API round-trip and leaving a junk session in the dashboard's own history.
+ * Reusing live panes means this module creates no sessions at all.
+ *
+ * Only `claude` lanes are addressed: Codex has no such command, and typing a
+ * slash command into a Codex pane would land as literal prompt text.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const tmux = require("./tmux");
+const { listRuns } = require("./pty-run");
+
+/** Shell process names — a pane sitting at one of these has no REPL to reload. */
+const SHELL_COMMANDS = new Set(["sh", "bash", "zsh", "fish", "dash", "ksh", "csh", "tcsh"]);
+
+/** The only commands this module is ever allowed to type. Not caller-supplied:
+ *  a pane's stdin is an arbitrary-code boundary, so the set is fixed here. */
+const RELOAD_COMMANDS = {
+  plugins: "/reload-plugins",
+  skills: "/reload-skills",
+};
+
+/**
+ * Live `claude` panes that can accept a slash command right now.
+ *
+ * A pane whose `pane_current_command` is a shell is excluded: the `claude`
+ * process there has exited (or never started), so the text would be typed at a
+ * bash prompt and run as a shell command instead — `/reload-plugins` would come
+ * back as "No such file or directory".
+ *
+ * @returns {{id: string, laneId: number|null, paneCommand: string|null}[]}
+ */
+function reloadableLanes() {
+  const out = [];
+  for (const run of listRuns()) {
+    if (run.status !== "running") continue;
+    if (run.tool !== "claude") continue;
+    const cmd = tmux.paneCommand(run.id);
+    if (SHELL_COMMANDS.has(cmd || "")) continue;
+    out.push({ id: run.id, laneId: run.laneId, paneCommand: cmd });
+  }
+  return out;
+}
+
+/**
+ * Type the requested reload commands into every live `claude` pane.
+ *
+ * Sends to a pane even when its agent is mid-turn: tmux queues the keystrokes
+ * into the REPL's input buffer, so the command lands when the turn ends rather
+ * than being lost. That is a deliberate choice — a reload that arrives late is
+ * still a reload, whereas skipping busy panes silently leaves exactly the
+ * sessions the user is actually working in running stale code.
+ *
+ * Never throws: one unreachable pane (killed between the listing and the send)
+ * must not fail a batch that updated everything else successfully.
+ *
+ * @param {{kinds?: ("plugins"|"skills")[]}} [options] which commands to send;
+ *   defaults to both, plugins first (a skill shipped BY a plugin only exists on
+ *   disk once the plugin has been reloaded).
+ * @returns {{lanes: {id: string, laneId: number|null, sent: string[], error?: string}[],
+ *   commands: string[], lanes_total: number}}
+ */
+function reloadOpenSessions(options = {}) {
+  const kinds = (options.kinds || ["plugins", "skills"]).filter((k) => k in RELOAD_COMMANDS);
+  const commands = kinds.map((k) => RELOAD_COMMANDS[k]);
+  const lanes = [];
+
+  for (const lane of reloadableLanes()) {
+    const sent = [];
+    let error;
+    for (const command of commands) {
+      try {
+        tmux.sendText(lane.id, command);
+        sent.push(command);
+      } catch (err) {
+        error = err.message || String(err);
+        break; // the pane is gone; the next command would fail identically
+      }
+    }
+    lanes.push({ id: lane.id, laneId: lane.laneId, sent, ...(error ? { error } : {}) });
+  }
+
+  return { commands, lanes, lanes_total: lanes.length };
+}
+
+module.exports = { reloadOpenSessions, reloadableLanes, RELOAD_COMMANDS, SHELL_COMMANDS };
@@ -0,0 +1,111 @@
+/**
+ * @file Starts and reports on the "Update all" batch: every registered
+ * marketplace, then every installed plugin, then a reload of the Claude Code
+ * sessions the dashboard has open.
+ *
+ * Why a detached worker with an on-disk journal instead of a plain request
+ * handler: the batch includes AgentHub ITSELF when the dashboard runs from the
+ * plugin cache. Updating that plugin ends in `plugin-bootstrap.js --force`,
+ * which SIGTERMs this very server, so an in-process loop would die partway
+ * through with the remaining steps unrun and no way to report anything. The
+ * worker outlives the swap, keeps going, and writes each step's outcome to
+ * `cc-update-all.json` under the runtime directory — outside the plugin cache,
+ * which the update replaces — so whichever server is alive can serve progress
+ * from it. AgentHub is ordered LAST for the same reason: every other plugin is
+ * already done by the time the restart happens.
+ *
+ * The reload step comes after all updates, not per-plugin, because that is what
+ * "update everything, then reload" means for a session: one `/reload-plugins`
+ * picks up every pending change at once, where N of them would just re-scan the
+ * same directory N times. A single-plugin update reloads immediately instead —
+ * see the `reload` flag on `POST /api/cc-config/plugins/action`.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+const { getDataDir } = require("./claude-home");
+
+const JOURNAL_NAME = "cc-update-all.json";
+/** A batch still "running" after this long is treated as abandoned, so a worker
+ *  killed by a reboot can't wedge the button forever. */
+const STALE_MS = 60 * 60 * 1000;
+
+function runtimeDir() {
+  return path.join(getDataDir(), "runtime");
+}
+
+function journalPath(rt = runtimeDir()) {
+  return path.join(rt, JOURNAL_NAME);
+}
+
+/**
+ * Current (or last) batch state, or null when none has ever run.
+ *
+ * A `running` journal older than `STALE_MS` is reported as `abandoned` rather
+ * than `running`: the worker is detached, so a host reboot leaves no one to
+ * write the terminal entry and the UI would otherwise show a spinner forever.
+ *
+ * @returns {{status: string, steps: object[], started_at?: string,
+ *   finished_at?: string} | null}
+ */
+function readUpdateAll(rt = runtimeDir()) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(journalPath(rt), "utf8"));
+  } catch {
+    return null; // never run, unreadable, or malformed — all "nothing to report"
+  }
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.steps)) return null;
+  if (parsed.status === "running") {
+    const started = Date.parse(parsed.started_at || "");
+    if (Number.isFinite(started) && Date.now() - started > STALE_MS) {
+      return { ...parsed, status: "abandoned" };
+    }
+  }
+  return parsed;
+}
+
+/** True when a batch is in flight — used to refuse a concurrent start rather
+ *  than run two `claude plugin update` chains over the same config dir. */
+function isRunning(rt = runtimeDir()) {
+  return readUpdateAll(rt)?.status === "running";
+}
+
+/**
+ * Spawn the detached batch worker.
+ *
+ * The caller must have written its HTTP response first: when `selfPlugin` is
+ * set, this process is going to be stopped before the batch finishes.
+ *
+ * @param {{plugins: string[], selfPlugin: {marketplace: string, plugin: string}|null,
+ *   selfRoot: string|null, reload: boolean}} plan
+ *   `plugins` are `name@marketplace` ids, already validated by the caller.
+ * @returns {{spawned: true, runtime_dir: string}}
+ */
+function startUpdateAll(plan) {
+  const rt = runtimeDir();
+  fs.mkdirSync(rt, { recursive: true });
+  // Clear the previous batch so a stale terminal state is never read as this
+  // run's progress in the window before the worker writes its first entry.
+  try {
+    fs.rmSync(journalPath(rt), { force: true });
+  } catch {
+    /* best effort */
+  }
+
+  const helper = path.join(__dirname, "..", "..", "scripts", "cc-update-all-helper.js");
+  const child = spawn(process.execPath, [helper, rt, JSON.stringify(plan)], {
+    // Never the plugin root: when selfPlugin is set that directory is replaced
+    // mid-run, and a cwd inside a replaced directory can wedge the process.
+    cwd: rt,
+    detached: true,
+    stdio: "ignore",
+    env: process.env,
+  });
+  child.unref();
+  return { spawned: true, runtime_dir: rt };
+}
+
+module.exports = { startUpdateAll, readUpdateAll, isRunning, runtimeDir, journalPath, STALE_MS };
@@ -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}`);
  }
 }

@@ -0,0 +1,89 @@
+/**
+ * @file Launches and reports on the plugin-cache update chain — the path that
+ * makes "Update now" work for an install running out of
+ * `~/.claude/plugins/cache/` instead of a plain git checkout.
+ *
+ * All the work happens in the DETACHED `scripts/plugin-update-helper.js`, for a
+ * structural reason: its last step runs `plugin-bootstrap.js --force`, which
+ * SIGTERMs the dashboard server that asked for the update. An in-process
+ * version would kill itself halfway through and leave no server to finish the
+ * job or report what happened. Same split as `self-restart.js`, one step
+ * further: there the helper only waits and respawns, here it also pulls the new
+ * plugin version first.
+ *
+ * This module deliberately does NOT run `/reload-plugins`. That is a Claude Code
+ * REPL action, and it re-resolves plugins only for the session that runs it — a
+ * background process cannot perform it on an interactive session's behalf, and a
+ * throwaway one-shot session would reload its own plugin view and exit. The
+ * dashboard does not need it: `plugin-bootstrap.js` derives `PLUGIN_ROOT` from
+ * its own `__dirname`, so being executed out of the new cache directory is
+ * sufficient to move the server onto the new code. Only new
+ * skills/commands/hooks in an already-open Claude Code session still require the
+ * user to reload.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+const { getDataDir } = require("./claude-home");
+
+/** Runtime directory the helper writes its verdict into. Outside the plugin
+ *  cache on purpose — that directory is replaced by the update itself. */
+function runtimeDir() {
+  return path.join(getDataDir(), "runtime");
+}
+
+/**
+ * Result of the most recent plugin update attempt, or null when there has never
+ * been one. Surfaced on the update-status payload as `last_plugin_update` so a
+ * failed chain is visible instead of looking like a server that is merely slow
+ * to come back.
+ *
+ * @returns {{ok: boolean, step: string, error?: string, note?: string,
+ *   plugin_root?: string, finished_at?: string} | null}
+ */
+function readLastPluginUpdate(rt = runtimeDir()) {
+  try {
+    const raw = fs.readFileSync(path.join(rt, "plugin-update.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null; // never run, unreadable, or malformed — all "nothing to report"
+  }
+}
+
+/**
+ * Spawn the detached update chain. Returns immediately; the caller must have
+ * already written its HTTP response, because this process is about to be
+ * stopped by the helper's final step.
+ *
+ * Clears any previous verdict first, so a stale success can never be read back
+ * as the outcome of THIS run while the chain is still in flight.
+ *
+ * @param {{marketplace: string, plugin: string, root: string}} install
+ * @returns {{spawned: true, runtime_dir: string}}
+ */
+function schedulePluginUpdate({ marketplace, plugin, root }) {
+  const rt = runtimeDir();
+  try {
+    fs.mkdirSync(rt, { recursive: true });
+    fs.rmSync(path.join(rt, "plugin-update.json"), { force: true });
+  } catch {
+    /* best effort — a stale verdict is better than failing the update */
+  }
+
+  const helper = path.join(root, "scripts", "plugin-update-helper.js");
+  const child = spawn(process.execPath, [helper, marketplace, plugin, root, rt], {
+    // cwd is the runtime dir, NOT the plugin root: the root is about to be
+    // superseded, and a cwd inside a replaced directory can wedge the process.
+    cwd: rt,
+    detached: true,
+    stdio: "ignore",
+    env: process.env,
+  });
+  child.unref();
+  return { spawned: true, runtime_dir: rt };
+}
+
+module.exports = { schedulePluginUpdate, readLastPluginUpdate, runtimeDir };
@@ -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);
 }
@@ -1,15 +1,42 @@
 /**
- * @file Detects whether the dashboard git checkout is behind the canonical
- * remote default branch (origin/master or origin/main on a
- * direct clone) after a non-destructive fetch. Branch- and fork-aware:
- * picks the right remote, recognises feature-branch checkouts, and shapes
- * manual_command so it actually closes the gap for the user's situation.
+ * @file Detects whether this install is behind the newest published RELEASE of
+ * its own repository, and can fast-forward onto that release tag on request.
+ *
+ * The release is read straight from the forge's REST API
+ * (`/api/v1/repos/<owner>/<repo>/releases/latest` — the Gitea/Forgejo shape
+ * this project is hosted on), so the check needs no hardcoded host and no
+ * credentials for a public repo. When no release can be read — a non-HTTP
+ * remote, an offline machine, a repo with no releases yet — detection degrades
+ * to the original commit-count comparison against the canonical default branch
+ * rather than reporting a false "up to date".
+ *
+ * **Two independent paths, chosen by install kind.** A checkout derives the API
+ * URL from its `origin` remote. A plugin-cache install does NOT: when a
+ * marketplace entry declares `"source": "url"` (this project's own does) Claude
+ * Code unpacks an archive, so the cache directory has no `.git` and there is no
+ * remote to read. That path is answered entirely without git — the repository
+ * URL comes from the marketplace manifest on disk (`pluginMarketplaceUrl`) and
+ * the package.json version is the only comparison signal. Getting this wrong is
+ * what shipped in 1.5.1: the `.git` probe ran first, returned "not a git clone",
+ * and skipped the release layer, so `update_available` stayed false however many
+ * releases were published — a bug that reads as "up to date" and is therefore
+ * invisible while the install happens to be current. Keep the plugin branch
+ * ahead of the `.git` probe.
+ *
+ * Two states the release model makes visible that a commit count cannot:
+ * a checkout sitting AHEAD of the newest release tag is a `dev_build`, not an
+ * up-to-date install; and an install living under `~/.claude/plugins/cache/`
+ * is `plugin_managed`, which this process does not rewrite itself — Claude Code
+ * owns that directory, so `applyUpdate` refuses and `routes/updates.js` hands
+ * the job to the detached `claude plugin update` chain instead.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

 const fs = require("fs");
 const path = require("path");
 const { execFile } = require("child_process");
+const { readLastPluginUpdate } = require("./plugin-update");
+const { getClaudeHome } = require("./claude-home");

 const DEFAULT_ROOT = path.join(__dirname, "..", "..");

@@ -141,6 +168,298 @@ function stripRemotePrefix(ref) {
  return idx === -1 ? ref : ref.slice(idx + 1);
 }

+/** This install's own declared version, or null when package.json is unreadable. */
+function readLocalVersion(root) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The plugin cache coordinates when `root` lives under
+ * `~/.claude/plugins/cache/<marketplace>/<plugin>/<sha>`, else null.
+ * Read from the path because it is the one place the marketplace name is
+ * available locally — shelling out to `claude plugin list` to learn it would
+ * make a status poll depend on another CLI being on PATH.
+ */
+function detectPluginInstall(root) {
+  const posix = root.split(path.sep).join("/");
+  const m = posix.match(/\/\.claude\/plugins\/cache\/([^/]+)\/([^/]+)(?:\/|$)/);
+  return m ? { marketplace: m[1], plugin: m[2] } : null;
+}
+
+/**
+ * Numeric-triple version compare: -1 / 0 / 1. Tolerates the inconsistent tag
+ * naming this repo already carries (`v1.5.0` alongside `1.4.6`) by stripping a
+ * leading `v`. Prerelease and build suffixes are dropped rather than ordered —
+ * this project publishes plain releases, and a wrong prerelease ordering would
+ * be worse than ignoring one.
+ */
+function compareVersions(a, b) {
+  const parts = (v) =>
+    String(v)
+      .trim()
+      .replace(/^v/i, "")
+      .split(/[-+]/)[0]
+      .split(".")
+      .map((n) => Number.parseInt(n, 10) || 0);
+  const x = parts(a);
+  const y = parts(b);
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (x[i] || 0) - (y[i] || 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Derives the forge's "latest release" REST endpoint from a git remote URL.
+ * Returns null for anything that isn't owner/repo shaped, which is what keeps
+ * the local file-path remotes used by the tests off the network entirely.
+ */
+function releaseApiUrl(remoteUrl) {
+  const raw = String(remoteUrl).trim();
+  let m = raw.match(/^https?:\/\/(?:[^@/]*@)?([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  if (!m) {
+    // scp-style (`git@host:owner/repo.git`) and ssh:// forms.
+    m = raw.match(/^(?:ssh:\/\/)?[^@/]+@([^:/]+)(?::\d+)?[:/]([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  }
+  if (!m) return null;
+  const [, host, owner, repo] = m;
+  if (!host.includes(".")) return null;
+  return `https://${host}/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(
+    repo
+  )}/releases/latest`;
+}
+
+/**
+ * Reads the newest published release from the forge API. Never throws: every
+ * failure resolves to `{ ok: false, reason }` so a status poll degrades to the
+ * commit-count path instead of surfacing an error to the user.
+ *
+ * @returns {Promise<{ok: true, tag: string, name: string|null, url: string|null,
+ *   published_at: string|null, notes: string|null} | {ok: false, reason: string}>}
+ */
+async function fetchLatestRelease(root, timeoutMs = 10_000) {
+  let remoteUrl;
+  try {
+    const remote = await pickCanonicalRemote(root);
+    if (!remote) return { ok: false, reason: "no_remote" };
+    remoteUrl = await execGit(root, ["remote", "get-url", remote], { timeout: 10_000 });
+  } catch {
+    return { ok: false, reason: "no_remote" };
+  }
+  return fetchReleaseFromUrl(remoteUrl, timeoutMs);
+}
+
+/**
+ * The HTTP half of the release lookup, split out because a **plugin-cache
+ * install has no git remote to derive the URL from** — it is unpacked from an
+ * archive, so `pluginMarketplaceUrl()` supplies the repository URL instead and
+ * calls straight in here. Same contract as `fetchLatestRelease`: never throws.
+ *
+ * @param {string} repoUrl a repository URL (https, scp-style, or ssh://)
+ * @param {number} [timeoutMs]
+ */
+async function fetchReleaseFromUrl(repoUrl, timeoutMs = 10_000) {
+  if (!repoUrl) return { ok: false, reason: "no_remote" };
+  const api = releaseApiUrl(repoUrl);
+  if (!api) return { ok: false, reason: "remote_not_http" };
+
+  try {
+    const res = await fetch(api, {
+      signal: AbortSignal.timeout(timeoutMs),
+      headers: { accept: "application/json" },
+      redirect: "follow",
+    });
+    // A repo with no releases yet answers 404 — a normal state, not a fault.
+    if (res.status === 404) return { ok: false, reason: "no_releases" };
+    if (!res.ok) return { ok: false, reason: `http_${res.status}` };
+    const body = await res.json();
+    if (!body || typeof body.tag_name !== "string" || !body.tag_name) {
+      return { ok: false, reason: "bad_payload" };
+    }
+    return {
+      ok: true,
+      tag: body.tag_name,
+      name: typeof body.name === "string" && body.name ? body.name : null,
+      url: typeof body.html_url === "string" ? body.html_url : null,
+      published_at: typeof body.published_at === "string" ? body.published_at : null,
+      // Release notes are rendered in a modal, not stored — cap the size so a
+      // pathological changelog can't bloat every status poll and WS broadcast.
+      notes: typeof body.body === "string" && body.body ? body.body.slice(0, 4000) : null,
+    };
+  } catch (err) {
+    return { ok: false, reason: "unreachable", error: err.message || String(err) };
+  }
+}
+
+/**
+ * True for a shallow clone (`--depth`), where EVERY commit-distance number is
+ * a lie: history is grafted, so `git rev-list --count <tag>..HEAD` counts the
+ * graft boundary instead of real ancestry. The Claude Code plugin cache is
+ * exactly this — a depth-1 clone — which reported "306 behind AND 1 ahead" of
+ * a tag that is actually a plain ancestor. Callers must fall back to comparing
+ * version strings, the one signal a shallow clone still answers correctly.
+ */
+/**
+ * Repository URL a marketplace declares for one of its plugins, read off disk.
+ *
+ * This exists because a plugin-cache install is NOT necessarily a git clone.
+ * When a marketplace entry uses `"source": "url"` (this project's own does),
+ * Claude Code unpacks an archive and the cache directory has no `.git` at all —
+ * so there is no remote to derive the releases API from, and every git-based
+ * signal is unavailable. The marketplace manifest is the authority on where the
+ * plugin came from, and it is already on disk next to the cache.
+ *
+ * Path: `<claude home>/plugins/known_marketplaces.json` gives the marketplace's
+ * `installLocation`; that directory's `.claude-plugin/marketplace.json` lists
+ * the plugins, each with its own `source`.
+ *
+ * @param {string} marketplace marketplace name (from the cache path)
+ * @param {string} plugin plugin name (from the cache path)
+ * @returns {string|null} the URL, or null when it cannot be determined. Never throws.
+ */
+function pluginMarketplaceUrl(marketplace, plugin) {
+  try {
+    const pluginsDir = path.join(getClaudeHome(), "plugins");
+    let installLocation = path.join(pluginsDir, "marketplaces", marketplace);
+    try {
+      const known = JSON.parse(
+        fs.readFileSync(path.join(pluginsDir, "known_marketplaces.json"), "utf8")
+      );
+      const entry = known && known[marketplace];
+      if (entry && typeof entry.installLocation === "string" && entry.installLocation) {
+        installLocation = entry.installLocation;
+      }
+    } catch {
+      // Fall back to the conventional location — the manifest below is what
+      // actually matters, and it may well be readable without this index.
+    }
+
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(installLocation, ".claude-plugin", "marketplace.json"), "utf8")
+    );
+    const entry = (manifest?.plugins || []).find((p) => p && p.name === plugin);
+    if (!entry) return null;
+
+    // `source` is either a string (a bare URL or owner/repo) or an object with
+    // its own `source` discriminator plus `url`/`repo`.
+    const src = entry.source;
+    if (typeof src === "string") return src.includes("://") ? src : null;
+    if (src && typeof src.url === "string" && src.url) return src.url;
+    // A `github`-style `repo: "owner/repo"` shorthand carries no host; this
+    // build is distributed from its own forge, so rather than guessing
+    // github.com the caller reports "remote_not_http" and prints the manual
+    // command instead of inventing an API URL that would 404.
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Full update status for an install running out of the plugin cache, computed
+ * WITHOUT git. Version comparison is the only signal available and the only one
+ * that means anything here: the cache directory name is a content hash, and
+ * even when a `.git` happens to exist it is a depth-1 clone whose commit
+ * distances are graft artefacts.
+ *
+ * Returns the same payload shape as the git path, with every git-derived field
+ * null, so one client renders both.
+ */
+async function pluginStatus(root, pluginInstall, options = {}) {
+  const localVersion = readLocalVersion(root);
+  const repoUrl = pluginMarketplaceUrl(pluginInstall.marketplace, pluginInstall.plugin);
+  const release =
+    options.latestRelease ??
+    (options.skipFetch ? { ok: false, reason: "skipped" } : await fetchReleaseFromUrl(repoUrl));
+
+  // No local version means nothing to compare against — report "could not
+  // look" rather than a false "up to date".
+  const comparable = release.ok && Boolean(localVersion);
+  const releaseIsNewer = comparable && compareVersions(release.tag, localVersion) > 0;
+
+  const manualParts = [
+    `claude plugin marketplace update ${pluginInstall.marketplace}`,
+    `claude plugin update ${pluginInstall.plugin}@${pluginInstall.marketplace} -y`,
+  ];
+
+  return {
+    // Truthfully false: there is no clone here. Consumers must branch on
+    // `install_kind`, not on this, or they will report "check manually" for an
+    // install the dashboard can in fact check AND update.
+    git_repo: false,
+    update_available: releaseIsNewer,
+    repo_root: root,
+    situation: "plugin_managed",
+    situation_note:
+      `This dashboard runs from the Claude Code plugin cache (marketplace ` +
+      `'${pluginInstall.marketplace}'). Updating is handled by Claude Code's own plugin ` +
+      `commands — "Update now" runs them for you and restarts the dashboard. An already-open ` +
+      `Claude Code session still needs '/reload-plugins' to pick up new skills and commands.`,
+    manual_command: manualParts.join(" && "),
+    // A plugin install compares versions exactly like a checkout does, so it
+    // gets the same sentence. Left null, `agenthub update-check` printed the
+    // literal "null" as its headline on every plugin-cache install — the one
+    // install kind that cannot fall back to a commit count.
+    message: releaseIsNewer
+      ? `Release ${release.tag} is available (this install reports ${localVersion || "no version"}).`
+      : comparable
+        ? `Running the newest release (${release.tag}).`
+        : release.ok
+          ? `This install reports no version, so it cannot be compared with release ${release.tag}.`
+          : `Could not read the latest release (${release.reason}); version comparison unavailable.`,
+
+    install_kind: "plugin",
+    plugin_marketplace: pluginInstall.marketplace,
+    plugin_name: pluginInstall.plugin,
+    last_plugin_update: readLastPluginUpdate(),
+
+    local_version: localVersion,
+    // Not a clone, so there is nothing to be shallow about and no distances to
+    // report. Kept present-and-null so the payload shape never varies.
+    shallow_clone: false,
+    local_sha: null,
+    remote_sha: null,
+    commits_behind: 0,
+    release_check: release.ok ? (localVersion ? "ok" : "no_local_version") : release.reason,
+    latest_release: release.ok ? release.tag : null,
+    latest_release_name: release.ok ? release.name : null,
+    latest_release_url: release.ok ? release.url : null,
+    latest_release_published_at: release.ok ? release.published_at : null,
+    latest_release_notes: release.ok ? release.notes : null,
+    release_sha: null,
+    commits_behind_release: null,
+    commits_ahead_of_release: null,
+    // A plugin install is whatever the marketplace shipped; it cannot be ahead.
+    dev_build: false,
+  };
+}
+
+async function isShallowClone(root) {
+  try {
+    const out = await execGit(root, ["rev-parse", "--is-shallow-repository"], { timeout: 10_000 });
+    return out.trim() === "true";
+  } catch {
+    return false;
+  }
+}
+
+/** Commit count for `range`, or 0 when it can't be resolved. */
+async function countCommits(root, range) {
+  try {
+    const out = await execGit(root, ["rev-list", "--count", range], { timeout: 30_000 });
+    const n = Number.parseInt(out, 10);
+    return Number.isNaN(n) ? 0 : n;
+  } catch {
+    return 0;
+  }
+}
+
 /**
 * @param {string} [gitRoot]
 * @param {{ skipFetch?: boolean }} [options]
@@ -148,6 +467,17 @@ function stripRemotePrefix(ref) {
 */
 async function getUpdatesStatus(gitRoot = DEFAULT_ROOT, options = {}) {
  const root = path.resolve(gitRoot);
+
+  // A plugin-cache install is answered WITHOUT git, and this must come before
+  // the `.git` probe below. When a marketplace entry uses `"source": "url"`,
+  // Claude Code unpacks an archive and there is no `.git` at all — so the probe
+  // would return "not a git clone; check for updates manually" and skip the
+  // entire release layer, leaving update_available permanently false however
+  // many releases get published. Version compare needs no clone; the repository
+  // URL comes from the marketplace manifest.
+  const earlyPluginInstall = detectPluginInstall(root);
+  if (earlyPluginInstall) return pluginStatus(root, earlyPluginInstall, options);
+
  const gitDir = path.join(root, ".git");
  if (!fs.existsSync(gitDir)) {
    return {
@@ -175,7 +505,9 @@ async function getUpdatesStatus(gitRoot = DEFAULT_ROOT, options = {}) {

  if (!options.skipFetch) {
    try {
-      await execGit(root, ["fetch", canonicalRemote, "--prune"], { timeout: 120_000 });
+      // `--tags` so the release tag resolved below exists locally; without it
+      // a freshly published release has no local commit to compare against.
+      await execGit(root, ["fetch", canonicalRemote, "--prune", "--tags"], { timeout: 120_000 });
    } catch (err) {
      return {
        git_repo: true,
@@ -225,7 +557,54 @@ async function getUpdatesStatus(gitRoot = DEFAULT_ROOT, options = {}) {
    };
  }

-  const updateAvailable = commitsBehind > 0;
+  // ── Release layer ────────────────────────────────────────────────────────
+  // The published release is the version signal; the commit count above stays
+  // as the fallback for when no release can be read, and as the raw distance
+  // that tells a dev build apart from a stale one.
+  const localVersion = readLocalVersion(root);
+  const pluginInstall = detectPluginInstall(root);
+  const shallow = await isShallowClone(root);
+  const release = options.latestRelease ?? (await fetchLatestRelease(root));
+
+  let releaseSha = null;
+  let commitsBehindRelease = null;
+  let commitsAheadOfRelease = null;
+  let releaseIsNewer = false;
+  if (release.ok) {
+    try {
+      releaseSha = await execGit(
+        root,
+        ["rev-parse", "--verify", `refs/tags/${release.tag}^{commit}`],
+        { timeout: 10_000 }
+      );
+    } catch {
+      releaseSha = null; // tag not fetched locally (offline, or skipFetch in tests)
+    }
+    // Distances stay null on a shallow clone: see isShallowClone().
+    if (releaseSha && !shallow) {
+      commitsBehindRelease = await countCommits(root, `HEAD..${releaseSha}`);
+      commitsAheadOfRelease = await countCommits(root, `${releaseSha}..HEAD`);
+    }
+    // Version compare is the primary test, and the ONLY one a shallow clone can
+    // answer. The commit distance decides only when this install declares no
+    // version of its own and the distance is actually trustworthy.
+    releaseIsNewer = localVersion
+      ? compareVersions(release.tag, localVersion) > 0
+      : commitsBehindRelease !== null && commitsBehindRelease > 0;
+  }
+
+  const updateAvailable = release.ok
+    ? releaseIsNewer
+    : shallow
+      ? false // no release to compare and no usable commit distance — say nothing
+      : commitsBehind > 0;
+  // Ahead of the newest release with nothing of that release missing: a build
+  // from the branch, not a shipped version. Reported so the widget never claims
+  // "up to date" for a checkout carrying commits no release contains. Requires
+  // behind === 0, or a diverged history would be mislabelled a dev build.
+  const devBuild =
+    release.ok && !releaseIsNewer && commitsBehindRelease === 0 && (commitsAheadOfRelease ?? 0) > 0;
+
  const isProd = process.env.NODE_ENV === "production";
  const installSteps = ["npm run setup"];
  if (isProd) installSteps.push("npm run build");
@@ -245,7 +624,35 @@ async function getUpdatesStatus(gitRoot = DEFAULT_ROOT, options = {}) {
  let manualParts;
  let situationNote;
  let situation;
-  if (tracksCanonical) {
+  if (pluginInstall) {
+    // Claude Code owns this directory and replaces it wholesale on update, so
+    // the only correct move is its own update path. The printed commands do
+    // pull the new version, but `/reload-plugins` is a REPL action — nothing
+    // here can finish the job, which is why `applyUpdate` refuses outright.
+    situation = "plugin_managed";
+    manualParts = [
+      `claude plugin marketplace update ${pluginInstall.marketplace}`,
+      `claude plugin update ${pluginInstall.plugin}@${pluginInstall.marketplace} -y`,
+    ];
+    situationNote =
+      `This dashboard runs from the Claude Code plugin cache (marketplace '${pluginInstall.marketplace}'), ` +
+      `so it can't update itself. Run the commands above, then '/reload-plugins' in Claude Code — ` +
+      `or just run '/agenthub-update', which does both and rebuilds the runtime.`;
+  } else if (release.ok && releaseIsNewer) {
+    // Move onto the release TAG rather than the branch tip: the tag is what
+    // was published, and a fast-forward keeps the tracking branch intact (a
+    // `git checkout <tag>` would detach HEAD and break every later update).
+    situation = "release_available";
+    manualParts = [
+      `cd "${root}"`,
+      `git fetch ${canonicalRemote} --tags`,
+      `git merge --ff-only ${release.tag}`,
+      ...installSteps,
+    ];
+    situationNote = releaseSha
+      ? null
+      : `Release ${release.tag} isn't in your local clone yet — the fetch above brings its tag in.`;
+  } else if (tracksCanonical) {
    situation = "tracking_canonical";
    manualParts = [`cd "${root}"`, "git pull --ff-only", ...installSteps];
    situationNote = null;
@@ -285,9 +692,42 @@ async function getUpdatesStatus(gitRoot = DEFAULT_ROOT, options = {}) {
    commits_behind: commitsBehind,
    manual_command: manualCommand,
    situation_note: situationNote,
+
+    // Release layer. `release_check` names why the release fields are absent
+    // when they are, so the UI can say "offline" rather than "up to date".
+    install_kind: pluginInstall ? "plugin" : "checkout",
+    plugin_marketplace: pluginInstall ? pluginInstall.marketplace : null,
+    plugin_name: pluginInstall ? pluginInstall.plugin : null,
+    // Verdict of the last detached plugin-update chain, if any. Read here so
+    // every consumer (route, WS broadcast, CLI) gets it from one place — and so
+    // a chain that died is visible instead of looking like a slow restart.
+    last_plugin_update: pluginInstall ? readLastPluginUpdate() : null,
+    local_version: localVersion,
+    // True when commit distances are unusable and version strings are the only
+    // signal — the UI must not render an "N commits" badge in that case.
+    shallow_clone: shallow,
+    release_check: release.ok ? "ok" : release.reason,
+    latest_release: release.ok ? release.tag : null,
+    latest_release_name: release.ok ? release.name : null,
+    latest_release_url: release.ok ? release.url : null,
+    latest_release_published_at: release.ok ? release.published_at : null,
+    latest_release_notes: release.ok ? release.notes : null,
+    release_sha: releaseSha,
+    commits_behind_release: commitsBehindRelease,
+    commits_ahead_of_release: commitsAheadOfRelease,
+    dev_build: devBuild,
+
    message: updateAvailable
-      ? `${commitsBehind} commit(s) on ${remoteRef} not in your checkout.`
-      : "Your checkout includes the tip of the canonical default branch.",
+      ? release.ok
+        ? `Release ${release.tag} is available (this install reports ${localVersion || "no version"}).`
+        : `${commitsBehind} commit(s) on ${remoteRef} not in your checkout.`
+      : devBuild
+        ? `Dev build: ${commitsAheadOfRelease} commit(s) ahead of release ${release.tag}.`
+        : release.ok
+          ? `Running the newest release (${release.tag}).`
+          : shallow
+            ? `Shallow clone — could not read the latest release (${release.reason}); version comparison unavailable.`
+            : "Your checkout includes the tip of the canonical default branch.",
  };
 }

@@ -306,11 +746,27 @@ async function getUpdatesStatus(gitRoot = DEFAULT_ROOT, options = {}) {
 *   `reason` when `applied` is false).
 */
 async function applyUpdate(gitRoot = DEFAULT_ROOT) {
+  // A plugin-cache install is Claude Code's to replace. Pulling here would
+  // leave a cache directory named after one commit but holding another, and
+  // the running session would keep resolving ${CLAUDE_PLUGIN_ROOT} to the old
+  // path until `/reload-plugins` — which no server can invoke. Refuse and let
+  // the printed commands (or `/agenthub-update`) do it.
+  //
+  // Decided from the PATH, before any status lookup: the refusal is true
+  // whether or not the machine is online and whatever the version gap is.
+  // Reading it off `status.situation` instead would mis-report `up_to_date`
+  // every time the fetch failed, since that error returns early.
+  if (detectPluginInstall(path.resolve(gitRoot))) {
+    const status = await getUpdatesStatus(gitRoot);
+    return { ...status, applied: false, reason: "plugin_managed" };
+  }
+
  const status = await getUpdatesStatus(gitRoot);
  if (!status.update_available) {
    return { ...status, applied: false, reason: "up_to_date" };
  }
  if (
+    status.situation !== "release_available" &&
    status.situation !== "tracking_canonical" &&
    status.situation !== "fork_or_diverged_tracking"
  ) {
@@ -318,7 +774,13 @@ async function applyUpdate(gitRoot = DEFAULT_ROOT) {
  }

  const root = path.resolve(gitRoot);
-  if (status.situation === "tracking_canonical") {
+  if (status.situation === "release_available") {
+    await execGit(root, ["fetch", status.canonical_remote, "--tags"], { timeout: 120_000 });
+    // --ff-only is the guard: a release that isn't a descendant of HEAD (a
+    // rollback, or a rewritten history) aborts here instead of creating a
+    // merge commit in the user's install.
+    await execGit(root, ["merge", "--ff-only", status.latest_release], { timeout: 30_000 });
+  } else if (status.situation === "tracking_canonical") {
    await execGit(root, ["pull", "--ff-only"], { timeout: 120_000 });
  } else {
    await execGit(root, ["fetch", status.canonical_remote], { timeout: 120_000 });
@@ -334,4 +796,16 @@ async function applyUpdate(gitRoot = DEFAULT_ROOT) {
  return { ...refreshed, applied: true };
 }

-module.exports = { getUpdatesStatus, applyUpdate, DEFAULT_ROOT };
+module.exports = {
+  getUpdatesStatus,
+  applyUpdate,
+  DEFAULT_ROOT,
+  // Exported for tests: each is a pure decision the status shape depends on.
+  compareVersions,
+  releaseApiUrl,
+  detectPluginInstall,
+  pluginMarketplaceUrl,
+  fetchReleaseFromUrl,
+  fetchLatestRelease,
+  isShallowClone,
+};
@@ -1556,6 +1556,118 @@ const paths = {
    },
  },

+  "/api/cc-config/plugins/update-all": {
+    get: {
+      tags: ["CcConfig"],
+      summary: "Progress of the current or last update-all batch",
+      description:
+        "Read-only. Returns the detached batch worker's on-disk journal from ~/.claude/agenthub/runtime/cc-update-all.json, or `{batch:null}` when no batch has ever run. `status` is `running`|`done`|`partial`|`failed`|`abandoned`; `abandoned` is DERIVED, not stored — a `running` journal older than one hour is reported that way because the worker is detached and a host reboot leaves nobody to write the terminal entry. `partial` means the batch finished with at least one failed step. Malformed or half-written journals return null rather than erroring, since the UI polls this endpoint.",
+      operationId: "ccConfigGetUpdateAll",
+      responses: {
+        200: {
+          description: "The batch journal, or null.",
+          content: {
+            "application/json": {
+              schema: { type: "object", additionalProperties: true },
+              example: {
+                batch: {
+                  status: "partial",
+                  started_at: "2026-09-10T08:30:00.000Z",
+                  finished_at: "2026-09-10T08:34:12.000Z",
+                  steps: [
+                    { key: "marketplaces", label: "Update all marketplaces", status: "ok" },
+                    { key: "plugin:ponytail@ponytail", label: "ponytail@ponytail", status: "ok" },
+                    {
+                      key: "plugin:vercel@claude-plugins-official",
+                      label: "vercel@claude-plugins-official",
+                      status: "failed",
+                      error: "marketplace unreachable",
+                    },
+                    {
+                      key: "reload",
+                      label: "Reload open Claude Code sessions",
+                      status: "ok",
+                      lanes_total: 2,
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    post: {
+      tags: ["CcConfig"],
+      summary: "Update every marketplace and plugin, then reload the open sessions",
+      description:
+        'Mutating. Spawns a DETACHED worker and returns immediately — the response is an acknowledgement, not a result; poll GET on this path to follow it. Order: `claude plugin marketplace update` (no name = all), then `claude plugin update <id> -y` for every installed plugin, then `/reload-plugins` + `/reload-skills` typed into the live lane panes. The plugin this dashboard itself runs from is updated LAST and followed by `plugin-bootstrap.js --force`, which stops this server and starts the replacement — which is why the work cannot happen in the request handler and why the journal lives outside the plugin cache. Plugin ids come from `claude plugin list --json`, never from the body, and the "self" plugin is derived from this server\'s own path, so no caller can nominate a different plugin for the restart. Answers 409 EBUSY when a batch is already in flight; the body is ignored apart from an optional `reload:false`.',
+      operationId: "ccConfigUpdateAll",
+      responses: {
+        200: {
+          description: "Batch worker spawned.",
+          content: {
+            "application/json": {
+              schema: { type: "object", additionalProperties: true },
+              example: {
+                ok: true,
+                spawned: true,
+                runtime_dir: "/Users/son/.claude/agenthub/runtime",
+                planned: 7,
+                self_plugin: { marketplace: "sg", plugin: "agenthub" },
+              },
+            },
+          },
+        },
+        409: {
+          description: "A batch is already running.",
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } },
+          },
+        },
+      },
+    },
+  },
+
+  "/api/cc-config/reload": {
+    post: {
+      tags: ["CcConfig"],
+      summary: "Tell the open Claude Code sessions to re-read plugins and skills",
+      description:
+        'Types `/reload-plugins` and `/reload-skills` into the dashboard\'s live lane panes over `tmux send-keys`. Both commands are scoped BY CLAUDE CODE to the session that runs them, so there is no way to reload a session from outside — typing into a session that is already running is what a human would do, and it is what this does. It spawns no `claude` process: a one-shot `claude -p "/reload-plugins"` would reload only its own short-lived session and leave a junk session behind. Changes nothing on disk, so it does not queue on the CLI mutation chain and emits no `cc_config_changed`. Panes sitting at a shell prompt are skipped (the text would run as a shell command); only `claude` lanes are addressed, since Codex has no such command. Optional body `{kinds:["plugins"|"skills"]}` narrows which commands are sent; unknown kinds are ignored, as the command strings are fixed server-side.',
+      operationId: "ccConfigReload",
+      responses: {
+        200: {
+          description:
+            "Commands delivered. `lanes_total` counts only panes running a live claude; zero is a normal outcome, not a failure.",
+          content: {
+            "application/json": {
+              schema: { type: "object", additionalProperties: true },
+              example: {
+                ok: true,
+                commands: ["/reload-plugins", "/reload-skills"],
+                lanes_total: 1,
+                lanes: [
+                  {
+                    id: "agenthub-lane-3",
+                    laneId: 3,
+                    sent: ["/reload-plugins", "/reload-skills"],
+                  },
+                ],
+              },
+            },
+          },
+        },
+        400: {
+          description: "`kinds` was present but not an array.",
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } },
+          },
+        },
+      },
+    },
+  },
+
  "/api/cc-config/mcp": {
    get: {
      tags: ["CcConfig"],
@@ -2387,7 +2387,7 @@ function createOpenApiSpec() {
      "/api/updates/status": {
        get: {
          tags: ["Updates"],
-          summary: "Check whether the dashboard git checkout is behind origin",
+          summary: "Check whether a newer release of the dashboard has been published",
          operationId: "getUpdatesStatus",
          responses: {
            200: {
@@ -2398,7 +2398,7 @@ function createOpenApiSpec() {
                    type: "object",
                    additionalProperties: true,
                    description:
-                      "Includes git_repo, update_available, commits_behind, remote_ref, local_sha, remote_sha, manual_command, and optional error/message fields.",
+                      'Reads the newest published release from the forge API (derived from the origin remote) and compares its tag against this install\'s package.json version; falls back to a commit count against the canonical default branch when no release can be read, with the reason in release_check. Includes git_repo, update_available, install_kind ("plugin" | "checkout"), plugin_marketplace, local_version, shallow_clone, release_check, latest_release, latest_release_name, latest_release_url, latest_release_published_at, latest_release_notes, release_sha, commits_behind_release, commits_ahead_of_release, dev_build, commits_behind, remote_ref, local_sha, remote_sha, situation, manual_command, and optional error/message fields. dev_build is true when this install is strictly ahead of the newest release; commits_* fields are null on a shallow clone, where distances are meaningless.',
                  },
                },
              },
@@ -2443,18 +2443,21 @@ function createOpenApiSpec() {
      "/api/updates/apply": {
        post: {
          tags: ["Updates"],
-          summary: "Pull, rebuild, and restart the dashboard when fast-forwardable",
+          summary: "Update this install to the newest release and restart the dashboard",
+          description:
+            "Two modes, chosen by how this copy was installed and never by the request body (which is ignored). checkout: fast-forward onto the release tag, npm run setup, npm run build in production, then self-restart. plugin: the install runs from ~/.claude/plugins/cache/, so a detached helper runs `claude plugin marketplace update`, `claude plugin update -y`, then plugin-bootstrap.js --force from the NEW cache directory, which stops this server and starts the new one. In both modes the response is written before anything stops the process.",
          operationId: "applyUpdate",
          responses: {
            200: {
              description:
-                "Checkout fast-forwarded and rebuilt; the process is about to self-restart",
+                'Update is being applied; the process is about to be replaced. mode: "plugin" means the detached plugin chain is running, otherwise the checkout was fast-forwarded and rebuilt in-place',
              content: {
                "application/json": {
                  schema: {
                    type: "object",
                    additionalProperties: true,
-                    description: "Same shape as GET /api/updates/status, plus applied: true.",
+                    description:
+                      'Same shape as GET /api/updates/status, plus applied: true. In plugin mode also mode: "plugin" and runtime_dir (where the chain writes its verdict, read back afterwards as last_plugin_update).',
                  },
                },
              },
@@ -2468,7 +2471,7 @@ function createOpenApiSpec() {
                    type: "object",
                    additionalProperties: true,
                    description:
-                      'applied: false plus reason: "up_to_date" | "not_fast_forwardable".',
+                      'applied: false plus reason: "up_to_date" | "not_fast_forwardable" | "plugin_managed". plugin_managed appears here only when a plugin-cache install has nothing to pull: either release_check is "ok" and the published release is already installed, or the release check did not succeed (the message says which — an unknown is never reported as "nothing newer"). When a newer release exists the plugin chain runs and the answer is 200 instead. Run /agenthub-update to force a refresh.',
                  },
                },
              },
@@ -24,6 +24,7 @@
 */

 const { Router } = require("express");
+const path = require("path");
 const cc = require("../lib/cc-discovery");
 const ccMutate = require("../lib/cc-mutate");
 const ccCli = require("../lib/cc-plugin-cli");
@@ -32,6 +33,13 @@ const ccProfiles = require("../lib/cc-profiles");
 const projectMemory = require("../lib/project-memory");
 const { sameOriginGuard } = require("../lib/same-origin");
 const { broadcast } = require("../websocket");
+const { reloadOpenSessions } = require("../lib/cc-reload");
+const { startUpdateAll, readUpdateAll, isRunning } = require("../lib/cc-update-all");
+const { detectPluginInstall } = require("../lib/update-check");
+
+/** Mirrors cc-plugin-cli's own spec rule — ids from the CLI's JSON still reach
+ *  an argv in the detached batch worker, so they are filtered before they go. */
+const PLUGIN_SPEC_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*(@[A-Za-z0-9][A-Za-z0-9._-]*)?$/;

 const router = Router();

@@ -265,7 +273,7 @@ function cliError(res, err) {
 }

 /** Map a finished CLI run onto a response; a non-zero exit is a 422, not a 500. */
-function cliResult(res, result, changed) {
+function cliResult(res, result, changed, extra) {
  if (!result.ok) {
    return res.status(422).json({
      error: {
@@ -278,7 +286,7 @@ function cliResult(res, result, changed) {
    });
  }
  emitChanged(changed);
-  res.json({ ok: true, stdout: result.stdout, stderr: result.stderr });
+  res.json({ ok: true, stdout: result.stdout, stderr: result.stderr, ...extra });
 }

 router.get("/plugins/available", async (_req, res) => {
@@ -307,7 +315,7 @@ const PLUGIN_ACTIONS = {
 };

 router.post("/plugins/action", async (req, res) => {
-  const { key, action } = req.body || {};
+  const { key, action, reload } = req.body || {};
  const run = PLUGIN_ACTIONS[action];
  if (!run) {
    return res.status(400).json({
@@ -319,12 +327,102 @@ router.post("/plugins/action", async (req, res) => {
  }
  try {
    const result = await run({ spec: key });
-    return cliResult(res, result, { action, type: "plugin", name: key });
+    // "Update one, reload that one" — the counterpart to the batch, which
+    // reloads once at the end. Only on success, and only when asked: an
+    // enable/disable already needs a reload but the caller decides, and a
+    // reload after a FAILED update would tell the session to activate nothing.
+    let reloaded;
+    if (reload && result.ok) {
+      try {
+        reloaded = reloadOpenSessions();
+      } catch {
+        /* a reload that cannot be delivered must not fail the update itself */
+      }
+    }
+    return cliResult(res, result, { action, type: "plugin", name: key }, { reloaded });
  } catch (err) {
    return cliError(res, err);
  }
 });

+/**
+ * Type `/reload-plugins` + `/reload-skills` into the live Claude Code lane
+ * panes. Not a config mutation — it changes nothing on disk, it just tells
+ * sessions to re-read what is already there — so it neither queues on the CLI
+ * mutation chain nor emits `cc_config_changed`.
+ */
+router.post("/reload", (req, res) => {
+  const { kinds } = req.body || {};
+  if (kinds !== undefined && !Array.isArray(kinds)) {
+    return res.status(400).json({
+      error: { code: "EBADARG", message: "kinds must be an array of 'plugins' | 'skills'" },
+    });
+  }
+  try {
+    res.json({ ok: true, ...reloadOpenSessions({ kinds }) });
+  } catch (err) {
+    res.status(500).json({
+      error: { code: "ERELOAD", message: err.message || String(err) },
+    });
+  }
+});
+
+// ── Update all ─────────────────────────────────────────────────────────
+//
+// Runs detached (see server/lib/cc-update-all.js): the batch ends with AgentHub
+// itself when this server runs from the plugin cache, and that step stops the
+// process. The response is therefore only an acknowledgement — progress is
+// polled from GET below, which reads the worker's on-disk journal.
+
+router.get("/plugins/update-all", (_req, res) => {
+  res.json({ batch: readUpdateAll() });
+});
+
+router.post("/plugins/update-all", async (req, res) => {
+  if (isRunning()) {
+    return res.status(409).json({
+      error: { code: "EBUSY", message: "an update-all batch is already running" },
+      batch: readUpdateAll(),
+    });
+  }
+
+  let installed;
+  try {
+    installed = (await ccCli.listAvailable()).installed || [];
+  } catch (err) {
+    return cliError(res, err);
+  }
+
+  // Ids come from the CLI's own JSON, never from the request body, but they
+  // reach an argv in a detached process — so they are filtered here too.
+  const plugins = installed.map((p) => String(p.id || "")).filter((id) => PLUGIN_SPEC_RE.test(id));
+
+  // Which plugin, if any, is the one this dashboard is running from. Derived
+  // from our own path — never from the request — so no caller can nominate a
+  // different plugin as "self" and get a bootstrap run against it.
+  const selfRoot = path.resolve(__dirname, "..", "..");
+  const detected = detectPluginInstall(selfRoot);
+  const selfPlugin = detected
+    ? { marketplace: detected.marketplace, plugin: detected.plugin }
+    : null;
+
+  const plan = {
+    plugins,
+    selfPlugin,
+    selfRoot: selfPlugin ? selfRoot : null,
+    reload: req.body?.reload !== false,
+  };
+
+  try {
+    const started = startUpdateAll(plan);
+    res.json({ ok: true, ...started, planned: plugins.length, self_plugin: selfPlugin });
+  } catch (err) {
+    res.status(500).json({
+      error: { code: "EUPDATEALL", message: err.message || String(err) },
+    });
+  }
+});
+
 router.post("/marketplaces/add", async (req, res) => {
  const { source, scope } = req.body || {};
  try {
@@ -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 } });
    }
@@ -1,15 +1,26 @@
 /**
- * @file HTTP routes for dashboard upstream-update detection, plus the one
- * self-applying path: POST /apply fast-forwards, rebuilds, and restarts the
- * process on the user's explicit click (see `server/lib/update-check.js`'s
- * `applyUpdate` and `server/lib/self-restart.js`). Everywhere else, the
- * dashboard only ever prints a command for the user to run themselves.
+ * @file HTTP routes for release-update detection plus the self-applying path.
+ * `POST /apply` has two modes, chosen by how this copy was installed:
+ *
+ * - **checkout** — fast-forward onto the newest release tag, rebuild, and
+ *   restart in place (`update-check.js`'s `applyUpdate` + `self-restart.js`).
+ * - **plugin** — `applyUpdate` cannot touch a `~/.claude/plugins/cache/`
+ *   directory, so it refuses with `plugin_managed`; this route catches that and
+ *   hands the job to the detached chain in `plugin-update.js` instead
+ *   (`claude plugin marketplace update` → `claude plugin update` →
+ *   `plugin-bootstrap.js --force`, which retires this server and starts the new
+ *   one). Answered 200 with `mode: "plugin"`, not 409.
+ *
+ * Both modes reply BEFORE anything stops the process, and the request is only
+ * ever a trigger: the marketplace and plugin names come from the local cache
+ * path, never from the body, so there is nothing in the payload to validate.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

 const { Router } = require("express");
 const { getUpdatesStatus, applyUpdate } = require("../lib/update-check");
 const { scheduleRestart } = require("../lib/self-restart");
+const { schedulePluginUpdate } = require("../lib/plugin-update");

 const router = Router();

@@ -44,6 +55,33 @@ router.post("/check", async (_req, res) => {
 router.post("/apply", async (_req, res) => {
  try {
    const result = await applyUpdate();
+
+    // A plugin-cache install is refused by applyUpdate on purpose (it must not
+    // rewrite a directory Claude Code owns). Route it to the detached chain,
+    // which pulls the new version and re-bootstraps from the NEW cache dir.
+    // Only when there is genuinely something to pull — a `plugin_managed`
+    // refusal with nothing newer published must stay a 409, not spawn a
+    // process that would stop the server for no reason.
+    if (
+      !result.applied &&
+      result.reason === "plugin_managed" &&
+      result.update_available &&
+      result.plugin_marketplace &&
+      result.plugin_name &&
+      result.repo_root
+    ) {
+      const scheduled = schedulePluginUpdate({
+        marketplace: result.plugin_marketplace,
+        plugin: result.plugin_name,
+        root: result.repo_root,
+      });
+      // `applied: true` because the update IS being applied — just by the
+      // plugin chain rather than by a git fast-forward. `mode` tells the client
+      // which one, so it can word the progress text honestly.
+      res.json({ ...result, applied: true, mode: "plugin", ...scheduled });
+      return;
+    }
+
    if (!result.applied) {
      res.status(409).json({
        ...result,
@@ -52,7 +90,15 @@ router.post("/apply", async (_req, res) => {
          message:
            result.reason === "up_to_date"
              ? "Already up to date."
-              : "Current branch can't be fast-forwarded automatically.",
+              : result.reason === "plugin_managed"
+                ? // Do not claim "nothing newer is published" unless the release
+                  // lookup actually succeeded — saying so after a failed check
+                  // reports an unknown as a negative, which is how a broken
+                  // check looks identical to an up-to-date install.
+                  result.release_check === "ok"
+                  ? `This install runs from the Claude Code plugin cache and ${result.latest_release || "the published release"} is already the newest; run /agenthub-update to force a refresh.`
+                  : `This install runs from the Claude Code plugin cache and the release check did not succeed (${result.release_check || "unknown"}), so there is nothing to apply; run /agenthub-update to update it by hand.`
+                : "Current branch can't be fast-forwarded automatically.",
        },
      });
      return;
Author	SHA1	Message	Date
nntrivi2001	91af3dca86	chore(release): bump version to 1.5.9	2026-09-14 11:22:11 +07:00
nntrivi2001	baa355bee4	feat(lanes): offer a create/update readme run when adding a lane An optional checkbox in the Add-lane modal starts the new lane's terminal run right after creation with `/sg-all:sg-md-writing` as its first message, so the lane opens already writing or refreshing its CLAUDE.md/AGENTS.md set. Claude lanes only — codex has no slash commands.	2026-09-14 11:20:37 +07:00
nntrivi2001	b7e81af0b6	chore(release): bump version to 1.5.8	2026-09-11 16:48:00 +07:00
nntrivi2001	c90dd7b147	fix(bootstrap): self-heal a systemd unit left on a retired plugin root The residue an interrupted update leaves behind is invisible: the server runs, every doctor row reads OK, and the unit quietly still names a cache directory Claude Code deleted during the update. Nothing surfaces it until a reboot, when the dashboard does not come back and nothing recorded why. - fastPathOk now rejects a stale unit, so the next SessionStart repairs it instead of short-circuiting. `unitIsStale` is pure fs on purpose: that path runs on every session and may not spawn a process. - Repairing the unit is not restarting the server. A current, healthy server keeps running and the corrected unit takes effect at the next start (`pendingSystemdRestart = systemdOwned && needsServer`), and the detached-spawn fallback is guarded by needsServer so a stale unit alone cannot start a second server onto a bound port. - systemdOwned now also requires the unit to be ACTIVE. Installed-but- stopped owns nothing: skipping the stop there and asking systemd to start would bind an occupied port and crash-loop under Restart=always. - /agenthub-doctor gains a systemd row naming the consequence ("will NOT come back after a reboot") and the fix. WARN, never FAIL — the dashboard in front of you works, and having no unit at all is a normal setup. The fast-path test pins the regression against an otherwise fully healthy install, live server included; without a live server it would have passed against the unfixed code either way.	2026-09-11 16:45:47 +07:00
nntrivi2001	49a041b1dc	chore(release): bump version to 1.5.7	2026-09-11 16:32:50 +07:00
nntrivi2001	de8d1079e0	fix(bootstrap): never stop the dashboard from inside its own systemd cgroup A plugin self-update took the dashboard down and left it down. The chain ran correctly up to the point where the bootstrap SIGTERMs the server it is replacing — and that server was systemd-managed, with the bootstrap running as its descendant, i.e. inside its cgroup. Two failures fired at once: * the server exits 0, and `Restart=on-failure` reads a clean exit as "meant to stop", so systemd did not bring it back; * `KillMode=control-group` reaped the bootstrap itself, mid-run, before it could repoint the unit at the new plugin root or write state.json. Evidence from the incident: bootstrap.log ends at "stopped the server started from the previous plugin version" with no systemd line after it, .bootstrap.lock survived with a dead pid, state.json still named the previous version, and the unit's ExecStart still pointed at the old cache dir. The same truncation is visible on three earlier updates — those only recovered because a later SessionStart bootstrapped again. systemd-service.js now splits install into writeUserService (repoints the unit, starts nothing) and restartUserService (--no-block). The bootstrap skips the manual stop whenever a unit of ours owns the server, and defers the restart past writeState and releaseLock, so being killed by its own request costs nothing. The unit is Restart=always: a graceful SIGTERM from anything must no longer read as "leave it stopped". installUserService keeps its old semantics for `agenthub service install`, which runs from a user's shell and is not in the cgroup.	2026-09-11 16:30:10 +07:00
nntrivi2001	0335e0e6bc	chore(release): bump version to 1.5.6	2026-09-11 15:59:33 +07:00
nntrivi2001	18614f378d	fix(updates): give a plugin-cache install a real message, not null `agenthub update-check` prints `message` as its headline, so every plugin-cache install saw the literal "null" where the verdict belongs — and that is the one install kind with no commit count to fall back on, so the line carried nothing at all. The plugin branch of getUpdatesStatus compares versions exactly like the checkout branch does; it now builds the same four sentences from what it already computed (newer release / newest / no local version to compare / release lookup failed). The nogit regression test asserted `message === null` as a proxy for "did not fall through to the not-a-git-clone payload" — it now asserts that on the message's content instead, which is what it always meant.	2026-09-11 15:54:03 +07:00
nntrivi2001	63ed90ba05	docs(plugins): stop promising an MCP server the plugin no longer ships `c7dbaf2` dropped it. The doctor row list also claimed an 'MCP build freshness' check that plugin-doctor.js does not emit.	2026-09-11 15:39:24 +07:00
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
nntrivi2001	b868a2fa85	chore(release): bump version to 1.5.2	2026-09-10 16:47:16 +07:00
nntrivi2001	30bc6debde	fix(updates): check releases for a plugin install with no .git An archive-sourced marketplace entry ("source": "url" — this project's own) makes Claude Code unpack the plugin rather than clone it, so the cache dir has no .git. getUpdatesStatus probed for .git first and returned "not a git clone; check for updates manually", skipping the entire release layer: update_available stayed false however many releases were published, and plugin_marketplace/plugin_name were never set, so POST /api/updates/apply's plugin branch could never fire (it answered 409, claiming nothing newer was published). The bug reads as "up to date", so it stayed invisible for as long as the install happened to be current. The plugin branch now runs BEFORE the .git probe and answers without git at all: the repository URL comes from the marketplace manifest on disk (known_marketplaces.json -> .claude-plugin/marketplace.json -> source.url, null rather than a guessed host for a github owner/repo shorthand), and package.json is the only local comparison signal. A failed release lookup is reported as release_check, never as "nothing newer". UI/CLI: the "not a git clone" note is gated on install_kind !== "plugin", so the Update now button is offered where the dashboard can actually check and apply.	2026-09-10 16:46:06 +07:00
nntrivi2001	d4052ed235	chore(release): bump version to 1.5.1 openapi.yaml embeds info.version and the Settings screen snapshot pins the UI build string, so both are regenerated in the same commit - repo-links.test.js and the snapshot test each fail otherwise.	2026-09-10 16:16:47 +07:00
nntrivi2001	aca35dd4cd	feat(cc-config): update every plugin and marketplace at once, then reload the open sessions The plugins tab could already update one plugin or one marketplace at a time. It gains an install-wide batch and, separately, the reload step that actually makes an update take effect. Update all runs in a DETACHED worker rather than the request handler, for a structural reason: the batch ends with the plugin the dashboard ITSELF runs from, and that step's plugin-bootstrap.js --force SIGTERMs this very server. An in-process loop would die partway through with the remaining plugins unrun and nothing left to report. Order is marketplaces (one call, no name = all) -> every other installed plugin -> AgentHub last -> one reload. Each transition is journalled to cc-update-all.json in the runtime dir, outside the plugin cache the update replaces, so whichever server is alive serves progress from it; the POST's response is only an acknowledgement. readUpdateAll DERIVES an abandoned status for a running journal older than an hour, because a detached worker killed by a reboot leaves nobody to write the terminal entry and the button would stay wedged forever. isRunning gates a concurrent batch: two claude plugin update chains over one config dir race. Reload is its own capability (server/lib/cc-reload.js, POST /api/cc-config/reload). /reload-plugins and /reload-skills are scoped BY CLAUDE CODE to the session that runs them, so nothing can reload a session from outside - typing into a session already running is the only real mechanism, and that is what this does, over tmux send-keys into the dashboard's live lane panes. It spawns NO claude process on purpose: a one-shot claude -p "/reload-plugins" would reload only its own short-lived session, exit, and leave a junk session in the dashboard's history - a headless run gets a full sessions row and there is no filter anywhere to suppress it. Reusing live panes means no session is created at all. Panes at a shell prompt are skipped (the text would run as a shell command) and only claude lanes are addressed, since Codex has no such command. Update-all reloads once at the end; updating a single plugin passes reload:true and reloads immediately, and never after a failed action. Fixes a real pre-existing bug on the way: pluginUpdate omitted -y while runClaude closes stdin, and the CLI requires it whenever stdin is not a TTY - so the per-plugin Update button failed for any plugin whose marketplace declares an install command. Also completes CcConfigChangedPayload's action union, which claimed write\|delete while nine other values were already being emitted. Verified: server 1683/1683, client 486/486 (27 new tests), build, prettier, file-header audit, openapi.yaml regenerated (117 paths). Update all was NOT executed against this machine - it would update 7 real plugins and restart the running dashboard.	2026-09-10 16:05:07 +07:00
nntrivi2001	cc85e35439	feat(updates): detect the newest release and self-apply it, including plugin installs Update detection was a commit count against the default branch, which says nothing about whether a version shipped and is pure noise on the plugin cache (a depth-1 clone, where every distance is a graft artefact). It now reads the forge's own releases API and compares the published tag to this install's package.json version, falling back to the commit count only when no release can be read — with the reason in release_check, so "up to date" never silently means "we could not look". Two states a commit count cannot express: dev_build (ahead of the newest release, missing nothing from it) now reads "Dev build - N ahead" instead of a false "Up to date"; and on a shallow clone every commits_*_release field is null and dev_build is never asserted, because the numbers would be meaningless. POST /api/updates/apply gains a second mode, chosen by install kind and never by the request body. A checkout still fast-forwards onto the release tag, rebuilds and self-restarts. A ~/.claude/plugins/cache/ install is refused by applyUpdate (that directory is Claude Code's to replace) and handed instead to a detached chain: claude plugin marketplace update -> claude plugin update -y -> plugin-bootstrap.js --force from the NEW cache dir, which retires this server and starts its replacement. Both write the HTTP response before anything stops the process. The chain records every outcome to plugin-update.json in the runtime dir, outside the cache the update replaces, so the next server reports it as last_plugin_update: a failed chain is otherwise indistinguishable from a slow one, and the tab would poll a server that never returns. /reload-plugins is deliberately not in the chain - it is REPL-scoped to the session that runs it, so no background process can perform it, and plugin-bootstrap derives PLUGIN_ROOT from its own __dirname, which is what makes it unnecessary for the dashboard. Also rebrands the sidebar subtitle, splash and page title to SmartGift Solution, and corrects three ARCHITECTURE.md statements that claimed /apply did not exist. Verified: server 1683/1683, client 486/486, build, prettier, file-header audit, openapi.yaml regenerated.	2026-09-10 16:03:07 +07:00
nntrivi2001	eb63569324	Merge pull request 'chore: remove unused surfaces (VS Code extension, statusline, landing assets, Docker)' (#14 ) from chore/remove-unused-surfaces into main	2026-09-10 07:12:08 +00:00
nntrivi2001	a146284087	Merge pull request 'fix: make every plugin in the marketplace actually installable, and repoint the repo-rename leftovers' (#13 ) from fix/plugin-install-and-repo-rename into main	2026-09-10 07:11:45 +00:00